mirror of
https://git.rtems.org/rtems-docs/
synced 2025-06-03 10:19:23 +08:00
188 lines
6.6 KiB
ReStructuredText
188 lines
6.6 KiB
ReStructuredText
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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".
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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
|
||
|