MAN page from Mandrake Other ax25-utils-2.1.42a-3.i386.rpm

HDLCDRV

Section: Kernel Reference Guide (9)
Updated: 2 October 1996
Index

NAME

hdlcdrv - HDLC amateur (AX.25) packet radio network driver

SYNOPSIS

#include <linux/hdlcdrv.h>

linux/drivers/net/hdlcdrv.c

extern inline void hdlcdrv_putbits(struct hdlcdrv_state * s, unsigned int bits);

extern inline unsigned int hdlcdrv_getbits(struct hdlcdrv_state * s);

extern inline void hdlcdrv_channelbit(struct hdlcdrv_state * s, unsigned int bit);

extern inline void hdlcdrv_setdcd(struct hdlcdrv_state * s , int dcd);

extern inline int hdlcdrv_ptt(struct hdlcdrv_state * s);

void hdlcdrv_receiver(struct device *, struct hdlcdrv_state *);

void hdlcdrv_transmitter(struct device *, struct hdlcdrv_state *);

void hdlcdrv_arbitrate(struct device *, struct hdlcdrv_state *);

int hdlcdrv_register_hdlcdrv(struct device * dev, struct hdlcdrv_ops * ops, unsigned int privsize, char * ifname, unsigned int baseaddr , unsigned int irq, unsigned int dma);

int hdlcdrv_unregister_hdlcdrv(struct device * dev);

DESCRIPTION

This driver should ease the implementation of simple AX.25 packet radiomodems where the software is responsible for the HDLC encoding and decoding.Examples of such modems include the baycom family and the soundcard modems.

This driver provides a standard Linux network driver interface.It can even be compiled if Kernel AX.25 is not enabled in the Linuxconfiguration. This allows this driver to be used even for userlandAX.25 stacks such as Wampes or TNOS, with the help ofthe net2kiss utility.

This driver does not access any hardware; it is the responsibility ofan additional hardware driver such as baycom or soundmodemto access the hardware and derive the bitstream to feed into thisdriver.

The hardware driver should store its state in a structure of thefollowing form:

struct hwdrv_state {        struct hdlc_state hdrv;        ... the drivers private state};

A pointer to this structure will be stored in dev->priv.

hdlcdrv_register_hdlcdrv registers a hardware driver to thehdlc driver. dev points to storage for the device structure,which must be provided by the hardware driver, but gets initialized bythis function call. ops provides information about the hardware driverand its calls. privsize should be sizeof(struct hwdrv_state).ifname specifies the name the interface should get. baseaddr,irq and dma are simply stored in the device structure.After this function succeeds, the interface is registered with the kernel.It is not running, however, this must be done withifconfig ifname up.

hdlcdrv_unregister_hdlcdrv shuts the interface down and unregistersit with the kernel.

hdlcdrv_putbits delivers 16 received bits for processing to the HDLCdriver. This routine merely stores them in a buffer and does not process them.It is thus fast and can be called with interrupts off. The least significantbit should be the first one received.

hdlcdrv_getbits requests 16 bits from the driver for transmission.The least significant bit should be transmitted first. This routine takesthem from a buffer and is therefore fast. It can be called with interruptsoff.

hdlcdrv_channelbit puts a single bit into a buffer, which can bedisplayed with sethdlc -s. It is intended for driver debuggingpurposes.

hdlcdrv_setdcd informs the HDLC driver about the channel state(i.e. if the hardware driver detected a data carrier). This informationis used in the channel access algorithm, i.e. it prevents the driverfrom transmitting on a half duplex channel if there is already atransmitter on air.

hdlcdrv_ptt should be called by the hardware driver to determineif it should start or stop transmitting. The hardware driver does notneed to worry about keyup delays. This is done by the HDLC driver.

hdlcdrv_receiver actually processes the received bits deliveredby hdlcdrv_putbits. It should be called with interrupts on.It guards itself against reentrance problems.

hdlcdrv_transmitter actually prepares the bits to be transmitted.It should be called with interrupts on. It guards itself againstreentrance problems.

hdlcdrv_arbitrate does the channel access algorithm(p-persistent CSMA). It should be called once every 10ms. Note that thehardware driver must set the hdrv.par.bitrate field priorto starting operation so that hdlcdrv can calculate the transmitterkeyup delay correctly.

HARDWARE DRIVER ENTRY POINTS

The hardware driver should provide the following information tothe HDLC driver:

struct hdlcdrv_ops {        const char *drvname;        const char *drvinfo;        int (*open)(struct device *);        int (*close)(struct device *);        int (*ioctl)(struct device *, struct ifreq *, int);};

drvname and drvinfo are just for informational purposes.

The following routines receive a pointer to the device structure,where they may find the io address, irq and dma channels.

open must be provided. It is called duringifconfig ifname up and should check for the hardware,grab it and initialize it. It usually installs an interrupt handlerwhich then gets invoked by the hardware.

close must be provided. It is called duringifconfig ifname down and should undo all actions doneby open, i.e. release io regions and irqs.

ioctl may be provided to implement device specific ioctl's.

IOCTL CALLS

The driver only responds to SIOCDEVPRIVATE. Parameters are passedfrom and to the driver using the following struct:

struct hdlcdrv_ioctl {        int cmd;        union {                struct hdlcdrv_params mp;                struct hdlcdrv_channel_params cp;                struct hdlcdrv_channel_state cs;                unsigned int calibrate;                unsigned char bits;        } data;};

Since the 16 private ioctl request numbers for network driverswere not enough, the driver implements its own sub request numberwith cmd. The following numbers are implemented:

HDLCDRVCTL_GETMODEMPAR: returns the IO parameters of the modem in data.mp. This includesthe io address, irq, eventually dma, and ports to output a PTT signal.
HDLCDRVCTL_SETMODEMPAR: sets the modem parameters. Only superuser can do this. Parameterscan only be changed if the interface is not running (i.e. down).
HDLCDRVCTL_GETCHANNELPAR: returns the channel access parameters.
HDLCDRVCTL_SETCHANNELPAR: sets the channel access parameters. Only superuser can do this.They may also be changed using the kissparms command if usingkernel AX.25 or the param command of *NOS.
HDLCDRVCTL_GETSTAT: statistics and status information, such as if a carrier is detectedon the channel and if the interface is currently transmitting.
HDLCDRVCTL_CALIBRATE: instructs the driver to transmit a calibration pattern for thespecified number of seconds.
HDLCDRVCTL_GETSAMPLES: returns the bits delivered by the hardware driver withhdlcdrv_channelbit. The bits are returned 8 at a timewith the least significant bit the first one. This command may not beavailable, depending on debugging settings.
HDLCDRVCTL_GETBITS: returns the bits delivered by the hardware driver to the HDLC decoder.The bits are returned 8 at a time with the least significant bit thefirst one. This command may not be available, depending on debuggingsettings.

AUTHOR

hdlcdrv was written by Thomas Sailer, HB9JNX/AE4WA, (sailerAATTife.ee.ethz.ch).

This document was created byman2html,using the manual pages.