Sensoray 2600 - Manual (Page 25)

Sensoray 2600 Programming Guide
21
Gateway Action Scheduling
Chapter 7: Gateway Action Scheduling
7.1 Overview
This chapter details all of the functions that are used to schedule I/O actions on IOMs and the gateway. Except where noted, all of
these functions assume that a gateway transaction has been previously opened and is ready to schedule IOM actions.
7.1.1 Performance Benchmarks
Timing benchmarks are specified in all of the scheduling function descriptions. These benchmark times are nominal values that
may be used to estimate gateway transaction times. Benchmarks are conservatively rated and, as a result, applications will tend to
exhibit better performance than indicated by the benchmarks.
Each published benchmark specifies the time required for execution of a specific I/O action. The total gateway transaction time
may be estimated by summing the action execution benchmark times, and then adding overhead for protocol stack transit, packet
time on the wire, etc. Since the overhead time is influenced by elements that are not under control of the middleware, the latencies
associated with these overhead items are not specified in this document.
Important: Benchmark times are conservatively rated, but they are not worst-case values.
7.1.2 Returned IOM Status
A status byte, consisting of a set of bit flags, is returned by an IOM when it executes a scheduled IOM action. Two of the bit flags,
STATUS_RST and STATUS_CERR , are common to all IOM types. If these flags are asserted by any IOM, a transaction error of type
GWERR_IOMRESET or GWERR_IOMERROR , respectively, will be generated.
In addition to the common bit flags, some IOM types support type-specific bit flags. These special flags are described in the
“Type-Specific Errors” subsection near the beginning of each IOM reference section. If any of the type-specific bit flags are
asserted by any IOM, a transaction error of type
GWERR_IOMSPECIFIC will be generated.
7.1.3 Argument Lifetime
Most scheduling functions have arguments that specify data that is to be exchanged with a target module. Examples of this
include the value to be written to an analog output channel (outgoing data), or a pointer to a buffer that will receive analog input
data (incoming data). Each such argument has a life expectancy that depends on whether the associated data is outgoing or
incoming.
7.1.3.1 Outgoing Data
All scheduling functions copy outgoing data to private internal storage before returning. Consequently, outgoing data is no longer
needed and thus may be permitted to change value or go out of scope after the scheduling function returns. For example, this code
is legal because
states is copied by the scheduling function:
// Program solid state relay control outputs on a model 2652 IOM.
u8 states = 0x55; // Desired SSR output states.
void *x = S26_SchedOpen( 0, 1 ); // Obtain a transaction object.
S26_Sched2652_SetOutputs( x, 9, &states ); // Schedule the action.
states = 0xAA; // IT’S OK TO CHANGE THE VALUE NOW !!!
S26_SchedExecute( x, 1000, 0 ); // Execute the transaction.
7.1.3.2 Incoming Data
The scheduling functions handle incoming data by scheduling a callback for each incoming data argument. All scheduled
callbacks will execute when the associated transaction executes. Accordingly, buffers that will receive incoming data must remain
in scope until the transaction is completed. This code example illustrates a violation of this requirement:
// Fetch solid state relay inputs from a model 2652 IOM.
void ScheduleReadSSR( void *x )
{