: Hardware Information : Using the Delay Driver

Hardware Information: Using the Delay Driver

Overview

The Delay Driver provides a way for a program using the Protocol to send FT_DATA messages to a card which are transmitted after specified time delays. Normal FT_DATA frames are used with the timestamp element of the FT_DATA header set to the delay time expressed in tens of microseconds. Any FT_DATA message with a timestamp value of zero is sent to the card immediately, bypassing any messages that may be waiting to be transmitted.

Using IOCTLs defined below, the user is able to configure various characteristics of the Delay Driver.

Two FT_EVENT messages, Low Water Mark and Empty, are sent to the program supplying the FT_DATA messages when the backlog of FT_DATA messages is running low and when it empties.

Details

The CMD_SERVER_SET_TIMED_XMIT command is used to enable and disable the delay driver for a channel. By default, the Delay Driver is disabled for all channels. Multiple commands may be used to enable the Delay Driver for multiple channels. If a given channel is enabled to delay messages, any FT_DATA message with a non-zero timestamp value written to that channel will be delayed by the requested amount of time. Disabling the Delay Driver for a channel that has a backlog of delayed messages, has no effect on that backlog, nor on when the back logged messages will be sent.

All of the delayed FT_DATA messages written to cards via the Server are kept in stream queues. In each stream queue there is a single delay time line that is applied to all of its messages regardless to which card channel an individual FT_DATA message was sent. In other words, as each new FT_DATA message with a non-zero timestamp is sent to a card, it is placed at the end of the stream queue to be sent following the message in front of it after the requested delay time has elapsed. At the front of the stream queue, messages are removed and sent to the desired card channel as the requested delay times expire.

The time delay is measured from the beginning (transmission) of one message to the beginning (transmission) of the next message. For the first message in a stream queue the delay time is from the receipt of the message by the Delay Driver to its transmission.

The Delay Driver's time resolution is one millisecond (0.001 second). The FT_DATA message's timestamp has a resolution of ten microseconds (0.00001 second). In order to maintain more accurate timing, fractional millisecond values from one delay are added to next instead of being discarded. This allows the desired message distribution to be approximated as best as possible over time.

Each normal Client connection has its own stream queue. A program's stream queue number is the same as its client ID number. If a program needs two or more independent stream queues, a client connection needs to be established for each stream queue.

A program may make use of the Delay Driver indirectly by starting a schedule or registering with the USDT Server. In both cases, separate stream queues are used which have no direct impact on the program's own stream queue if it creates one by using the CMD_SERVER_SET_TIMED_XMIT command.

Events

The following values may be transmitted as FT_EVENT type GCProtocol frames. Unlike normal FT_EVENT messages, these are sent only to the client that corresponds to the stream queue.

The event value will be in the event field of such a frame.
Note: Please see the include file dev_delay.h for numeric values of the following symbols.

Event name Event meaning

GDELAYLOW The number of messages in the stream queue has just crossed the low water mark.

GDELAYEMPTY The stream queue is empty.

IOCTL definitions

These values are used with the CMD_CARD_IOCTL command.

Normally the destination for the CMD_CARD_IOCTL command is set to SD_CARD and the Destination Channel is set to the channel number. The Server knows which driver is used for a given channel and routes the command to the correct driver. In this case, however, the Destination Channel needs to be set to the channel used by the delay driver which is DELAY_CHAN. The Destination should be set to SD_CARD as normal.

Please see the include file dev_delay.h for numeric values of IOCTLS.

IOCTL name Function Data field length/purpose

GDLYGETHIVALUE Get the current high water mark value 4 data bytes, 2 recv
2 bytes: Stream number (send)
2 bytes: High water number of msgs(recv)

GDLYSETHIVALUE Set the high water mark value 4 data bytes, 4 send
2 bytes: Stream number
2 bytes: High water number of msgs

GDLYGETLOVALUE Get the current low water mark value 4 data bytes, 2 recv
2 bytes: Stream number (send)
2 bytes: Low water number of msgs (recv)

GDLYSETLOVALUE Set the low water mark value 4 data bytes, 4 send
2 bytes: Stream number
2 bytes: Low water number of msgs

GDLYGETHITIME Get the current high water mark time 4 data bytes, 2 recv
2 bytes: Stream number (send)
2 bytes: High water time in ms(recv)

GDLYSETHITIME Set the high water mark time 4 data bytes, 4 send
2 bytes: Stream number
2 bytes: High water time in ms

GDLYGETLOTIME Get the current low water mark time 4 data bytes, 2 recv
2 bytes: Stream number (send)
2 bytes: Low water time in ms (recv)

GDLYSETLOTIME Set the low water mark time 4 data bytes, 4 send
2 bytes: Stream number
2 bytes: Low water time in ms

GDLYGETLOREPORT Get the low water report flag 4 data bytes, 2 recv
2 bytes: Stream number (send)
2 bytes: Low water report flag
1: Report when low
0: Do not report when low

GDLYFLUSHSTREAM Flush the delay stream queue 2 data bytes, send
2 bytes: Stream number

GDLYPARTIALFLUSHSTREAM Flush the delay stream queue, keeping some entries 4 data bytes, send
2 bytes: Stream number
2 bytes: Keep msgs within this time in ms

GDLYINITSTREAM set default high & low water marks 2 data bytes, send
2 bytes: Stream number

Notes:

For normal Client programs, the stream number required for the IOCTLS is identical to the Client ID number. For the USDT server, the stream number is MAXCLIENTS plus the USDT client number which is assigned by the USDT Server and used for internal purposes only. For the Scheduler, the stream number is MAXCLIENTS plus MAXUSDTCLIENTS plus the internal schedule index number. Users of the USDT Server and the scheduler do not need to be concerned with those programs' usage of the Delay Driver

The high and low water marks consist of two values each; a number and a time expressed in milliseconds. In order for a stream queue to be above either water mark, the messages in the stream queue must meet or exceed the two values. That is, there must be at least a minimum number of messages present and the total time represented by those messages must be greater than the stated minimum time.

In order for the Delay Driver to report a low water mark event, it must be armed. In order to arm the low water mark event, the number of messages present in a stream queue must exceed the high water value and the time delay of those messages must exceed the high water time. The GDLYGETLOREPORT ioctl returns the armed state of the low water mark event.

A program writing FT_DATA messages to the Delay Driver would typically send a batch of messages, wait for the low water mark event and send the next batch of messages. This process would be continued until all of the messages were sent. In order to insure arming of the low water event, the program should keep track of the number of messages sent in a batch as well as the accumulated time delay of those messages to insure that the high water mark is exceeded.

The high and low water marks are initialized to their default values once when a program is assigned a Client ID. The GDLYINITSTREAM ioctl can be used to reset the high and low water marks to their default values at any time. The current default high water mark values are 5 messages and 150 milliseconds. The current default low water mark values are 3 messages and 100 milliseconds

The time value passed in a partial flush of a stream queue applies to the delay times for the queued messages, not the time remaining before the message is to be sent. If, for example, the first message in a stream queue has a delay time of 20ms which will expire in 3ms, a partial flush to keep 10ms worth of messages in the queue would flush that message and all of the other messages in the stream.

Event name	Event meaning
GDELAYLOW	The number of messages in the stream queue has just crossed the low water mark.
GDELAYEMPTY	The stream queue is empty.

IOCTL name	Function	Data field length/purpose
GDLYGETHIVALUE	Get the current high water mark value	4 data bytes, 2 recv 2 bytes: Stream number (send) 2 bytes: High water number of msgs(recv)
GDLYSETHIVALUE	Set the high water mark value	4 data bytes, 4 send 2 bytes: Stream number 2 bytes: High water number of msgs
GDLYGETLOVALUE	Get the current low water mark value	4 data bytes, 2 recv 2 bytes: Stream number (send) 2 bytes: Low water number of msgs (recv)
GDLYSETLOVALUE	Set the low water mark value	4 data bytes, 4 send 2 bytes: Stream number 2 bytes: Low water number of msgs
GDLYGETHITIME	Get the current high water mark time	4 data bytes, 2 recv 2 bytes: Stream number (send) 2 bytes: High water time in ms(recv)
GDLYSETHITIME	Set the high water mark time	4 data bytes, 4 send 2 bytes: Stream number 2 bytes: High water time in ms
GDLYGETLOTIME	Get the current low water mark time	4 data bytes, 2 recv 2 bytes: Stream number (send) 2 bytes: Low water time in ms (recv)
GDLYSETLOTIME	Set the low water mark time	4 data bytes, 4 send 2 bytes: Stream number 2 bytes: Low water time in ms
GDLYGETLOREPORT	Get the low water report flag	4 data bytes, 2 recv 2 bytes: Stream number (send) 2 bytes: Low water report flag 1: Report when low 0: Do not report when low
GDLYFLUSHSTREAM	Flush the delay stream queue	2 data bytes, send 2 bytes: Stream number
GDLYPARTIALFLUSHSTREAM	Flush the delay stream queue, keeping some entries	4 data bytes, send 2 bytes: Stream number 2 bytes: Keep msgs within this time in ms
GDLYINITSTREAM	set default high & low water marks	2 data bytes, send 2 bytes: Stream number
Notes: For normal Client programs, the stream number required for the IOCTLS is identical to the Client ID number. For the USDT server, the stream number is MAXCLIENTS plus the USDT client number which is assigned by the USDT Server and used for internal purposes only. For the Scheduler, the stream number is MAXCLIENTS plus MAXUSDTCLIENTS plus the internal schedule index number. Users of the USDT Server and the scheduler do not need to be concerned with those programs' usage of the Delay Driver The high and low water marks consist of two values each; a number and a time expressed in milliseconds. In order for a stream queue to be above either water mark, the messages in the stream queue must meet or exceed the two values. That is, there must be at least a minimum number of messages present and the total time represented by those messages must be greater than the stated minimum time. In order for the Delay Driver to report a low water mark event, it must be armed. In order to arm the low water mark event, the number of messages present in a stream queue must exceed the high water value and the time delay of those messages must exceed the high water time. The GDLYGETLOREPORT ioctl returns the armed state of the low water mark event. A program writing FT_DATA messages to the Delay Driver would typically send a batch of messages, wait for the low water mark event and send the next batch of messages. This process would be continued until all of the messages were sent. In order to insure arming of the low water event, the program should keep track of the number of messages sent in a batch as well as the accumulated time delay of those messages to insure that the high water mark is exceeded. The high and low water marks are initialized to their default values once when a program is assigned a Client ID. The GDLYINITSTREAM ioctl can be used to reset the high and low water marks to their default values at any time. The current default high water mark values are 5 messages and 150 milliseconds. The current default low water mark values are 3 messages and 100 milliseconds The time value passed in a partial flush of a stream queue applies to the delay times for the queued messages, not the time remaining before the message is to be sent. If, for example, the first message in a stream queue has a delay time of 20ms which will expire in 3ms, a partial flush to keep 10ms worth of messages in the queue would flush that message and all of the other messages in the stream.