summaryrefslogtreecommitdiffstats
path: root/bsp_howto/discrete.rst
blob: c5ce45025e1406a9a1631904ea625c2e90bdc610 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
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