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 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.

HARDWARE DRIVER ENTRY POINTS

       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.

IOCTL CALLS

       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.

SEE ALSO

       baycom (9), soundmodem (9), sethdlc (8), linux/drivers/net/hdlcdrv.c,

AUTHOR

       hdlcdrv was written by Thomas Sailer, HB9JNX/AE4WA, (t.sailer@alumni.ethz.ch).