Sensoray 826 - Manual (Page 10)

Chapter 3: Programming
A software developers kit (SDK) for Model 826 is available for download from Sensoray's web site. The SDK includes
Linux and Windows device drivers, sample application programs, and an application programming interface (API) that is
supplied as a both a Windows dynamic link library (DLL) and a Linux static library. The API core is available in source
code form to OEMs who need to port the API to other operating systems.
This chapter provides an overview of the API and discusses functions that are used in all applications. Later chapters
discuss API functions that are specific to the board's I/O systems.
3.1 Thread Safety
API functions are thread and process safe when they are not used to access shared hardware resources. For example,
consider the case of an API function that is used to control general-purpose digital I/O (DIO) outputs where two threads or
processes can call the function simultaneously. The function is guaranteed to be thread and process safe if those threads or
processes interact with mutually exclusive DIOs. However, if the threads or processes attempt to manipulate the same DIO,
that DIO will be a shared resource and the function is not guaranteed to be thread/process safe.
3.1.1 Atomic Read-Modify-Write
To facilitate high-performance thread-safe behavior, many of the API functions include a “mode” argument that specifies
how a register write operation is to be performed. The mode argument works in conjunction with a bit-set and bit-clear
hardware function that is implemented on many of the board's interface control registers.
mode Operation
0 Write all data bits unconditionally. All register bits are programmed to explicit values.
1 Clear (program to '0') all register bits that have '1' in the corresponding data bit. All other register bits are unaffected.
2 Set (program to '1') all register bits that have '1' in the corresponding data bit. All other register bits are unaffected.
For example, if mode=2 and the data value is 0x00000003, register bits 0 and 1 will be set to '1' and all other register bits
will retain their previous values.
3.2 Event-Driven Applications
Event-driven applications can be implemented by calling the API's blocking functions: S826_CounterSnapshotRead,
S826_AdcRead, S826_DioCapRead, and S826_WatchdogEventWait. These functions can be used to block the calling
thread while it waits for hardware signal events. Blocking functions will return immediately (without blocking) if the event
occurs before the function is called.
All of the blocking functions include a “tmax” argument that specifies how long, in microseconds, to wait for events:
tmax Blocking function behavior
0 Return immediately even if event has not occurred (never blocks).
1 to 4294967294 Block until event occurs or tmax microseconds elapse, whichever comes first.
This corresponds to times ranging from 1 microsecond to approximately 71.6 minutes.
S826_WAIT_INFINITE Block until event occurs, with no time limit.
Note that non-realtime operating systems (such as Windows) may not respond to events with deterministic timing. The
responsiveness of such systems can depend on a number of factors including CPU loading, thread and process priorities,
memory capacity and architecture, core architecture and count, and clock frequency.
826 Instruction Manual 5 Programming