Chapter 2. Overview
- Table of Contents
- 2.1. System Overview
- 2.2. Dataflow and Synchronization
- 2.3. Driver Startup
- 2.4. Error Handling
2.1. System Overview
The Cascade Driver architecture is shown in the figure below. The device driver interfaces to the specific hardware (typically a network interface card) and offers a choice of user interfaces:
The ASCII command interface provides access to the driver's function vocabulary.
The point data interface provides access to named data points, and returning ASCII data.
The block interface provides binary access to block data.
An event-drcfiven, exception reporting interface for the Cascade DataHub.
2.1.1. Driver Interfaces
The most common and powerful interface is the ASCII command interface. By sending ASCII commands, the entire command set of the driver is available. The driver interprets the command and returns an ASCII message with the requested response data (if any). This command set is also used to configure the driver, and common configuration commands can be stored in a configuration file which is processed before the driver opens its interface to any user applications. The command interface is formatted in a syntax as follows:
(command [parameter [parameter ...]])
where command is the name of the command to be invoked, followed by the list of parameters. Parameters must be separated by white space.
While the command interface provides the maximum flexibility and ease of use, better performance can be achieved when transferring blocks of data, using the binary interface. The binary interface uses a message header that identifies the command code to be executed. Data to be transferred is packaged directly (as binary) with the message packet.
Another class of interface is designed to provide an optimal interface to the Cascade DataHub. Field points which have been configured as such will initiate an unsolicited transfer of data to the datahub when the point changes value. This capability allows the driver, in combination with the datahub, to immediately provide the underlying mechanism for event-drcfiven applications.
2.1.2. Data Model
Data from the device is modeled in two ways: as named points, and as blocks. Named points model the individual field devices, such as switches, indicators, etc, and allow the user to interact with them using only their names, completely independently of the hardware configuration. Blocks model the physical reality, in that the data from field devices is actually accessed in blocks, and is therefore generally a more 'raw' or direct representation of the data. However, to access specific field devices requires knowledge of the address, type, and format.
The philosophy adopted by the Cascade Driver is that the configuration information should originate from only one place: the device driver's configuration file. The driver makes all of this information available, so that a user's application can 'discover' the system configuration and make use of it as required.
2.1.2.1. Points
Named points allow the user to interface with the device on a named-point basis. The user does not need to be concerned with the details of how the data is read or written. The relationship between a point and its physical attributes is configured through an appropriate command (via the ASCII command interface), typically from the configuration file.
The driver models point addresses as follows:
[[card:]buffer:]word [.bit_offset[.bit_width]];[flag[,flag]]
where:
- card
Corresponds to an interface card. Each card is a bus master device on its fieldbus network. Up to 4 cards may exist, referred to as 0, 1, 2, and 3.
- buffer
The buffer ID; either a write buffer (0), or a read buffer (1) with either 512, 3.5K or 7.5K bytes each depending on whether the card is a 2K, 8K or 16K card respectively. Field points from the fieldbus slave devices map to either the read or write buffer, depending on the type of field device.
- word
Expressed as a 16-bit word offset. The offset within a buffer depends on how the field slave I/O has mapped the field points. Note that input and output points from the same physical unit within a slave do not necessarily map to the same read and write addresses.
- flags
One of the following:
- -s
Treat the value as a signed number.
- -eN
Enables 'endian' swapping. This refers to the representation of data in the computer. The default mode of the driver is 'little endian', also known as Intel format, which represents a multibyte number with the lowest-order byte first. This flag causes the number of bytes specified by the parameter N to be swapped to a 'big endian' (high byte - low byte) format, as follows:
- -m
Enables a special bit-mirror mode, where the data width specified by the -e flag is mirrored bit for bit, instead of the normal byte-based swapping.
- bit_offset
Specifies the starting bit of the data of interest, relative to the beginning (low-order bit) of the specified device:buffer:offset. The least significant bit is designated as 1 (this is equivalent to a bit offset of 0, word-aligned). Values range from 1 (the least significant bit), to 16.
- bit_width
Specifies the bit width of the data of interest. Typical values are 1 (single-bit digital data), 8 (byte data), 12 or 16 (instrumentation data), 24 or 32 (counter-based data).
When points are configured (using the analog and digital commands), the following defaults apply:
The card defaults to 0 if not specified.
The buffer defaults to 1 (the input buffer) if not specified, but will be overridden to 0 (the output buffer) if the point is specified as writeable (W or RW). This means that while it is possible to read a writeable point, it is not possible to write a readable point.
The bit_offset defaults to 0 if not specified (for example a 16-bit analog value would normally be word-aligned).
The bit_width defaults to 1 for a digital point, and 16 for an analog point.
No flags are applied if not specified (no byte or bit swapping performed; number is treated as unsigned).
 | The group command must specify an address of 0, since there is no address information associated with the group. |
All point data has a type. The user needs to know a point's type in order to pass the correct type of data variable. The following types are currently supported:
- DR_API_INT16_TYPE
Equivalent to a short, models the 16-bit word field data.
- DR_API_DOUBLE_TYPE
Represents floating-point (real-valued) numbers with the 8- byte double C type.
- DR_API_BIT_TYPE
Uses only bit 0 of whatever data format is passed to it.
| A point may have a real type (double) even though it is based on a physical field type that is fixed-point (such as a 12 or 16 bit analog I/O point) if the point is given an engineering unit conversion as part of its configuration. |
In addition to reading or writing a point, the list of available points and the configuration data for a point can be obtained at any time, if necessary, by the user through the appropriate commands.
The following provides some examples of valid point addresses:
| Access the third 16-bit word as an analog from the input buffer of card 0 (provided point is NOT defined as writeable) |
| |||||
| Access the third 16-bit word as an analog value from the output buffer of card 0 (whether or not point is defined as writeable) | 0:0:2 | |||||
| Access the upper 12 bits of the third 16-bit word as an analog value from the output buffer of card 0 | 0:0:2.4.12 | |||||
| Access the lowest order bit (a digital) in the third 16-bit word from the output buffer of card 0 |
| |||||
| Access the upper byte of the third 16-bit word (as a digital or analog value) from the output buffer of card 0. | 0:0:2.9.8 | |||||
| Treat the buffer data as 32-bit words. Access the upper byte in the second 32-bit word from the output buffer of card 0. | 0:0:2.25.8 | |||||
| Treat the buffer data as 32-bit words. Access a 24-bit signed analog value in the low order three bytes of the second 32-bit word from the output buffer of card 0. | 0:0:2.0.24;-s | |||||
| Treat the buffer data as 32-bit words, organized in Motorola format (high byte first). Access the 24-bit signed analog value in the lower 24 bits (upper 3 bytes) of the second 32-bit word from the output buffer of card 0. | 0:2.0.24;-e32,-s |
Most fieldbus protocols 'pack' the input or output data from a slave device, independently of the actual physical arrangement of the I/O. For example, an I/O rack with a selection of single, dual and quad digital input and/or output modules, will typically simply pack together the bits into separate input and output groups. Modules with both inputs and outputs are not even guaranteed that a particular I/O point will be mapped to the same bit position. In some cases analog I/O will be mapped to the beginning of the buffers, followed by digital.
The point to remember is that there is a mapping from the physical device installation to the buffer address. This mapping is dependent on the protocol and manufacturer of the equipment, and you must determine this mapping for your particular installation. Neither the CIF card nor the Cascade CIF Driver is involved in this mapping.
2.1.2.2. Blocks
Blocks allow a user to acquire or modify entire sets of input or output values with a single data transfer to the driver. The user is responsible for determining where the data of interest lies within the block.
The driver models block addresses as follows:
card : buffer
where:
- card
Corresponds to an interface card. Each card is a bus master device on its fieldbus network. Up to 4 cards may exist, referred to as 0, 1, 2, and 3.
- buffer
The buffer ID; either a write buffer (0), or a read buffer (1) with either 512, 3.5K or 7.5K bytes each depending on whether the card is a 2K, 8K or 16K card respectively. Field points from the fieldbus slave devices map to either the read or write buffer, depending on the type of field device.
Access to buffer blocks typically requires offset and size parameters, permitting sub-blocks within the buffer to be read or written. The user can inquire from the driver how many buffers are available (numbered consecutively from 0), and of what size.
When blocks of data are read from or written to the hardware device, only the 'active' portions of the buffers are transferred. The 'active' portion of a buffer always starts at zero, and grows as points are defined to form a contiguous block that includes the highest point address, up to the maximum buffer size. Note: if block transfers only are being used, a 'bogus' point must be defined at the upper required address in order to 'activate' a block of the required size.
In some cases, it is important to know what type of point data is contained within a buffer. Buffers will often contain sub-blocks of data of differing types, and the user may actually only require, for example, the analog input sub-block. Or the user may require access to all analog input sub-blocks, which may be spread over multiple buffers. These sub-blocks are termed segments. In keeping with the philosophy of the driver as the single source of configuration information, a buffer may have its segment attributes configured and queried by the user's application.
2.1.2.2.1. Segment Attributes
Segment attributes provide a mechanism for documenting and disseminating information about the type of data contained by a data buffer, as defined in the driver. Each buffer may have any number of segment attribute descriptions, where each defines the attributes of a block of data within the buffer. A buffer can have any number of such attributed segments, of any size, and possibly overlapping. A segment attribute description contains the following:
The id of the buffer to which this segment description refers.
The byte offset of the segment into the buffer.
The length of the segment (in bytes).
The type of data associated with this segment.
Whether the data can be read or written (or both).
This information must be explicitly provided to the driver through the defineSegment command (also see Configuration File and Command Specifications).
2.1.3. User Interface Model
An application programmer can interface to the driver through two basic paradigms: the API and the Direct Interface.
2.1.3.1. API
The API defines a set of functions which provide an easy-to-use interface to the driver ASCII commands and the binary block transfer mechanism.
2.1.3.2. Direct Interface
A low level interface is available for those users that want to access the data blocks with the absolute minimum of overhead. The user is responsible for managing the required data structure and performing the appropriate send/receive calls to the driver.