1  [[cha:general-reference]]
  2  
  3  = General Reference
  4  
  5  == General Naming Conventions
  6  
  7  Consistent naming conventions would make HAL much easier to use. For
  8  example, if every encoder driver provided the same set of pins and
  9  named them the same way it would be easy to change from one type of
 10  encoder driver to another. Unfortunately, like many open-source
 11  projects, HAL is a combination of things that were designed, and things
 12  that simply evolved. As a result, there are many inconsistencies. This
 13  section attempts to address that problem by defining some conventions,
 14  but it will probably be a while before all the modules are converted to
 15  follow them.
 16  
 17  Halcmd and other low-level HAL utilities treat HAL names as single
 18  entities, with no internal structure. However, most modules do have
 19  some implicit structure. For example, a board provides several
 20  functional blocks, each block might have several channels, and each
 21  channel has one or more pins. This results in a structure that
 22  resembles a directory tree. Even though halcmd doesn't recognize the
 23  tree structure, proper choice of naming conventions will let it group
 24  related items together (since it sorts the names). In addition, higher
 25  level tools can be designed to recognize such structure, if the names
 26  provide the necessary information. To do that, all HAL components should
 27  follow these rules:
 28  
 29   - Dots (“.”) separate levels of the hirearchy. 
 30     This is analogous to the slash (“/”) in a filename. 
 31   - Hyphens (“-”) separate words or fields in the same level of the hirearchy.
 32   - HAL components should not use underscores or “MixedCase”.
 33   - Use only lowercase letters and numbers in names. 
 34  
 35  == Hardware Driver Naming Conventions
 36  
 37  === Pin/Parameter names
 38  
 39  Hardware drivers should use five fields (on three levels) to make up a
 40  pin or parameter name, as follows:
 41  
 42  +*<device-name>.<device-num>.<io-type>.<chan-num>.<specific-name>*+ 
 43  
 44  The individual fields are:
 45  
 46  <device-name>::
 47        The device that the driver is intended to work with. This is most
 48      often an interface board of some type, but there are other
 49      possibilities. 
 50  
 51  <device-num>::
 52        It is possible to install more than one servo board, parallel port,
 53      or other hardware device in a computer. The device number identifies a
 54      specific device. Device numbers start at 0 and increment.
 55  
 56  <io-type>::
 57        Most devices provide more than one type of I/O. Even the simple
 58      parallel port has both digital inputs and digital outputs. More complex
 59      boards can have digital inputs and outputs, encoder counters, pwm or
 60      step pulse generators, analog-to-digital converters, digital-to-analog
 61      converters, or other unique capabilities. The I/O type is used to
 62      identify the kind of I/O that a pin or parameter is associated with.
 63      Ideally, drivers that implement the same I/O type, even if for very
 64      different devices, should provide a consistent set of pins and
 65      parameters and identical behavior. For example, all digital inputs
 66      should behave the same when seen from inside the HAL, regardless of the
 67      device.
 68  
 69  <chan-num>::
 70        Virtually every I/O device has multiple channels, and the channel
 71      number identifies one of them. Like device numbers, channel numbers
 72      start at zero and increment.footnote:[One exception to the
 73      “channel numbers start at zero” rule is 
 74      the parallel port. Its HAL pins are numbered with the corresponding pin
 75      number on the DB-25 connector. This is convenient for wiring, but
 76      inconsistent with other drivers. There is some debate over whether this
 77      is a bug or a feature.] 
 78      If more than one device is installed, the channel numbers on
 79      additional devices start over at zero. If it is possible to have a
 80      channel number greater than 9, then channel numbers should be two
 81      digits, with a leading zero on numbers less than 10 to preserve sort
 82      ordering. Some modules have pins and/or parameters that affect more
 83      than one channel. For example a PWM generator might have four channels
 84      with four independent “duty-cycle” inputs, but one “frequency”
 85      parameter that controls all four channels (due to hardware
 86      limitations). The frequency parameter should use “0-3” as the channel
 87      number. 
 88  
 89  <specific-name>::
 90        An individual I/O channel might have just a single HAL pin associated
 91      with it, but most have more than one. For example, a digital input has
 92      two pins, one is the state of the physical pin, the other is the same
 93      thing inverted. That allows the configurator to choose between active
 94      high and active low inputs. For most io-types, there is a standard set
 95      of pins and parameters, (referred to as the “canonical interface”) that
 96      the driver should implement. The canonical interfaces are described in
 97      the <<cha:canonical-device-interfaces,Canonical Device Interfaces>>
 98      chapter.
 99  
100  .Examples
101  
102  motenc.0.encoder.2.position::
103        -- the position output of the third encoder channel on the first
104      Motenc board.
105  
106  stg.0.din.03.in::
107        -- the state of the fourth digital input on the first Servo-to-Go
108      board.
109  
110  ppmc.0.pwm.00-03.frequency::
111       -- the carrier frequency used for PWM channels 0 through 3 on the first Pico Systems ppmc board.
112  
113  === Function Names
114  
115  Hardware drivers usually only have two kinds of HAL functions, ones
116  that read the hardware and update HAL pins, and ones that write to the
117  hardware using data from HAL pins. They should be named as follows:
118  
119  +*<device-name>-<device-num>.<io-type>-<chan-num-range>.read|write*+ 
120  
121  <device-name>::
122       The same as used for pins and parameters.
123  
124  <device-num>::
125       The specific device that the function will access.
126  
127  <io-type>::
128        Optional. A function may access all of the I/O on a board, or it may
129      access only a certain type. For example, there may be independent
130      functions for reading encoder counters and reading digital I/O. If such
131      independent functions exist, the <io-type> field identifies the type of
132      I/O they access. If a single function reads all I/O provided by the
133      board, <io-type> is not used.
134      footnote:[Note to driver programmers: do NOT implement separate 
135      functions for different I/O types unless they are interruptible and can 
136      work in independent threads. If interrupting an encoder read, reading 
137      digital inputs, and then resuming the encoder read will cause problems, 
138      then implement a single function that does everything.] 
139  
140  <chan-num-range>::
141      Optional. Used only if the <io-type> I/O is broken into groups and
142      accessed by different functions.
143  
144  read|write::
145       Indicates whether the function reads the hardware or writes to it.
146  
147  .Examples
148  
149  motenc.0.encoder.read::
150       -- reads all encoders on the first motenc board.
151  
152  generic8255.0.din.09-15.read::
153        -- reads the second 8 bit port on the first generic 8255 based
154      digital I/O board.
155  
156  ppmc.0.write::
157        -- writes all outputs (step generators, pwm, DACs, and digital) on
158      the first Pico Systems ppmc board.