tutorial.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 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\leftmargin 1in
\topmargin 1in
\rightmargin 0.8in
\bottommargin 0.8in
\secnumdepth 1
\tocdepth 5
\paragraph_separation skip
\defskip smallskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Chapter


\begin_inset LatexCommand \label{cha:HAL-Tutorial}

\end_inset 

HAL Tutorial
\layout Section


\begin_inset LatexCommand \label{sec:Tutorial - Intro}

\end_inset 

Before we start
\layout Standard

Configuration moves from theory to device -- HAL device that is.
 For those who have had just a bit of computer programming, this section
 is the 
\begin_inset Quotes eld
\end_inset 

Hello World
\begin_inset Quotes erd
\end_inset 

 of the HAL.
 As noted above halrun can be used to create a working system.
 It is a command line or text file tool for configuration and tuning.
 The following examples illustrate its setup and operation.
 
\layout Subsection

Notation
\layout Standard

Command line examples are presented in 
\family typewriter 
\series bold 
bold typewriter
\family default 
\series default 
 font.
 Responses from the computer will be in 
\family typewriter 
typewriter
\family default 
 font.
 Text inside square brackets 
\family typewriter 
[like-this]
\family default 
 is optional.
 Text inside angle brackets 
\family typewriter 
<like-this>
\family default 
 represents a field that can take on different values, and the adjacent
 paragraph will explain the appropriate values.
 Text items separated by a vertical bar means that one or the other, but
 not both, should be present.
 All command line examples assume that you are in the 
\family typewriter 
emc2/
\family default 
 directory, and paths will be shown accordingly when needed.
 
\layout Subsection

The RTAPI environment
\layout Standard

RTAPI stands for Real Time Application Programming Interface.
 Many HAL components work in realtime, and all HAL components store data
 in shared memory so realtime components can access it.
 Normal Linux does not support realtime programming or the type of shared
 memory that HAL needs.
 Fortunately there are realtime operating systems (RTOS's) that provide
 the neccessary extensions to Linux.
 Unfortunately, each RTOS does things a little differently.
\layout Standard

To address these differences, the EMC team came up with RTAPI, which provides
 a consistent way for programs to talk to the RTOS.
 If you are a programmer who wants to work on the internals of EMC, you
 may want to study 
\family typewriter 
emc2/src/rtapi/rtapi.h
\family default 
 to understand the API.
 But if you are a normal person all you need to know about RTAPI is that
 it (and the RTOS) needs to be loaded into the memory of your computer before
 you do anything with HAL.
\layout Standard

For this tutorial, we are going to assume that you have successfully compiled
 the emc2/ source tree and, if necessary, invoked the 
\family typewriter 
emc-environment
\family default 
 script to prepare your shell.
 In that case, all you need to do is load the required RTOS and RTAPI modules
 into memory.
 Just run the following command:
\layout LyX-Code

emc2$ 
\series bold 
halrun
\newline 

\series default 
halcmd:
\layout Standard

With the realtime OS and RTAPI loaded, we can move into the first example.
 Notice that the prompt has changed from the shell's 
\begin_inset Quotes eld
\end_inset 

$
\begin_inset Quotes erd
\end_inset 

 to 
\begin_inset Quotes eld
\end_inset 

halcmd
\begin_inset Quotes erd
\end_inset 

.
 This is because subsequent commands will be interpreted as HAL commands,
 not shell commands.
 
\family typewriter 
halrun
\family default 
 is a simple shell script, and it is more or less equivalent to running
\layout LyX-Code

emc2$ 
\series bold 
realtime start
\newline 

\series default 
emc2$ 
\series bold 
halcmd -kf
\layout Standard

When 
\family typewriter 
halcmd
\family default 
 exits, halrun stops the realtime system, just like
\layout LyX-Code

emc2$ 
\series bold 
realtime stop
\layout Standard

You can also supply arguments to halrun that are passed on to halcmd, or
 give the name of a .hal file.
 Because 
\family typewriter 
halrun
\family default 
 stops the realtime system when it exits, the hal file run in this way will
 typically end with a command that waits for completion, like 
\family typewriter 
loadrt -w halscope
\family default 
.
\layout Section

Tab-completion
\layout Standard

Your version of halcmd may include tab-completion.
 Instead of completing filenames as a shell does, it completes commands
 with HAL identifiers.
 Try pressing tab after starting a HAL command:
\layout LyX-Code

halcmd: 
\series bold 
lo<TAB>
\series default 

\newline 
loadrt    loadusr   lock
\newline 
halcmd: 
\series bold 
loadrt d<TAB>
\series default 

\newline 
ddt       debounce
\layout Section


\begin_inset LatexCommand \label{sec:Tutorial - Simple Example}

\end_inset 

A Simple Example
\layout Subsection

Loading a realtime component
\layout Standard

For the first example, we will use a HAL component called 
\family typewriter 
siggen
\family default 
, which is a simple signal generator.
 A complete description of the 
\family typewriter 
siggen
\family default 
 component can be found in section 
\begin_inset LatexCommand \ref{sec:Siggen}

\end_inset 

 of this document.
 It is a realtime component, implemented as a Linux kernel module.
 To load 
\family typewriter 
siggen
\family default 
 use the 
\family typewriter 
halcmd loadrt
\family default 
 command:
\layout LyX-Code

halcmd:
\series bold 
 loadrt siggen
\layout Subsection

Examining the HAL
\layout Standard

Now that the module is loaded, it is time to introduce 
\family typewriter 
halcmd
\family default 
, the command line tool used to configure the HAL.
 This tutorial will introduce some halcmd features, for a more complete
 description try 
\family typewriter 
man halcmd
\family default 
, or see the 
\family typewriter 
halcmd
\family default 
 reference in section 
\begin_inset LatexCommand \ref{sec:Halcmd}

\end_inset 

 of this document.
 The first halcmd feature is the show command.
 This command displays information about the current state of the HAL.
 To show all installed components:
\layout LyX-Code

halcmd:
\series bold 
 show comp
\series default 

\newline 
Loaded HAL Components:
\newline 
ID     Type  Name                                      PID   State
\newline 
32769  RT    siggen                                          ready 
\newline 
9775   User  halcmd9775                                 9775 initializing
\layout Standard

Since 
\family typewriter 
halcmd
\family default 
 itself is a HAL component, it will always show up in the list
\begin_inset Foot
collapsed true

\layout Standard

The number after halcmd in the component list is the process ID.
 It is possible to run more than one copy of halcmd at the same time (in
 different windows for example), so the PID is added to the end of the name
 to make it unique.
\end_inset 

.
 The list also shows the 
\family typewriter 
siggen
\family default 
 component that we installed in the previous step.
 The 
\begin_inset Quotes eld
\end_inset 

RT
\begin_inset Quotes erd
\end_inset 

 under 
\begin_inset Quotes eld
\end_inset 

Type
\begin_inset Quotes erd
\end_inset 

 indicates that 
\family typewriter 
siggen
\family default 
 is a realtime component.
\layout Standard

Next, let's see what pins 
\family typewriter 
siggen
\family default 
 makes available:
\layout LyX-Code

halcmd:
\series bold 
 show pin
\series default 

\newline 
Component Pins:
\newline 
Owner  Type  Dir    Value      Name 02    float -W   0.00000e+00  siggen.0.cosine
 
\newline 
32769  float OUT  0.00000e+00  siggen.0.sawtooth 
\newline 
32769  float OUT  0.00000e+00  siggen.0.sine 
\newline 
32769  float OUT  0.00000e+00  siggen.0.square 
\newline 
32769  float OUT  0.00000e+00  siggen.0.triangle
\layout Standard

This command displays all of the pins in the HAL - a complex system could
 have dozens or hundreds of pins.
 But right now there are only five pins.
 All five of these pins are floating point, and all five carry data out
 of the 
\family typewriter 
siggen
\family default 
 component.
 Since we have not yet executed the code contained within the component,
 all the pins have a value of zero.
\layout Standard

The next step is to look at parameters:
\layout LyX-Code

halcmd:
\series bold 
 show param
\series default 

\newline 
Parameters:
\newline 
Owner  Type  Dir    Value      Name
\newline 
 32769    float  RW   1.00000e+00  siggen.0.amplitude
\newline 
 32769    float  RW   1.00000e+00  siggen.0.frequency
\newline 
 32769    float  RW   0.00000e+00  siggen.0.offset
\newline 
 32769    s32    RO            0   siggen.0.update.time
\newline 
 32769    s32    RW            0   siggen.0.update.tmax
\layout Standard

The show param command shows all the parameters in the HAL.
 Right now each parameter has the default value it was given when the component
 was loaded.
 Note the column labeled 
\family typewriter 
Dir
\family default 
.
 The parameters labeled 
\family typewriter 
-W
\family default 
 are writeable ones that are never changed by the component itself, instead
 they are meant to be changed by the user to control the component.
 We will see how to do this later.
 Parameters labeled 
\family typewriter 
R-
\family default 
 are read only parameters.
 They can be changed only by the component.
 Finally, parameter labeled 
\family typewriter 
RW
\family default 
 are read-write parameters.
 That means that thay are changed by the component, but can also be changed
 by the user.
 Note: the parameters 
\family typewriter 
siggen.0.update.time
\family default 
 and 
\family typewriter 
siggen.0.update.tmax
\family default 
 are for debugging purposes, and won't be covered in this section.
 
\begin_inset Note
collapsed false

\layout Standard

The thread.time and thread.tmax parameters are associated with the thread
 that was created when the component was loaded.
 Once the rewrite is complete, the thread would not have been created at
 this point, so those parameters would not be present.
\layout Standard

SWP: There are no threads created yet, but there are still siggen.0.update.{time,tm
ax} parameters.
\end_inset 


\begin_inset Note
collapsed false

\layout Standard

The thread parameters are owned by component 02, the siggen module.
 This is incorrect, they should be owned by the hal_lib module, because
 the thread itself is no longer owned by siggen, and in fact, if siggen
 is removed, the parameters should stay.
\end_inset 


\begin_inset Note
collapsed false

\layout Standard

Well actually 
\begin_inset Quotes eld
\end_inset 

fixing
\begin_inset Quotes erd
\end_inset 

 the thread parameters is gonna take longer than I thought.
 So I eliminated them, at least for now.
 When the HAL rewrite is done, I'll put them back.
\end_inset 


\layout Standard

Most realtime components export one or more functions to actually run the
 realtime code they contain.
 Let's see what function(s) 
\family typewriter 
siggen
\family default 
 exported:
\layout LyX-Code

halcmd:
\series bold 
 show funct
\series default 

\newline 
Exported Functions:
\newline 
Owner CodeAddr   Arg    FP  Users  Name
\newline 
 32769   b7f74ac5 b7d0c0b4 YES    0   siggen.0.update
\layout Standard

The siggen component exported a single function.
 It requires floating point.
 It is not currently linked to any threads, so 
\begin_inset Quotes eld
\end_inset 

users
\begin_inset Quotes erd
\end_inset 

 is zero
\begin_inset Foot
collapsed true

\layout Standard

The codeaddr and arg fields were used in development, and should probably
 be removed from the halcmd listing.
\end_inset 

.
 
\layout Subsection

Making realtime code run
\layout Standard

To actually run the code contained in the function 
\family typewriter 
siggen.0.update
\family default 
, we need a realtime thread.
 The component called 
\family typewriter 
threads
\family default 
 that is used to create a new thread.
 Lets create a thread called 
\family typewriter 
test-thread
\family default 
 with a period of 1mS (1000000nS):
\layout LyX-Code

halcmd:
\series bold 
 loadrt threads name1=test-thread period1=1000000
\layout Standard

Let's see if that worked:
\layout LyX-Code

halcmd:
\series bold 
 show thread
\newline 

\series default 
Realtime Threads:
\newline 
   Period   FP   Name    (Time, Max-Time)
\newline 
     999849 YES  test-thread    ( 0, 0 )
\layout Standard

It did.
 The period is not exactly 1000000nS because of hardware limitations, but
 we have a thread that runs at approximately the correct rate, and which
 can handle floating point functions.
 The next step is to connect the function to the thread:
\layout LyX-Code

halcmd:
\series bold 
 addf siggen.0.update test-thread
\layout Standard

Up till now, we've been using 
\family typewriter 
halcmd
\family default 
 only to look at the HAL.
 However, this time we used the 
\family typewriter 
addf
\family default 
 (add function) command to actually change something in the HAL.
 We told 
\family typewriter 
halcmd
\family default 
 to add the function 
\family typewriter 
siggen.0.update
\family default 
 to the thread 
\family typewriter 
test-thread
\family default 
, and if we look at the thread list again, we see that it succeeded:
\layout LyX-Code

halcmd:
\series bold 
 show thread
\newline 

\series default 
Realtime Threads:
\newline 
   Period   FP   Name    (Time, Max-Time)
\newline 
     999849 YES  test-thread    ( 0, 0 )
\newline 
                 1 siggen.0.update
\layout Standard

There is one more step needed before the 
\family typewriter 
siggen
\family default 
 component starts generating signals.
 When the HAL is first started, the thread(s) are not actually running.
 This is to allow you to completely configure the system before the realtime
 code starts.
 Once you are happy with the configuration, you can start the realtime code
 like this:
\layout LyX-Code

halcmd:
\series bold 
 start
\layout Standard

Now the signal generator is running.
 Let's look at its output pins:
\layout LyX-Code

halcmd: show pin
\newline 
Component Pins:
\newline 
Owner  Type  Dir     Value      Name
\newline 
 32769    float OUT   2.12177e-01  siggen.0.cosine
\newline 
 32769    float OUT  -5.64055e-01  siggen.0.sawtooth
\newline 
 32769    float OUT   9.79820e-01  siggen.0.sine
\newline 
 32769    float OUT  -1.00000e+00  siggen.0.square
\newline 
 32769    float OUT   1.28110e-01  siggen.0.triangle
\newline 
halcmd: show pin
\newline 
Component Pins:
\newline