A device map file (dmap file) allows to give alias names for ChimeraTK device descriptors. This provides an additional layer of abstraction so that device addresses and types do not need to be hardcoded into the application. A dmap file is a simple text file with one entry per line. Each line corresponds to one device and each line has two space-separated columns:

Alias name
ChimeraTK device descriptor

Example:

A PCI express device (device node /dev/pciedevs5) with the map file "mps_v00.07.map" get the alias name "MPS"
A pure software dummy device with the map file "DFMC_MD22_v3.0.map" gets the alias name "DUMMY"
A DOOCS control system server with the address "XFEL.RF/TIMER/LLA6M" gets the alias name "TIMER"

MPS (pci:pciedevs5?map=mps_v00.07.map)
DUMMY (dummy?map=DFMC_MD22_v3.0.map)
TIMER (doocs:XFEL.RF/TIMER/LLA6M)

The alias names can be chosen freely by the developer.

Please note that for compatibility reasons an old format with three columns is still supported. The third column was specifying the map file in combination with either specifying directly the path to the device node for PCI express or with a "standard device model" URI. Since both approaches do not really fit the structure of the DeviceAccess library any more, they have been superseeded by the ChimeraTK device descriptor. If you encounter a dmap file containing the old format, consider updating it to the new format. Support for the old formats will eventually be deprecated and removed.

The DOOCS backend is not build into the DeviceAccess core library. It needs to be linked at compile time or loaded dynamically (see instructions on The Plugin Mechanism).

CimeraTK device descriptor

The CimeraTK device descriptor (CDD) specifies the type of the device, the address of the device and additional parameters needed. The basic form of a CDD looks like this:

(backend_type:address?key1=value1&key2=value2)

backend_type - This is the name of the backend like it registered itself with the backend factory, e.g. "pci", "dummy" etc.
address - This is the address of the device. The exact interpretation depends on the backend. For some backends (e.g. the dummy) no address must be specified.
keyX=valueX - Any number of key-value pairs can be passed to the backend. The interpretation depends on the backend. Some backends require no parameters at all, others have optional or certain mandatory paramters.

CDDs can be nested, i.e. a CDD can be passed as e.g. an address or as a parameter value of another CDD, without any escaping.

The formal parsing rules are as following:

CDD must be surrounded by parentheses.
Within the outer parentheses of the CDD, any matching parentheses (with potentially even nested parentheses inside) is interpreted as one token resp. as being part of the current token. The following tokenising rules are not applied within those parentheses.
The first token is terminated by either ":" or "?". It is called "type" and denominates the backend type. It must consist of alphanumeric characters only and must have a non-zero length.
If the first separator character was ":", the second token is terminated by "?" and is called address. It can contain any character and may also have zero length.
If the first separator character was "?", the address is set to zero length.
The remainder of the string following the "?" separator is a list of key=value pairs each separated by "&":
- The first "=" character of each list member will separate the key from the value.
- There must be at least one "=" character, additional "=" characters will just be part of the value.
- The key must consist of alphanumeric characters only and must have a non-zero length.
- The value can contain any character and may have a zero length.
- Any empty part of the key=value list will be ignored, i.e. "&&" will be interpreted as the normal separator "&" and any trailing or leading separator is ignored.
The list of key=value pairs is optional, in which case the "?" separator can be omitted. The previous token is then terminated by the end of the CDD (i.e. the closing parentheses).
All parts of the CDD are case sensitive.
Any number of white space characters directly adjacent to any separator character (including the "=" of the key=value pairs) or the outer parentheses are ignored.
Escaping rules: The following characters can be escaped by prepending a backslash: "&", "(", ")", " " (blank), "?" and "\". "\t" will be unescaped into a tab character. Inside matching parentheses, escaped characters are not unescaped.