1HDLCDRV(9) Kernel Reference Guide HDLCDRV(9)
2
6 hdlcdrv - HDLC amateur (AX.25) packet radio network driver
7
9 #include <linux/hdlcdrv.h>
10 linux/drivers/net/hdlcdrv.c
12 extern inline void hdlcdrv_putbits(struct hdlcdrv_state * s, unsigned
14 int bits);
15 extern inline unsigned int hdlcdrv_getbits(struct hdlcdrv_state * s);
17 extern inline void hdlcdrv_channelbit(struct hdlcdrv_state * s,
19 unsigned int bit);
20 extern inline void hdlcdrv_setdcd(struct hdlcdrv_state * s , int dcd);
22 extern inline int hdlcdrv_ptt(struct hdlcdrv_state * s);
24 void hdlcdrv_receiver(struct device *, struct hdlcdrv_state *);
26 void hdlcdrv_transmitter(struct device *, struct hdlcdrv_state *);
28 void hdlcdrv_arbitrate(struct device *, struct hdlcdrv_state *);
30 int hdlcdrv_register_hdlcdrv(struct device * dev, struct hdlcdrv_ops *
32 ops, unsigned int privsize, char * ifname, unsigned int baseaddr ,
33 unsigned int irq, unsigned int dma);
34 int hdlcdrv_unregister_hdlcdrv(struct device * dev);
36
39 This driver should ease the implementation of simple AX.25 packet radio
40 modems where the software is responsible for the HDLC encoding and
41 decoding. Examples of such modems include the baycom family and the
42 soundcard modems.
43 This driver provides a standard Linux network driver interface. It can
45 even be compiled if Kernel AX.25 is not enabled in the Linux configura‐
46 tion. This allows this driver to be used even for userland AX.25 stacks
47 such as Wampes or TNOS, with the help of the net2kiss utility.
48 This driver does not access any hardware; it is the responsibility of
50 an additional hardware driver such as baycom or soundmodem to access
51 the hardware and derive the bitstream to feed into this driver.
52 The hardware driver should store its state in a structure of the fol‐
54 lowing form:
55 struct hwdrv_state {
57 struct hdlc_state hdrv;
58 ... the drivers private state
60 };
61 A pointer to this structure will be stored in dev->priv.
63 hdlcdrv_register_hdlcdrv registers a hardware driver to the hdlc
65 driver. dev points to storage for the device structure, which must be
66 provided by the hardware driver, but gets initialized by this function
67 call. ops provides information about the hardware driver and its calls.
68 privsize should be sizeof(struct hwdrv_state). ifname specifies the
69 name the interface should get. baseaddr, irq and dma are simply stored
70 in the device structure. After this function succeeds, the interface
71 is registered with the kernel. It is not running, however, this must
72 be done with ifconfig ifname up.
73 hdlcdrv_unregister_hdlcdrv shuts the interface down and unregisters it
75 with the kernel.
76 hdlcdrv_putbits delivers 16 received bits for processing to the HDLC
78 driver. This routine merely stores them in a buffer and does not
79 process them. It is thus fast and can be called with interrupts off.
80 The least significant bit should be the first one received.
81 hdlcdrv_getbits requests 16 bits from the driver for transmission. The
83 least significant bit should be transmitted first. This routine takes
84 them from a buffer and is therefore fast. It can be called with inter‐
85 rupts off.
86 hdlcdrv_channelbit puts a single bit into a buffer, which can be dis‐
88 played with sethdlc -s. It is intended for driver debugging purposes.
89 hdlcdrv_setdcd informs the HDLC driver about the channel state (i.e. if
91 the hardware driver detected a data carrier). This information is used
92 in the channel access algorithm, i.e. it prevents the driver from
93 transmitting on a half duplex channel if there is already a transmitter
94 on air.
95 hdlcdrv_ptt should be called by the hardware driver to determine if it
97 should start or stop transmitting. The hardware driver does not need to
98 worry about keyup delays. This is done by the HDLC driver.
99 hdlcdrv_receiver actually processes the received bits delivered by hdl‐
101 cdrv_putbits. It should be called with interrupts on. It guards itself
102 against reentrance problems.
103 hdlcdrv_transmitter actually prepares the bits to be transmitted. It
105 should be called with interrupts on. It guards itself against reen‐
106 trance problems.
107 hdlcdrv_arbitrate does the channel access algorithm (p-persistent
109 CSMA). It should be called once every 10ms. Note that the hardware
110 driver must set the hdrv.par.bitrate field prior to starting operation
111 so that hdlcdrv can calculate the transmitter keyup delay correctly.
112
115 The hardware driver should provide the following information to the
116 HDLC driver:
117 struct hdlcdrv_ops {
119 const char *drvname;
120 const char *drvinfo;
121 int (*open)(struct device *);
122 int (*close)(struct device *);
123 int (*ioctl)(struct device *, struct ifreq *, int);
124 };
125 drvname and drvinfo are just for informational purposes.
127 The following routines receive a pointer to the device structure, where
129 they may find the io address, irq and dma channels.
130 open must be provided. It is called during ifconfig ifname up and
132 should check for the hardware, grab it and initialize it. It usually
133 installs an interrupt handler which then gets invoked by the hardware.
134 close must be provided. It is called during ifconfig ifname down and
136 should undo all actions done by open, i.e. release io regions and irqs.
137 ioctl may be provided to implement device specific ioctl's.
139
142 The driver only responds to SIOCDEVPRIVATE. Parameters are passed from
143 and to the driver using the following struct:
144 struct hdlcdrv_ioctl {
146 int cmd;
147 union {
148 struct hdlcdrv_params mp;
149 struct hdlcdrv_channel_params cp;
150 struct hdlcdrv_channel_state cs;
151 unsigned int calibrate;
152 unsigned char bits;
153 } data;
154 };
155 Since the 16 private ioctl request numbers for network drivers were not
157 enough, the driver implements its own sub request number with cmd. The
158 following numbers are implemented:
159 HDLCDRVCTL_GETMODEMPAR
162 returns the IO parameters of the modem in data.mp. This includes
163 the io address, irq, eventually dma, and ports to output a PTT
164 signal.
165 HDLCDRVCTL_SETMODEMPAR
168 sets the modem parameters. Only superuser can do this. Parame‐
169 ters can only be changed if the interface is not running (i.e.
170 down).
171 HDLCDRVCTL_GETCHANNELPAR
174 returns the channel access parameters.
175 HDLCDRVCTL_SETCHANNELPAR
178 sets the channel access parameters. Only superuser can do this.
179 They may also be changed using the kissparms command if using
180 kernel AX.25 or the param command of *NOS.
181 HDLCDRVCTL_GETSTAT
184 statistics and status information, such as if a carrier is
185 detected on the channel and if the interface is currently trans‐
186 mitting.
187 HDLCDRVCTL_CALIBRATE
190 instructs the driver to transmit a calibration pattern for the
191 specified number of seconds.
192 HDLCDRVCTL_GETSAMPLES
195 returns the bits delivered by the hardware driver with hdl‐
196 cdrv_channelbit. The bits are returned 8 at a time with the
197 least significant bit the first one. This command may not be
198 available, depending on debugging settings.
199 HDLCDRVCTL_GETBITS
202 returns the bits delivered by the hardware driver to the HDLC
203 decoder. The bits are returned 8 at a time with the least sig‐
204 nificant bit the first one. This command may not be available,
205 depending on debugging settings.
206
209 baycom (9), soundmodem (9), sethdlc (8), linux/drivers/net/hdlcdrv.c,
210
213 hdlcdrv was written by Thomas Sailer, HB9JNX/AE4WA,
214 (t.sailer@alumni.ethz.ch).
215Linux 2.1.x 2 October 1996 HDLCDRV(9)