Provided by: ax25-tools_0.0.8-13.1ubuntu1_i386 bug

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,
       (sailer@ife.ee.ethz.ch).