1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | Discrete Driver |
---|
4 | ############### |
---|
5 | |
---|
6 | The Discrete driver is responsible for providing an interface to Discrete |
---|
7 | Input/Outputs. The capabilities provided by this class of device driver are: |
---|
8 | |
---|
9 | - Initialize a Discrete I/O Board |
---|
10 | |
---|
11 | - Open a Particular Discrete Bitfield |
---|
12 | |
---|
13 | - Close a Particular Discrete Bitfield |
---|
14 | |
---|
15 | - Read from a Particular Discrete Bitfield |
---|
16 | |
---|
17 | - Write to a Particular Discrete Bitfield |
---|
18 | |
---|
19 | - Reset DACs |
---|
20 | |
---|
21 | - Reinitialize DACS |
---|
22 | |
---|
23 | Most discrete I/O devices are found on I/O cards that support many bits of |
---|
24 | discrete I/O on a single card. This driver model is centered on the notion of |
---|
25 | reading bitfields from the card. |
---|
26 | |
---|
27 | There are currently no discrete I/O device drivers included in the RTEMS source |
---|
28 | tree. The information provided in this chapter is based on drivers developed |
---|
29 | for applications using RTEMS. It is hoped that this driver model information |
---|
30 | can form the discrete I/O driver model that can be supported in future RTEMS |
---|
31 | distribution. |
---|
32 | |
---|
33 | Major and Minor Numbers |
---|
34 | ======================= |
---|
35 | |
---|
36 | The ``major`` number of a device driver is its index in the RTEMS Device |
---|
37 | Address Table. |
---|
38 | |
---|
39 | A ``minor`` number is associated with each device instance managed by a |
---|
40 | particular device driver. An RTEMS minor number is an ``unsigned32`` entity. |
---|
41 | Convention calls for dividing the bits in the minor number down into categories |
---|
42 | that specify a particular bitfield. This results in categories like the |
---|
43 | following: |
---|
44 | |
---|
45 | - ``board`` - indicates the board a particular bitfield is located on |
---|
46 | |
---|
47 | - ``word`` - indicates the particular word of discrete bits the bitfield is |
---|
48 | located within |
---|
49 | |
---|
50 | - ``start`` - indicates the starting bit of the bitfield |
---|
51 | |
---|
52 | - ``width`` - indicates the width of the bitfield |
---|
53 | |
---|
54 | From the above, it should be clear that a single device driver can support |
---|
55 | multiple copies of the same board in a single system. The minor number is used |
---|
56 | to distinguish the devices. |
---|
57 | |
---|
58 | By providing a way to easily access a particular bitfield from the device |
---|
59 | driver, the application is insulated with knowing how to mask fields in and out |
---|
60 | of a discrete I/O. |
---|
61 | |
---|
62 | Discrete I/O Driver Configuration |
---|
63 | ================================= |
---|
64 | |
---|
65 | There is not a standard discrete I/O driver configuration table but some fields |
---|
66 | are common across different drivers. The discrete I/O driver configuration |
---|
67 | table is typically an array of structures with each structure containing the |
---|
68 | information for a particular board. The following is a list of the type of |
---|
69 | information normally required to configure an discrete I/O board: |
---|
70 | |
---|
71 | ``board_offset`` |
---|
72 | is the base address of a board. |
---|
73 | |
---|
74 | ``relay_initial_values`` |
---|
75 | is an array of the values that should be written to each output word on the |
---|
76 | board during initialization. This allows the driver to start with the |
---|
77 | board's output in a known state. |
---|
78 | |
---|
79 | Initialize a Discrete I/O Board |
---|
80 | =============================== |
---|
81 | |
---|
82 | At system initialization, the discrete I/O driver's initialization entry point |
---|
83 | will be invoked. As part of initialization, the driver will perform whatever |
---|
84 | board initializatin is required and then set all outputs to their configured |
---|
85 | initial state. |
---|
86 | |
---|
87 | The discrete I/O driver may register a device name for bitfields of particular |
---|
88 | interest to the system. Normally this will be restricted to the names of each |
---|
89 | word and, if the driver supports it, an "all words". |
---|
90 | |
---|
91 | Open a Particular Discrete Bitfield |
---|
92 | =================================== |
---|
93 | |
---|
94 | This is the driver open call. Usually this call does nothing other than |
---|
95 | validate the minor number. |
---|
96 | |
---|
97 | With some drivers, it may be necessary to allocate memory when a particular |
---|
98 | device is opened. If that is the case, then this is often the place to do this |
---|
99 | operation. |
---|
100 | |
---|
101 | Close a Particular Discrete Bitfield |
---|
102 | ==================================== |
---|
103 | |
---|
104 | This is the driver close call. Usually this call does nothing. |
---|
105 | |
---|
106 | With some drivers, it may be necessary to allocate memory when a particular |
---|
107 | device is opened. If that is the case, then this is the place where that |
---|
108 | memory should be deallocated. |
---|
109 | |
---|
110 | Read from a Particular Discrete Bitfield |
---|
111 | ======================================== |
---|
112 | |
---|
113 | This corresponds to the driver read call. After validating the minor number |
---|
114 | and arguments, this call reads the indicated bitfield. A discrete I/O devices |
---|
115 | may have to store the last value written to a discrete output. If the bitfield |
---|
116 | is output only, saving the last written value gives the appearance that it can |
---|
117 | be read from also. If the bitfield is input, then it is sampled. |
---|
118 | |
---|
119 | .. note:: |
---|
120 | |
---|
121 | Many discrete inputs have a tendency to bounce. The application may have to |
---|
122 | take account for bounces. |
---|
123 | |
---|
124 | The value returned is an ``unsigned32`` number representing the bitfield read. |
---|
125 | This value is stored in the ``argument_block`` passed in to the call. |
---|
126 | |
---|
127 | .. note:: |
---|
128 | |
---|
129 | Some discrete I/O drivers have a special minor number used to access all |
---|
130 | discrete I/O bits on the board. If this special minor is used, then the |
---|
131 | area pointed to by ``argument_block`` must be the correct size. |
---|
132 | |
---|
133 | Write to a Particular Discrete Bitfield |
---|
134 | ======================================= |
---|
135 | |
---|
136 | This corresponds to the driver write call. After validating the minor number |
---|
137 | and arguments, this call writes the indicated device. If the specified device |
---|
138 | is an ADC, then an error is usually returned. |
---|
139 | |
---|
140 | The value written is an ``unsigned32`` number representing the value to be |
---|
141 | written to the specified bitfield. This value is stored in the |
---|
142 | ``argument_block`` passed in to the call. |
---|
143 | |
---|
144 | .. note:: |
---|
145 | |
---|
146 | Some discrete I/O drivers have a special minor number used to access all |
---|
147 | discrete I/O bits on the board. If this special minor is used, then the |
---|
148 | area pointed to by ``argument_block`` must be the correct size. |
---|
149 | |
---|
150 | Disable Discrete Outputs |
---|
151 | ======================== |
---|
152 | |
---|
153 | This is one of the IOCTL functions supported by the I/O control device driver |
---|
154 | entry point. When this IOCTL function is invoked, the discrete outputs are |
---|
155 | disabled. |
---|
156 | |
---|
157 | .. note:: |
---|
158 | |
---|
159 | It may not be possible to disable/enable discrete output on all discrete I/O |
---|
160 | boards. |
---|
161 | |
---|
162 | Enable Discrete Outputs |
---|
163 | ======================= |
---|
164 | |
---|
165 | This is one of the IOCTL functions supported by the I/O control device driver |
---|
166 | entry point. When this IOCTL function is invoked, the discrete outputs are |
---|
167 | enabled. |
---|
168 | |
---|
169 | .. note:: |
---|
170 | |
---|
171 | It may not be possible to disable/enable discrete output on all discrete |
---|
172 | I/O boards. |
---|
173 | |
---|
174 | Reinitialize Outputs |
---|
175 | ==================== |
---|
176 | |
---|
177 | This is one of the IOCTL functions supported by the I/O control device driver |
---|
178 | entry point. When this IOCTL function is invoked, the discrete outputs are |
---|
179 | rewritten with the configured initial output values. |
---|
180 | |
---|
181 | Get Last Written Values |
---|
182 | ======================= |
---|
183 | |
---|
184 | This is one of the IOCTL functions supported by the I/O control device driver |
---|
185 | entry point. When this IOCTL function is invoked, the following information is |
---|
186 | returned to the caller: |
---|
187 | |
---|
188 | - last value written to the specified output word |
---|
189 | |
---|
190 | - timestamp of when the last write was performed |
---|