comp.lyx

CNC 的开放码,EMC2 V2.2.8版

 The function includes a parameter '
\family typewriter 
period
\family default 
' which is the integer number of nanoseconds between calls to the function.
\layout Description

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

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.
\layout Description


\emph on 
pin_name
\layout Description


\emph on 
parameter_name
\emph default 
 For each pin 
\family typewriter 
pin_name
\family default 
 or param 
\family typewriter 
parameter_name
\family default 
 there is a macro which allows the name to be used on its own to refer to
 the pin or parameter.
\begin_deeper 
\layout Standard

When 
\family typewriter 
pin_name
\family default 
 or 
\family typewriter 
parameter_name
\family default 
 is an array, the macro is of the form 
\emph on 
pin_name(idx)
\emph default 
 or 
\emph on 
param_name(idx) 
\emph default 
where 
\emph on 
idx
\emph default 
 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 
\emph on 
condsize
\emph default 
.
\layout Standard

When the item is a conditional item, it is only legal to refer to it when
 its 
\emph on 
condition
\emph default 
 evalued to a nonzero value.
\end_deeper 
\layout Description


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

data If 'option data' is specified, this macro allows access to the instance
 data.
\layout Description

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

FOR_ALL_INSTS()\SpecialChar ~
{
\family typewriter 
\SpecialChar \ldots{}

\family default 
} For userspace components.
 This macro uses the variable 
\family typewriter 
struct state *inst
\family default 
 to iterate over all the defined instances.
 Inside the body of the loop, the 
\series bold 
\emph on 
pin_name
\series default 
\emph default 
, 
\series bold 
\emph on 
parameter_name
\series default 
\emph default 
, and 
\series bold 
data
\series default 
 macros work as they do in realtime functions.
\layout Section

Components with one function
\layout Standard

If a component has only one function and the string 
\begin_inset Quotes eld
\end_inset 

FUNCTION
\begin_inset Quotes erd
\end_inset 

 does not appear anywhere after 
\family typewriter 
;;
\family default 
, then the portion after 
\family typewriter 
;;
\family default 
 is all taken to be the body of the component's single function.
\layout Section

Component 
\begin_inset Quotes eld
\end_inset 

Personality
\begin_inset Quotes erd
\end_inset 


\layout Standard

If a component has any pins or parameters with an 
\begin_inset Quotes eld
\end_inset 

if 
\emph on 
condition
\emph default 

\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

[
\emph on 
maxsize : condsize
\emph default 
]
\begin_inset Quotes erd
\end_inset 

, it is called a component with 
\begin_inset Quotes eld
\end_inset 


\emph on 
personality
\emph default 

\begin_inset Quotes erd
\end_inset 

.
 The 
\begin_inset Quotes eld
\end_inset 

personality
\begin_inset Quotes erd
\end_inset 

 of each instance is specified when the module is loaded.
 
\begin_inset Quotes eld
\end_inset 

Personality
\begin_inset Quotes erd
\end_inset 

 can be used to create pins only when needed.
 For instance, personality is used in the 
\family typewriter 
logic
\family default 
 component, to allow for a variable number of input pins to each logic gate
 and to allow for a selection of any of the basic boolean logic functions
 
\series bold 
and
\series default 
, 
\series bold 
or
\series default 
, and 
\series bold 
xor
\series default 
.
\layout Section

Compiling 
\family typewriter 
.comp
\family default 
 files in the source tree
\layout Standard

Place the 
\family typewriter 
.comp
\family default 
 file in the source directory 
\family typewriter 
emc2/src/hal/components
\family default 
 and re-run 
\family typewriter 
make
\family default 
.
 
\family typewriter 
Comp
\family default 
 files are automatically detected by the build system.
\layout Standard

If a 
\family typewriter 
.comp
\family default 
 file is a driver for hardware, it may be placed in 
\family typewriter 
emc2/src/hal/components
\family default 
 and will be built except if emc2 is configured as a userspace simulator.
\layout Section

Compiling realtime components outside the source tree
\layout Standard


\family typewriter 
comp
\family default 
 can process, compile, and install a realtime component in a single step,
 placing 
\family typewriter 
rtexample.ko
\family default 
 in the emc2 realtime module directory:
\layout LyX-Code

comp --install rtexample.comp
\layout Standard

Or, it can process and compile in one step, leaving 
\family typewriter 
example.ko
\family default 
 (or 
\family typewriter 
example.so
\family default 
 for the simulator) in the current directory:
\layout LyX-Code

comp --compile rtexample.comp
\layout Standard

Or it can simply process, leaving 
\family typewriter 
example.c
\family default 
 in the current directory:
\layout LyX-Code

comp rtexample.comp
\layout Standard


\family typewriter 
comp
\family default 
 can also compile and install a component written in C, using the 
\family typewriter 
--install
\family default 
 and 
\family typewriter 
--compile
\family default 
 options shown above:
\layout LyX-Code

comp --install rtexample2.c
\layout Standard

man-format documentation can also be created from the information in the
 declaration section:
\layout LyX-Code

comp --document rtexample.comp
\layout Standard

The resulting manpage, 
\family typewriter 
example.9
\family default 
 can be viewed with
\layout LyX-Code

man ./example.9
\layout Standard

or copied to a standard location for manual pages.
\layout Section

Compiling userspace components outside the source tree
\layout Standard


\family typewriter 
comp
\family default 
 can process, compile, install, and document userspace components:
\layout LyX-Code

comp usrexample.comp
\newline 
comp --compile usrexample.comp
\newline 
comp --install usrexample.comp
\newline 
comp --document usrexample.comp
\layout Standard

This only works for 
\family typewriter 
.comp
\family default 
 files, not for 
\family typewriter 
.c
\family default 
 files.
\layout Section

Examples
\layout Subsection

constant
\layout Standard

This component functions like the one in 'blocks', including the default
 value of 1.0.
 The declaration 
\begin_inset Quotes eld
\end_inset 

function _
\begin_inset Quotes erd
\end_inset 

 creates functions named 'constant.0', etc.
\layout LyX-Code

component constant;
\newline 
pin out float out;
\newline 
param r float value = 1.0;
\newline 
function _;
\newline 
;;
\newline 
FUNCTION(_) { out = value; }
\layout Subsection

sincos
\layout Standard

This component computes the sine and cosine of an input angle in radians.
 It has different capabilities than the 'sine' and 'cosine' outputs of siggen,
 because the input is an angle, rather than running freely based on a 'frequency
' parameter.
\layout Standard

The pins are declared with the names 
\family typewriter 
sin_
\family default 
 and 
\family typewriter 
cos_
\family default 
 in the source code so that they do not interfere with the functions 
\family typewriter 
sin()
\family default 
 and 
\family typewriter 
cos()
\family default 
.
 The HAL pins are still called 
\family typewriter 
sincos.<num>.sin
\family default 
.
\layout LyX-Code

component sincos;
\newline 
pin out float sin_;
\newline 
pin out float cos_;
\newline 
pin in float theta;
\newline 
function _;
\newline 
;;
\newline 
#include <rtapi_math.h>
\newline 
FUNCTION(_) { sin_ = sin(theta); cos_ = cos(theta); }
\layout Subsection

out8
\layout Standard

This component is a driver for a 
\emph on 
fictional
\emph default 
 card called 
\begin_inset Quotes eld
\end_inset 

out8
\begin_inset Quotes erd
\end_inset 

, which has 8 pins of digital output which are treated as a single 8-bit
 value.
 There can be a varying number of such cards in the system, and they can
 be at various addresses.
 The pin is called 
\family typewriter 
out_
\family default 
 because 
\family typewriter 
out
\family default 
 is an identifier used in 
\family typewriter 
<asm/io.h>
\family default 
.
 It illustrates the use of 
\family typewriter 
EXTRA_SETUP
\family default 
 and 
\family typewriter 
EXTRA_CLEANUP
\family default 
 to request an I/O region and then free it in case of error or when the
 module is unloaded.
\layout LyX-Code


\begin_inset Include \verbatiminput{out8.comp}
preview false

\end_inset 


\layout Subsection

hal_loop
\layout LyX-Code

component hal_loop;
\newline 
pin out float example;
\layout Standard

This fragment of a component illustrates the use of the 
\family typewriter 
hal_
\family default 
 prefix in a component name.
 
\family typewriter 
loop
\family default 
 is the name of a standard Linux kernel module, so a 
\family typewriter 
loop
\family default 
 component might not successfully load if the Linux 
\family typewriter 
loop
\family default 
 module was also present on the system.
\layout Standard

When loaded, 
\family typewriter 
halcmd show comp
\family default 
 will show a component called 
\family typewriter 
hal_loop
\family default 
.
 However, the pin shown by 
\family typewriter 
halcmd show pin
\family default 
 will be 
\family typewriter 
loop.0.example
\family default 
, not 
\family typewriter 
hal-loop.0.example
\family default 
.
\layout Subsection

arraydemo
\layout Standard

This realtime component illustrates use of fixed-size arrays:
\layout LyX-Code

component arraydemo "4-bit Shift register";
\newline 
pin in bit in;
\newline 
pin out bit out-# [4];
\newline 
function _ nofp;
\newline 
;;
\newline 
int i; 
\newline 
for(i=3; i>0; i--) out(i) = out(i-1); 
\newline 
out(0) = in;
\layout Subsection

rand
\layout Standard

This userspace component changes the value on its output pin to a new random
 value in the range 
\begin_inset Formula $[0,1)$
\end_inset 

 about once every 1ms.
\layout LyX-Code


\begin_inset Include \verbatiminput{rand.comp}
preview false

\end_inset 


\layout Subsection

logic
\layout Standard

This realtime component shows how to use 
\begin_inset Quotes eld
\end_inset 

personality
\begin_inset Quotes erd
\end_inset 

 to create variable-size arrays and optional pins.
\layout LyX-Code


\begin_inset Include \verbatiminput{../../../src/hal/components/logic.comp}
preview false

\end_inset 


\layout Standard

A typical load line for this component might be
\layout LyX-Code

loadrt logic count=3 personality=0x102,0x305,0x503
\layout Standard

which creates the following pins:
\layout Itemize

A 2-input AND gate: logic.0.and, logic.0.in-00, logic.0.in-01
\layout Itemize

5-input AND and OR gates: logic.1.and, logic.1.or, logic.1.in-00, logic.1.in-01,
 logic.1.in-02, logic.1.in-03, logic.1.in-04, 
\layout Itemize

3-input AND and XOR gates: logic.2.and, logic.2.xor, logic.2.in-00, logic.2.in-01,
 logic.2.in-02
\the_end