---
name: "hal_port"
section: "3hal"
platform: "linux"
package: "linuxcnc-uspace-dev"
version: "1:2.9.4-2+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/hal_port"
---

# hal\_port(3hal)

a HAL pin type that acts as an asynchronous one way byte stream

## NAME

hal\_port - a HAL pin type that acts as an asynchronous one way byte stream

## SYNOPSIS

.B #include \<hal.h\>

bool hal\_port\_read(hal\_port\_t port, char\* dest, unsigned count);\
 bool hal\_port\_peek(hal\_port\_t port, char\* dest, unsigned count);\
 bool hal\_port\_peek\_commit(hal\_port\_t port, unsigned count);\
 unsigned hal\_port\_readable(hal\_port\_t port);\
 void hal\_port\_clear(hal\_port\_t port);

bool hal\_port\_write(hal\_port\_t port, const char\* src, unsigned count);\
 unsigned hal\_port\_writable(hal\_port\_t port);

unsigned hal\_port\_buffer\_size(hal\_port\_t port);

.B #ifdef ULAPI\
 void hal\_port\_wait\_readable(hal\_port\_t \*\*port, unsigned count, sig\_atomic\_t \*stop);\
 void hal\_port\_wait\_writable(hal\_port\_t \*\*port, unsigned count, sig\_atomic\_t \*stop);\
 .B #endif

## DESCRIPTION

A HAL port pin is a HAL pin that acts as a one way byte oriented data stream in real-time. An output port on any component may be connected to an input port on any other component via a signal. Data written on the output pin becomes accessible to the input pin. A HAL port signal may link only a single writer and a single reader.

A port also buffers data. Users should determine the proper buffer size based upon their intended application.

### hal\_port\_read

Reads count bytes from the port into destination buffer dest. hal\_port\_read will read *count* bytes if and only if *count* bytes are available for reading and otherwise it will leave the port unaffected. Returns true if count bytes were read and false otherwise. This function should only be called by the component that owns the IN PORT pin.

### hal\_port\_peek

Behaves the same as hal\_port\_read, however it does not consume bytes from the HAL port. Repeated calls to hal\_port\_peek will return the same data. Returns true if count bytes were read and false otherwise. This function should only be called by the component that owns the IN PORT pin.

### hal\_port\_peek\_commit

Advances the read position in the port buffer by count bytes.  A hal\_port\_peek followed by a hal\_port\_peek\_commit would function equivalently to hal\_port\_read given the same count value.  Returns true if count readable bytes were skipped and are no longer accessible and false if no bytes wer skipped. This function should only be called by the component that owns the IN PORT pin.

### hal\_port\_readable

Returns the number of bytes available for reading from port. It is safe to call this function from any component.

### hal\_port\_clear

Emptys a given port of all data. hal\_port\_clear should only be called by the component that owns the IN PORT pin.

### hal\_port\_write

Writes count bytes from src into the port.  Returns true if count bytes were written and false otherwise. This function should only be called by the component that owns the OUT PORT pin.

### hal\_port\_writable

Returns the number of bytes that can be written into the port. It is safe to call this function from any component.

### hal\_port\_buffer\_size

Returns the maximum number of bytes that a port can buffer. It is safe to call this function from any component.

### hal\_port\_wait\_readable

Waits until the port has count bytes or more available for reading or the stop flag is set.

### hal\_port\_wait\_writable

Waits until the port has count bytes or more available for writing or the stop flag is set.

## ARGUMENTS

- **hal\_port\_t**

  A handle to a port object. Created by hal\_pin\_new

- **dest**

  An array of bytes that hal\_port\_read and hal\_port\_peek will copy data into. This must be allocated by the caller and be at least count bytes long.

- **count**

  The number of bytes that hal\_port\_read, hal\_port\_peek, and hal\_port\_write will copy in to dest or out from src

- **src**

  An array of bytes that hal\_port\_write will copy data from into the port buffer. This must be of size count bytes or larger.

- **stop**

  A pointer to a value which is monitored while waiting.  If it is nonzero, the wait operation returns early.  This allows a wait call to be safely terminated in the case of a signal.

## SAMPLE CODE

In the source tree under\
  src/hal/components/raster.comp is a realtime component intended for laser control.\
  src/tests/raster is a test program that also programs the raster component from python.

## REALTIME CONSIDERATIONS

**hal\_port\_read**, **hal\_port\_peek**, **hal\_port\_peek\_commit**, **hal\_port\_readable**, **hal\_port\_clear**, **hal\_port\_write**, **hal\_port\_writable**, **hal\_port\_buffer\_size** may be called from realtime code.

**hal\_port\_wait\_writable**, **hal\_port\_wait\_readable** may be called from ULAPI code.

## SEE ALSO

**raster**(9),