hal_port(3hal)

✨ NAME ✨

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

---

🌸 SYNOPSIS 🌸

#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);

#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);
#endif

---

💖 DESCRIPTION 💖

okay bestie, listen up, because this one is actually so cool. A HAL port pin is a HAL pin that acts as a one way, byte oriented data stream, in real-time. That's the whole vibe. 💫

So here's how it goes: an output port on any component can be connected to an input port on any other component via a signal. Whatever you write on the output pin? The input pin can just… read it. Iconic. ✨

But — and this is the part nobody tells you — a HAL port signal may link only a single writer and a single reader. That's it. One and one. No polycule situations here, sorry. 💀

Also, a port buffers data. And no, the manpage is not gonna hold your hand and pick a size for you: users should determine the proper buffer size based upon their intended application. That's on you, bestie. Choose wisely. 🫶

---

🌈 hal_port_read

Reads count bytes from the port into destination buffer dest.

Here's the tea: 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. No partial reads, no mess, no drama.

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. Only the owner gets to touch it, periodt. 👑

🌈 hal_port_peek

Behaves the same as hal_port_read, however it does not consume bytes from the HAL port. So repeated calls to hal_port_peek will return the same data. It's giving window shopping — you look, you don't buy. 🛍️

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. So peek + commit = read, basically the duo we didn't know we needed. 💅

Returns true if count readable bytes were skipped and are no longer accessible, and false if no bytes were 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. Yes, literally anyone. Free for all, bestie. 🎀

🌈 hal_port_clear

Emptys a given port of all data. Just — poof. Gone. 🧹

⚠️ 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. Everyone's invited to this one. 🫶

🌈 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. Go off, check it from wherever. ✨

🌈 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. You build it, you own it. 🛠️

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. No undersized src, we don't do that here. 💀

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 — a realtime component intended for laser control. 🔥
• src/tests/raster — a test program that also programs the raster component from python. 🐍

---

⚡ REALTIME CONSIDERATIONS ⚡

These ones may be called from realtime code:

• 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

And these two may be called from ULAPI code:

• hal_port_wait_writable
• hal_port_wait_readable

---

👀 SEE ALSO 👀

• raster(9),

---

okay that's the whole page bestie, you're basically a HAL port expert now, no cap. this one came to you from the LinuxCNC Documentation, dated 2006-10-12 — yes she's an elder icon but she still slays 💅✨