hdlcdrv - HDLC amateur (AX.25) packet radio network driver
#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);
This driver should ease the implementation of simple AX.25 packet radio modems
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 Linux configuration. This
allows this driver to be used even for userland AX.25 stacks such as
Wampes or
TNOS, with the help of the
net2kiss utility.
This driver does not access any hardware; it is the responsibility of an
additional hardware driver such as
baycom or
soundmodem to
access the hardware and derive the bitstream to feed into this driver.
The hardware driver should store its state in a structure of the following 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 the hdlc driver.
dev points to storage for the
device structure, which must be
provided by the hardware driver, but gets initialized by this function call.
ops provides information about the hardware driver and 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 with
ifconfig ifname up.
hdlcdrv_unregister_hdlcdrv shuts the interface down and unregisters it
with the kernel.
hdlcdrv_putbits delivers 16 received bits for processing to the HDLC
driver. 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 significant
bit 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 takes them
from a buffer and is therefore fast. It can be called with interrupts off.
hdlcdrv_channelbit puts a single bit into a buffer, which can be
displayed with
sethdlc -s. It is intended for driver debugging
purposes.
hdlcdrv_setdcd informs the HDLC driver about the channel state (i.e. if
the hardware driver detected a data carrier). This information is used in the
channel access algorithm, i.e. it prevents the driver from transmitting on a
half duplex channel if there is already a transmitter on air.
hdlcdrv_ptt should be called by the hardware driver to determine if it
should start or stop transmitting. The hardware driver does not need to worry
about keyup delays. This is done by the HDLC driver.
hdlcdrv_receiver actually processes the received bits delivered by
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 against reentrance
problems.
hdlcdrv_arbitrate does the channel access algorithm (p-persistent CSMA).
It should be called once every 10ms. Note that the hardware driver
must
set the
hdrv.par.bitrate field prior to starting operation so that
hdlcdrv can calculate the transmitter keyup delay correctly.
The hardware driver should provide the following information to the 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 during
ifconfig ifname up and should check for
the hardware, grab it and initialize it. It usually installs an interrupt
handler which then gets invoked by the hardware.
close must be provided. It is called during
ifconfig ifname down and should undo all
actions done by
open, i.e. release io regions and irqs.
ioctl may be provided to implement device specific ioctl's.
The driver only responds to
SIOCDEVPRIVATE. Parameters are passed from
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 drivers
were not enough, the driver implements its own
sub request
number with
cmd. The following numbers are implemented:
- HDLCDRVCTL_GETMODEMPAR
- returns the IO parameters of the modem in data.mp.
This includes the io address, irq, eventually dma, and ports to output a
PTT signal.
- HDLCDRVCTL_SETMODEMPAR
- sets the modem parameters. Only superuser can do this.
Parameters can 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 using
kernel AX.25 or the param command of *NOS.
- HDLCDRVCTL_GETSTAT
- statistics and status information, such as if a carrier is
detected on the channel and if the interface is currently transmitting.
- HDLCDRVCTL_CALIBRATE
- instructs the driver to transmit a calibration pattern for
the specified number of seconds.
- HDLCDRVCTL_GETSAMPLES
- returns the bits delivered by the hardware driver with
hdlcdrv_channelbit. The bits are returned 8 at a time with the
least significant bit the first one. This command may not be available,
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 the first one. This command may not be available, depending on
debugging settings.
baycom (9),
soundmodem (9),
sethdlc (8), linux/drivers/net/hdlcdrv.c,
hdlcdrv was written by Thomas Sailer, HB9JNX/AE4WA,
(
[email protected]).