The HAL Component Generator

component - A component is a single real-time module, which is loaded with halcmd loadrt. One .comp file specifies one component. The component name and file name must match.

instance - A component can have zero or more instances. Each instance of a component is created equal (they all have the same pins, parameters, functions, and data) but behave independently when their pins, parameters, and data have different values.

singleton - It is possible for a component to be a "singleton", in which case exactly one instance is created. It seldom makes sense to write a singleton component, unless there can literally only be a single object of that kind in the system (for instance, a component whose purpose is to provide a pin with the current UNIX time, or a hardware driver for the internal PC speaker)

component HALNAME (DOC);

pin PINDIRECTION TYPE HALNAME ([SIZE]|[MAXSIZE: CONDSIZE]) (if CONDITION) (= STARTVALUE) (DOC) ;

param PARAMDIRECTION TYPE HALNAME ([SIZE]|[MAXSIZE: CONDSIZE]) (if CONDITION) (= STARTVALUE) (DOC) ;

function HALNAME (fp | nofp) (DOC);

option OPT (VALUE);

variable CTYPE STARREDNAME ([SIZE]);

description DOC;

notes DOC;

see_also DOC;

license LICENSE;

author AUTHOR;

include HEADERFILE;

NAME - A standard C identifier

STARREDNAME - A C identifier with zero or more * before it. This syntax can be used to declare instance variables that are pointers. Note that because of the grammar, there may not be whitespace between the * and the variable name.

HALNAME - An extended identifier. When used to create a HAL identifier, any underscores are replaced with dashes, and any trailing dash or period is removed, so that "this_name_" will be turned into "this-name", and if the name is "_", then a trailing period is removed as well, so that "function _" gives a HAL function name like "component.<num>" instead of "component.<num>."

if CONDITION - An expression involving the variable personality which is nonzero when the pin or parameter should be created

SIZE - A number that gives the size of an array. The array items are numbered from 0 to SIZE-1.

MAXSIZE : CONDSIZE - A number that gives the maximum size of the array followed by an expression involving the variable personality and which always evaluates to less than MAXSIZE. When the array is created its size will be CONDSIZE.

DOC - A string that documents the item. String can be a C-style "double quoted" string, like:

"Selects the desired edge: TRUE means falling, FALSE means rising"

"""The effect of this parameter, also known as "the orb of zot",
will require at least two paragraphs to explain.

Hopefully these paragraphs have allowed you to understand "zot"
better."""

"\\fIexample\\fB"

r"\fIexample\fB"

TYPE - One of the HAL types: bit, signed, unsigned, or float. The old names s32 and u32 may also be used, but signed and unsigned are preferred.

PINDIRECTION - One of the following: in, out, or io. A component sets a value for an out pin, it reads a value from an in pin, and it may read or set the value of an io pin.

PARAMDIRECTION - One of the following: r or rw. A component sets a value for a r parameter, and it may read or set the value of a rw parameter.

STARTVALUE - Specifies the initial value of a pin or parameter. If it is not specified, then the default is 0 or FALSE, depending on the type of the item.

HEADERFILE - The name of a header file, either in double-quotes (include "myfile.h";) or in angle brackets (include <systemfile.h>;). The header file will be included (using C’s #include) at the top of the file, before pin and parameter declarations.

Anything beginning with _comp.

comp_id

fperiod

rtapi_app_main

rtapi_app_exit

extra_setup

extra_cleanup

FUNCTION(name) - Use this macro to begin the definition of a realtime function which was previously declared with function NAME. The function includes a parameter period which is the integer number of nanoseconds between calls to the function.

EXTRA_SETUP() - Use this macro to begin the definition of the function called to perform extra setup of this instance. Return a negative Unix errno value to indicate failure (e.g., return -EBUSY on failure to reserve an I/O port), or 0 to indicate success.

EXTRA_CLEANUP() - Use this macro to begin the definition of the function called to perform extra cleanup of the component. Note that this function must clean up all instances of the component, not just one. The "pin_name", "parameter_name", and "data" macros may not be used here.

pin_name or parameter_name - For each pin pin_name or param parameter_name there is a macro which allows the name to be used on its own to refer to the pin or parameter. When pin_name or parameter_name is an array, the macro is of the form pin_name(idx) or param_name(idx) where idx is the index into the pin array. When the array is a variable-sized array, it is only legal to refer to items up to its condsize.

variable_name - For each variable variable_name there is a macro which allows the name to be used on its own to refer to the variable. When variable_name is an array, the normal C-style subscript is used: variable_name[idx]

data - If "option data" is specified, this macro allows access to the instance data.

fperiod - The floating-point number of seconds between calls to this realtime function.

FOR_ALL_INSTS() {…} - For userspace components. This macro iterates over all the defined instances. Inside the body of the loop, the pin_name, parameter_name, and data macros work as they do in realtime functions.