DRIVER for SNS RTDL Encoder Module (v105) and Input Module (v106) - rev. 0-4

11/7/2001

Command Synopsis
Include Files
Description
Initialization
Default Mode
Device Names
IOCTL
Concurrency Control
Interrupt Handling
Read/Write
Parameter ID Table
See Also
Bugs

Back to SNS Timing Software Main Page

Command Synopsis

rtdlDrv - install driver
rtdlDevCreate - Create each rtdl input/encoder device

int rtdlDrv(void);

int rtdlDevCreate( deviceName, baseAddress, moduleType, intNumber, intLevel )

Include Files

rtdlDrv.h

Description

The driver was ported from RHIC's control system. The SNS Real Time Data Link system will be used to transmit certain machine parameters throughout the SNS machine.

Values to be transmitted are input to one of the dual channel (or 8 channles for newer version) input modules which sends the value to the Real Time Data Link encoder module to be transmitted on the Real Time Data Serial Link. The values input to the Real Time Data Link Input modules are either analog or digital.

The Real Time Data Link system has one Real Time Data Link Encoder module and many (up to 128) Real Time Data Link dual channel input modules or (up to 32) 8 channel input modules.

Initialization

Before using the Real Time Data Link driver, rtdlDrv() must be called directly to install the driver in the VxWorks I/O system. rtdlDevCreate() must then be called to initialize and install each device.

After installing the driver and creating the devices the following functions are available; open(), close(), ioctl(), read(), write(). These are available through the VxWorks I/O system.

Default Mode

When new input channel devices are installed, the driver will not affect the state of the input channels. Ioctl functions are provided which can be used to determine the current state.

When new encoder devices are installed, the driver reads an indication on the encoder board to see if initialization is necessary. If the board had been previously initialized, the driver does not affect the state of the board. If initialization is necessary, the encoder module will be configured as follows:

Interrupts are enabled.
Encoder GO bit is set.

Device Names

A device will be defined as either an encoder module or an input module. Each module within the system will have a unique device name. The driver supports arbitrary names. However, it is recommended that, for ease of use, device names reflect the function or position of the device in the system.

Extended naming will be used when using open() to access a specific channel on an input module. E.g. if the name of the input device is "/dev/rtdlIA", the name of channel 1 is "/dev/rtdlIA/1", and the name of channel 2 is "/dev/rtdlIA/2". The file descriptor returned is used to subsequently access that channel.

E.g. the C command :

fd = fopen("/dev/rtdlIA/1");

will open a device for Real Time Data Link input module A which is used to read channel 1.

IOCTL

This driver provides a brief (<1024 bytes) text description, along with the source code version identifier, in response to ioctl code FIOLABELGET. Seek support is provided for the READ/WRITE functions.

CD_GET_BOARD_ID is a control device standard ioctl function supported by the driver.

In addition there are some special ioctl functions available. A list of these follows. Please click on them for more information.

RTDL_INPUT_SET_MODE
RTDL_INPUT_GET_MODE
RTDL_INPUT_SET_VME_DATA
RTDL_INPUT_GET_VME_DATA
RTDL_INPUT_GET_DEVICE_DATA
RTDL_ENCODER_GET_STATUS
RTDL_ENCODER_SET_TRIGGER
RTDL_ENCODER_GET_TRIGGER
RTDL_ENCODER_NO_REPLY_ERROR_COUNT
RTDL_ENCODER_NO_REPLY_ERROR_ID
RTDL_ENCODER_NO_CARRIER_ERROR_COUNT
RTDL_INPUT_NO_LINK_ERROR_COUNT
RTDL_INPUT_FRAME_ERROR_COUNT
RTDL_INPUT_CRC_ERROR_COUNT
RTDL_ENCODER_ADD_CODE
RTDL_ENCODER_DELETE_CODE
RTDL_INPUT_GET_PARAMETER_ID
RTDL_SET_RESET
RTDL_GET_RESET
RTDL_GET_BASE_ADDRESS
RTDL_ENCODER_VERIFY_CODE

RTDL_INPUT_SET_MODE
Description:	Sets data mode of input channel (not valid for encoder module).
Arg Usage:	1 for VME mode, 0 for device mode.
Return Value:	OK if success ERROR if unsuccessful.

RTDL_INPUT_GET_MODE
Description:	Returns data mode of input channel (not valid for encoder module).
Arg Usage:	N/A
Return Value:	1 for VME data mode, 0 for device data mode.

RTDL_INPUT_SET_VME_DATA
Description:	Write to VME data register for input channel (not valid for encoder module).
Arg Usage:	Desired VME data.
Return Value:	OK if success ERROR if unsuccessful.

RTDL_INPUT_GET_VME_DATA
Description:	Returns the current VME data register for input channel (not valid for encoder module).
Arg Usage:	N/A
Return Value:	Current VME data register

RTDL_INPUT_GET_DEVICE_DATA
Description:	Returns the current DEVICE data register for input channel (not valid for encoder module).
Arg Usage:	N/A
Return Value:	Current DEVICE data register for input channel

RTDL_ENCODER_GET_STATUS
Description:	Returns the current value of the encoder status register.
Arg Usage:	N/A
Return Value:	Current value of encoder status register

RTDL_ENCODER_SET_TRIGGER
Description:	Enable or disable external trigger on the encoder module (not valid for input channels).
Arg Usage:	1 for enable, 0 for disable.
Return Value:	OK if success ERROR if unsuccessful.

RTDL_ENCODER_GET_TRIGGER
Description:	Returns the state of external trigger bit on encoder module (not valid for input channels).
Arg Usage:	N/A
Return Value:	1 for external trigger enabled, 0 for disabled.

RTDL_ENCODER_NO_REPLY_ERROR_COUNT
Description:	Returns the count NO REPLY errors for input channel. (not valid for input channels).
Arg Usage:	N/A
Return Value:	count NO REPLY errors for input channel

RTDL_ENCODER_NO_REPLY_ERROR_ID
Description:	Returns the parameter ID of channel with NO REPLY error. (not valid for input channels).
Arg Usage:	N/A
Return Value:	parameter ID of channel with NO REPLY error

RTDL_ENCODER_NO_CARRIER_ERROR_COUNT
Description:	Returns the count of event line CARRIER NOT DETECTED errors. (not valid for input channels).
Arg Usage:	N/A
Return Value:	count of event line CARRIER NOT DETECTED errors

RTDL_INPUT_NO_LINK_ERROR_COUNT
Description:	Returns the count of local serial LINK NOT DETECTED errors. (not valid for encoder module).
Arg Usage:	N/A
Return Value:	count of local serial LINK NOT DETECTED errors

RTDL_INPUT_FRAME_ERROR_COUNT
Description:	Returns the count of FRAME errors for input channel. (not valid for encoder module).
Arg Usage:	N/A
Return Value:	count of FRAME errors for input channel

RTDL_INPUT_CRC_ERROR_COUNT
Description:	Returns the count of CRC errors for input channel (not valid for encoder module).
Arg Usage:	N/A
Return Value:	count of CRC errors for input channel.

RTDL_ENCODER_ADD_CODE
Description:	Add a parameter ID to the current end of the parameter ID list. (not valid for input module).
Arg Usage:	Parameter ID to add
Return Value:	OK if success ERROR if unsuccessful.

RTDL_ENCODER_DELETE_CODE
Description:	Delete last occurrence of a code in parameter ID list. (not valid for input module)
Arg Usage:	Parameter ID to delete
Return Value:	Remaining number of occurrences in list.

RTDL_INPUT_GET_PARAMETER_ID
Description:	Get the parameter ID for an input channel.
Arg Usage:	N/A
Return Value:	Returns the jumper selected parameter ID for input channel used by this open device.

RTDL_SET_RESET
Description:	Set or clear the reset bit for the module or channel used by this open device. (valid for either encoder or input module).
Arg Usage:	1 for set, 0 for clear
Return Value:	OK if success ERROR if unsuccessful.

RTDL_GET_RESET
Description:	Get the current status of the reset bit for the module or channel used by this open device.
Description:	Verify that the given parameter ID has been loaded into the table on the encoder module. (valid for either encoder or input module).
Arg Usage:	N/A
Return Value:	Returns 1 for set, 0 for clear.

RTDL_GET_BASE_ADDRESS
Description:	Get the base address of the module used by this open device. (valid for either encoder or input module).
Arg Usage:	N/A
Return Value:	Returns local base address of module.

RTDL_ENCODER_VERIFY_CODE
Description:	Verify that the given parameter ID has been loaded into the table on the encoder module. (not valid for input module)
Arg Usage:	Parameter ID to verify
Return Value:	Count of occurrences in the table

Concurrency Control

A semaphore is used internally within the driver to control access to the read and write functions to one user at a time. If the semaphore is not available, the driver will wait until it does become available.

Interrupt Handling

Interrupts are generated when the encoder module does not get a response from a particular input channel, as well as when no event line carrier (RCLK) has been detected for 1 us. The PARAMETER ID on the encoder module is read by the interrupt handler when a NO RESPONSE interrupt occurs in order to decipher which channel is at fault.

Interrupts are generated on the input module when the carrier on the local serial link has not been detected for 2us, when a frame has been received with a data integrity (CRC) error, and when a frame error occurs.

A count is kept of each type of error for each device. These are available through the ioctl functions.

Read/write

The read and write functions of the driver will be limited to reading and writing from the parameter ID table within the encoder module.

Parameter ID Table

The encoder module has a special table which is used for configuration, known as the parameter ID table. In it is the parameter ID list which the encoder board will use to determine the sequence of transmission for the input channel values at each transmission event.

The table can contain a list of up to 256 entries. The table may be accessed using either the IOCTL functions RTDL_ENCODER_ADD_CODE, or RTDL_ENCODER_DELETE_CODE (see above), or the driver's read or write functions if the user desires to read or insert a parameter list in one driver call. The beginning of the table will be assigned to offset 0 of the read/write buffer used. It contains the following format:

	MSB ..... Parameter ID ..... LSB
Entry 0	\|___\|___\|___\|___\|___\|___\|___\|___\|
. . . .	. . . . . .
Entry 255	\|___\|___\|___\|___\|___\|___\|___\|___\|

where "Entry" is an 8-bit code for an input channel. The first zero entry in the list will cause the encoder to stop scanning the table for more entries.

Bugs