1  [[cha:hal-twopass]]
  2  
  3  = HAL TWOPASS
  4  
  5  == TWOPASS
  6  
  7  LinuxCNC 2.5 supports TWOPASS processing of hal configuration files
  8  that can help in the modularization and readability of hal files.
  9  (Hal files are specified in an LinuxCNC ini file in the HAL stanza
 10  as [HAL]HALFILE=filename).
 11  
 12  Normally, a set of one or more hal configuration files must use
 13  a single, unique loadrt line to load a kernel module that may
 14  handle multiple instances of a component.  For example, if you
 15  use a two input AND gate component (and2) in three different
 16  places in your setup, you would need to have a single line
 17  somewhere to specify:
 18  
 19  ----
 20     loadrt and2 count=3
 21  ----
 22  
 23  resulting in components and2.0, and2.1, and2.2.
 24  
 25  Configurations are more readable if you specify with the
 26  names=option for components where it is supported, e.g.,:
 27  
 28  ----
 29  loadrt and2 names=aa,ab,ac
 30  ----
 31  
 32  resulting in components aa,ab,ac.
 33  
 34  It can be a maintenance problem to keep track of the components
 35  and their names since when you add (or remove) a component, you
 36  must find and update the single loadrt directive applicable to
 37  the component.
 38  
 39  TWOPASS processing is enabled by including an ini file parameter in
 40  the [HAL] section:
 41  
 42  ----
 43  [HAL]
 44  
 45  TWOPASS = anystring
 46  ----
 47  
 48  Where "anystring" can be any non-null string.
 49  With this setting, you can have multiple specifications like:
 50  
 51  ----
 52  loadrt and2 names=aa
 53  ...
 54  loadrt and2 names=ab,ac
 55  ...
 56  loadrt and2 names=ad
 57  ----
 58  
 59  These commands can appear in different HALFILES.  The HALFILES
 60  are processed in the order of their appearance in the ini file.
 61  
 62  The TWOPASS option can be specified with options to add output for
 63  debugging (verbose) and to prevent deletion of temporary files (nodelete).
 64  The options are separated with commas.
 65  
 66  Example:
 67  
 68  ----
 69  [HAL]
 70  
 71  TWOPASS = on,verbose,nodelete
 72  ----
 73  
 74  
 75  With TWOPASS processing, all [HAL]HALFILES are first read and
 76  multiple appearances of loadrt directives for each module are
 77  accumulated.  User components (loadusr) are loaded in order
 78  but no other hal commands are executed in the initial pass.
 79  
 80  [NOTE]
 81  
 82  User components should use the wait (-W) option to ensure
 83  the component is ready before other commands are executed.
 84  
 85  After the initial pass, the realtime modules are loaded (loadrt)
 86  automatically with a number equal to the total number when using
 87  the count= option or with all of the individual names specified
 88  when using the names= option.
 89  
 90  A second pass is then made to execute all of the other hal
 91  instructions specified in the HALFILES.  The addf commands that
 92  associate a component's functions with thread execution are
 93  executed in the order of appearance with other commands during
 94  this second pass.
 95  
 96  While you can use either the count= or names= options, they are
 97  mutually exclusive -- only one type can  be specified for a
 98  given module.
 99  
100  TWOPASS processing is most effective when using the names=
101  option.  This option allows you to provide unique names that
102  are mnemonic or otherwise relevant to the configuration.   For
103  example, if you use a derivative component to estimate the
104  velocities and accelerations on each (x,y,z) coordinate, using
105  the count= method will give arcane component names like ddt.0,
106  ddt.1, ddt.2, etc.
107  
108  Alternatively, using the names= option like:
109  
110  ----
111  loadrt ddt names=xvel,yvel,zvel
112  ...
113  loadrt ddt names=xaccel,yaccel,zaccel
114  ----
115  
116  results in components sensibly named xvel,yvel,zvel, xaccel,yaccel,zaccel.
117  
118  Many comps supplied with the distribution are created with the
119  halcompile utility and support the names= option.  These include the
120  common logic components that are the glue of many hal configurations.
121  
122  User-created comps that use the halcompile utility automatically
123  support the names= option as well.  In addition to comps generated
124  with the halcompile utility, numerous other comps support the names=option.
125  Comps that support names= option include: at_pid, encoder,
126  encoder_ratio, pid, siggen, and sim_encoder.
127  
128  == Post GUI
129  
130  Some GUIs support halfiles that are processed after the GUI is started in order
131  to connect hal pins that are created by the GUI.  When using a postgui halfile with
132  TWOPASS processing, include all loadrt items for components added by postgui halfiles
133  in a separate halfile that is processed before the GUI.  The addf commands can also
134  be included in the file.
135  Example:
136  ----
137  [HAL]
138  TWOPASS = on
139  HALFILE = file_1.hal
140  ...
141  HALFILE = file_n.hal
142  HALFILE = file_with_all_loads_for_postgui.hal
143  ...
144  POSTGUI_HALFILE = the_postgui_file.hal
145  ----
146  
147  == Exluding .hal files
148  
149  TWOPASS processing converts '.hal' files to equivalent '.tcl' files and uses
150  haltcl to find loadrt and addf commands in order to accumulate and consolidate
151  their usage.  Loadrt parameters that conform to the simple 'names=' (or
152  'count=') parameters accepted by the HAL Component Generator ('halcompile') are
153  expected.  More complex parameter items included in specialized hal components
154  may not be handled properly.
155  
156  A '.hal' file may be excluded from TWOPASS processing by including a magic
157  comment line anywhere in the '.hal' file.   The magic comment line must begin
158  with the string: '#NOTWOPASS'.  Files specified with this magic comment are
159  sourced by halcmd using the '-k' (keep going if failure) and '-v' (verbose)
160  options.
161  
162  This exclusion provision can be used to isolate problems or for loading any
163  special hal component that does not require or benefit from TWOPASS processing.
164  
165  Ordinarily, the loadrt ordering of realtime components is not critical,
166  but loadrt ordering for special components can be enforced by placing the
167  such loadrt directives in an excluded file.
168  
169  [NOTE]
170  
171  While the order of loadrt directives is not usually critical,
172  ordering of addf directives is often very important for proper
173  operation of servo loop components.
174  
175  Excluded '.hal' file example:
176  ----
177  $ cat twopass_excluded.hal
178  # The following magic comment causes this file to
179  # be excluded from twopass processing:
180  # NOTWOPASS
181  
182  # debugging component with complex options:
183  loadrt mycomponent parm1="abc def" parm2=ghi
184  show pin mycomponent
185  
186  # ordering special components
187  loadrt component_1
188  loadrt component_2
189  ----
190  
191  [NOTE]
192  
193  Case and whitespace within the magic comment are ignored.  The loading of
194  components that use names= or count= parameters (typically built by
195  halcompile) should not be used in excluded files as that would eliminate
196  the benefits of TWOPASS processing.  The hal commands that create signals
197  (net) and commands that establish execution order (addf) should not be
198  placed in excluded files.  This is especially true for addf commands since
199  their ordering may be important.
200  
201  
202  == Examples
203  
204  Examples of TWOPASS usage for a simulator are included in the directories:
205  
206     configs/sim/axis/twopass/
207  
208     configs/sim/axis/simtcl/