pktdrive(3z)

💖 pktdrive — the packet driver descriptor structure 💖

okay so bestie, this one lives in the z88dk Programmer's Manual, section 3z, and it's genuinely iconic if you're the kind of girl who writes network drivers for fun (which, obviously, you are). let's get into it 🦋

---

✨ NAME ✨

pktdrive — the packet driver descriptor structure. that's it, that's the whole vibe. it's the lil struct that tells ZSock how to talk to a device. 💅

---

🌸 SYNOPSIS 🌸

#include <net/device.h>

---

🎀 DESCRIPTION 🎀

so the pktdrive structure is literally the access layer for a device, and it's only used by the ZSock kernel. like, ZSock and nobody else, periodt. if you wanna write a packet driver yourself (main character energy, honestly), you fill this structure in with the relevant routines and you're off. 💖

here's the tea: all external packet drivers run at address 8192 ($2000), and that's exactly where the structure has to be placed. no wiggle room, no negotiating. if z88dk actually had the capability to express this, pktdrive would be defined like this:

struct pktdrive {
        char    magic[10];
        char    *type;
        char    *copymsg;
        void    (*initfunc)(void);
        void    (*queuefn)(void *pkt, size_t len);
        void    *(*packetfn)(void);
        void    *(*sendfn)(void);
        int     (*readfn)(void);
        void    (*onlinefn)();
        void    (*offlinefn)(int);
        int     (*statusfn)(void);
};

and now the members, one by one, because we're not skipping anybody:

• magic — magic that identifies the file as a packet driver. it's defined as ZS0PKTDRV. yes it's literally magic, no we don't question it ✨
• type — a pointer to the type of the device.
• copymsg — a pointer to the copyright message.
• initfunc — a function that initialises the device during the initial configuration in this function.
• queuefn — a function that stores outgoing packets in a queue pending sending. depending on how fast the device is, it may also inject packets into the interface. multitasking queen 🫶
• packetfn — a function that returns the address of the incoming packet. it's called immediately after initialisation, and also after the readfn function (down below) has returned a packet.
• sendfn — a function called on the interrupt to inject bytes out of the interface. if this function returns non-zero, then the packet at the address returned is freed. bye bestie 💀
• readfn — a function called on the interrupt to read incoming bytes. if it returns non-zero, a packet is assumed to have been read, with length as returned by readfn and lying at the address specified by packetfn.
• onlinefn — a function that's called when the device is to be turned online. we love a glow-up 🔥
• offlinefn — a function that's called when the device is to be turned offline. if the parameter is non-zero then the function should hang up the line (if appropriate), otherwise it should just suspend sending and receiving packets. it's giving "do not disturb" 😭
• statusfn — a function that returns the status of the device. the idea is it returns 0 for offline and 1 for online, though it may return other values. what that value actually means is left for the user to understand. cryptic on purpose, iykyk 💅

---

⭐ NOTES ⭐

when the packet is passed to the driver for output, 4 bytes of header space is available at dp-4. the SLIP driver by Dominic Morris uses these bytes to implement a linked list and to hold the length of the outgoing packet. iconic behaviour honestly. 👑

other packet drivers might wanna copy the packet to their own address space so they can convert it into other forms — eg CSLIP form. alternatively, they might just create a link from their own space to the packet in the queue, so as to reduce time wasted copying bytes. efficient queen, we stan 🌈

---

💜 AUTHOR 💜

Dominic Morris <dom@jb.man.ac.uk> — thank you for your service, king 🫶

---

aaaand that's the whole page, bestie. this lil slice of the z88dk Programmer's Manual was dated 18 February 2000, and it's filed under pktdrive(3z). go forth and write your packet driver, you've absolutely got this 💖✨🎀