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
|
= General Reference
[[cha:general-reference]]
== General Naming Conventions[[sec:GR-Naming-Conventions]]
Consistent naming conventions would make HAL much easier to use. For
example, if every encoder driver provided the same set of pins and
named them the same way it would be easy to change from one type of
encoder driver to another. Unfortunately, like many open-source
projects, HAL is a combination of things that were designed, and things
that simply evolved. As a result, there are many inconsistencies. This
section attempts to address that problem by defining some conventions,
but it will probably be a while before all the modules are converted to
follow them.
Halcmd and other low-level HAL utilities treat HAL names as single
entities, with no internal structure. However, most modules do have
some implicit structure. For example, a board provides several
functional blocks, each block might have several channels, and each
channel has one or more pins. This results in a structure that
resembles a directory tree. Even though halcmd doesn't recognize the
tree structure, proper choice of naming conventions will let it group
related items together (since it sorts the names). In addition, higher
level tools can be designed to recognize such structure, if the names
provide the necessary information. To do that, all HAL components should
follow these rules:
- Dots (“.”) separate levels of the hirearchy.
This is analogous to the slash (“/”) in a filename.
- Hyphens (“-”) separate words or fields in the same level of the hirearchy.
- HAL components should not use underscores or “MixedCase”.
- Use only lowercase letters and numbers in names.
== Hardware Driver Naming Conventions [[sec:GR-Driver-Naming]]
=== Pin/Parameter names
Hardware drivers should use five fields (on three levels) to make up a
pin or parameter name, as follows:
+*<device-name>.<device-num>.<io-type>.<chan-num>.<specific-name>*+
The individual fields are:
<device-name>::
The device that the driver is intended to work with. This is most
often an interface board of some type, but there are other
possibilities.
<device-num>::
It is possible to install more than one servo board, parallel port,
or other hardware device in a computer. The device number identifies a
specific device. Device numbers start at 0 and increment.
<io-type>::
Most devices provide more than one type of I/O. Even the simple
parallel port has both digital inputs and digital outputs. More complex
boards can have digital inputs and outputs, encoder counters, pwm or
step pulse generators, analog-to-digital converters, digital-to-analog
converters, or other unique capabilities. The I/O type is used to
identify the kind of I/O that a pin or parameter is associated with.
Ideally, drivers that implement the same I/O type, even if for very
different devices, should provide a consistent set of pins and
parameters and identical behavior. For example, all digital inputs
should behave the same when seen from inside the HAL, regardless of the
device.
<chan-num>::
Virtually every I/O device has multiple channels, and the channel
number identifies one of them. Like device numbers, channel numbers
start at zero and increment.footnote:[One exception to the
“channel numbers start at zero” rule is
the parallel port. Its HAL pins are numbered with the corresponding pin
number on the DB-25 connector. This is convenient for wiring, but
inconsistent with other drivers. There is some debate over whether this
is a bug or a feature.]
If more than one device is installed, the channel numbers on
additional devices start over at zero. If it is possible to have a
channel number greater than 9, then channel numbers should be two
digits, with a leading zero on numbers less than 10 to preserve sort
ordering. Some modules have pins and/or parameters that affect more
than one channel. For example a PWM generator might have four channels
with four independent “duty-cycle” inputs, but one “frequency”
parameter that controls all four channels (due to hardware
limitations). The frequency parameter should use “0-3” as the channel
number.
<specific-name>::
An individual I/O channel might have just a single HAL pin associated
with it, but most have more than one. For example, a digital input has
two pins, one is the state of the physical pin, the other is the same
thing inverted. That allows the configurator to choose between active
high and active low inputs. For most io-types, there is a standard set
of pins and parameters, (referred to as the “canonical interface”) that
the driver should implement. The canonical interfaces are described in
the <<cha:Canonical-Device-Interfaces,Canonical Device Interfaces>>
chapter.
.Examples
motenc.0.encoder.2.position::
-- the position output of the third encoder channel on the first
Motenc board.
stg.0.din.03.in::
-- the state of the fourth digital input on the first Servo-to-Go
board.
ppmc.0.pwm.00-03.frequency::
-- the carrier frequency used for PWM channels 0 through 3 on the first Pico Systems ppmc board.
=== Function Names
Hardware drivers usually only have two kinds of HAL functions, ones
that read the hardware and update HAL pins, and ones that write to the
hardware using data from HAL pins. They should be named as follows:
+*<device-name>-<device-num>.<io-type>-<chan-num-range>.read|write*+
<device-name>::
The same as used for pins and parameters.
<device-num>::
The specific device that the function will access.
<io-type>::
Optional. A function may access all of the I/O on a board, or it may
access only a certain type. For example, there may be independent
functions for reading encoder counters and reading digital I/O. If such
independent functions exist, the <io-type> field identifies the type of
I/O they access. If a single function reads all I/O provided by the
board, <io-type> is not used.
footnote:[Note to driver programmers: do NOT implement separate
functions for different I/O types unless they are interruptible and can
work in independent threads. If interrupting an encoder read, reading
digital inputs, and then resuming the encoder read will cause problems,
then implement a single function that does everything.]
<chan-num-range>::
Optional. Used only if the <io-type> I/O is broken into groups and
accessed by different functions.
read|write::
Indicates whether the function reads the hardware or writes to it.
.Examples
motenc.0.encoder.read::
-- reads all encoders on the first motenc board.
generic8255.0.din.09-15.read::
-- reads the second 8 bit port on the first generic 8255 based
digital I/O board.
ppmc.0.write::
-- writes all outputs (step generators, pwm, DACs, and digital) on
the first Pico Systems ppmc board.
|
