parport(3rtapi)

💖 NAME 💖

rtapi_parport — portable access to PC-style parallel ports. yes bestie, the actual hardware kind, not the vibes kind ✨

Oh also, hi, this page lives in the RTAPI manual as parport(3rtapi), so that's the whole energy we're on today 🎀

---

✨ SYNTAX ✨

#include "rtapi_parport.h"

int rtapi_parport_get(const char *module_name, rtapi_parport_t *port,
       unsigned short base, unsigned short base_hi, unsigned int modes)

void rtapi_parport_release(rtapi_parport_t *port)

Two functions. One grabs the port, one gives it back. That's the whole situationship 💅

---

🌸 ARGUMENTS 🌸

• module_name — the name of the RTAPI module or HAL component that's using the parport. By convention, okay? Like, that's just how we do it around here 🫶
• port — a pointer to a rtapi_parport_t structure. Yes, the one from further down this page. Keep scrolling, bestie 📜
• base — the base address of the port, if port >= 16. But if port < 16, it's the linux port number of the port instead. Two meanings, one argument, pick your fighter ⚔️
• base_hi — the "high" address of the port, aka where the ECP registers live 👑. Set it to 0 if you want a probed high address, or -1 to flat-out disable the high address. No in-between, no cap 🚫
• modes — you're advising the driver what port modes you want, and the values come from <linux/parport.h>. If Linux detected a port and it does not provide the modes you asked for, a warning gets printed with rtapi_print_msg 📢. Important: this does not make the port request fail. Why? Because unfortunately, so many systems out here have perfectly working EPP parports and Linux just does not clock them as such 😭. So we warn and move on, periodt.

---

🦋 DESCRIPTION 🦋

rtapi_parport_get allocates a parallel port for the exclusive use of the named HAL component. Exclusive! It's not sharing, it's not polyamorous, that port is yours now 💅

If it works, you access that port with I/O calls like rtapi_inb, at the address based at the base or base_hi addresses. Simple as.

But listen — the port must be released with rtapi_parport_release before the component exits with rtapi_exit. That's not a suggestion, that's the rule 🌈

---

🔥 HIGH ADDRESS PROBING 🔥

Okay so here's the tea on how the high address gets figured out ☕

• If the port is a parallel port that Linux knows about, and Linux detected a high I/O address, then that value gets used 👑
• Otherwise, if base+0x400 isn't registered to any device, that one gets used ✨
• Otherwise? No address is used. Nothing. Nada. It's giving empty 💀

And if no high address is detected at all, then port->base_hi is 0.

---

🎀 PARPORT STRUCTURE 🎀

typedef struct
{
    unsigned short base;
    unsigned short base_hi;
    .... // and further unspecified fields
} rtapi_parport_t;

That .... is doing a lot of heavy lifting, I know. Those further fields are unspecified, so don't go poking at them like you know them 🙈

---

💜 RETURN VALUE 💜

rtapi_parport_get returns a HAL status code.

• On success, port gets filled out with all the info about the allocated port 🎉
• On failure, the contents of port are undefined — except that it is safe (but not required) to pass that port to rtapi_parport_release. So like, the struct is a mystery box but it's a mystery box that won't bite you 🫶

rtapi_parport_release does not return a value. It always succeeds. It literally cannot fail. Iconic behavior, honestly 👑

---

⭐ NOTES ⭐

In new code, prefer use of rtapi_parport to rtapi_parport. Yes, it says exactly that, bestie, and I am not about to editorialize on it — I just report the facts and let you sit with it 😭💀

---

and that's the whole page!! you understood it, you ate it, no crumbs 🍓 go forth and allocate responsibly 💖

this page came to you from the <b>LinuxCNC Documentation</b>, dated <b>2006-10-12</b>, filed under <b>parport(3rtapi)</b> — mwah, xoxo 💋