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