comp.lyx

CNC 的开放码,EMC2 V2.2.8版

#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass book
\begin_preamble
\usepackage[plainpages=false,pdfpagelabels,colorlinks=true,linkcolor=blue]{hyperref}
\end_preamble
\language english
\inputencoding default
\fontscheme bookman
\graphics default
\float_placement !htbp
\paperfontsize default
\spacing single 
\papersize letterpaper
\paperpackage a4
\use_geometry 1
\use_amsmath 1
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\leftmargin 1in
\topmargin 1in
\rightmargin 0.8in
\bottommargin 0.8in
\secnumdepth 3
\tocdepth 5
\paragraph_separation skip
\defskip smallskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Chapter


\emph on 
comp
\emph default 
: a tool for creating HAL modules
\layout Section

Introduction
\layout Standard

Writing a HAL component can be a tedious process, most of it in setup calls
 to 
\family typewriter 
rtapi_
\family default 
 and 
\family typewriter 
hal_
\family default 
 functions and associated error checking.
 
\emph on 
comp
\emph default 
 will write all this code for you, automatically.
\layout Standard

Compiling a HAL component is also much easier when using 
\emph on 
comp
\emph default 
, whether the component is part of the emc2 source tree, or outside it.
\layout Standard

For instance, the 
\begin_inset Quotes eld
\end_inset 

ddt
\begin_inset Quotes erd
\end_inset 

 portion of 
\family typewriter 
blocks
\family default 
 is around 80 lines of code.
 The equivalent component is very short when written using the 
\emph on 
comp
\emph default 
 preprocessor:
\layout LyX-Code

component ddt "Compute the derivative of the input function";
\newline 
pin in float in;
\newline 
pin out float out;
\newline 
variable float old;
\newline 
function _;
\newline 
license "GPL";
\newline 
;;
\newline 
float tmp = in;
\newline 
out = (tmp - old) / fperiod;
\newline 
old = tmp;
\layout Standard

and it can be compiled and installed very easily: by simply placing 
\family typewriter 
ddt.comp
\family default 
 in 
\family typewriter 
src/hal/components
\family default 
 and running '
\family typewriter 
make
\family default 
', or by placing it anywhere on the system and running 
\family typewriter 
comp --install ddt.comp
\layout Section

Definitions
\layout Description

component A component is a single real-time module, which is loaded with
 
\family typewriter 
halcmd loadrt
\family default 
.
 One 
\family typewriter 
.comp
\family default 
 file specifies one component.
\layout Description

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

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 
\family typewriter 
singleton
\family default 
 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)
\layout Section

Instance creation
\layout Standard

For a singleton, the one instance is created when the component is loaded.
\layout Standard

For a non-singleton, the '
\family typewriter 
count
\family default 
' module parameter determines how many numbered instances are created.
\layout Section

Syntax
\layout Standard

A 
\family typewriter 
.comp
\family default 
 file consists of a number of declarations, followed by 
\family typewriter 
;;
\family default 
 on a line of its own, followed by C code implementing the module's functions.
\layout Standard

Declarations include:
\layout Itemize


\family typewriter 
component 
\emph on 
HALNAME
\emph default 
 
\emph on 
(DOC
\emph default 
);
\layout Itemize


\family typewriter 
pin 
\emph on 
PINDIRECTION
\emph default 
 
\emph on 
TYPE
\emph default 
 
\emph on 
HALNAME
\emph default 
 ([
\emph on 
SIZE
\emph default 
]|[
\emph on 
MAXSIZE 
\emph default 
: 
\emph on 
CONDSIZE]
\emph default 
) (if 
\emph on 
CONDITION
\emph default 
) (= 
\emph on 
STARTVALUE
\emph default 
) (
\emph on 
DOC
\emph default 
);
\layout Itemize


\family typewriter 
param 
\emph on 
PARAMDIRECTION
\emph default 
 
\emph on 
TYPE
\emph default 
 
\emph on 
HALNAME
\emph default 
 ([
\emph on 
SIZE
\emph default 
]|[
\emph on 
MAXSIZE 
\emph default 
: 
\emph on 
CONDSIZE]
\emph default 
) (if 
\emph on 
CONDITION) 
\emph default 
(= 
\emph on 
STARTVALUE
\emph default 
) (
\emph on 
DOC
\emph default 
) ;
\layout Itemize


\family typewriter 
function 
\emph on 
HALNAME
\emph default 
 (fp | nofp) (
\emph on 
DOC
\emph default 
);
\layout Itemize


\family typewriter 
option 
\emph on 
OPT
\emph default 
 (
\emph on 
VALUE
\emph default 
);
\layout Itemize


\family typewriter 
variable 
\emph on 
CTYPE NAME 
\emph default 
([
\emph on 
SIZE
\emph default 
]);
\layout Itemize


\family typewriter 
description DOC;
\layout Itemize


\family typewriter 
see_also DOC;
\layout Itemize


\family typewriter 
license LICENSE;
\layout Standard

Parentheses indicate optional items.
 A vertical bar indicates alternatives.
 Words in 
\emph on 
CAPITALS
\emph default 
 indicate variable text, as follows:
\layout Description

HALNAME An identifier.
\begin_deeper 
\layout Standard

When used to create a HAL identifier, any underscores are replaced with
 dashes, and any trailing dash or period is removed, so that 
\begin_inset Quotes eld
\end_inset 

this_name_
\begin_inset Quotes erd
\end_inset 

 will be turned into 
\begin_inset Quotes eld
\end_inset 

this-name
\begin_inset Quotes erd
\end_inset 

, and if the name is 
\begin_inset Quotes eld
\end_inset 


\family typewriter 
_
\family default 

\begin_inset Quotes erd
\end_inset 

, then a trailing period is removed as well, so that 
\begin_inset Quotes eld
\end_inset 


\family typewriter 
function _
\family default 

\begin_inset Quotes erd
\end_inset 

 gives a HAL function name like 
\family typewriter 
component.<num>
\family default 
 instead of 
\family typewriter 
component.<num>.
\layout Standard

If present, the prefix 
\family typewriter 
hal_
\family default 
 is removed from the beginning of the component name when creating pins,
 parameters and functions.
\layout Standard

In the HAL identifier for a pin or parameter, # denotes an array item, and
 must be used in conjunction with a 
\family typewriter 
[SIZE]
\family default 
 declaration.
 The hash marks are replaced with a 0-padded number with the same length
 as the number of # characters.
\layout Standard

When used to create a C identifier, the following changes are applied to
 the HALNAME:
\layout Enumerate

Any # characters, and any 
\begin_inset Quotes eld
\end_inset 

.
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

_
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

-
\begin_inset Quotes erd
\end_inset 

 characters immediately before them, are removed.
\layout Enumerate

Any remaining 
\begin_inset Quotes eld
\end_inset 

.
\begin_inset Quotes erd
\end_inset 

 and 
\begin_inset Quotes eld
\end_inset 

-
\begin_inset Quotes erd
\end_inset 

 characters are replaced with 
\begin_inset Quotes eld
\end_inset 

_
\begin_inset Quotes erd
\end_inset 


\layout Enumerate

Repeated 
\begin_inset Quotes eld
\end_inset 

_
\begin_inset Quotes erd
\end_inset 

 characters are changed to a single 
\begin_inset Quotes eld
\end_inset 

_
\begin_inset Quotes erd
\end_inset 

 character.
\layout Standard

A trailing _ is retained, so that HAL identifiers which would otherwise
 collide with reserved names or keywords (e.g., 'min') can be used.
\layout Standard


\begin_inset  Tabular
<lyxtabular version="3" rows="6" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="top" leftline="true" width="0">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

HALNAME
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

C Identifier
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

HAL Identifier
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

x_y_z
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

x_y_z
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

x-y-z
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

x-y.z
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

x_y_z
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

x-y.z
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

x_y_z_
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

x_y_z_
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

x-y-z
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

x.##.y
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

x_y(MM)
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

x.MM.z
\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

x.##
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

x(MM)
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

x.MM
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\end_deeper 
\layout Description

if\SpecialChar ~