DRIVER for SNS Beam Sync Event Encoder Module (v123s) and Input Module (v101) - Rev. 0-4


11/7/2001
 

Table of Contents

Back to SNS Timing Software Main Page


Command Synopsis

bsyncDrv - Install driver
bsyncDevCreate - Create each beam-sync input or encoder device

int bsyncDrv(void);

int bsyncDevCreate(deviceName, baseAddress,  moduleIndex, intLevel, intNumber);
char *deviceName  - Name of input or encoder device (e.g. /dev/eventE; /dev/eventIA). 
void *baseAddress  - V123s (encoder module) base address. 
signed char moduleIndex  - -1 for encoder, 0-15 for input modules 
unsigned char intNumber  - Interrupt number, set separately for encoder and input modules. 
unsigned char intLevel  - VMEbus interrupt level, set for encoder, used by input modules. 
 

Include Files

bsyncDrv.h

Description

This driver provides an interface to the V123s beam-synchronous encoder module and the 16-channel V101 beam-synchronous input modules.

Most of the routines in this driver are accessible only through the I/O system. bsyncDrv(), however, must be called directly to install the driver and bsyncDevCreate() to initialize and install each device.

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

The write() function is only available for encoder module devices. The bytes written to these devices appear as event codes on the event link at the time they are written. The write() function returns the number of bytes successfully transferred to the V123s for encoding. These values are stored in a FIFO until they can be encoded on the event link. In a normally functioning system, this design detail is transparent to the user.  In a malfunctioning system, values can be queued indefinitely in the FIFO. A successful return value from the write() function merely guarantees that the values have been transferred to the FIFO, not that the values have been encoded on the event link.

IOCTL

This driver provides a brief (<1024 bytes) text description, along with the source code version identifier, in response to ioctl code FIOGETLABEL.

In addition there are some special ioctl functions available. A list of these follows. Please select them for more information.
BSYNC_ENCODER_REV_TICK_STATUS
BSYNC_ENCODER_REV_TICK_FAIL_COUNT
BSYNC_ENCODER_CLOCK_STATUS
BSYNC_ENCODER_CLOCK_FAIL_COUNT
BSYNC_ENCODER_EXTERNAL_EVENT_STATUS
BSYNC_ENCODER_EXTERNAL_EVENT_FAIL_COUNT
BSYNC_ENCODER_SYNC_STATUS
BSYNC_ENCODER_SYNC_FAIL_COUNT
BSYNC_ENCODER_AUTO_OVERRIDE_CONTROL
BSYNC_ENCODER_AUTO_OVERRIDE_STATUS
BSYNC_ENCODER_REV_COUNTER_READ
BSYNC_ENCODER_REV_COUNTER_CLEAR
BSYNC_ENCODER_REFRESH_STATUS_BITS
BSYNC_INPUT_ENABLE
BSYNC_INPUT_DISABLE
BSYNC_INPUT_IS_ENABLED
BSYNC_INPUT_TRIGGER
BSYNC_INPUT_ERROR_COUNT
BSYNC_INPUT_GET_EVENT_LIST
BSYNC_INPUT_SET_EVENT_LIST

BSYNC_ENCODER_REV_TICK_STATUS
Description: Return the current state of the revolution tick. The V123s depends on a signal 
indicating the start of a new revolution of bunches. If this signal does 
not occur in a timely manner, the status is set to failed. If the signal 
is reestablished, the status reverts to OK.
Arg Usage: N/A 
Return Value: 1 means rev. tick failed, 0 means rev. tick OK
BSYNC_ENCODER_REV_TICK_FAIL_COUNT
Description: The driver accumulates a count of state changes of the 
rev. tick status. Each time the rev. tick status changes 
from failed to OK, or vice versa, the count increments. 
This count can be used for historical analysis. The 
count is maintained by the interrupt service routine. 
If interrupts are disabled, the count will not be 
properly maintained.
Arg Usage: N/A
Return Value: Count of state changes of rev. tick status
BSYNC_ENCODER_CLOCK_STATUS
Description: Return the current state of the external clock. The V123 depends on an 
external beam-synchronous clock at about 28 Mhz. If the clock signal does 
not occur in a timely manner, the status is set to failed. If the clock 
is reestablished, the status reverts to OK.
Arg Usage: N/A 
Return Value: 1 means clock failed, 0 means clock OK
BSYNC_ENCODER_CLOCK_FAIL_COUNT
Description: The driver accumulates a count of state changes of the 
clock status. Each time the clock status changes 
from failed to OK, or vice versa, the count increments. 
This count can be used for historical analysis. The 
count is maintained by the interrupt service routine. 
If interrupts are disabled, the count will not be 
properly maintained.
Arg Usage: N/A
Return Value: Count of state changes of clock status
BSYNC_EXTERNAL_EVENT_STATUS
Description: Returns one if an external event has occurred. An improperly configured 
V101 may produce an out of range event code index. 
If this happens, the V123s will "latch" that fact, and this 
function will return 1. The latch can be cleared via the 
BSYNC_ENCODER_REFRESH_STATUS_BITS ioctl function.
Arg Usage: N/A 
Return Value: 1 means external event has occurred, 0 means external event state cleared
BSYNC_ENCODER_EXTERNAL_EVENT_COUNT
Description: The driver accumulates a count of state changes of the 
external event status. Each time the external event status changes 
from failed to OK, or vice versa, the count increments. 
This count can be used for historical analysis. The 
count is maintained by the interrupt service routine. 
If interrupts are disabled, the count will not be 
properly maintained. Currently, the V123s does not issue 
an interrupt on this state change. Therefore the count is 
always 0.
Arg Usage: N/A
Return Value: Count of state changes of external event status
BSYNC_ENCODER_SYNC_STATUS
Description: Return the current state of external clock synchronization. The V123s depends on an 
external beam-synchronous clock at about 28 Mhz. If the clock frequency 
is too far out of range, the status is set to failed. If synchronization 
is reestablished, the status reverts to OK.
Arg Usage: N/A 
Return Value: 1 means synchronization has failed, 0 means synchronization is OK
BSYNC_ENCODER_SYNC_FAIL_COUNT
Description: The driver accumulates a count of state changes of the 
synchronization status. Each time the synchronization status changes 
from failed to OK, or vice versa, the count increments. 
This count can be used for historical analysis. The 
count is maintained by the interrupt service routine. 
If interrupts are disabled, the count will not be 
properly maintained.
Arg Usage: N/A
Return Value: Count of state changes of synchronization status
BSYNC_ENCODER_AUTO_OVERRIDE_CONTROL
Description: Sets the clock auto/override mode of the V123s. 
In automatic mode, the V123s gives preference to the 
external clock, but will switch to an internal clock 
if the external clock fails. In override mode, the V123s 
only uses the internal clock. 

Note that this feature is currently disabled on the V123s. 
The V123s will never use the internal clock in either 
mode. It will only ever use the external clock.

Arg Usage: 0 for override mode, non-zero for automatic mode
Return Value: OK
BSYNC_ENCODER_AUTO_OVERRIDE_STATUS
Description: Returns the V123s clock mode.
Arg Usage: N/A
Return Value: 0 for override mode, 1 for automatic mode
BSYNC_ENCODER_REV_COUNTER_READ
Description: The V123s keeps a 32-bit counter of beam revolutions. 
This counter can be read via the driver. However, the 
counter cannot be read atomically, and changes at a high rate, so the value has little significance 
except to provide comfort if it is changing at all.
Arg Usage: N/A
Return Value: The approximate number of beam revolutions since the counter was cleared
BSYNC_ENCODER_REV_COUNTER_CLEAR
Description: Clear the internal revolution counter
Arg Usage: N/A
Return Value: OK
BSYNC_ENCODER_REFRESH_STATUS_BITS
Description: The external event status condition is latched when it 
occurs, and remains latched until this function is 
invoked. Other status indicators change without user 
intervention.
Arg Usage: N/A
Return Value: OK
BSYNC_INPUT_ENABLE
Description: When an input channel is enabled, signals connected to 
that channel will produce event codes.
Arg Usage: channel number (0-15)
Return Value: OK
BSYNC_INPUT_DISABLE
Description: When an input channel is disabled, signals connected to 
that channel will not produce event codes.
Arg Usage: channel number (0-15)
Return Value: OK
BSYNC_INPUT_IS_ENABLED
Description: Return the enable status of a channel.
Arg Usage: channel number (0-15)
Return Value: 1 if enabled, 0 if not
BSYNC_INPUT_TRIGGER
Description: Simulate a signal connected to a channel to produce an event code.
Arg Usage: channel number (0-15)
Return Value: OK
BSYNC_INPUT_ERROR_COUNT
Description: If the input signal frequency is higher than the polling frequency 
of the V123s, then not all signals will produce event codes. A 
count of "lost" input signals is maintained by the driver, 
and returned by this function. The count is maintained 
by the interrupt service routine. If interrupts are disabled, 
the count will not be properly maintained.
Arg Usage: channel number (0-15)
Return Value: OK
BSYNC_INPUT_GET_EVENT_LIST
Description: Return the event codes associated with each of the 16 channels 
which comprise the input module.
Arg Usage: pointer to user-provided bsyncEventList data structure
Return Value: OK
BSYNC_INPUT_SET_EVENT_LIST
Description: Assign the event codes associated with each of the 16 channels 
which comprise the input module.
Arg Usage: pointer to user-provided bsyncEventList data structure
Return Value: OK
 

Interrupt Handling

The interrupt service routine accumulates input errors from various sources.
 

See Also

Related man pages: open(2), close(2), ioctl(2), write(2), ioLib(1)

"I/O System" Chapter in VxWorks Manual.

Bugs

Back to SNS Timing Software Main Page