comp.txt
1 [[cha:hal-component-generator]] 2 3 = The HAL Component Generator 4 5 == Introduction 6 7 Writing a HAL component can be a tedious process, most of it in setup 8 calls to 'rtapi_' and 'hal_' functions and associated error checking. 9 'halcompile' will write all this code for you, automatically. 10 11 Compiling a HAL component is also much easier when using 'halcompile', 12 whether the component is part of the LinuxCNC source tree, or outside it. 13 14 For instance, when coded in C, a simple component such as "ddt" is around 80 15 lines of code. The equivalent component is very short when written using the 16 'halcompile' preprocessor: 17 18 [[code:simple-comp-example]] 19 20 .Simple Component Example 21 ---- 22 component ddt "Compute the derivative of the input function"; 23 pin in float in; 24 pin out float out; 25 variable double old; 26 function _; 27 license "GPL"; // indicates GPL v2 or later 28 ;; 29 float tmp = in; 30 out = (tmp - old) / fperiod; 31 old = tmp; 32 ---- 33 34 == Installing 35 36 To compile a component you need to install dev. 37 38 ---- 39 sudo apt install linuxcnc-dev 40 or 41 sudo apt install linuxcnc-uspace-dev 42 ---- 43 44 Another method is to use the Synaptic Package Manager to install linuxcnc-dev or 45 linuxcnc-uspace-dev. 46 47 == Using a Component 48 49 Components need to be loaded and added to a thread before it can be used. 50 51 .Example 52 ---- 53 loadrt threads name1=servo-thread period1=1000000 54 loadrt ddt 55 addf ddt.0 servo-thread 56 ---- 57 58 More information on 'loadrt' and 'addf' can be found in the 59 <<cha:basic-hal-reference,Hal Basic Referece>>. 60 61 To test your component you can follow the examples in the 62 <<cha:hal-tutorial,HAL Tutorial>>. 63 64 == Definitions 65 66 * 'component' - A component is a single real-time module, which is loaded with 67 'halcmd loadrt'. One '.comp' file specifies one component. The component 68 name and file name must match. 69 70 * 'instance' - A component can have zero or more instances. Each instance of a 71 component is created equal (they all have the same pins, parameters, 72 functions, and data) but behave independently when their pins, 73 parameters, and data have different values. 74 75 * 'singleton' - It is possible for a component to be a "singleton", in which case 76 exactly one instance is created. It seldom makes sense to write a 77 'singleton' component, unless there can literally only be a single 78 object of that 79 kind in the system (for instance, a component whose purpose is to 80 provide a pin with the current UNIX time, or a hardware driver for the 81 internal PC speaker) 82 83 == Instance creation 84 85 For a singleton, the one instance is created when the component is 86 loaded. 87 88 For a non-singleton, the 'count' module parameter determines how 89 many numbered instances are created. If 'count' is not specified, the 90 'names' module parameter determines how many named instances are created. 91 If neither 'count' nor 'names' is specified, a single numbered instance 92 is created. 93 94 == Implicit Parameters 95 96 Functions are implicitly passed the 'period' parameter which is the time in 97 nanoseconds of the last period to execute the component. Functions which use 98 floating-point can also refer to 'fperiod' which is the floating-point time in 99 seconds, or (period*1e-9). This can be useful in components that need the timing 100 information. 101 102 == Syntax 103 104 A '.comp' file consists of a number of declarations, followed by ';;' 105 on a line of its own, followed by C code implementing the module's 106 functions. 107 108 Declarations include: 109 110 * 'component HALNAME (DOC);' 111 * 'pin PINDIRECTION TYPE HALNAME ([SIZE]|[MAXSIZE: CONDSIZE]) (if CONDITION) (= STARTVALUE) (DOC) ;' 112 * 'param PARAMDIRECTION TYPE HALNAME ([SIZE]|[MAXSIZE: CONDSIZE]) (if CONDITION) (= STARTVALUE) (DOC) ;' 113 * 'function HALNAME (fp | nofp) (DOC);' 114 * 'option OPT (VALUE);' 115 * 'variable CTYPE STARREDNAME ([SIZE]);' 116 * 'description DOC;' 117 * 'notes DOC;' 118 * 'see_also DOC;' 119 * 'license LICENSE;' 120 * 'author AUTHOR;' 121 * 'include HEADERFILE;' 122 123 Parentheses indicate optional items. A vertical bar indicates 124 alternatives. Words in 'CAPITALS' indicate variable text, as follows: 125 126 * 'NAME' - A standard C identifier 127 128 * 'STARREDNAME' - A C identifier with zero or more * before it. This syntax can be used 129 to declare instance variables that are pointers. Note that because of the 130 grammar, there may not be whitespace between the * and the variable name. 131 132 * 'HALNAME' - An extended identifier. 133 When used to create a HAL identifier, any underscores are replaced 134 with dashes, and any trailing dash or period is removed, so that 135 "this_name_" will be turned into "this-name", and if the name is "_", 136 then a trailing period is removed as well, so that "function _" gives 137 a HAL function name like "component.<num>" instead of "component.<num>." 138 + 139 If present, the prefix 'hal_' is removed from the beginning of the 140 component name when creating pins, parameters and functions. 141 + 142 In the HAL identifier for a pin or parameter, # denotes an array item, 143 and must be used in conjunction with a '[SIZE]' declaration. The hash 144 marks are replaced with a 0-padded number with 145 the same length as the number of # characters. 146 + 147 When used to create a C identifier, the following changes are applied 148 to the HALNAME: 149 + 150 -- 151 . Any "#" characters, and any ".", "_" or "-" characters immediately 152 before them, are removed. 153 . Any remaining "." and "-" characters are replaced with "_". 154 . Repeated "\_" characters are changed to a single "\_" character. 155 156 A trailing "_" is retained, so that HAL identifiers which would otherwise 157 collide with reserved names or keywords (e.g., 'min') can be used. 158 159 [width="90%", options="header"] 160 |======================================== 161 |HALNAME | C Identifier | HAL Identifier 162 |x_y_z | x_y_z | x-y-z 163 |x-y.z | x_y_z | x-y.z 164 |x_y_z_ | x_y_z_ | x-y-z 165 |x.##.y | x_y(MM) | x.MM.z 166 |x.## | x(MM) | x.MM 167 |======================================== 168 -- 169 * 'if CONDITION' - An expression involving the variable 'personality' which is nonzero 170 when the pin or parameter should be created 171 172 * 'SIZE' - A number that gives the size of an array. The array items are numbered 173 from 0 to 'SIZE'-1. 174 175 * 'MAXSIZE : CONDSIZE' - A number that gives the maximum size of the array followed by an 176 expression involving the variable 'personality' and which always 177 evaluates to less than 'MAXSIZE'. When the array is created its size 178 will be 'CONDSIZE'. 179 180 * 'DOC' - A string that documents the item. String can be a C-style "double 181 quoted" string, like: 182 + 183 ---- 184 "Selects the desired edge: TRUE means falling, FALSE means rising" 185 ---- 186 + 187 or a Python-style "triple quoted" string, which 188 may include embedded newlines and quote characters, such as: 189 + 190 ---- 191 """The effect of this parameter, also known as "the orb of zot", 192 will require at least two paragraphs to explain. 193 194 Hopefully these paragraphs have allowed you to understand "zot" 195 better.""" 196 ---- 197 + 198 Or a string may be preceded by the literal character 'r', in which 199 case the string is interpreted like a Python raw-string. 200 + 201 The documentation string is in "groff -man" format. For more 202 information on this markup format, see 'groff_man(7)'. Remember that 203 'halcompile' interprets backslash escapes in strings, so for instance 204 to set the italic font for the word 'example', write: 205 + 206 ---- 207 "\\fIexample\\fB" 208 ---- 209 + 210 In this case, r-strings are particularly useful, because the backslashes 211 in an r-string need not be doubled: 212 + 213 ---- 214 r"\fIexample\fB" 215 ---- 216 217 * 'TYPE' - One of the HAL types: 'bit', 'signed', 'unsigned', or 'float'. The old 218 names 's32' and 'u32' may also be used, but 'signed' and 'unsigned' are 219 preferred. 220 221 * 'PINDIRECTION' - One of the following: 'in', 'out', or 'io'. A component sets a value 222 for an 'out' pin, it reads a value from an 'in' pin, and it may read or 223 set the value of an 'io' pin. 224 225 * 'PARAMDIRECTION' - One of the following: 'r' or 'rw'. A component sets a value for a 'r' 226 parameter, and it may read or set the value of a 'rw' parameter. 227 228 * 'STARTVALUE' - Specifies the initial value of a pin or parameter. If it is not 229 specified, then the default is '0' or 'FALSE', depending on the type of 230 the item. 231 232 * 'HEADERFILE' - The name of a header file, either in double-quotes 233 (`include "myfile.h";`) or in angle brackets (`include 234 <systemfile.h>;`). The header file will be included (using 235 C's #include) at the top of the file, before pin and parameter 236 declarations. 237 238 === HAL functions 239 240 * 'fp' - Indicates that the function performs floating-point calculations. 241 242 * 'nofp' - Indicates that it only performs integer calculations. If neither is 243 specified, 'fp' is assumed. Neither 'halcompile' nor gcc can detect the use of 244 floating-point calculations in functions that are tagged 'nofp', but use of 245 such operations results in undefined behavior. 246 247 === Options 248 249 The currently defined options are: 250 251 * 'option singleton yes' - (default: no) 252 Do not create a 'count' module parameter, and always create a single 253 instance. With 'singleton', items are named 'component-name.item-name' 254 and without 'singleton', items for numbered instances are named 255 'component-name.<num>.item-name'. 256 257 * 'option default_count number' - (default: 1) 258 Normally, the module parameter 'count' defaults to 1. If specified, 259 the 'count' will default to this value instead. 260 261 * 'option count_function yes' - (default: no) 262 Normally, the number of instances to create is specified in the 263 module parameter 'count'; if 'count_function' is specified, the value 264 returned by the function 'int get_count(void)' is used instead, 265 and the 'count' module parameter is not defined. 266 267 * 'option rtapi_app no' - (default: yes) 268 Normally, the functions `rtapi_app_main()` and `rtapi_app_exit()` are 269 automatically defined. With 'option rtapi_app no', they are not, and 270 must be provided in the C code. Use the following prototypes: 271 + 272 `int rtapi_app_main(void);` 273 + 274 `void rtapi_app_exit(void);` 275 + 276 When implementing your own `rtapi_app_main()`, call the function `int 277 export(char *prefix, long extra_arg)` to register the pins, 278 parameters, and functions for `prefix`. 279 280 * 'option data TYPE' - (default: none) *deprecated* 281 If specified, each instance of the component will have an associated 282 data block of type 'TYPE' (which can be a simple type like 'float' or the 283 name of a type created with 'typedef'). 284 In new components, 'variable' should be used instead. 285 286 * 'option extra_setup yes' - (default: no) 287 If specified, call the function defined by 'EXTRA_SETUP' for each 288 instance. If using the automatically defined 'rtapi_app_main', 289 'extra_arg' is the number of this instance. 290 291 * 'option extra_cleanup yes' - (default: no) 292 If specified, call the function defined by 'EXTRA_CLEANUP' from the 293 automatically defined 'rtapi_app_exit', or if an error is detected 294 in the automatically defined 'rtapi_app_main'. 295 296 * 'option userspace yes' - (default: no) 297 If specified, this file describes a userspace (ie, non-realtime) component, rather 298 than a regular (ie, realtime) one. A userspace component may not have functions 299 defined by the 'function' directive. Instead, after all the 300 instances are constructed, the C function `void user_mainloop(void);` 301 is called. When this function returns, the component exits. 302 Typically, 'user_mainloop()' will use 'FOR_ALL_INSTS()' to 303 perform the update action for each instance, then sleep for 304 a short time. Another common action in 'user_mainloop()' may 305 be to call the event handler loop of a GUI toolkit. 306 307 * 'option userinit yes' - (default: no) 308 This option is ignored if the option 'userspace' (see above) is set to 309 'no'. If 'userinit' is specified, the function 'userinit(argc,argv)' 310 is called before 'rtapi_app_main()' (and thus before the call to 311 'hal_init()' ). This function may process the commandline arguments or 312 take other actions. Its return type is 'void'; it may call 'exit()' 313 if it wishes to terminate rather than create a HAL component (for 314 instance, because the commandline arguments were invalid). 315 316 * 'option extra_link_args "..."' - (default: "") 317 This option is ignored if the option 'userspace' (see above) is set to 318 'no'. When linking a userspace component, the arguments given are inserted 319 in the link line. Note that because compilation takes place in a temporary 320 directory, "-L." refers to the temporary directory and not the directory where 321 the .comp source file resides. 322 323 324 If an option's VALUE is not specified, then it is equivalent to 325 specifying 'option … yes'. 326 The result of assigning an inappropriate value to an option is undefined. 327 The result of using any other option is undefined. 328 329 === License and Authorship 330 331 * 'LICENSE' - Specify the license of the module for the documentation and for the 332 MODULE_LICENSE() module declaration. For example, to specify that the 333 module's license is GPL v2 or later, 334 335 license "GPL"; // indicates GPL v2 or later 336 + 337 For additional information on the meaning of MODULE_LICENSE() and 338 additional license identifiers, see '<linux/module.h>'. or the manual page 339 'rtapi_module_param(3)' 340 + 341 This declaration is required. 342 343 * 'AUTHOR' - Specify the author of the module for the documentation. 344 345 === Per-instance data storage 346 347 * 'variable CTYPE STARREDNAME;' 348 349 * 'variable CTYPE STARREDNAME[SIZE];' 350 351 * 'variable CTYPE STARREDNAME = DEFAULT;' 352 353 * 'variable CTYPE STARREDNAME[SIZE] = DEFAULT;' 354 + 355 Declare a per-instance variable 'STARREDNAME' of type 'CTYPE', optionally as 356 an array of 'SIZE' items, and optionally with a default value 357 'DEFAULT'. Items with no 'DEFAULT' are initialized to all-bits-zero. 358 'CTYPE' is a simple one-word C type, such as 'float', 'u32', 's32', 359 int, etc. Access to array variables uses square brackets. 360 + 361 If a variable is to be of a pointer type, there may not be any space 362 between the "*" and the variable name. 363 Therefore, the following is acceptable: 364 + 365 ---- 366 variable int *example; 367 ---- 368 + 369 but the following are not: 370 + 371 ---- 372 variable int* badexample; 373 variable int * badexample; 374 ---- 375 376 === Comments 377 378 C++-style one-line comments (//... ) and 379 380 C-style multi-line comments (/* ... */) are both supported in the declaration section. 381 382 == Restrictions 383 384 Though HAL permits a pin, a parameter, and a function to have the same 385 name, 'halcompile' does not. 386 387 Variable and function names that can not be used or are likely to cause 388 problems include: 389 390 * Anything beginning with '__comp_'. 391 392 * 'comp_id' 393 394 * 'fperiod' 395 396 * 'rtapi_app_main' 397 398 * 'rtapi_app_exit' 399 400 * 'extra_setup' 401 402 * 'extra_cleanup' 403 404 405 == Convenience Macros 406 407 Based on the items in the declaration section, 'halcompile' creates a C 408 structure called `struct __comp_state`. However, instead of referring to the 409 members of this structure (e.g., `*(inst->name)`), they will generally 410 be referred to using the macros below. The 411 details of `struct __comp_state` and these macros may change from one version 412 of 'halcompile' to the next. 413 414 * 'FUNCTION(name)' - Use this macro to begin the definition of a realtime function which 415 was previously declared with 'function NAME'. The function includes a 416 parameter 'period' which is the integer number of nanoseconds 417 between calls to the 418 function. 419 420 * 'EXTRA_SETUP()' - Use this macro to begin the definition of the function called to 421 perform extra setup of this instance. Return a negative Unix 'errno' 422 value to indicate failure (e.g., 'return -EBUSY' on failure to reserve 423 an I/O port), or 0 to indicate success. 424 425 * 'EXTRA_CLEANUP()' - Use this macro to begin the definition of the function called to 426 perform extra cleanup of the component. Note that this function must 427 clean up all instances of the component, not just one. The "pin_name", 428 "parameter_name", and "data" macros may not be used here. 429 430 * 'pin_name' or 'parameter_name' - For each pin 'pin_name' or param 'parameter_name' 431 there is a macro which allows the name to be used on its own to refer 432 to the pin or parameter. 433 When 'pin_name' or 'parameter_name' is an array, the macro is of the 434 form 'pin_name(idx)' or 'param_name(idx)' where 'idx' is the index 435 into the pin array. When the array is a variable-sized 436 array, it is only legal to refer to items up to its 'condsize'. 437 + 438 When the item is a conditional item, it is only legal to refer to it 439 when its 'condition' evaluated to a nonzero value. 440 441 * 'variable_name' - For each variable 'variable_name' there is a macro which allows the 442 name to be used on its own to refer 443 to the variable. When 'variable_name' is an array, the normal C-style 444 subscript is used: 'variable_name[idx]' 445 446 * 'data' - If "option data" is specified, this macro allows access to the 447 instance data. 448 449 * 'fperiod' - The floating-point number of seconds between calls to this realtime 450 function. 451 452 * 'FOR_ALL_INSTS() {...}' - For userspace components. This macro 453 iterates over all the defined instances. Inside the 454 body of the 455 loop, the 'pin_name', 'parameter_name', and 'data' macros work as they 456 do in realtime functions. 457 458 == Components with one function 459 460 If a component has only one function and the string "FUNCTION" does 461 not appear anywhere after ';;', then the portion after ';;' is all 462 taken to be the body of the component's single function. See the 463 <<code:simple-comp-example,Simple Comp>> for and example of this. 464 465 == Component Personality 466 467 If a component has any pins or parameters with an "if condition" or 468 "[maxsize : condsize]", it is called a component with 'personality'. 469 The 'personality' of each instance is specified when the module is 470 loaded. 'Personality' can be used to create pins only when needed. 471 For instance, personality is used in the 'logic' component, to allow 472 for a variable number of input pins to each logic gate and to allow 473 for a selection of any of the basic boolean logic functions 'and', 474 'or', and 'xor'. 475 476 The default number of allowed 'personality' items is a 477 compile-time setting (64). The default applies to numerous 478 components included in the distribution that are built using 479 halcompile. 480 481 To alter the allowed number of personality items for user-built 482 components, use the '--personality' option with halcompile. For 483 example, to allow up to 128 personality times: 484 485 ---- 486 [sudo] halcompile --personality=128 --install ... 487 ---- 488 489 When using components with personality, normal usage is to 490 specify a personality item for *each* specified component 491 instance. Example for 3 instances of the logic component: 492 493 ---- 494 loadrt logic names=and4,or3,nand5, personality=0x104,0x203,0x805 495 ---- 496 497 [NOTE] 498 499 If a loadrt line specifies more instances than personalities, the 500 instances with unspecified personalities are assigned a 501 personality of 0. If the requested number of instances 502 excedes the number of allowed personalities, personalities are 503 assigned by indexing modulo the number of allowed personalities. 504 A message is printed denoting such assignments. 505 506 == Compiling 507 508 Place the '.comp' file in the source directory 509 'linuxcnc/src/hal/components' and re-run 'make'. 510 'Comp' files are automatically detected by the build system. 511 512 If a '.comp' file is a driver for hardware, it may be placed in 513 'linuxcnc/src/hal/drivers' and will be built unless LinuxCNC is 514 configured as a userspace simulator. 515 516 == Compiling realtime components outside the source tree 517 518 'halcompile' can process, compile, and install a realtime component 519 in a single step, placing 'rtexample.ko' in the LinuxCNC realtime 520 module directory: 521 522 ---- 523 [sudo] halcompile --install rtexample.comp 524 ---- 525 526 [NOTE] 527 528 sudo (for root permission) is needed when using LinuxCNC from 529 a deb package install. When using a Run-In-Place (RIP) build, 530 root privileges should not be needed. 531 532 Or, it can process and compile in one step, leaving 'example.ko' (or 533 'example.so' for the simulator) in the current directory: 534 535 ---- 536 halcompile --compile rtexample.comp 537 ---- 538 539 Or it can simply process, leaving 'example.c' in the current directory: 540 541 ---- 542 halcompile rtexample.comp 543 ---- 544 545 'halcompile' can also compile and install a component written in C, using 546 the '--install' and '--compile' options shown above: 547 548 ---- 549 [sudo] halcompile --install rtexample2.c 550 ---- 551 552 man-format documentation can also be created from the information in 553 the declaration section: 554 555 ---- 556 halcompile --document rtexample.comp 557 ---- 558 559 The resulting manpage, 'example.9' can be viewed with 560 561 ---- 562 man ./example.9 563 ---- 564 565 or copied to a standard location for manual pages. 566 567 == Compiling userspace components outside the source tree 568 569 'halcompile' can process, compile, install, and document userspace components: 570 571 ---- 572 halcompile usrexample.comp 573 halcompile --compile usrexample.comp 574 [sudo] halcompile --install usrexample.comp 575 halcompile --document usrexample.comp 576 ---- 577 578 This only works for '.comp' files, not for '.c' files. 579 580 == Examples 581 582 === constant 583 584 Note that the declaration "function _" creates functions named "constant.0" 585 , etc. The file name must match the component name. 586 587 [source,c] 588 ---- 589 component constant; 590 pin out float out; 591 param r float value = 1.0; 592 function _; 593 license "GPL"; // indicates GPL v2 or later 594 ;; 595 FUNCTION(_) { out = value; } 596 ---- 597 598 === sincos 599 600 This component computes the sine and cosine of an input angle in 601 radians. It has different capabilities than the "sine" and "cosine" 602 outputs of siggen, because the input is an angle, rather than running 603 freely based on a "frequency" parameter. 604 605 The pins are declared with the names 'sin_' and 'cos_' in the source 606 code so that they do not interfere with the functions 'sin()' and 607 'cos()'. The HAL pins are still called 'sincos.<num>.sin'. 608 609 [source,c] 610 ---- 611 component sincos; 612 pin out float sin_; 613 pin out float cos_; 614 pin in float theta; 615 function _; 616 license "GPL"; // indicates GPL v2 or later 617 ;; 618 #include <rtapi_math.h> 619 FUNCTION(_) { sin_ = sin(theta); cos_ = cos(theta); } 620 ---- 621 622 === out8 623 624 This component is a driver for a 'fictional' card called "out8", 625 which has 8 pins of digital output which are 626 treated as a single 8-bit value. There can be a varying number of such 627 cards in the system, and they can be at various addresses. The pin is 628 called 'out_' because 'out' is an identifier used in '<asm/io.h>'. It 629 illustrates the use of 'EXTRA_SETUP' and 'EXTRA_CLEANUP' to request an 630 I/O region and then free it in case of error or when 631 the module is unloaded. 632 633 [source,c] 634 ---- 635 component out8; 636 pin out unsigned out_ "Output value; only low 8 bits are used"; 637 param r unsigned ioaddr; 638 639 function _; 640 641 option count_function; 642 option extra_setup; 643 option extra_cleanup; 644 option constructable no; 645 646 license "GPL"; // indicates GPL v2 or later 647 ;; 648 #include <asm/io.h> 649 650 #define MAX 8 651 int io[MAX] = {0,}; 652 RTAPI_MP_ARRAY_INT(io, MAX, "I/O addresses of out8 boards"); 653 654 int get_count(void) { 655 int i = 0; 656 for(i=0; i<MAX && io[i]; i++) { /* Nothing */ } 657 return i; 658 } 659 660 EXTRA_SETUP() { 661 if(!rtapi_request_region(io[extra_arg], 1, "out8")) { 662 // set this I/O port to 0 so that EXTRA_CLEANUP does not release the IO 663 // ports that were never requested. 664 io[extra_arg] = 0; 665 return -EBUSY; 666 } 667 ioaddr = io[extra_arg]; 668 return 0; } 669 670 EXTRA_CLEANUP() { 671 int i; 672 for(i=0; i < MAX && io[i]; i++) { 673 rtapi_release_region(io[i], 1); 674 } 675 } 676 677 FUNCTION(_) { outb(out_, ioaddr); } 678 ---- 679 680 681 === hal_loop 682 683 [source,c] 684 ---- 685 component hal_loop; 686 pin out float example; 687 ---- 688 689 This fragment of a component illustrates the use of the 'hal_' prefix 690 in a component name. 'loop' is the name of a standard Linux kernel 691 module, so a 'loop' component might not successfully load if the Linux 692 'loop' module was also present on the system. 693 694 When loaded, 'halcmd show comp' will show a component called 695 'hal_loop'. However, the pin shown by 'halcmd show pin' will be 696 'loop.0.example', not 'hal-loop.0.example'. 697 698 === arraydemo 699 700 This realtime component illustrates use of fixed-size arrays: 701 702 [source,c] 703 ---- 704 component arraydemo "4-bit Shift register"; 705 pin in bit in; 706 pin out bit out-# [4]; 707 function _ nofp; 708 license "GPL"; // indicates GPL v2 or later 709 ;; 710 int i; 711 for(i=3; i>0; i--) out(i) = out(i-1); 712 out(0) = in; 713 ---- 714 715 === rand 716 717 This userspace component changes the value on its output pin to a new 718 random value in the range (0,1) about once every 1ms. 719 720 [source,c] 721 ---- 722 component rand; 723 option userspace; 724 725 pin out float out; 726 license "GPL"; // indicates GPL v2 or later 727 ;; 728 #include <unistd.h> 729 730 void user_mainloop(void) { 731 while(1) { 732 usleep(1000); 733 FOR_ALL_INSTS() out = drand48(); 734 } 735 } 736 ---- 737 738 === logic 739 740 This realtime component shows how to use "personality" to create 741 variable-size arrays and optional pins. 742 743 [source,c] 744 ---- 745 component logic "LinuxCNC HAL component providing experimental logic functions"; 746 pin in bit in-##[16 : personality & 0xff]; 747 pin out bit and if personality & 0x100; 748 pin out bit or if personality & 0x200; 749 pin out bit xor if personality & 0x400; 750 function _ nofp; 751 description """ 752 Experimental general 'logic function' component. Can perform 'and', 'or' 753 and 'xor' of up to 16 inputs. Determine the proper value for 'personality' 754 by adding: 755 .IP \\(bu 4 756 The number of input pins, usually from 2 to 16 757 .IP \\(bu 758 256 (0x100) if the 'and' output is desired 759 .IP \\(bu 760 512 (0x200) if the 'or' output is desired 761 .IP \\(bu 762 1024 (0x400) if the 'xor' (exclusive or) output is desired"""; 763 license "GPL"; // indicates GPL v2 or later 764 ;; 765 FUNCTION(_) { 766 int i, a=1, o=0, x=0; 767 for(i=0; i < (personality & 0xff); i++) { 768 if(in(i)) { o = 1; x = !x; } 769 else { a = 0; } 770 } 771 if(personality & 0x100) and = a; 772 if(personality & 0x200) or = o; 773 if(personality & 0x400) xor = x; 774 } 775 ---- 776 777 A typical load line for this component might be 778 779 ---- 780 loadrt logic count=3 personality=0x102,0x305,0x503 781 ---- 782 which creates the following pins: 783 784 - A 2-input AND gate: logic.0.and, logic.0.in-00, logic.0.in-01 785 - 5-input AND and OR gates: logic.1.and, logic.1.or, logic.1.in-00, 786 logic.1.in-01, logic.1.in-02, logic.1.in-03, logic.1.in-04, 787 - 3-input AND and XOR gates: logic.2.and, logic.2.xor, logic.2.in-00, 788 logic.2.in-01, logic.2.in-02 789 790 791 == Command Line Usage 792 793 The halcompile man page gives details for invoking halcompile. 794 795 ---- 796 $ man halcompile 797 ---- 798 799 A brief summary of halcompile usage is given by: 800 801 ---- 802 $ halcompile --help 803 ----