Direct Memory Access API - DLS-Controls-Private-org/MBF-docs GitHub Wiki
For fast access to large amounts of data from the fast memory and detector memory there is a separate channel provided by a dedicated socket. Currently only matlab support is provided for fast readout, but the socket interface is straightforward and is documented below. See Matlab Scripts for documentation of the matlab scripts.
Matlab API
See Fast memory readout for documentation of readout from fast memory using Matlab.
See Detector readout for documentation of readout from detector memory using Matlab.
See below for the underlying direct socket API.
Socket API
To make a data request over the socket interface the client should connect to$(server):$(port) where$(server) is found by reading PV$(device):INFO:HOSTNAME and$(port) by reading PV$(device):INFO:SOCKET. A one line command should be sent terminated by a single'\n' newline character, and the response will be as documented below.
Two commands are supported,M for memory readout andD for detector readout. Both commands can be preceded by an optionR character which affects error handling:
- IfR is not specified and a parsing error or locking error occurs (for example,L is specified and the target cannot be locked) then a newline terminated error string describing the failure is returned. If no error occurs the first character returned will always be null'\0'.
- IfR is specified then the leading null character is never sent, but if an error occurs then nothing is returned and the server will just close the connection.
All values returned (apart from the error string described above) are integers in little endian format.
Fast memory readout
\[R] M count \[F] \[O offset] \[C channel] \[B bunch | \[D decimation] \[T tune]] \[L \[W timeout]]
For example:
$ echo M1 |nc ts-di-lmbf-01 8888 |hd
00000000 00 f0 ff fe ff e4 ff fd ff d0 ff fa ff f0 ff fe |................|
00000010 ff cc ff fa ff 00 00 00 00 e0 ff fc ff d8 ff fb |................|
00000020 ff e8 ff fd ff e0 ff fc ff d8 ff fb ff 04 00 01 |................|
...
00000e90 00 e4 ff fd ff e8 ff fd ff d8 ff fb ff d8 ff fb |................|
00000ea0 ff |.|
Here the leading null can be suppressed by sending RM1 instead. Data is returned as a sequence of pairs of 16-bit integers, alternating between values from channel 0 and channel 1, and with a leading null character, unlessR orC options are used to change the behaviour.
Data formatThe format of the returned data depends on the selected options. The following blocks of data may be sent, depending on options:
- UnlessR is specified, an initial null byte is sent to indicate success, or the entire returned data is a printable error message.
- An optional eight byte header, if optionF selected:
| Offset | Length | Description |
|---|---|---|
| 0 | 4 | Number of samples that will be sent. |
| 4 | 2 | Number of channels per sample, 1 or 2. |
| 6 | 2 | Specifies the memory format for each sample in the data stream, as determined by the command options. One of the following values: |
| Format | Data Type | Bytes per Sample | Option | Description |
|---|---|---|---|---|
| 0 | int16 | 2 | - | Raw samples as read from memory. Used if neitherD norT selected. |
| 1 | float32 | 4 | D | Averaged samples. Used ifD is selected withoutT. |
| 2 | complex64 | 8 | T | Averaged frequency shifted samples in IQ complex format. |
|
- The data is sent as specified in the header above with each sample occupying 2, 4, or 8 bytes according to whetherD orT have been selected.
Command Options
| Argument | Description |
|---|---|
| R | This option suppresses the leading zero and error reporting. |
| count | This mandatory argument specifies how many turns of data have been requested. |
| F | If this option is set then the memory data will be preceded by an eight byte header describing the format of the data. The header format is described above. |
| O offset | Starting offset in turns from trigger point, defaults to 0, can be signed. |
| C channel | If this is set thenchannel must be 0 or 1 and only the requested channel is sent. |
| B bunch | If specified then data for the selected bunch only will be sent. This cannot be combined withD orT. |
| D decimation | If specified then turns will be averaged over the specified number of turns, bunch-by-bunch, to reduce the amount of data returned. IfT is not specified data will be returned as 32-bit IEEE floats. |
| T tune | If specified then data will be frequency shifted by multiplying by \exp(2\pi i \frac{f_{\text{T}}}{N_{\text{turn}}}t), where f_{\text{T}} is the selected frequency andN_{\text{turn}} is the number of bunches per turn, and t counts bunches. |
| | L | This requests that the channel be locked for readout. | | W timeout | This specifies an optional timeout for locking. The timeout value should be supplied as an integer number of milliseconds. The default timeout is 0. |
Detector readout
\[R] D axis \[F] \[S \[L]] \[T] \[L \[W timeout]]
Data FormatThe format of returned data depends on the selected options. The following blocks of data may be sent, depending on options:
- UnlessR is specified, an initial null byte is sent to indicate success, or the entire returned data is a printable error message.
- A optional twelve byte header, if optionF selected:
| Offset | Length | Description |
|---|---|---|
| 0 | 1 | Number of active detectors. |
| 1 | 1 | Mask of active detectors, detectorn is active if bitn is set forn in range 0 to 3. |
| 2 | 2 | Compensation delay in bunches. |
| 4 | 4 | Number of samplesN captured by detector. |
| 8 | 4 | Number of bunches in a machine revolution. |
- Detector data. This consists ofN rows of samples where each row consists of a pair of 32-bit samples I, Q in sequence for each active detector. For example, if 2 detectors are active then the data sequence would be (whereI_{n,t} andQ_{n,t} are the samples for detector n at time t):
I_{0,0} ; Q_{0,0} ; I_{1,0} ; Q_{1,0} ; I_{0,1} ; Q_{0,1} ; I_{1,1} ; Q_{1,1} ; \dots ; I_{0,N-1} ; Q_{0,N-1} ; I_{1,N-1} ; Q_{1,N-1}
Note that the detector data is not corrected for phase, see below for the correction algorithm.
- Frequency scale, if optionS selected. This is a sequence ofN integers recording the sweep frequency of each sample. The integer size and scaling factor depend on whetherS orSL was specified, as shown in the table below:
| Arg | Integer bits | Scaling |
|---|---|---|
| S | 32 | K_S=2^{-32} |
| | SL | 64 | K_S=2^{-48}
|
The sweep frequency is recorded in units ofK_S revolutions per bunch, such that the frequency in tunes is obtained by multiplying by the number of bunches in the machine. In other words, given a frequency reading ofs as an integer, the corresponding tune frequency isK_S, s,N_{\text{turn}} and the frequency in Hertz is K_S,s,f_{\text{rf}} where N_\text{turn} is the number of bunches per machine revolution and f_\text{rf} is the machine RF frequency in Hertz.
- Timebase, if optionT selected. This is a sequence of N 32-bit integers recording the start time of each sample in units of machine turns.
| Argument | Description |
|---|---|
| R | This option suppresses the leading zero and error reporting. |
| axis | This mandatory argument specifies for which axis data will be returned. |
| F | If this option is set then the detector data will be preceded by a twelve byte header describing the format of the data. The header format is described above. |
| S [L] | If this option is set then the frequency scale is sent immediately after the detector readout data. IfL is specified as well then the frequency scale is sent as a sequence of 48 bit numbers padded to 64 bits, otherwise the scale is set as 32 bit numbers. In the latter case the frequency resolution is reduced accordingly. |
| T | If this option is set then the timebase scale is sent immediately after the frequency scale if sent, otherwise immediately after the detector data. |
| L | This requests that the channel be locked for readout. |
| W timeout | This specifies an optional timeout (in millisecond) for locking. The timeout value should be supplied as an integer number of milliseconds. The default timeout is 0. |
Restriction on optionsNote that it is impossible to specify 32-bit frequency scale with locking and no timebase: the option string for this would be SL, which is interpreted as a request for 48-bit frequency scale.
As noted above, the detector data is not corrected for phase advance. To do this correction, the following conversion is recommended:
- Read compensation delay from field 2 (bytes 2-3) in header, call this d bunches.
- Capture raw detector data as a sequence of I,Q pairs and convert to complex numbers z_t = 2^{-31}(\text{I}_t + i\text{Q}_t) (here we have scaled to maximum range of \pm1).
- Capture raw frequency scale s_t and scale tof_t=K_Ss_t.
- Compute corrected data as c_t=\exp(-2i\pi,d,f_t),z_t.