DRIVER for SNS Beam Sync Trigger Module (Event Decoder) (v124s) - Rev. 0-4


11/5/2001
 

Table of Contents

Back to SNS Timing Software Main page


Command Synopsis

bsTrigDrv - Install driver
bsTrigDevCreate - Create each beam-sync trigger device

int bsTrigDrv(void);

int bsTrigDevCreate(deviceName, baseAddress, intNumber, intLevel, ReSyncEventCode, TSResetEventCode, ClockDelay);
char *deviceName  - Name of V124s trigger module device (e.g. /dev/bsA). 
void *baseAddress - V124s base address. 
unsigned char intNumber  - Interrupt number. 
unsigned char intLevel  - VMEbus interrupt level.
unsigned char ReSyncEventCode  - Event code for Revolution Frequency ReSync.
unsigned char TSResetEventCode  - Event code for Timestamp Reset
unsigned char ClockDelay  - Clock delay.
 

Include Files

bsTrigDrv.h

Description

This driver provides an interface to the V124s 8-channel, beam-synchronous trigger module. The driver allows configuring each of the 8 channels individually.

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

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

Device Names

For this device driver, a VxWorks logical device will be defined as a single V124s trigger module. Each trigger module within each IOC 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 one of the eight trigger output channels (numbered channels 0-7) on a V124s  module.

E.g. if the name of the V124s device is "/dev/bsA", the name of channel 0 is "/dev/bsA/0", and the name of channel 7 is "/dev/bsA/7".

The file descriptor returned is used to subsequently access that channel.

E.g. the C command :

fd = fopen("/dev/bsA/1");
will open a device for DAC module A which is used to access channel 1.

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.
BS_TRIG_CLOCK_MODE
BS_TRIG_SET_TIMESTAMP_RESET_EVENT
BS_TRIG_GET_TIMESTAMP_RESET_EVENT
BS_TRIG_SET_CLK_DELAY
BS_TRIG_GET_CLK_DELAY
BS_TRIG_SET_REVOLUTION_F_RESYNC_EVENT
BS_TRIG_GET_REVOLUTION_F_RESYNC_EVENT
BS_TRIG_SET_REVOLUTION_COUNTER
BS_TRIG_GET_REVOLUTION_COUNTER
BS_TRIG_READ_REVOLUTION_COUNTER_LSB
BS_TRIG_SET_SUB_REVOLUTION_COUNTER
BS_TRIG_GET_SUB_REVOLUTION_COUNTER
BS_TRIG_SET_TRIGGER_COUNTER
BS_TRIG_GET_TRIGGER_COUNTER
BS_TRIG_SET_PULSE_WIDTH
BS_TRIG_GET_PULSE_WIDTH
BS_TRIG_SET_FINE_DELAY
BS_TRIG_GET_FINE_DELAY
BS_TRIG_GET_TIMESTAMP_VALUE
BS_TRIG_SET_EVENT_MASK
BS_TRIG_CLEAR_EVENT_MASK
BS_TRIG_GET_BSLINK_CARRIER_ERROR
BS_TRIG_GET_BSLINK_FRAME_ERROR
BS_TRIG_GET_BSLINK_PARITY_ERROR
BS_TRIG_GET_CHANNEL_STATUS
BS_TRIG_SW_TRIGGER
BS_TRIG_SUB_REVOLUTION_COUNTER_ENABLE
BS_TRIG_REVOLUTION_COUNTER_ENABLE
BS_TRIG_HALT_TRIGGER_CLOCK
BS_TRIG_RELOAD_ALL_COUNTERS
BS_TRIG_HALT_COUNTERS
BS_TRIG_OUTPUT_POLARITY
BS_TRIG_RESET_COUNTERS
BS_TRIG_RELOAD_COUNTERS
BS_TRIG_RELOAD_REV_COUNTER
BS_TRIG_LINK_STATUS_OK
BS_TRIG_WAIT_TIME

BS_TRIG_CLOCK_MODE
Description: Set or query the clock mode. The system clock is usually based 
on the beam-sync link carrier, but can be set to an internal xtal oscillator 
for test purposes. The setting is usually controlled when the device is 
first created. This function is provided to support debugging efforts.
Arg Usage: BS_TRIG_CLOCK_MODE, BS_TRIG_CLOCK_TEST_MODE, BS_TRIG_CLOCK_MODE_QUERY 
Return Value: OK, or current setting if arg is BS_TRIG_CLOCK_MODE_QUERY
BS_TRIG_SET_TIMESTAMP_RESET_EVENT
Description: Set the timestamp resynchronizing event. The setting is usually controlled when 
the device is first created. This function is provided to support debugging efforts.
Arg Usage: Event code for beam-sync event to be used as sync event 
(reset timestamp counters)
Return Value: OK
BS_TRIG_GET_TIMESTAMP_RESET_EVENT
Description: Return the sync event. 
Arg Usage: N/A
Return Value: Sync event code
BS_TRIG_SET_CLK_DELAY
Description: To allow a shift in the phase of RF clock/Link Clock output, the V124s provides an 8-bit counter 
to be loaded into the RF clock/Link clock delay hold register. Resolution is 500ps. The delay is adjustable from 12ns to 139.5ns.
Arg Usage: 0-255
Return Value: OK 
BS_TRIG_GET_CLK_DELAY
Description: Return the position-dependent delay value. 
Arg Usage: N/A
Return Value: Clock delay counts
BS_TRIG_SET_REVOLUTION_F_RESYNC_EVENT
Description: Sets beam-synchronous event to be used as revolution frequency resync. 
The beam-sync event link will always encode an event at the 
revolution frequency, with minimum jitter. The V124s will use 
this event as a reference for all time (delayed by the clock
delay). The setting is usually controlled when the device is first 
created. This function is provided to support debugging efforts. 
Arg Usage: The revolution frequency resyn event code
Return Value: OK
BS_TRIG_GET_REVOLUTION_F_RESYNC_EVENT
Description: Return the revolution frequency resync event code used by the V124s
Arg Usage: N/A
Return Value: Revolution frequency resync event code
BS_TRIG_SET_REVOLUTION_COUNTER
Description: Provide a value for the "revolution counter" that is loaded from the revolution delay hold register and counts the number of revolution clocks until terminal count is reached. This count can count from 1 (945ns) to 65536 (61.97ms).
Arg Usage: 16-bit revolution counter value
Return Value: OK
BS_TRIG_GET_REVOLUTION_COUNTER
Description: Return the 16-bit revolution counter.
Arg Usage: N/A
Return Value: Revolution counter value
BS_TRIG_READ_REVOLUTION_COUNTER_LSB
Description: For diagnostic purposes, it is possible to read the 8 least 
significant bits of the actual revolution counter, as it is 
counting down. This is especially useful is a lab environment 
where the revolution frequency may occur at lower rate.
Arg Usage: N/A
Return Value: Least significant byte of the revolution counter
BS_TRIG_SET_SUB_REVOLUTION_COUNTER
Description: Provide a value for the "Sub-Revolution counter" that is loaded from the sub-revolution delay hold register and counts each occurrence of the carrier clock. This counter can count from 1 to 31 to allow a delay of least two full revolutions. 
Arg Usage: sub-revolution counter delay value (8 bit loadable/5-bit used, from 1 to 31)
Return Value: OK
BS_TRIG_GET_SUB_REVOLUTION_COUNTER
Description: Return the sub-revolution counter delay value
Arg Usage: N/A
Return Value: 5-bit delay value
BS_TRIG_SET_TRIGGER_COUNTER
Description: The V124s provides a 32-bit trigger counter. This counter counts the number of trigger pulses output and can be set to any value from 1 to 4.29E9.
Arg Usage: 32-bit halt trigger count (from 1 to 4.28E9)
Return Value: OK
BS_TRIG_GET_TRIGGER_COUNTER
Description: Return the 32-bit halt trigger value.
Arg Usage: N/A
Return Value: 32-bit halt trigger value
BS_TRIG_SET_PULSE_WIDTH
Description: The Pulse Width Counter is a 16-bit count-down counter that is loaded from the pulse width hold register with the required pulse width of all output pulses. It is enabled by the Sub-Revolution Counter Terminal Count. This counter counts the carrier clock. The width can be set from 59ns (1) to 3.87ms (65536).
Arg Usage: 16-bit pulse width
Return Value: OK, or ERROR
BS_TRIG_GET_PULSE_WIDTH
Description: Return the 16-bit pulse width counter value.
Arg Usage: N/A
Return Value: Pulse width counter
BS_TRIG_SET_FINE_DELAY
Description: An 8-bit value is loaded into the Fine Delay hold register and the fine delay module. Resolution is 500ps. The delay is adjustable from 12ns to 139.5ns.
Arg Usage: N/A
Return Value: OK
BS_TRIG_GET_FINE_DELAY
Description: Return the fine counter value.
Arg Usage: N/A
Return Value: 8-bit fine delay value
BS_TRIG_GET_TIMESTAMP_VALUE
Description: Return last recorded timestamp value. The timestamp is recorded 
when the timestamp trigger event occurs. The timestamp counter is 
cleared when the sync event occurs.
Arg Usage: N/A
Return Value: 32-bit timestamp
BS_TRIG_SET_EVENT_MASK
Description: Add an event to the set of beam-sync events which trigger 
ANY event triggerable component of this channel. 
Typically, events trigger the revolution counter, 
but they can also trigger the sub-revolution counter directly.
Arg Usage: beam-sync event code number
Return Value: OK
BS_TRIG_CLEAR_EVENT_MASK
Description: Remove an event from the set of events which 
trigger this channel.
Arg Usage: beam-sync event code number
Return Value: OK
BS_TRIG_GET_BSLINK_CARRIER_ERROR
Description: Return count of state changes in beam-sync 
event-link carrier error monitoring.
Arg Usage: N/A
Return Value: count of state changes
BS_TRIG_GET_BSLINK_FRAME_ERROR
Description: Return count of state changes in beam-sync 
event-link frame error monitoring.
Arg Usage: N/A
Return Value: count of state changes
BS_TRIG_GET_BSLINK_PARITY_ERROR
Description: Return count of state changes in beam-sync 
event-link parity error monitoring.
Arg Usage: N/A
Return Value: count of state changes
BS_TRIG_GET_CHANNEL_STATUS
Description: For diagnostic purposes, it is possible to monitor the 
state of event processing within the V124. This 
feature probably has no operational use.
Arg Usage: N/A
Return Value: The logical OR of any of these values : 
BS_TRIG_STATUS_WAITING_FOR_REVOLUTION_CNTR_ENABLE , 
BS_TRIG_STATUS_WAITING_FOR_CNTR_DONE, 
BS_TRIG_STATUS_WAITING_FOR_BUCKET_CNTR_DONE, 
BS_TRIG_STATUS_WAITING_FOR_HALT_CNTR_DONE, 
BS_TRIG_STATUS_HALTED, 
BS_TRIG_STATUS_RESET
BS_TRIG_SET_TIMESTAMP_EVENT_CODE
Description: Sets the event which advances the timestamp counter. The 
event can be an event on the beam-sync event link, or it can 
a 1 MHz clock derived from the 10Mhz carrier on the event link 
(not beam-synchronous).
Arg Usage: BS_TRIG_TIMESTAMP_EVENT_10MHZ, or beam-sync event code
Return Value: OK
BS_TRIG_GET_TIMESTAMP_EVENT_CODE
Description: Return event which advances the timestamp counter.
Arg Usage: N/A
Return Value: BS_TRIG_TIMESTAMP_EVENT_10MHZ, or beam-sync event code
BS_TRIG_SW_TRIGGER
Description: Trigger revolution counter or sub-revolution counter, if 
either is so programmed.
Arg Usage: N/A
Return Value: OK
BS_TRIG_SUB_REVOLUTION_COUNTER_ENABLE
Description: Set or query the sub-revolution counter enable mode. s.
Arg Usage: BS_TRIG_SUB_REVOLUTION_COUNTER_ENABLE_SW, 
BS_TRIG_SUB_REVOLUTION_COUNTER_ENABLE_EVENT, 
BS_TRIG_SUB_REVOLUTION_COUNTER_ENABLE_REV_COUNTER, 
BS_TRIG_SUB_REVOLUTION_COUNTER_ENABLE_QUERY
Return Value: OK, or current setting if arg is BS_TRIG_SUB_REVOLUTION_COUNTER_ENABLE_QUERY
BS_TRIG_REVOLUTION_COUNTER_ENABLE
Description: The revolution counter can be enabled by a beam-synchronous event, via an 
external signal (there is one external signal for each pair of output channels), 
via software, or via the leading edge of an output pulse generated by the 
previous channel (except for the first channel).
Arg Usage: BS_TRIG_REVOLUTION_COUNTER_ENABLE_SW, 
BS_TRIG_REVOLUTION_COUNTER_ENABLE_EVENT, 
BS_TRIG_REVOLUTION_COUNTER_ENABLE_EXTERNAL, 
BS_TRIG_REVOLUTION_COUNTER_ENABLE_PREVIOUS, 
BS_TRIG_REVOLUTION_COUNTER_ENABLE_QUERY
Return Value: OK, or current setting if arg is BS_TRIG_REVOLUTION_COUNTER_ENABLE_QUERY
BS_TRIG_HALT_TRIGGER_CLOCK
Description: The halt trigger can be used to terminate a timing sequence after a 
specified number of pulses have been generated. The trigger counter 
can be incremented on the leading edge of an output pulse for this 
channel, or by the bucket counter terminal count for the next channel 
(except the last channel). This mode is useful for terminating the 
timing sequence on the occurrence of a particular bucket after some 
number of revolutions. Note that the next channel must be programmed 
to use the bucket delay, not the bucket pattern when using this mode.
Arg Usage: BS_TRIG_HALT_TRIGGER_ENABLE_PULSE, 
BS_TRIG_HALT_TRIGGER_ENABLE_NOT, 
BS_TRIG_HALT_TRIGGER_ENABLE_NEXT, 
BS_TRIG_HALT_TRIGGER_ENABLE_QUERY
Return Value: OK, or current setting if arg is BS_TRIG_HALT_TRIGGER_ENABLE_QUERY 
BS_TRIG_RELOAD_ALL_COUNTERS
Description: Restore all counters to their previous values. This function 
is necessary for manually repeating a one-shot timing sequence.
Arg Usage: N/A
Return Value: OK
BS_TRIG_HALT_COUNTERS
Description: Set or query the counter halt state. Halting the counters 
may be necessary during periods of channel reconfiguration. 
E.g. If the revolution counter is armed by a regularly 
occurring beam-sync event, it may be necessary to halt 
counters while reloading counter values to avoid premature 
initiation of the timing sequence. The same effect could 
be accomplished in other ways, however, those other techniques 
require more understanding of the configuration of the channel. 
This function suspends channel operation without otherwise 
affecting channel configuration.
Arg Usage: BS_TRIG_TRIGGER_HALT, 
BS_TRIG_TRIGGER_RESUME, 
BS_TRIG_TRIGGER_HALT_QUERY
Return Value: OK, or current setting if arg is BS_TRIG_TRIGGER_HALT_QUERY
BS_TRIG_OUTPUT_POLARITY
Description: Set or query the output pulse polarity 
(active high or active low).
Arg Usage: BS_TRIG_OUTPUT_POLARITY_POSITIVE, 
BS_TRIG_OUTPUT_POLARITY_NEGATIVE, 
BS_TRIG_OUTPUT_POLARITY_QUERY
Return Value: OK, or current setting if arg is BS_TRIG_OUTPUT_POLARITY_QUERY
BS_TRIG_RESET_COUNTERS
Description: Sets all counter values to 0
Arg Usage: N/A
Return Value: OK
BS_TRIG_RELOAD_COUNTERS
Description: The counters can be configured to reload when a halt condition 
occurs. This allows continuous generation of a timing sequence. 
Alternatively, the timing sequence can be terminated when a 
halt condition occurs. In that case, the counters must be 
manually reloaded after the halt condition occurs.
Arg Usage: BS_TRIG_RELOAD_COUNTERS_ON_HALT, 
BS_TRIG_RELOAD_COUNTERS_MANUALLY, 
BS_TRIG_RELOAD_COUNTERS_QUERY
Return Value: OK, or current setting if arg is BS_TRIG_RELOAD_COUNTERS_QUERY 
BS_TRIG_RELOAD_REV_COUNTER
Description: The revolution counter can be configured to reload when 
the bucket delay is enabled.  This mode is useful for 
generating a output pulses every 'n' revolutions, without 
having to create a halt condition every 'n' revolutions. 
The halt condition (if desired) can be configured to occur 
only after some number of output pulses have been generated.
Arg Usage: BS_TRIG_RELOAD_REV_COUNTER_ON_TRIGGER, 
BS_TRIG_RELOAD_REV_COUNTER_MANUALLY, 
BS_TRIG_RELOAD_REV_COUNTER_QUERY
Return Value: OK, or current setting if arg is BS_TRIG_RELOAD_REV_COUNTER_QUERY 
BS_TRIG_LINK_STATUS_OK
Description: Return the current status of the eventlink indicated in arg.
Arg Usage: BS_TRIG_EVLINK_OK, 
BS_TRIG_BSEVLINK_OK
Return Value: OK, or ERROR is eventlink malfunction is detected
BS_TRIG_WAIT_TIME
Description: Sets the number of system ticks to wait for condition to occur 
before timing out. By default, there is no time limit, i.e. 
The BS_TRIG_WAIT function will wait forever for the 
indicated condition to occur.
Arg Usage: Number of system ticks to wait for condition.
Return Value: OK

Interrupt Handling

The interrupt service routine stores timestamp values as they occur, and accumulates link failure statistics.

The interrupt service routine also provides user notification of sync events and/or channel halt events when they occur.

As each interrupt is processed, it's source is disabled, to provide a cooling off period, after which each interrupt source is re-enabled. In general, interrupts should be few and far between for this module, I.e. link errors, timestamp synchronizing pulses, and halt triggers. Timestamp triggers are more problematic. There is only one timestamp interrupt enable bit, rather than one bit per channel. Each channel can be independently programmed, so that timestamp interrupts could come in close temporal proximity for two independent channels. On the other hand, if no "cooling off" period is enforced, a user could accidentally program this device to generate interrupts almost every usec. As a compromise, the timestamp interrupt is disabled for half the period of the other interrupts (~100 milliseconds). This will delay user notification of timestamp interrupt by up to this amount, but the timestamp itself will be correct (unless timestamps occur faster than 10 Hz for a particular channel).

See Also

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

"I/O System" Chapter

Bugs

No known bugs.

 

Back to SNS Timing Software Main page