Commit | Line | Data |
---|---|---|
c7e21544 MCC |
1 | ======================= |
2 | Z8530 Programming Guide | |
3 | ======================= | |
4 | ||
5 | :Author: Alan Cox | |
6 | ||
7 | Introduction | |
8 | ============ | |
9 | ||
10 | The Z85x30 family synchronous/asynchronous controller chips are used on | |
11 | a large number of cheap network interface cards. The kernel provides a | |
12 | core interface layer that is designed to make it easy to provide WAN | |
13 | services using this chip. | |
14 | ||
15 | The current driver only support synchronous operation. Merging the | |
16 | asynchronous driver support into this code to allow any Z85x30 device to | |
17 | be used as both a tty interface and as a synchronous controller is a | |
18 | project for Linux post the 2.4 release | |
19 | ||
20 | Driver Modes | |
21 | ============ | |
22 | ||
23 | The Z85230 driver layer can drive Z8530, Z85C30 and Z85230 devices in | |
24 | three different modes. Each mode can be applied to an individual channel | |
25 | on the chip (each chip has two channels). | |
26 | ||
27 | The PIO synchronous mode supports the most common Z8530 wiring. Here the | |
28 | chip is interface to the I/O and interrupt facilities of the host | |
29 | machine but not to the DMA subsystem. When running PIO the Z8530 has | |
30 | extremely tight timing requirements. Doing high speeds, even with a | |
31 | Z85230 will be tricky. Typically you should expect to achieve at best | |
32 | 9600 baud with a Z8C530 and 64Kbits with a Z85230. | |
33 | ||
34 | The DMA mode supports the chip when it is configured to use dual DMA | |
35 | channels on an ISA bus. The better cards tend to support this mode of | |
36 | operation for a single channel. With DMA running the Z85230 tops out | |
37 | when it starts to hit ISA DMA constraints at about 512Kbits. It is worth | |
38 | noting here that many PC machines hang or crash when the chip is driven | |
39 | fast enough to hold the ISA bus solid. | |
40 | ||
41 | Transmit DMA mode uses a single DMA channel. The DMA channel is used for | |
42 | transmission as the transmit FIFO is smaller than the receive FIFO. it | |
43 | gives better performance than pure PIO mode but is nowhere near as ideal | |
44 | as pure DMA mode. | |
45 | ||
46 | Using the Z85230 driver | |
47 | ======================= | |
48 | ||
49 | The Z85230 driver provides the back end interface to your board. To | |
50 | configure a Z8530 interface you need to detect the board and to identify | |
51 | its ports and interrupt resources. It is also your problem to verify the | |
52 | resources are available. | |
53 | ||
54 | Having identified the chip you need to fill in a struct z8530_dev, | |
55 | which describes each chip. This object must exist until you finally | |
56 | shutdown the board. Firstly zero the active field. This ensures nothing | |
57 | goes off without you intending it. The irq field should be set to the | |
58 | interrupt number of the chip. (Each chip has a single interrupt source | |
59 | rather than each channel). You are responsible for allocating the | |
60 | interrupt line. The interrupt handler should be set to | |
61 | :c:func:`z8530_interrupt()`. The device id should be set to the | |
62 | z8530_dev structure pointer. Whether the interrupt can be shared or not | |
63 | is board dependent, and up to you to initialise. | |
64 | ||
65 | The structure holds two channel structures. Initialise chanA.ctrlio and | |
66 | chanA.dataio with the address of the control and data ports. You can or | |
67 | this with Z8530_PORT_SLEEP to indicate your interface needs the 5uS | |
68 | delay for chip settling done in software. The PORT_SLEEP option is | |
69 | architecture specific. Other flags may become available on future | |
70 | platforms, eg for MMIO. Initialise the chanA.irqs to &z8530_nop to | |
71 | start the chip up as disabled and discarding interrupt events. This | |
72 | ensures that stray interrupts will be mopped up and not hang the bus. | |
73 | Set chanA.dev to point to the device structure itself. The private and | |
74 | name field you may use as you wish. The private field is unused by the | |
75 | Z85230 layer. The name is used for error reporting and it may thus make | |
76 | sense to make it match the network name. | |
77 | ||
78 | Repeat the same operation with the B channel if your chip has both | |
79 | channels wired to something useful. This isn't always the case. If it is | |
80 | not wired then the I/O values do not matter, but you must initialise | |
81 | chanB.dev. | |
82 | ||
83 | If your board has DMA facilities then initialise the txdma and rxdma | |
84 | fields for the relevant channels. You must also allocate the ISA DMA | |
85 | channels and do any necessary board level initialisation to configure | |
86 | them. The low level driver will do the Z8530 and DMA controller | |
87 | programming but not board specific magic. | |
88 | ||
89 | Having initialised the device you can then call | |
90 | :c:func:`z8530_init()`. This will probe the chip and reset it into | |
91 | a known state. An identification sequence is then run to identify the | |
92 | chip type. If the checks fail to pass the function returns a non zero | |
93 | error code. Typically this indicates that the port given is not valid. | |
94 | After this call the type field of the z8530_dev structure is | |
95 | initialised to either Z8530, Z85C30 or Z85230 according to the chip | |
96 | found. | |
97 | ||
98 | Once you have called z8530_init you can also make use of the utility | |
99 | function :c:func:`z8530_describe()`. This provides a consistent | |
100 | reporting format for the Z8530 devices, and allows all the drivers to | |
101 | provide consistent reporting. | |
102 | ||
103 | Attaching Network Interfaces | |
104 | ============================ | |
105 | ||
106 | If you wish to use the network interface facilities of the driver, then | |
107 | you need to attach a network device to each channel that is present and | |
108 | in use. In addition to use the generic HDLC you need to follow some | |
109 | additional plumbing rules. They may seem complex but a look at the | |
110 | example hostess_sv11 driver should reassure you. | |
111 | ||
112 | The network device used for each channel should be pointed to by the | |
113 | netdevice field of each channel. The hdlc-> priv field of the network | |
114 | device points to your private data - you will need to be able to find | |
115 | your private data from this. | |
116 | ||
117 | The way most drivers approach this particular problem is to create a | |
118 | structure holding the Z8530 device definition and put that into the | |
119 | private field of the network device. The network device fields of the | |
120 | channels then point back to the network devices. | |
121 | ||
122 | If you wish to use the generic HDLC then you need to register the HDLC | |
123 | device. | |
124 | ||
125 | Before you register your network device you will also need to provide | |
126 | suitable handlers for most of the network device callbacks. See the | |
127 | network device documentation for more details on this. | |
128 | ||
129 | Configuring And Activating The Port | |
130 | =================================== | |
131 | ||
132 | The Z85230 driver provides helper functions and tables to load the port | |
133 | registers on the Z8530 chips. When programming the register settings for | |
134 | a channel be aware that the documentation recommends initialisation | |
135 | orders. Strange things happen when these are not followed. | |
136 | ||
137 | :c:func:`z8530_channel_load()` takes an array of pairs of | |
138 | initialisation values in an array of u8 type. The first value is the | |
139 | Z8530 register number. Add 16 to indicate the alternate register bank on | |
140 | the later chips. The array is terminated by a 255. | |
141 | ||
142 | The driver provides a pair of public tables. The z8530_hdlc_kilostream | |
143 | table is for the UK 'Kilostream' service and also happens to cover most | |
144 | other end host configurations. The z8530_hdlc_kilostream_85230 table | |
145 | is the same configuration using the enhancements of the 85230 chip. The | |
146 | configuration loaded is standard NRZ encoded synchronous data with HDLC | |
147 | bitstuffing. All of the timing is taken from the other end of the link. | |
148 | ||
149 | When writing your own tables be aware that the driver internally tracks | |
150 | register values. It may need to reload values. You should therefore be | |
151 | sure to set registers 1-7, 9-11, 14 and 15 in all configurations. Where | |
152 | the register settings depend on DMA selection the driver will update the | |
153 | bits itself when you open or close. Loading a new table with the | |
154 | interface open is not recommended. | |
155 | ||
156 | There are three standard configurations supported by the core code. In | |
157 | PIO mode the interface is programmed up to use interrupt driven PIO. | |
158 | This places high demands on the host processor to avoid latency. The | |
159 | driver is written to take account of latency issues but it cannot avoid | |
160 | latencies caused by other drivers, notably IDE in PIO mode. Because the | |
161 | drivers allocate buffers you must also prevent MTU changes while the | |
162 | port is open. | |
163 | ||
164 | Once the port is open it will call the rx_function of each channel | |
165 | whenever a completed packet arrived. This is invoked from interrupt | |
166 | context and passes you the channel and a network buffer (struct | |
167 | sk_buff) holding the data. The data includes the CRC bytes so most | |
168 | users will want to trim the last two bytes before processing the data. | |
169 | This function is very timing critical. When you wish to simply discard | |
170 | data the support code provides the function | |
171 | :c:func:`z8530_null_rx()` to discard the data. | |
172 | ||
60202365 MCC |
173 | To active PIO mode sending and receiving the ``z8530_sync_open`` is called. |
174 | This expects to be passed the network device and the channel. Typically | |
175 | this is called from your network device open callback. On a failure a | |
176 | non zero error status is returned. | |
c7e21544 MCC |
177 | The :c:func:`z8530_sync_close()` function shuts down a PIO |
178 | channel. This must be done before the channel is opened again and before | |
179 | the driver shuts down and unloads. | |
180 | ||
181 | The ideal mode of operation is dual channel DMA mode. Here the kernel | |
182 | driver will configure the board for DMA in both directions. The driver | |
183 | also handles ISA DMA issues such as controller programming and the | |
184 | memory range limit for you. This mode is activated by calling the | |
185 | :c:func:`z8530_sync_dma_open()` function. On failure a non zero | |
186 | error value is returned. Once this mode is activated it can be shut down | |
187 | by calling the :c:func:`z8530_sync_dma_close()`. You must call | |
188 | the close function matching the open mode you used. | |
189 | ||
190 | The final supported mode uses a single DMA channel to drive the transmit | |
191 | side. As the Z85C30 has a larger FIFO on the receive channel this tends | |
192 | to increase the maximum speed a little. This is activated by calling the | |
60202365 | 193 | ``z8530_sync_txdma_open``. This returns a non zero error code on failure. The |
c7e21544 MCC |
194 | :c:func:`z8530_sync_txdma_close()` function closes down the Z8530 |
195 | interface from this mode. | |
196 | ||
197 | Network Layer Functions | |
198 | ======================= | |
199 | ||
200 | The Z8530 layer provides functions to queue packets for transmission. | |
201 | The driver internally buffers the frame currently being transmitted and | |
202 | one further frame (in order to keep back to back transmission running). | |
203 | Any further buffering is up to the caller. | |
204 | ||
205 | The function :c:func:`z8530_queue_xmit()` takes a network buffer | |
206 | in sk_buff format and queues it for transmission. The caller must | |
207 | provide the entire packet with the exception of the bitstuffing and CRC. | |
208 | This is normally done by the caller via the generic HDLC interface | |
209 | layer. It returns 0 if the buffer has been queued and non zero values | |
210 | for queue full. If the function accepts the buffer it becomes property | |
211 | of the Z8530 layer and the caller should not free it. | |
212 | ||
213 | The function :c:func:`z8530_get_stats()` returns a pointer to an | |
214 | internally maintained per interface statistics block. This provides most | |
215 | of the interface code needed to implement the network layer get_stats | |
216 | callback. | |
217 | ||
218 | Porting The Z8530 Driver | |
219 | ======================== | |
220 | ||
221 | The Z8530 driver is written to be portable. In DMA mode it makes | |
222 | assumptions about the use of ISA DMA. These are probably warranted in | |
223 | most cases as the Z85230 in particular was designed to glue to PC type | |
224 | machines. The PIO mode makes no real assumptions. | |
225 | ||
226 | Should you need to retarget the Z8530 driver to another architecture the | |
227 | only code that should need changing are the port I/O functions. At the | |
228 | moment these assume PC I/O port accesses. This may not be appropriate | |
229 | for all platforms. Replacing :c:func:`z8530_read_port()` and | |
60202365 MCC |
230 | ``z8530_write_port`` is intended to be all that is required to port |
231 | this driver layer. | |
c7e21544 MCC |
232 | |
233 | Known Bugs And Assumptions | |
234 | ========================== | |
235 | ||
236 | Interrupt Locking | |
237 | The locking in the driver is done via the global cli/sti lock. This | |
238 | makes for relatively poor SMP performance. Switching this to use a | |
239 | per device spin lock would probably materially improve performance. | |
240 | ||
241 | Occasional Failures | |
242 | We have reports of occasional failures when run for very long | |
243 | periods of time and the driver starts to receive junk frames. At the | |
244 | moment the cause of this is not clear. | |
245 | ||
246 | Public Functions Provided | |
247 | ========================= | |
248 | ||
249 | .. kernel-doc:: drivers/net/wan/z85230.c | |
250 | :export: | |
251 | ||
252 | Internal Functions | |
253 | ================== | |
254 | ||
255 | .. kernel-doc:: drivers/net/wan/z85230.c | |
256 | :internal: |