Linux-2.6.12-rc2
[linux-2.6.git] / Documentation / DocBook / z8530book.tmpl
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5 <book id="Z85230Guide">
6  <bookinfo>
7   <title>Z8530 Programming Guide</title>
8   
9   <authorgroup>
10    <author>
11     <firstname>Alan</firstname>
12     <surname>Cox</surname>
13     <affiliation>
14      <address>
15       <email>alan@redhat.com</email>
16      </address>
17     </affiliation>
18    </author>
19   </authorgroup>
20
21   <copyright>
22    <year>2000</year>
23    <holder>Alan Cox</holder>
24   </copyright>
25
26   <legalnotice>
27    <para>
28      This documentation is free software; you can redistribute
29      it and/or modify it under the terms of the GNU General Public
30      License as published by the Free Software Foundation; either
31      version 2 of the License, or (at your option) any later
32      version.
33    </para>
34       
35    <para>
36      This program is distributed in the hope that it will be
37      useful, but WITHOUT ANY WARRANTY; without even the implied
38      warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
39      See the GNU General Public License for more details.
40    </para>
41       
42    <para>
43      You should have received a copy of the GNU General Public
44      License along with this program; if not, write to the Free
45      Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
46      MA 02111-1307 USA
47    </para>
48       
49    <para>
50      For more details see the file COPYING in the source
51      distribution of Linux.
52    </para>
53   </legalnotice>
54  </bookinfo>
55
56 <toc></toc>
57
58   <chapter id="intro">
59       <title>Introduction</title>
60   <para>
61         The Z85x30 family synchronous/asynchronous controller chips are
62         used on a large number of cheap network interface cards. The
63         kernel provides a core interface layer that is designed to make
64         it easy to provide WAN services using this chip.
65   </para>
66   <para>
67         The current driver only support synchronous operation. Merging the
68         asynchronous driver support into this code to allow any Z85x30
69         device to be used as both a tty interface and as a synchronous 
70         controller is a project for Linux post the 2.4 release
71   </para>
72   <para>
73         The support code handles most common card configurations and
74         supports running both Cisco HDLC and Synchronous PPP. With extra
75         glue the frame relay and X.25 protocols can also be used with this
76         driver.
77   </para>
78   </chapter>
79   
80   <chapter>
81         <title>Driver Modes</title>
82   <para>
83         The Z85230 driver layer can drive Z8530, Z85C30 and Z85230 devices
84         in three different modes. Each mode can be applied to an individual
85         channel on the chip (each chip has two channels).
86   </para>
87   <para>
88         The PIO synchronous mode supports the most common Z8530 wiring. Here
89         the chip is interface to the I/O and interrupt facilities of the
90         host machine but not to the DMA subsystem. When running PIO the
91         Z8530 has extremely tight timing requirements. Doing high speeds,
92         even with a Z85230 will be tricky. Typically you should expect to
93         achieve at best 9600 baud with a Z8C530 and 64Kbits with a Z85230.
94   </para>
95   <para>
96         The DMA mode supports the chip when it is configured to use dual DMA
97         channels on an ISA bus. The better cards tend to support this mode
98         of operation for a single channel. With DMA running the Z85230 tops
99         out when it starts to hit ISA DMA constraints at about 512Kbits. It
100         is worth noting here that many PC machines hang or crash when the
101         chip is driven fast enough to hold the ISA bus solid.
102   </para>
103   <para>
104         Transmit DMA mode uses a single DMA channel. The DMA channel is used
105         for transmission as the transmit FIFO is smaller than the receive
106         FIFO. it gives better performance than pure PIO mode but is nowhere
107         near as ideal as pure DMA mode. 
108   </para>
109   </chapter>
110
111   <chapter>
112         <title>Using the Z85230 driver</title>
113   <para>
114         The Z85230 driver provides the back end interface to your board. To
115         configure a Z8530 interface you need to detect the board and to 
116         identify its ports and interrupt resources. It is also your problem
117         to verify the resources are available.
118   </para>
119   <para>
120         Having identified the chip you need to fill in a struct z8530_dev,
121         which describes each chip. This object must exist until you finally
122         shutdown the board. Firstly zero the active field. This ensures 
123         nothing goes off without you intending it. The irq field should
124         be set to the interrupt number of the chip. (Each chip has a single
125         interrupt source rather than each channel). You are responsible
126         for allocating the interrupt line. The interrupt handler should be
127         set to <function>z8530_interrupt</function>. The device id should
128         be set to the z8530_dev structure pointer. Whether the interrupt can
129         be shared or not is board dependent, and up to you to initialise.
130   </para>
131   <para>
132         The structure holds two channel structures. 
133         Initialise chanA.ctrlio and chanA.dataio with the address of the
134         control and data ports. You can or this with Z8530_PORT_SLEEP to
135         indicate your interface needs the 5uS delay for chip settling done
136         in software. The PORT_SLEEP option is architecture specific. Other
137         flags may become available on future platforms, eg for MMIO.
138         Initialise the chanA.irqs to &amp;z8530_nop to start the chip up
139         as disabled and discarding interrupt events. This ensures that
140         stray interrupts will be mopped up and not hang the bus. Set
141         chanA.dev to point to the device structure itself. The
142         private and name field you may use as you wish. The private field
143         is unused by the Z85230 layer. The name is used for error reporting
144         and it may thus make sense to make it match the network name.
145   </para>
146   <para>
147         Repeat the same operation with the B channel if your chip has
148         both channels wired to something useful. This isn't always the
149         case. If it is not wired then the I/O values do not matter, but
150         you must initialise chanB.dev.
151   </para>
152   <para>
153         If your board has DMA facilities then initialise the txdma and
154         rxdma fields for the relevant channels. You must also allocate the
155         ISA DMA channels and do any necessary board level initialisation
156         to configure them. The low level driver will do the Z8530 and
157         DMA controller programming but not board specific magic.
158   </para>
159   <para>
160         Having initialised the device you can then call
161         <function>z8530_init</function>. This will probe the chip and 
162         reset it into a known state. An identification sequence is then
163         run to identify the chip type. If the checks fail to pass the
164         function returns a non zero error code. Typically this indicates
165         that the port given is not valid. After this call the
166         type field of the z8530_dev structure is initialised to either
167         Z8530, Z85C30 or Z85230 according to the chip found.
168   </para>
169   <para>
170         Once you have called z8530_init you can also make use of the utility
171         function <function>z8530_describe</function>. This provides a 
172         consistent reporting format for the Z8530 devices, and allows all
173         the drivers to provide consistent reporting.
174   </para>
175   </chapter>
176
177   <chapter>
178         <title>Attaching Network Interfaces</title>
179   <para>
180         If you wish to use the network interface facilities of the driver,
181         then you need to attach a network device to each channel that is
182         present and in use. In addition to use the SyncPPP and Cisco HDLC
183         you need to follow some additional plumbing rules. They may seem 
184         complex but a look at the example hostess_sv11 driver should
185         reassure you.
186   </para>
187   <para>
188         The network device used for each channel should be pointed to by
189         the netdevice field of each channel. The dev-&gt; priv field of the
190         network device points to your private data - you will need to be
191         able to find your ppp device from this. In addition to use the
192         sync ppp layer the private data must start with a void * pointer
193         to the syncppp structures.
194   </para>
195   <para>
196         The way most drivers approach this particular problem is to
197         create a structure holding the Z8530 device definition and
198         put that and the syncppp pointer into the private field of
199         the network device. The network device fields of the channels
200         then point back to the network devices. The ppp_device can also
201         be put in the private structure conveniently.
202   </para>
203   <para>
204         If you wish to use the synchronous ppp then you need to attach
205         the syncppp layer to the network device. You should do this before
206         you register the network device. The
207         <function>sppp_attach</function> requires that the first void *
208         pointer in your private data is pointing to an empty struct
209         ppp_device. The function fills in the initial data for the
210         ppp/hdlc layer.
211   </para>
212   <para>
213         Before you register your network device you will also need to
214         provide suitable handlers for most of the network device callbacks. 
215         See the network device documentation for more details on this.
216   </para>
217   </chapter>
218
219   <chapter>
220         <title>Configuring And Activating The Port</title>
221   <para>
222         The Z85230 driver provides helper functions and tables to load the
223         port registers on the Z8530 chips. When programming the register
224         settings for a channel be aware that the documentation recommends
225         initialisation orders. Strange things happen when these are not
226         followed. 
227   </para>
228   <para>
229         <function>z8530_channel_load</function> takes an array of
230         pairs of initialisation values in an array of u8 type. The first
231         value is the Z8530 register number. Add 16 to indicate the alternate
232         register bank on the later chips. The array is terminated by a 255.
233   </para>
234   <para>
235         The driver provides a pair of public tables. The
236         z8530_hdlc_kilostream table is for the UK 'Kilostream' service and
237         also happens to cover most other end host configurations. The
238         z8530_hdlc_kilostream_85230 table is the same configuration using
239         the enhancements of the 85230 chip. The configuration loaded is
240         standard NRZ encoded synchronous data with HDLC bitstuffing. All
241         of the timing is taken from the other end of the link.
242   </para>
243   <para>
244         When writing your own tables be aware that the driver internally
245         tracks register values. It may need to reload values. You should
246         therefore be sure to set registers 1-7, 9-11, 14 and 15 in all
247         configurations. Where the register settings depend on DMA selection
248         the driver will update the bits itself when you open or close.
249         Loading a new table with the interface open is not recommended.
250   </para>
251   <para>
252         There are three standard configurations supported by the core
253         code. In PIO mode the interface is programmed up to use
254         interrupt driven PIO. This places high demands on the host processor
255         to avoid latency. The driver is written to take account of latency
256         issues but it cannot avoid latencies caused by other drivers,
257         notably IDE in PIO mode. Because the drivers allocate buffers you
258         must also prevent MTU changes while the port is open.
259   </para>
260   <para>
261         Once the port is open it will call the rx_function of each channel
262         whenever a completed packet arrived. This is invoked from
263         interrupt context and passes you the channel and a network      
264         buffer (struct sk_buff) holding the data. The data includes
265         the CRC bytes so most users will want to trim the last two
266         bytes before processing the data. This function is very timing
267         critical. When you wish to simply discard data the support
268         code provides the function <function>z8530_null_rx</function>
269         to discard the data.
270   </para>
271   <para>
272         To active PIO mode sending and receiving the <function>
273         z8530_sync_open</function> is called. This expects to be passed
274         the network device and the channel. Typically this is called from
275         your network device open callback. On a failure a non zero error
276         status is returned. The <function>z8530_sync_close</function> 
277         function shuts down a PIO channel. This must be done before the 
278         channel is opened again and before the driver shuts down 
279         and unloads.
280   </para>
281   <para>
282         The ideal mode of operation is dual channel DMA mode. Here the
283         kernel driver will configure the board for DMA in both directions.
284         The driver also handles ISA DMA issues such as controller
285         programming and the memory range limit for you. This mode is
286         activated by calling the <function>z8530_sync_dma_open</function>
287         function. On failure a non zero error value is returned.
288         Once this mode is activated it can be shut down by calling the
289         <function>z8530_sync_dma_close</function>. You must call the close
290         function matching the open mode you used.
291   </para>
292   <para>
293         The final supported mode uses a single DMA channel to drive the
294         transmit side. As the Z85C30 has a larger FIFO on the receive
295         channel this tends to increase the maximum speed a little. 
296         This is activated by calling the <function>z8530_sync_txdma_open
297         </function>. This returns a non zero error code on failure. The
298         <function>z8530_sync_txdma_close</function> function closes down
299         the Z8530 interface from this mode.
300   </para>
301   </chapter>
302
303   <chapter>
304         <title>Network Layer Functions</title>
305   <para>
306         The Z8530 layer provides functions to queue packets for
307         transmission. The driver internally buffers the frame currently
308         being transmitted and one further frame (in order to keep back
309         to back transmission running). Any further buffering is up to
310         the caller.
311   </para>
312   <para>
313         The function <function>z8530_queue_xmit</function> takes a network
314         buffer in sk_buff format and queues it for transmission. The
315         caller must provide the entire packet with the exception of the
316         bitstuffing and CRC. This is normally done by the caller via
317         the syncppp interface layer. It returns 0 if the buffer has been 
318         queued and non zero values  for queue full. If the function accepts 
319         the buffer it becomes property of the Z8530 layer and the caller 
320         should not free it. 
321   </para>
322   <para>
323         The function <function>z8530_get_stats</function> returns a pointer
324         to an internally maintained per interface statistics block. This
325         provides most of the interface code needed to implement the network
326         layer get_stats callback.
327   </para>
328   </chapter>
329
330   <chapter>
331      <title>Porting The Z8530 Driver</title>
332   <para>
333         The Z8530 driver is written to be portable. In DMA mode it makes
334         assumptions about the use of ISA DMA. These are probably warranted
335         in most cases as the Z85230 in particular was designed to glue to PC
336         type machines. The PIO mode makes no real assumptions.
337   </para>
338   <para>
339         Should you need to retarget the Z8530 driver to another architecture
340         the only code that should need changing are the port I/O functions.
341         At the moment these assume PC I/O port accesses. This may not be
342         appropriate for all platforms. Replacing 
343         <function>z8530_read_port</function> and <function>z8530_write_port
344         </function> is intended to be all that is required to port this
345         driver layer.
346   </para>
347   </chapter>
348
349   <chapter id="bugs">
350      <title>Known Bugs And Assumptions</title>
351   <para>
352   <variablelist>
353     <varlistentry><term>Interrupt Locking</term>
354     <listitem>
355     <para>
356         The locking in the driver is done via the global cli/sti lock. This
357         makes for relatively poor SMP performance. Switching this to use a
358         per device spin lock would probably materially improve performance.
359     </para>
360     </listitem></varlistentry>
361
362     <varlistentry><term>Occasional Failures</term>
363     <listitem>
364     <para>
365         We have reports of occasional failures when run for very long
366         periods of time and the driver starts to receive junk frames. At
367         the moment the cause of this is not clear.
368     </para>
369     </listitem></varlistentry>
370   </variablelist>
371         
372   </para>
373   </chapter>
374
375   <chapter id="pubfunctions">
376      <title>Public Functions Provided</title>
377 !Edrivers/net/wan/z85230.c
378   </chapter>
379
380   <chapter id="intfunctions">
381      <title>Internal Functions</title>
382 !Idrivers/net/wan/z85230.c
383   </chapter>
384
385 </book>