6.1 Programming the S-bus interface

This page is part of the ING document INS-DAS-31 Design notes for UltraDAS

There is no programming manual for the S-bus interface; the vendor does not supply one. This section gives an outline of what is required.

Device names

The entry-point the device for an application are the device-special files /dev/astro0 and /dev/astro1. The former file refers to the first physical device and the latter to the second, if there are two; /dev/astro1 will be present even if there is only one device.

Basic calls

The device driver provides open and close calls with the normal behaviour. The behaviour of flags on the open call is not known; better not to play around.

The ioctl call is used to send commands directly to the interface device, and also to send commands through the device to the camera-controller. Most commands return status, but ioctl does not wait for the return message.

The read call reads bytes from the device. These bytes may form the reply to a command or they may be pixels, depending on context. The API does not distinguish the two kinds of data. The read call blocks until sufficient bytes are read; typically, one asks it to block until the end of a readout. The blocking read will time out if insufficient bytes arrive. The time-out in the vendor's version of the driver was 30 seconds. ING uses a version in which the time-out is 10 seconds.

There is no write call. If one were modifying the driver, it would make a pleasing symmetry to use write to send a command to the camera (complimentary to read), while reserving ioctl for commands to the interface device itself.

Modal behaviour

The fibre connection from the camera to the DAS is modal: it can be switched to message mode for command transactions, to pixel mode to capture readouts, or to reset mode to send a hardware-reset signal into the camera. If the link is wrongly in pixel mode, it mangles incoming stati from commands; if wrongly in message mode, it mangles or loses pixels. The mode must be switched explicitly by the application using ioctl calls.

To set the mode, use the ioctl command-code 0x80010104 and pass by reference the argument value for the desired mode: 0 for message mode, 1 for pixel mode and 7 for reset.

Commands to the camera

To send a command to a DSP in the camera controller, following the protocol of INS-DAS-18, use the ioctl call.

The ioctl command-code is 0x8000103, but the upper sixteen bits of the command code are altered to encode the number of words of data in the command. Set the number of data words into a 32-bit unsigned integer and left-shift them 16 places. Then combine the result with the ioctl command-code in a bitwise AND operation. The result is the code to pass into ioctl. Data words in this context are 32 bits wide.

Pass the message by reference as the argument of ioctl. The message must consist of a contiguous array of 32-bit (where the bytes of the integers are numbered 1..4 in order from most to least significant) used as follows.

Set byte 1 of each integer to 0xAC.
Set byte 2 of the first integer to 1 to indicate that the message comes from the DAS.
Set byte 3 of the first integer to 2 to send to the timing DSP or 3 to send to the utility DSP.
Set byte 4 of the first integer to the total number of data words in the command.
Set bytes 2, 3 and 4 of the second integer to the ASCII characters forming the command mnemonic, e.g. "BIN".
Add numeric arguments of the command to integers 3+ of the command, setting only bytes 2, 3 and 4 in each.

Note that the command-arguments arrive in the camera as 24-bit integers.

To get the camera's reply to the command, call read, supplying a suitable buffer. All replies are two data-words long. The first word has the same format as the equivalent word in the command, except that the source and destination bytes are reversed. The second word holds the useful part of the reply. To extract this as a number, mask out byte 1 of the word, setting all its bits to zero.

Most commands return the ASCII characters DON for success or ERR for failure in bytes 2..4 of the second word of the reply. After a reset of the camera DSPs, the first reply will have the ASCII characters SYR (for system reset) in these bytes. The RDM (read memory command) returns a numeric quantity if it succeeds, or ERR if it fails; it is unfortunate that the bit pattern for ERR might also be a valid numeric result.

Reading pixels

Having set the camera into pixel mode, issue the RDC command (which starts readout does not send a reply) and immediately call read. The read will capture the pixels if all is well. The whole readout must be read in one read call, or else pixels will be lost.

The above sequence is technically a race condition. It is possible to send RDC, then be delayed in calling read until after the first pixels have arrived and overflowed the buffer. However, given the real-time methods described in section 6.2, this is a race that the DAS always wins.

After readout, switch promptly back to message mode.

Resetting the interface

To reset the interface from software, call ioctl with command code set to 0x80000109 and argument set to zero. It is not certain that this does anything useful (the call is never actually made in the current udas_camera), but it seemed to be harmless when used in udas_server. The device seems not to need this treatment. It is properly reset whenever the DAS computer is booted, and anyway seems not to go wrong between reboots. It may be that either the open and close calls, or the mode-change commands, or both include a partial reset that is enough to recover from any problems.