19. Discrete Driver

The Discrete driver is responsible for providing an interface to Discrete Input/Outputs. The capabilities provided by this class of device driver are:

  • Initialize a Discrete I/O Board
  • Open a Particular Discrete Bitfield
  • Close a Particular Discrete Bitfield
  • Read from a Particular Discrete Bitfield
  • Write to a Particular Discrete Bitfield
  • Reset DACs
  • Reinitialize DACS

Most discrete I/O devices are found on I/O cards that support many bits of discrete I/O on a single card. This driver model is centered on the notion of reading bitfields from the card.

There are currently no discrete I/O device drivers included in the RTEMS source tree. The information provided in this chapter is based on drivers developed for applications using RTEMS. It is hoped that this driver model information can form the discrete I/O driver model that can be supported in future RTEMS distribution.

19.1. Major and Minor Numbers

The major number of a device driver is its index in the RTEMS Device Address Table.

A minor number is associated with each device instance managed by a particular device driver. An RTEMS minor number is an unsigned32 entity. Convention calls for dividing the bits in the minor number down into categories that specify a particular bitfield. This results in categories like the following:

  • board - indicates the board a particular bitfield is located on
  • word - indicates the particular word of discrete bits the bitfield is located within
  • start - indicates the starting bit of the bitfield
  • width - indicates the width of the bitfield

From the above, it should be clear that a single device driver can support multiple copies of the same board in a single system. The minor number is used to distinguish the devices.

By providing a way to easily access a particular bitfield from the device driver, the application is insulated with knowing how to mask fields in and out of a discrete I/O.

19.2. Discrete I/O Driver Configuration

There is not a standard discrete I/O driver configuration table but some fields are common across different drivers. The discrete I/O driver configuration table is typically an array of structures with each structure containing the information for a particular board. The following is a list of the type of information normally required to configure an discrete I/O board:

board_offset
is the base address of a board.
relay_initial_values
is an array of the values that should be written to each output word on the board during initialization. This allows the driver to start with the board’s output in a known state.

19.3. Initialize a Discrete I/O Board

At system initialization, the discrete I/O driver’s initialization entry point will be invoked. As part of initialization, the driver will perform whatever board initializatin is required and then set all outputs to their configured initial state.

The discrete I/O driver may register a device name for bitfields of particular interest to the system. Normally this will be restricted to the names of each word and, if the driver supports it, an “all words”.

19.4. Open a Particular Discrete Bitfield

This is the driver open call. Usually this call does nothing other than validate the minor number.

With some drivers, it may be necessary to allocate memory when a particular device is opened. If that is the case, then this is often the place to do this operation.

19.5. Close a Particular Discrete Bitfield

This is the driver close call. Usually this call does nothing.

With some drivers, it may be necessary to allocate memory when a particular device is opened. If that is the case, then this is the place where that memory should be deallocated.

19.6. Read from a Particular Discrete Bitfield

This corresponds to the driver read call. After validating the minor number and arguments, this call reads the indicated bitfield. A discrete I/O devices may have to store the last value written to a discrete output. If the bitfield is output only, saving the last written value gives the appearance that it can be read from also. If the bitfield is input, then it is sampled.

Note

Many discrete inputs have a tendency to bounce. The application may have to take account for bounces.

The value returned is an unsigned32 number representing the bitfield read. This value is stored in the argument_block passed in to the call.

Note

Some discrete I/O drivers have a special minor number used to access all discrete I/O bits on the board. If this special minor is used, then the area pointed to by argument_block must be the correct size.

19.7. Write to a Particular Discrete Bitfield

This corresponds to the driver write call. After validating the minor number and arguments, this call writes the indicated device. If the specified device is an ADC, then an error is usually returned.

The value written is an unsigned32 number representing the value to be written to the specified bitfield. This value is stored in the argument_block passed in to the call.

Note

Some discrete I/O drivers have a special minor number used to access all discrete I/O bits on the board. If this special minor is used, then the area pointed to by argument_block must be the correct size.

19.8. Disable Discrete Outputs

This is one of the IOCTL functions supported by the I/O control device driver entry point. When this IOCTL function is invoked, the discrete outputs are disabled.

Note

It may not be possible to disable/enable discrete output on all discrete I/O boards.

19.9. Enable Discrete Outputs

This is one of the IOCTL functions supported by the I/O control device driver entry point. When this IOCTL function is invoked, the discrete outputs are enabled.

Note

It may not be possible to disable/enable discrete output on all discrete I/O boards.

19.10. Reinitialize Outputs

This is one of the IOCTL functions supported by the I/O control device driver entry point. When this IOCTL function is invoked, the discrete outputs are rewritten with the configured initial output values.

19.11. Get Last Written Values

This is one of the IOCTL functions supported by the I/O control device driver entry point. When this IOCTL function is invoked, the following information is returned to the caller:

  • last value written to the specified output word
  • timestamp of when the last write was performed