hal_parport(1)

📦 version 2.9.0~pre1+git20230208.f1270d6ed7, in debian bookworm

💖 hal_parport(1) — HAL Realtime Component 💖

okay bestie, gather round, because this one is literally the driver that lets LinuxCNC talk to actual physical parallel ports. It's hal_parport(1), it lives in the HAL Realtime Component family, and it's about to be your new fave. 🦋

✨ NAME ✨

hal_parport — a Realtime HAL component that talks to one or more PC parallel ports. fr fr, that's the whole job.

✨ SYNOPSIS ✨

loadrt hal_parport cfg="port_addr [type] [[port_addr [type] ...]"

✨ DESCRIPTION ✨

So hal_parport is a realtime component, and what it does is give you a bridge: HAL pins on one side, the actual metal pins of one or more parallel ports on the other. It creates a read function and a write function so you can send data out to the attached parallel port(s) and receive data back. 💅

And she's generous — the hal_parport component supports up to 8 physical parallel ports. Eight!! 👑

✨ OPTIONS ✨

  • cfg="port_addr [type] [[port_addr [type] ...]" — this string is the whole personality of the component. It tells hal_parport the address(es) of your parallel port(s), and whether each port is being used as an input or an output. Up to eight parallel ports are supported, periodt.

So about that port_addr: it can be either the physical base address of a parallel port, or you can refer to a port that the Linux parport_pc driver detected. In that second case, port_addr of 0 means the first parallel port detected on the system, 1 is the next one, and so on. 🌈

Then there's the type parameter, which decides how the port's I/O bits get used. Four possible options, and if you don't specify one it defaults to out.

  • in — sets the 8 bits of the data port to input. In this mode the parallel port has a total of 13 input pins and 4 output pins.
  • out — sets the 8 bits of the data port to output. In this mode the parallel port has a total of 5 input pins and 12 output pins.
  • epp — same as setting it to out, but it can cause the computer to change the electrical characteristics of the port. See USAGE below. 👀
  • x — this one lets ports that have open collectors on the control group pins be configured as inputs, which gives you 8 output pins and 9 input pins. See USAGE below.

✨ PINS ✨

Which pins hal_parport creates depends entirely on how you configured it in the cfg="" string you passed it. See OPTIONS, bestie. 🎀

  • parport.<p>.pin-<n>-out (bit) — drives a physical output pin.
  • parport.<p>.pin-<n>-in (bit) — tracks a physical input pin.
  • parport.<p>.pin-<n>-in-not (bit) — tracks a physical input pin, but inverted.

For every pin created, <p> is the port number, and <n> is the physical pin number in the 25 pin D-shell connector. 🔌

For each physical output pin, the driver creates a single HAL pin, for example: parport.0.pin-14-out.

For each physical input pin, the driver creates two HAL pins, for example: parport.0.pin-12-in and parport.0.pin-12-in-not.

The -in HAL pin is TRUE if the physical pin is high, and FALSE if the physical pin is low. The -in-not HAL pin is inverted, so it's FALSE if the physical pin is high. 💀 (yes, that's the whole trick)

Here's the input/output pin breakdown for each type setting you can use in the cfg="" string:

  • in: Pins 2,3,4,5,6,7,8,9,10,11,12,13,15 are input pins and pins 1,14,16 and 17 are output pins.
  • out/epp: Pins 10,11,12,13 and 15 are input pins and pins 1,2,3,4,5,6,7,8,9,14,16 and 17 are output pins.
  • x: Pins 1,10,11,12,13,14,15,16 and 17 are input pins and pins 2,3,4,5,6,7,8,9 are output pins. (See USAGE section.)

✨ PARAMETERS ✨

  • parport.<p>.pin-<n>-out-invert (bit) — inverts an output pin. 🌸
  • parport.<p>.pin-<n>-out-reset (bit) — (only for out pins) TRUE if this pin should be reset when the .reset function is executed.
  • parport.<p>.reset-time' (U32) — the time (in nanoseconds) between a pin being set by write and being reset by the reset function, if it's enabled.

✨ FUNCTIONS ✨

  • parport.<p>.read(funct) — reads physical input pins of port <portnum> and updates the HAL -in and -in-not pins.
  • parport.read-all (funct) — reads physical input pins of all ports and updates the HAL -in and -in-not pins.
  • parport.<p>.write (funct) — reads the HAL -out pins of port <p> and updates that port's physical output pins.
  • parport.write-all (funct) — reads the HAL -out pins of all ports and updates all physical output pins.
  • parport.<p>.reset (funct) — waits until reset-time has elapsed since the associated write, then resets pins to the values indicated by the -out-reset and -out-invert settings. Reset must be later in the same thread as write. If -out-reset is TRUE, then the reset function will set the pin to the value of -out-invert. This can be used in conjunction with stepgen's doublefreq to produce one step per period. The stepgen stepspace for that pin must be set to 0 to enable doublefreq. 🔥

✨ USAGE ✨

okay so this is the section where we get into the lore. 📖

hal_parport is a driver for the traditional PC parallel port. That port has a total of 25 physical pins, and 17 of them are used for signals. The original parallel port split those pins into three groups: data, control, and status. The data group = 8 output pins, the control group = 4 output pins, and the status group = 5 input pins.

Then in the early 1990's, the bidirectional parallel port showed up, which lets the data group be used for either output or input. The HAL driver supports that bidirectional port, and lets you set the data group as input or output. If configured as out, a port gives you a total of 12 outputs and 5 inputs. If configured as in, it gives you 4 outputs and 13 inputs. ✨

In some parallel ports, the control group pins are open collectors, which may also be driven low by an external gate. On a board with open collector control pins, if configured as x, it provides 8 outputs, and 9 inputs.

In some parallel ports, the control group has push-pull drivers and cannot be used as an input. 🙈

🚨 Note: HAL and Open Collectors 🚨

HAL cannot automatically determine if the x mode bidirectional pins are actually open collectors (OC). If they are not, they cannot be used as inputs, and attempting to drive them LOW from an external source can damage the hardware. Not a vibe. Please don't.
To figure out whether your port has open collector pins, load hal_parport in x mode. With no device attached, HAL should read the pin as TRUE. Next, insert a 470 ohm resistor from one of the control pins to GND. If the resulting voltage on the control pin is close to 0V, and HAL now reads the pin as FALSE, then congrats, you have an OC port. 🎉 If the resulting voltage is far from 0V, or HAL does not read the pin as FALSE, then your port cannot be used in x mode.
The external hardware that drives the control pins should also use open collector gates (e.g., 74LS05).
On some computers, BIOS settings may affect whether x mode can be used. SPP mode is most likely to work. ⭐

No other combinations are supported, and a port cannot be changed from input to output once the driver is installed. Once it's committed, it's committed. 💅

The parport driver can control up to 8 ports (defined by MAX_PORTS in hal_parport.c). The ports are numbered starting at zero.

Loading the hal_parport component

The hal_parport driver is a real time component, so it must be loaded into the real time thread with loadrt. The configuration string describes the parallel ports to be used, and (optionally) their types. If the configuration string does not describe at least one port, it is an error. 😭

loadrt hal_parport cfg="port [type] [port [type] ...]"

Specifying the Port

Numbers below 16 refer to parallel ports detected by the system. This is the simplest way to configure the hal_parport driver, and it cooperates with the Linux parport_pc driver if it's loaded. A port of 0 is the first parallel port detected on the system, 1 is the next, and so on. 🦋

Basic configuration

This will use the first parallel port Linux detects:

loadrt hal_parport cfg="0"

Using the Port Address

Instead, the port address may be specified using the hex notation 0x followed by the address. 🌈

loadrt hal_parport cfg="0x378"

Specifying a port Type

For each parallel port handled by the hal_parport driver, a type can optionally be specified. The type is one of in, out, epp, or x.

If the type is not specified, the default is out.

A type of epp is the same as out, but the hal_parport driver requests that the port switch into EPP mode. The hal_parport driver does not use the EPP bus protocol, but on some systems EPP mode changes the electrical characteristics of the port in a way that may make some marginal hardware work better. The Gecko G540's charge pump is known to require this on some parallel ports. 👑

See the Note above about mode x.

Example with two parallel ports

This will enable two system-detected parallel ports, the first in output mode and the second in input mode:

loadrt hal_parport cfg="0 out 1 in"

Functions single port

You must also direct LinuxCNC to run the read and write functions.

addf parport.read-all base-thread
addf parport.write-all base-thread

Functions multiple ports

You can direct LinuxCNC to run the read and write functions for all the attached ports.

addf parport.0.read base-thread
addf parport.0.write base-thread

The individual functions are provided for situations where one port needs to be updated in a very fast thread, but other ports can be updated in a slower thread to save CPU time. It is probably not a good idea to use both an -all function and an individual function at the same time. 🫶

✨ SEE ALSO ✨

  • Parallel Port Driver (Hardware Drivers Section of LinuxCNC Docs)
  • PCIParallelPortExample(HardwareExamplesSectionofLinuxCNCDocs)

✨ AUTHOR ✨

This man page written by Joe Hildreth as part of the LinuxCNC project. Most of this information was taken from the parallel-port docs located in the Hardware Drivers section of the documentation. To the best of my knowledge that documentation was written by Sebastian Kuzminsky and Chris Radek. 💜 legends, honestly.

and that's the whole page bestie!! 🌟 This gorgeousness is LinuxCNC Documentation, dated 12 APR 2017 — hal_parport(1), forever iconic, no cap. 🎀✨

📦 where this page comes from