The EMC Team

{0.75in}This manual is a work in progress. If you are able to help with writing, editing, or graphic preparation please contact any member of the writing team or join and send an email to emc-users@lists.sourceforge.net.

{0.5in}

{0.5in}{normalsize}{-1\\parskip}Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and one Back-Cover Text: This EMC Handbook is the product of several authors writing for linuxCNC.org. As you find it to be of value in your work, we invite you to contribute to its revision and growth.A copy of the license is included in the section entitled GNU Free Documentation License. If you do not find the license you may order a copy from Free Software Foundation, Inc. 59 Temple Place, Suite 330 Boston, MA 02111-1307

This manual is for the person who wants to know more about HAL than is needed to just set up an EMC configuration file. HAL can run without EMC so this manual focuses on the stand alone HAL. For information on EMC related HAL see the Integrators manual.

level, it is simply a way to allow a number of "building blocks" to be loaded and interconnected to assemble a complex system. The "Hardware" part is because HAL was originally designed to make it easier to configure EMC for a wide variety of hardware devices. Many of the building blocks are drivers for hardware devices. However, HAL can do more than just configure hardware drivers.

HAL is based on the same principles that are used to design hardware circuits and systems, so it is useful to examine those principles first.

interconnected components. For the CNC machine, those components might be the main controller, servo amps or stepper drives, motors, encoders, limit switches, pushbutton pendants, perhaps a VFD for the spindle drive, a PLC to run a toolchanger, etc. The machine builder must select, mount and wire these pieces together to make a complete system.

The machine builder does not need to worry about how each individual part works. He treats them as black boxes. During the design stage, he decides which parts he is going to use - steppers or servos, which brand of servo amp, what kind of limit switches and how many, etc. The integrator’s decisions about which specific components to use is based on what that component does and the specifications supplied by the manufacturer of the device. The size of a motor and the load it must drive will affect the choice of amplifier needed to run it. The choice of amplifier may affect the kinds of feedback needed by the amp and the velocity or position signals that must be sent to the amp from a control.

In the HAL world, the integrator must decide what HAL components are needed. Usually every interface card will require a driver. Additional components may be needed for software generation of step pulses, PLC functionality, and a wide variety of other tasks.

The designer of a hardware system not only selects the parts, he also decides how those parts will be interconnected. Each black box has terminals, perhaps only two for a simple switch, or dozens for a servo drive or PLC. They need to be wired together. The motors connect to the servo amps, the limit switches connect to the controller, and so on. As the machine builder works on the design, he creates a large wiring diagram that shows how all the parts should be interconnected.

When using HAL, components are interconnected by signals. The designer must decide which signals are needed, and what they should connect.

Once the wiring diagram is complete it is time to build the machine. The pieces need to be acquired and mounted, and then they are interconnected according to the wiring diagram. In a physical system, each interconnection is a piece of wire that needs to be cut and connected to the appropriate terminals.

HAL provides a number of tools to help "build" a HAL system. Some of the tools allow you to "connect" (or disconnect) a single "wire". Other tools allow you to save a complete list of all the parts, wires, and other information about the system, so that it can be "rebuilt" with a single command.

Very few machines work right the first time. While testing, the builder may use a meter to see whether a limit switch is working or to measure the DC voltage going to a servo motor. He may hook up an oscilloscope to check the tuning of a drive, or to look for electrical noise. He may find a problem that requires the wiring diagram to be changed; perhaps a part needs to be connected differently or replaced with something completely different.

HAL provides the software equivalents of a voltmeter, oscilloscope, signal generator, and other tools needed for testing and tuning a system. The same commands used to build the system can be used to make changes as needed.

This document is aimed at people who already know how to do this kind of hardware system integration, but who do not know how to connect the hardware to EMC.

The traditional hardware design as described above ends at the edge of the main control. Outside the control are a bunch of relatively simple boxes, connected together to do whatever is needed. Inside, the control is a big mystery - one huge black box that we hope works.

HAL extends this traditional hardware design method to the inside of the big black box. It makes device drivers and even some internal parts of the controller into smaller black boxes that can be interconnected and even replaced just like the external hardware. It allows the "system wiring diagram"to show part of the internal controller, rather than just a big black box. And most importantly it allows the integrator to test and modify the controller using the same methods he would use on the rest of the hardware.

Terms like motors, amps, and encoders are familiar to most machine integrators. When we talk about using extra flexible eight conductor shielded cable to connect an encoder to the servo input board in the computer, the reader immediately understands what it is and is led to the question, "what kinds of connectors will I need to make up each end." The same sort of thinking is essential for the HAL but the specific train of thought may take a bit to get on track. Using HAL words may seem a bit strange at first, but the concept of working from one connection to the next is the same.

This idea of extending the wiring diagram to the inside of the controller is what HAL is all about. If you are comfortable with the idea of interconnecting hardware black boxes, you will probably have little trouble using HAL to interconnect software black boxes.

This section is a glossary that defines key HAL terms but it is a bit different than a traditional glossary because these terms are not arranged in alphabetical order. They are arranged by their relationship or flow in the HAL way of things.

As an example, suppose we have a parport component named hal\_parport. That component defines one or more HAL pins for each physical pin. The pins are described in that component’s doc section: their names, how each pin relates to the physical pin, are they inverted, can you change polarity, etc. But that alone doesn’t get the data from the HAL pins to the physical pins. It takes code to do that, and that is where functions come into the picture. The parport component needs at least two functions: one to read the physical input pins and update the HAL pins, the other to take data from the HAL pins and write it to the physical output pins. Both of these functions are part of the parport driver.

Each HAL component is a piece of software with well-defined inputs, outputs, and behavior, that can be installed and interconnected as needed. This section lists some of the available components and a brief description of what each does. Complete details for each component are available later in this document.

Each of these building blocks is described in detail in later chapters.

A first introduction to HAL concepts can be mind boggling. Building anything with blocks can be a challenge but some of the toys that we played with as kids can be an aid to building things with the HAL.

The notion of stacking cards to see how tall you can make a tower is a very old and honored way of spending spare time. At first read, the integrator may have gotten the impression that building a HAL was a bit like that. It can be but with proper planning an integrator can build a stable system as complex as the machine at hand requires.

{Erector Sets% \\footnote{The Erector Set was an invention of AC Gilbert% }}What was great about the sets was the building blocks, metal struts and angles and plates, all with regularly spaced holes. You could design things and hold them together with the little screws and nuts.

Hal components are not all the same size and shape but they allow for grouping into larger units that will do useful work.In this sense they are like the parts of an Erector set. Some components are long and thin. They essentially connect high level commands to specific physical pins. Other components are more like the rectangular platforms upon which whole machines could be built. An integrator will quickly get beyond the brief examples and begin to bolt together components in ways that are unique to them.

{Tinkertoys% \\footnote{Tinkertoy is now a registered trademark of the Hasbro company.% }}

The idea of one pin or component being the hub for many connections is also an easy concept within the HAL. Examples two and four (see section [cha:HAL-Tutorial]) connect the meter and scope to signals that are intended to go elsewhere. Less easy is the notion of a hub for several incoming signals but that is also possible with proper use of functions within that hub component that handle those signals as they arrive from other components.

Another thought that comes forward from this toy is a mechanical representation of HAL threads. A thread might look a bit like a centipede, caterpillar, or earwig. A backbone of hubs, HAL components, strung together with rods, HAL signals. Each component takes in it own parameters and input pins and passes on output pins and parameters to the next component. Signals travel along the backbone from end to end and are added to or modified by each component in turn.

Threads are all about timing and doing a set of tasks from end to end. A mechanical representation is available with Tinkertoys also when we think of the length of the toy as a measure of the time taken to get from one end to the other. A very different thread or backbone is created by connecting the same set of hubs with different length rods. The total length of the backbone can be changed by the length of rods used to connect the hubs. The order of operations is the same but the time to get from beginning to end is very different.

\\footnote{The Lego name is a trademark of the Lego company. % }}When Lego blocks first arrived in our stores they were pretty much all the same size and shape. Sure there were half sized one and a few quarter sized as well but that rectangular one did most of the work. Lego blocks interconnected by snapping the holes in the underside of one onto the pins that stuck up on another. By overlapping layers, the joints between could be made very strong, even around corners or tees.

Unlike the physical wiring models between black boxes that we have said that HAL is based upon, simply connecting two pins with a hal-signal falls far short of the action of the physical case.

True relay logic consists of relays connected together, and when a contact opens or closes, current flows (or stops) immediately. Other coils may change state, etc, and it all just happens. But in PLC style ladder logic, it doesn’t work that way. Usually in a single pass through the ladder, each rung is evaluated in the order in which it appears, and only once per pass. A perfect example is a single rung ladder, with a NC contact in series with a coil. The contact and coil belong to the same relay.

If this were a conventional relay, as soon as the coil is energized, the contacts begin to open and de-energize it. That means the contacts close again, etc, etc. The relay becomes a buzzer.

With a PLC, if the coil is OFF and the contact is closed when the PLC begins to evaluate the rung, then when it finishes that pass, the coil is ON. The fact that turning on the coil opens the contact feeding it is ignored until the next pass. On the next pass, the PLC sees that the contact is open, and de-energizes the coil. So the relay still switches rapidly between on and off, but at a rate determined by how often the PLC evaluates the rung.

In HAL, the function is the code that evaluates the rung(s). In fact, the HAL-aware realtime version of ClassicLadder exports a function to do exactly that. Meanwhile, a thread is the thing that runs the function at specific time intervals. Just like you can choose to have a PLC evaluate all its rungs every 10mS, or every second, you can define HAL threads with different periods.

What distinguishes one thread from another is not what the thread does - that is determined by which functions are connected to it. The real distinction is simply how often a thread runs.

In EMC you might have a 50:math:`$\mu$`s thread and a 1ms thread. These would be created based on BASE\_PERIOD and SERVO\_PERIOD-the actual times depend on the ini.

The next step is to decide what each thread needs to do. Some of those decisions are the same in (nearly) any EMC system-For instance, motion-command-handler is always added to servo-thread.

Other connections would be made by the integrator. These might include hooking the STG driver’s encoder read and DAC write functions to the servo thread, or hooking stepgen’s function to the base-thread, along with the parport function(s) to write the steps to the port.

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 Hello Worldof the HAL. 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.

Command line examples are presented in {textbf{bold typewriter}}font. Responses from the computer will be in `typewriter` font. Text inside square brackets {{[}like-this{]}}is optional. Text inside angle brackets `<like-this>` 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 `emc2/` directory, and paths will be shown accordingly when needed.

Your version of halcmd may include tab-completion. Instead of completing file names as a shell does, it completes commands with HAL identifiers. You will have to type enough letters for a unique match. Try pressing tab after starting a HAL command:

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 necessary extensions to Linux. Unfortunately, each RTOS does things a little differently.

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 `emc2/src/rtapi/rtapi.h` 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.

For this tutorial, we are going to assume that you have successfully installed the Live CD or compiled the emc2/ source tree and, if necessary, invoked the `emc-environment` 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 from a terminal window:

With the realtime OS and RTAPI loaded, we can move into the first example. Notice that the prompt has changed from the shell’s $to halcmd:. This is because subsequent commands will be interpreted as HAL commands, not shell commands.

For the first example, we will use a HAL component called `siggen, which is a simple signal generator. A complete description of the ``siggen` component can be found in Siggen section of the Integrators Manual. It is a realtime component, implemented as a Linux kernel module. To load `siggen` use the `halcmd loadrt` command:

Now that the module is loaded, it is time to introduce `halcmd, the command line tool used to configure the HAL. This tutorial will introduce some halcmd features, for a more complete description try ``man halcmd, or see the ``halcmd` reference in section [sec:Halscope] 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:

Since `halcmd` itself is a HAL component, it will always show up in the list. 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. The list also shows the `siggen` component that we installed in the previous step. The RTunder Typeindicates that `siggen` is a realtime component.

Next, let’s see what pins `siggen` makes available:

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 eight pins. All eight of these pins are floating point, and carry data out of the `siggen` component. Since we have not yet executed the code contained within the component, some the pins have a value of zero.

The next step is to look at parameters:

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 `Dir. The parameters labeled `-W`` are writable 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 `R-` are read only parameters. They can be changed only by the component. Finally, parameter labeled `RW` are read-write parameters. That means that they are changed by the component, but can also be changed by the user. Note: the parameters `siggen.0.update.time` and `siggen.0.update.tmax` are for debugging purposes, and won’t be covered in this section.

Most realtime components export one or more functions to actually run the realtime code they contain. Let’s see what function(s) `siggen` exported:

The siggen component exported a single function. It requires floating point. It is not currently linked to any threads, so usersis zero

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

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

Let’s see if that worked:

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:

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

There is one more step needed before the `siggen` 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:

Now the signal generator is running. Let’s look at its output pins:

We did two `show pin` commands in quick succession, and you can see that the outputs are no longer zero. The sine, cosine, sawtooth, and triangle outputs are changing constantly. The square output is also working, however it simply switches from +1.0 to -1.0 every cycle.

The real power of HAL is that you can change things. For example, we can use the {textquotedblsetp\\textquotedbl}command to set the value of a parameter. Let’s change the amplitude of the signal generator from 1.0 to 5.0:

Check the parameters and pins again:

Note that the value of parameter `siggen.0.amplitude` has changed to 5, and that the pins now have larger values.

Most of what we have done with `halcmd` so far has simply been viewing things with the `show` command. However two of the commands actually changed things. As we design more complex systems with HAL, we will use many commands to configure things just the way we want them. HAL has the memory of an elephant, and will retain that configuration until we shut it down. But what about next time? We don’t want to manually enter a bunch of commands every time we want to use the system. We can save the configuration of the entire HAL with a single command:

The output of the `save` command is a sequence of HAL commands. If you start with an emptyHAL and run all these commands, you will get the configuration that existed when the `save` command was issued. To save these commands for later use, we simply redirect the output to a file:

When your finished with your HAL session type exitat the halcmd: prompt. Do not simply close the terminal window without shutting down the HAL session.

To restore the HAL configuration stored in `saved.hal, we need to execute all of those HAL commands. To do that, we use {-f <file name>}which reads commands from a file, and `-I`` (upper case i) which shows the halcmd prompt after executing the commands:

Notice that there is not a start command in saved.hal. It’s necessary to issue it again (or edit saved.hal to add it there):

If an unexpected shut down of a HAL session occurs you might have to unload HAL before another session can begin. To do this type the following command in a terminal window:

You can build very complex HAL systems without ever using a graphical interface. However there is something satisfying about seeing the result of your work. The first and simplest GUI tool for the HAL is halmeter. It is a very simple program that is the HAL equivalent of the handy Fluke multimeter (or Simpson analog meter for the old timers).

We will use the siggen component again to check out halmeter. If you just finished the previous example, then you can load siggen using the saved file. If not, we can load it just like we did before:

At this point we have the siggen component loaded and running. It’s time to start halmeter. Since halmeter is a GUI app, X must be running.

The first window you will see is the Select Item to Probewindow.

HAL Meter Select Window

This dialog has three tabs. The first tab displays all of the HAL pins in the system. The second one displays all the signals, and the third displays all the parameters. We would like to look at the pin `siggen.0.cosine` first, so click on it then click the Close button. The probe selection dialog will close, and the meter looks something like the following figure.

Halmeter

To change what the meter displays press the Selectbutton which brings back the Select Item to Probewindow.

You should see the value changing as siggen generates its cosine wave. Halmeter refreshes its display about 5 times per second.

To shut down halmeter, just click the exit button.

If you want to look at more than one pin, signal, or parameter at a time, you can just start more halmeters. The halmeter window was intentionally made very small so you could have a lot of them on the screen at once.

Up till now we have only loaded one HAL component. But the whole idea behind the HAL is to allow you to load and connect a number of simple components to make up a complex system. The next example will use two components.

Before we can begin building this new example, we want to start with a clean slate. If you just finished one of the previous examples, we need to remove the all components and reload the RTAPI and HAL libraries:

Now we are going to load the step pulse generator component. For a detailed description of this component refer to Stepgen section of the Integrators Manual. For now, we can skip the details, and just run the following commands:

[The "\\" at the end of a long line indicates line wrapping (needed for formatting this document). When entering the commands at the command line, simply skip the "\\" (do not hit enter) and keep typing from the following line. ]

In this example we will use the velocitycontrol type of stepgen.

The first command loads two step generators, both configured to generate stepping type 0. The second command loads our old friend siggen, and the third one creates two threads, a fast one with a period of 50 micro-seconds and a slow one with a period of 1mS. The fast thread doesn’t support floating point functions.

As before, we can use `halcmd show` to take a look at the HAL. This time we have a lot more pins and parameters than before:

What we have is two step pulse generators, and a signal generator. Now it is time to create some HAL signals to connect the two components. We are going to pretend that the two step pulse generators are driving the X and Y axis of a machine. We want to move the table in circles. To do this, we will send a cosine signal to the X axis, and a sine signal to the Y axis. The siggen module creates the sine and cosine, but we need wiresto connect the modules together. In the HAL, wiresare called signals. We need to create two of them. We can call them anything we want, for this example they will be `X-vel` and `Y-vel. The signal ``X-vel` is intended to run from the cosine output of the signal generator to the velocity input of the first step pulse generator. The first step is to connect the signal to the signal generator output. To connect a signal to a pin we use the net command.

To see the effect of the `net` command, we show the signals again:

When a signal is connected to one or more pins, the show command lists the pins immediately following the signal name. The arrowshows the direction of data flow - in this case, data flows from pin `siggen.0.cosine` to signal `X-vel. Now let's connect the ``X-vel` to the velocity input of a step pulse generator:

We can also connect up the Y axis signal `Y-vel. It is intended to run from the sine output of the signal generator to the input of the second step pulse generator. The following command accomplishes in one line what two ``net` commands accomplished for `X-vel`:

Now let’s take a final look at the signals and the pins connected to them:

The `show sig` command makes it clear exactly how data flows through the HAL. For example, the `X-vel` signal comes from pin `siggen.0.cosine, and goes to pin ``stepgen.0.velocity`-cmd.

Thinking about data flowing through wiresmakes pins and signals fairly easy to understand. Threads and functions are a little more difficult. Functions contain the computer instructions that actually get things done. Thread are the method used to make those instructions run when they are needed. First let’s look at the functions available to us:

In general, you will have to refer to the documentation for each component to see what its functions do. In this case, the function `siggen.0.update` is used to update the outputs of the signal generator. Every time it is executed, it calculates the values of the sine, cosine, triangle, and square outputs. To make smooth signals, it needs to run at specific intervals.

The other three functions are related to the step pulse generators:

The first one, {stepgen.capture\\\_position}, is used for position feedback. It captures the value of an internal counter that counts the step pulses as they are generated. Assuming no missed steps, this counter indicates the position of the motor.

The main function for the step pulse generator is {stepgen.make\\\_pulses}. Every time {make\\\_pulses}runs it decides if it is time to take a step, and if so sets the outputs accordingly. For smooth step pulses, it should run as frequently as possible. Because it needs to run so fast, {make\\\_pulses}is highly optimized and performs only a few calculations. Unlike the others, it does not need floating point math.

The last function, `stepgen.update-freq`, is responsible for doing scaling and some other calculations that need to be performed only when the frequency command changes.

What this means for our example is that we want to run `siggen.0.update` at a moderate rate to calculate the sine and cosine values. Immediately after we run `siggen.0.update`, we want to run {stepgen.update\\\_freq}to load the new values into the step pulse generator. Finally we need to run {stepgen.make\\\_pulses}as fast as possible for smooth pulses. Because we don’t use position feedback, we don’t need to run {stepgen.capture\\\_position}at all.

We run functions by adding them to threads. Each thread runs at a specific rate. Let’s see what threads we have available:

The two threads were created when we loaded `threads. The first one, ``slow, runs every millisecond, and is capable of running floating point functions. We will use it for siggen.0.update` and {stepgen.update\\\_freq}. The second thread is `fast, which runs every 50 microseconds, and does not support floating point. We will use it for {stepgen.make\\\_pulses}. To connect the functions to the proper thread, we use the ``addf` command. We specify the function first, followed by the thread:

After we give these commands, we can run the `show thread` command again to see what happened:

Now each thread is followed by the names of the functions, in the order in which the functions will run.

We are almost ready to start our HAL system. However we still need to adjust a few parameters. By default, the siggen component generates signals that swing from +1 to -1. For our example that is fine, we want the table speed to vary from +1 to -1 inches per second. However the scaling of the step pulse generator isn’t quite right. By default, it generates an output frequency of 1 step per second with an input of 1.000. It is unlikely that one step per second will give us one inch per second of table movement. Let’s assume instead that we have a 5 turn per inch leadscrew, connected to a 200 step per rev stepper with 10x microstepping. So it takes 2000 steps for one revolution of the screw, and 5 revolutions to travel one inch. that means the overall scaling is 10000 steps per inch. We need to multiply the velocity input to the step pulse generator by 10000 to get the proper output. That is exactly what the parameter `stepgen.n.velocity-scale` is for. In this case, both the X and Y axis have the same scaling, so we set the scaling parameters for both to 10000:

This velocity scaling means that when the pin `stepgen.0.velocity-cmd` is 1.000, the step generator will generate 10000 pulses per second (10KHz). With the motor and leadscrew described above, that will result in the axis moving at exactly 1.000 inches per second. This illustrates a key HAL concept - things like scaling are done at the lowest possible level, in this case in the step pulse generator. The internal signal `X-vel` is the velocity of the table in inches per second, and other components such as `siggen` don’t know (or care) about the scaling at all. If we changed the leadscrew, or motor, we would change only the scaling parameter of the step pulse generator.

We now have everything configured and are ready to start it up. Just like in the first example, we use the `start` command:

Although nothing appears to happen, inside the computer the step pulse generator is cranking out step pulses, varying from 10KHz forward to 10KHz reverse and back again every second. Later in this tutorial we’ll see how to bring those internal signals out to run motors in the real world, but first we want to look at them and see what is happening.

The previous example generates some very interesting signals. But much of what happens is far too fast to see with halmeter. To take a closer look at what is going on inside the HAL, we want an oscilloscope. Fortunately HAL has one, called halscope.

Halscope has two parts - a realtime part that is loaded as a kernel module, and a user part that supplies the GUI and display. However, you don’t need to worry about this, because the userspace portion will automatically request that the realtime part be loaded.

The scope GUI window will open, immediately followed by a Realtime function not linkeddialog that looks like the following figure .

Realtime function not linked dialog

This dialog is where you set the sampling rate for the oscilloscope. For now we want to sample once per millisecond, so click on the 989uS thread slowand leave the multiplier at 1. We will also leave the record length at 4000 samples, so that we can use up to four channels at one time. When you select a thread and then click OK, the dialog disappears, and the scope window looks something like the following figure.

Initial scope window

{Hooking up the scope probes}At this point, Halscope is ready to use. We have already selected a sample rate and record length, so the next step is to decide what to look at. This is equivalent to hooking virtual scope probesto the HAL. Halscope has 16 channels, but the number you can use at any one time depends on the record length - more channels means shorter records, since the memory available for the record is fixed at approximately 16,000 samples.

The channel buttons run across the bottom of the halscope screen. Click button 1, and you will see the Select Channel Sourcedialog as shown in the following figure. This dialog is very similar to the one used by Halmeter. We would like to look at the signals we defined earlier, so we click on the Signalstab, and the dialog displays all of the signals in the HAL (only two for this example).

Select Channel Source

To choose a signal, just click on it. In this case, we want channel 1 to display the signal X-vel. Click on the Signals tab then click on X-veland the dialog closes and the channel is now selected.

Select Signal

The channel 1 button is pressed in, and channel number 1 and the name X-velappear below the row of buttons. That display always indicates the selected channel - you can have many channels on the screen, but the selected one is highlighted, and the various controls like vertical position and scale always work on the selected one.

Halscope

To add a signal to channel 2, click the 2button. When the dialog pops up, click the Signalstab, then click on Y-vel. We also want to look at the square and triangle wave outputs. There are no signals connected to those pins, so we use the Pinstab instead. For channel 3, select siggen.0.triangleand for channel 4, select siggen.0.square.

{Capturing our first waveforms}Now that we have several probes hooked to the HAL, it’s time to capture some waveforms. To start the scope, click the Normalbutton in the Run Modesection of the screen (upper right). Since we have a 4000 sample record length, and are acquiring 1000 samples per second, it will take halscope about 2 seconds to fill half of its buffer. During that time a progress bar just above the main screen will show the buffer filling. Once the buffer is half full, the scope waits for a trigger. Since we haven’t configured one yet, it will wait forever. To manually trigger it, click the Forcebutton in the Triggersection at the top right. You should see the remainder of the buffer fill, then the screen will display the captured waveforms. The result will look something like the following figure.

Captured Waveforms

The Selected Channelbox at the bottom tells you that the purple trace is the currently selected one, channel 4, which is displaying the value of the pin siggen.0.square. Try clicking channel buttons 1 through 3 to highlight the other three traces.

{Vertical Adjustments}The traces are rather hard to distinguish since all four are on top of each other. To fix this, we use the Verticalcontrols in the box to the right of the screen. These controls act on the currently selected channel. When adjusting the gain, notice that it covers a huge range - unlike a real scope, this one can display signals ranging from very tiny (pico-units) to very large (Tera-units). The position control moves the displayed trace up and down over the height of the screen only. For larger adjustments the offset button should be used (see the halscope reference in section [sec:Halscope] for details).

Vertical Adjustment

Using the Forcebutton is a rather unsatisfying way to trigger the scope. To set up real triggering, click on the Sourcebutton at the bottom right. It will pop up the Trigger Sourcedialog, which is simply a list of all the probes that are currently connected. Select a probe to use for triggering by clicking on it. For this example we will use channel 3, the triangle wave as shown in the following figure.

Trigger Source Dialog

After setting the trigger source, you can adjust the trigger level and trigger position using the sliders in the Triggerbox along the right edge. The level can be adjusted from the top to the bottom of the screen, and is displayed below the sliders. The position is the location of the trigger point within the overall record. With the slider all the way down, the trigger point is at the end of the record, and halscope displays what happened before the trigger point. When the slider is all the way up, the trigger point is at the beginning of the record, displaying what happened after it was triggered. The trigger point is visible as a vertical line in the progress box above the screen. The trigger polarity can be changed by clicking the button just below the trigger level display.

Now that we have adjusted the vertical controls and triggering, the scope display looks something like the following figure.

Waveforms with Triggering

{Horizontal Adjustments}To look closely at part of a waveform, you can use the zoom slider at the top of the screen to expand the waveforms horizontally, and the position slider to determine which part of the zoomed waveform is visible. However, sometimes simply expanding the waveforms isn’t enough and you need to increase the sampling rate. For example, we would like to look at the actual step pulses that are being generated in our example. Since the step pulses may be only 50uS long, sampling at 1KHz isn’t fast enough. To change the sample rate, click on the button that displays the number of samples and sample rate to bring up the Select Sample Ratedialog, figure . For this example, we will click on the 50uS thread, fast, which gives us a sample rate of about 20KHz. Now instead of displaying about 4 seconds worth of data, one record is 4000 samples at 20KHz, or about 0.20 seconds.

Sample Rate Dialog

{More Channels}Now let’s look at the step pulses. Halscope has 16 channels, but for this example we are using only 4 at a time. Before we select any more channels, we need to turn off a couple. Click on the channel 2 button, then click the Chan Offbutton at the bottom of the Verticalbox. Then click on channel 3, turn if off, and do the same for channel 4. Even though the channels are turned off, they still remember what they are connected to, and in fact we will continue to use channel 3 as the trigger source. To add new channels, select channel 5, and choose pin stepgen.0.dir, then channel 6, and select stepgen.0.step. Then click run mode Normalto start the scope, and adjust the horizontal zoom to 5mS per division. You should see the step pulses slow down as the velocity command (channel 1) approaches zero, then the direction pin changes state and the step pulses speed up again. You might want to increase the gain on channel 1 to about 20m per division to better see the change in the velocity command. The result should look like the following figure.

Step Pulses

If you want to record more samples at once, restart realtime and load halscope with a numeric argument which indicates the number of samples you want to capture, such as

if the {scope\\\_rt}component was not already loaded, halscope will load it and request 80000 total samples, so that when sampling 4 channels at a time there will be 20000 samples per channel. (If {scope\\\_rt}was already loaded, the numeric argument to halscope will have no effect)

Command line examples are presented in {textbf{bold typewriter}}font. Responses from the computer will be in `typewriter` font. As of early 2006, there are no longer commands that require root privileges, so all examples will be preceded by the normal user prompt, {$}. Text inside square brackets {{[}like-this{]}}is optional. Text inside angle brackets `<like-this>` 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 `emc2/` directory, and you configured/compiled emc2 for the run-in-place scenario. Paths will be shown accordingly when needed.

All HAL entities are accessed and manipulated by their names, so documenting the names of pins, signals, parameters, etc, is very important. HAL names are a maximum of 41 characters long (as defined by HAL\_NAME\_LEN in hal.h). Many names will be presented in a general form, with text inside angle brackets `<like-this>` representing fields that can take on different values.

When pins, signals, or parameters are described for the first time, their names will be preceeded by their type in {(small caps)}and followed by a brief description. A typical pin definition will look something like these examples:

At times, a shortened version of a name may be used - for example the second pin above might be referred to simply as `.output` when it can be done without causing confusion.

Consistent naming conventions would make HAL much easier to use. For example, if every encoder driver provided the same set of pins and named them the same way it would be easy to change from one type of encoder driver to another. Unfortunately, like many open-source projects, HAL is a combination of things that were designed, and things that simply evolved. As a result, there are many inconsistencies. This section attempts to address that problem by defining some conventions, but it will probably be a while before all the modules are converted to follow them.

Halcmd and other low-level HAL utilities treat HAL names as single entities, with no internal structure. However, most modules do have some implicit structure. For example, a board provides several functional blocks, each block might have several channels, and each channel has one or more pins. This results in a structure that resembles a directory tree. Even though halcmd doesn’t recognize the tree structure, proper choice of naming conventions will let it group related items together (since it sorts the names). In addition, higher level tools can be designed to recognize such structure, if the names provide the neccessary information. To do that, all HAL modules should follow these rules:

\\footnote{Most drivers do not follow these conventions as of version 2.0. This chapter is really a guide for future development.% }} === Pin/Parameter names

Hardware drivers should use five fields (on three levels) to make up a pin or parameter name, as follows:

The individual fields are:

Hardware drivers usually only have two kinds of HAL functions, ones that read the hardware and update HAL pins, and ones that write to the hardware using data from HAL pins. They should be named as follows:

\\footnote{As of version 2.0, most of the HAL drivers don’t quite match up to the canonical interfaces defined here. In version 2.1, the drivers will be changed to match these specs.% } }The following sections show the pins, parameters, and functions that are supplied by "canonical devices". All HAL device drivers should supply the same pins and parameters, and implement the same behavior.

Note that the only the `<io-type>` and `<specific-name>` fields are defined for a canonical device. The `<device-name>, `<device-num>`, and `<chan-num>`` fields are set based on the characteristics of the real device.

quite simple.

is also very simple.

expected to be used for analog to digital converters, which convert e.g. voltage to a continuous range of values.

intended for any kind of hardware that can output a more-or-less continuous range of values. Examples are digital to analog converters or PWM generators.

to the hardware. If enable is false, then the output will be 0, regardles of value, scale, and offset. The meaning of "0" is dependent on the hardware. For example, a bipolar 12-bit A/D may need to write 0x1FF (mid scale) to the D/A get 0 volts from the hardware pin. If enable is true, read scale, offset and value and output to the adc (scale {*} value) + offset. If enable is false, then output 0.

Halcmd is a command line tool for manipulating the HAL. There is a rather complete man page for halcmd, which will be installed if you have installed EMC2 from either source or a package. If you have compiled EMC2 for "run-in-place", the man page is not installed, but it is accessible. From the main EMC2 directory, do:

Chapter [cha:HAL-Tutorial] has a number of examples of halcmd usage, and is a good tutorial for halcmd.

Halmeter is a "voltmeter" for the HAL. It lets you look at a pin, signal, or parameter, and displays the current value of that item. It is pretty simple to use. Start it by typing "`halmeter`" in a X windows shell. Halmeter is a GUI application. It will pop up a small window, with two buttons labeled "Select" and "Exit". Exit is easy - it shuts down the program. Select pops up a larger window, with three tabs. One tab lists all the pins currently defined in the HAL. The next lists all the signals, and the last tab lists all the parameters. Click on a tab, then click on a pin/signal/parameter. Then click on "OK". The lists will disappear, and the small window will display the name and value of the selected item. The display is updated approximately 10 times per second. If you click "Accept" instead of "OK", the small window will display the name and value of the selected item, but the large window will remain on the screen. This is convenient if you want to look at a number of different items quickly.

You can have many halmeters running at the same time, if you want to monitor several items. If you want to launch a halmeter without tying up a shell window, type "{halmeter \\&}" to run it in the background. You can also make halmeter start displaying a specific item immediately, by adding "{pin\|sig\|par{[}am{]} <name>}" to the command line. It will display the pin, signal, or parameter <name> as soon as it starts. (If there is no such item, it will simply start normally.) And finally, if you specify an item to display, you can add "-s" before the pin\|sig\|param to tell halmeter to use a small window. The item name will be displayed in the title bar instead of under the value, and there will be no buttons. Usefull when you want a lot of meters in a small amount of screen space.

Halscope is an "oscilloscope" for the HAL. It lets you capture the value of pins, signals, and parameters as a function of time. Complete operating instructions should be located here eventually. For now, refer to section [sec:Tutorial - Halscope] in the tutorial chapter, which explains the basics.

Writing a HAL component can be a tedious process, most of it in setup calls to {rtapi\\_}and {hal\\\_}functions and associated error checking. comp will write all this code for you, automatically.

Compiling a HAL component is also much easier when using comp, whether the component is part of the emc2 source tree, or outside it.

For instance, the ddtportion of blocks is around 80 lines of code. The equivalent component is very short when written using the comp preprocessor:

and it can be compiled and installed very easily: by simply placing ddt.comp in src/hal/components and running{ \\textquotedblmake}, or by placing it anywhere on the system and running {comp --install ddt.comp}

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

For a non-singleton, the {textquotedblcount}module parameter determines how many numbered instances are created.

Comp’s are passed the {textquotedblperiod\\textquotedbl}parameter which is the time in nanoseconds of the last period to execute the comp. This can be useful in comps that need the timing information.

A .comp file consists of a number of declarations, followed by ;; on a line of its own, followed by C code implementing the module’s functions.

Declarations include:

Parentheses indicate optional items. A vertical bar indicates alternatives. Words in CAPITALS indicate variable text, as follows:

C++-style one-line comments ({// \\ldots}) and C-style multi-line comments ({/{*} \\ldots {*}/}) are both supported in the declaration section.

Though HAL permits a pin, a parameter, and a function to have the same name, comp does not.

Based on the items in the declaration section, comp creates a C structure called struct state. However, instead of referring to the members of this structure (e.g., {{*}(inst→name)}), they will generally be referred to using the macros below. The details of struct state and these macros may change from one version of comp to the next.

If a component has only one function and the string FUNCTIONdoes not appear anywhere after ;;, then the portion after ;; is all taken to be the body of the component’s single function.

If a component has any pins or parameters with an if condition*or {[}*maxsize : condsize{]}, it is called a component with personality. The personalityof each instance is specified when the module is loaded. Personalitycan be used to create pins only when needed. For instance, personality is used in the logic 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 and, or, and xor.

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

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

comp can process, compile, and install a realtime component in a single step, placing rtexample.ko in the emc2 realtime module directory:

Or, it can process and compile in one step, leaving example.ko (or example.so for the simulator) in the current directory:

Or it can simply process, leaving example.c in the current directory:

comp can also compile and install a component written in C, using the {--install}and {--compile}options shown above:

man-format documentation can also be created from the information in the declaration section:

The resulting manpage, example.9 can be viewed with

or copied to a standard location for manual pages.

comp can process, compile, install, and document userspace components:

This only works for .comp files, not for .c files.

This component functions like the one in blocks, including the default value of 1.0. The declaration function \_creates functions named constant.0, etc.

This component computes the sine and cosine of an input angle in radians. It has different capabilities than the sineand cosineoutputs of siggen, because the input is an angle, rather than running freely based on a frequencyparameter.

The pins are declared with the names {sin\\_}and {cos\\\_}in the source code so that they do not interfere with the functions sin() and cos(). The HAL pins are still called sincos.<num>.sin.

This component is a driver for a fictional card called out8, 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 {out\\\_}because out is an identifier used in <asm/io.h>. It illustrates the use of {EXTRA\\\_SETUP}and {EXTRA\\\_CLEANUP}to request an I/O region and then free it in case of error or when the module is unloaded.

This fragment of a component illustrates the use of the {hal\\\_}prefix in a component name. loop is the name of a standard Linux kernel module, so a loop component might not successfully load if the Linux loop module was also present on the system.

When loaded, halcmd show comp will show a component called {hal\\\_loop}. However, the pin shown by {halcmd show pin}will be loop.0.example, not hal-loop.0.example.

This realtime component illustrates use of fixed-size arrays:

This userspace component changes the value on its output pin to a new random value in the range :math:$[0,1)$ about once every 1ms.

This realtime component shows how to use personalityto create variable-size arrays and optional pins.

A typical load line for this component might be

which creates the following pins:

A userspace component begins by creating its pins and parameters, then enters a loop which will periodically drive all the outputs from the inputs. The following component copies the value seen on its input pin (`passthrough.in) to its output pin (passthrough.out`) approximately once per second.

Copy the above listing into a file named "passthrough", make it executable (`chmod +x),` and place it on your {$PATH}. Then try it out:

If you typed "show pin" quickly, you may see that `passthrough.out` still had its old value of 0. This is because of the call to time.sleep(1), which makes the assignment to the output pin occur at most once per second. Because this is a userspace component, the actual delay between assignments can be much longer-for instance, if the memory used by the passthrough component is swapped to disk, the assignment could be delayed until that memory is swapped back in.

Thus, userspace components are suitable for user-interactive elements such as control panels (delays in the range of milliseconds are not noticed, and longer delays are acceptable), but not for sending step pulses to a stepper driver board (delays must always be in the range of microseconds, no matter what).

The component itself is created by a call to the constructor `hal.component`. The arguments are the HAL component name and (optionally) the prefix used for pin and parameter names. If the prefix is not specified, the component name is used.

Then pins are created by calls to methods on the component object. The arguments are: pin name suffix, pin type, and pin direction. For parameters, the arguments are: parameter name suffix, parameter type, and parameter direction.

The full pin or parameter name is formed by joining the prefix and the suffix with a ".", so in the example the pin created is called `passthrough.in`.

Once all the pins and parameters have been created, call the `.ready()` method.

The prefix can be changed by calling the `.setprefix()` method. The current prefix can be retrieved by calling the `.getprefix()` method.

For pins and parameters which are also proper Python identifiers, the value may be accessed or set using the attribute syntax:

For all pins, whether or not they are also proper Python identifiers, the value may be accessed or set using the subscript syntax:

Periodically, usually in response to a timer, all HAL\_OUT pins should be "driven" by assigning them a new value. This should be done whether or not the value is different than the last one assigned. When a pin is connected to a signal, its old output value is not copied into the signal, so the proper value will only appear on the signal once the component assigns a new value.

The above rule does not apply to bidirectional pins. Instead, a bidirectional pin should only be driven by the component when the component wishes to change the value. For instance, in the canonical encoder interface, the encoder component only sets the index-enable pin to FALSE (when an index pulse is seen and the old value is TRUE), but never sets it to TRUE. Repeatedly driving the pin FALSE might cause the other connected component to act as though another index pulse had been seen.

A "`halcmd unload" request for the component is delivered as a ``KeyboardInterrupt` exception. When an unload request arrives, the process should either exit in a short time, or call the `.exit()` method on the component if substantial work (such as reading or writing files) must be done to complete the shutdown process.

Copyright (c) 2000 LinuxCNC.org

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and one Back-Cover Text: This EMC Handbook is the product of several authors writing for linuxCNC.org. As you find it to be of value in your work, we invite you to contribute to its revision and growth.A copy of the license is included in the section entitled GNU Free Documentation License. If you do not find the license you may order a copy from Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307

GNU Free Documentation License Version 1.1, March 2000

Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license manual, textbook, or other written document \\textquotedblfree\\textquotedbl in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose

work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The \\textquotedblDocument\\textquotedbl, below, refers to any such manual or work. Any member of the public of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not \\textquotedblTransparent\\textquotedbl copies include plain ASCII without markup, Texinfo input format, \\LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, \\textquotedblTitle Page\\textquotedbl means the text near the most prominent appearance of the work’s title, preceding

in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions

numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with

of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice. H. Include an unaltered copy of this License. I. Preserve the section entitled \\textquotedblHistory\\textquotedbl, and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled \\textquotedblHistory\\textquotedbl in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the \\textquotedblHistory\\textquotedbl section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. In any section entitled \\textquotedblAcknowledgements\\textquotedbl or \\textquotedblDedications\\textquotedbl, preserve the section’s title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section entitled \\textquotedblEndorsements\\textquotedbl. Such a section may not be included in the Modified Version. N. Do not retitle any existing section as \\textquotedblEndorsements\\textquotedbl or sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added do not by this License give permission to use their names for publicity

released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined sections entitled \\textquotedblHistory\\textquotedbl in the various original documents, forming one section entitled \\textquotedblHistory\\textquotedbl; likewise combine any sections entitled \\textquotedblAcknowledgements\\textquotedbl, and any sections entitled \\textquotedblDedications\\textquotedbl.

Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying

with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an \\textquotedblaggregate\\textquotedbl, and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document’s Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole

so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English

distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated

new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. version number. If the Document specifies that a particular numbered version of this License \\textquotedblor any later version\\textquotedbl applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free written, include a copy of the License in the document and put the is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled \\textquotedblGNU Free Documentation \\textquotedblwith no Invariant Sections\\textquotedbl instead of saying which ones are invariant. If you have no Front-Cover Texts, write \\textquotedblno Front-Cover Texts\\textquotedbl instead of \\textquotedblFront-Cover Texts being LIST\\textquotedbl; likewise of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.}