Contents of /alx-src/trunk/kernel26-alx/linux/Documentation/DocBook/z8530book.tmpl
Parent Directory | Revision Log
Revision 628 -
(show annotations)
(download)
Wed Mar 4 10:48:58 2009 UTC (15 years, 2 months ago) by niro
File size: 15620 byte(s)
Wed Mar 4 10:48:58 2009 UTC (15 years, 2 months ago) by niro
File size: 15620 byte(s)
import linux sources based on 2.6.12-alx-r9: -using linux-2.6.12.6 -using 2.6.12-ck6 patch set -using fbsplash-0.9.2-r3 -using vesafb-tng-0.9-rc7 -using squashfs-2.2 -added cddvd-cmdfilter-drop.patch as ck dropped it -added via-epia-dri (cle266) patch -added zd1211-svn-32 wlan driver (http://zd1211.ath.cx/download/) -added debian patches to zd1211 for wep256 etc
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 &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-> 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> |