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