pktdrive(3z)

NAME
pktdrive - packet driver descriptor structure

SYNOPSIS
#include <net/device.h>

DESCRIPTION
The pktdrive structure defines access to a device, it is only used by the ZSock kernel. Should you wish to write a packet driver then this structure should be filled with the relevent routines.

All external packet drivers run at address 8192 ($2000) and it as this address that the structure should be placed. Had z88dk the capability pktdrive would be defined as follows:

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

The members of the pktdrive structure are:

magic
    Magic to identifier the file as a packet driver, this is defined as ZS0PKTDRV

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 configurationin this function.

queuefn
    A function that stores outgoing backets in a queue pending sending. Depending on the speed of the device it may also inject packets into the interface.

packetfn
    A function that returns the address of the incoming packet. This function is called immediately after initialisation and after the readfn function (below) has returned a packet.

sendfn
    A function that is called on the interrupt to inject bytes out of the interface. If this function returns non-zero then packet at the address returned is freed.

readfn
    A function that is called on the interrupt to read incoming bytes. If the function returns non-zero then 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 is called when the device is to be turned online

offlinefn
    A function that is called when the device is to be turned offline, if the parameter is non-zero then the function should hang up line (if appropriate) otherwise it should just suspend sending and receiving packets.

statusfn
    A function that returns the status of the device. It is envisaged that it will return 0 for offline and 1 for online though it may return other values. The value returned is left for the user to understand.

NOTES
When the packet is passed to the driver for output a 4 bytes of header space is available at dp-4. The SLIP driver by Dominic Morris utilises these bytes to implement a linked list and to hold the length of the outgoing packet.

Other packet drivers might wish to copy the packet to their own address space for converting into other forms - eg CSLIP form. Alternatively they might simply create a link from their own space to the packet in the queue so to reduce time wasted copying bytes.

AUTHOR
Dominic Morris <dom@jb.man.ac.uk>