Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.
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 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. 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 193 ``z8530_sync_txdma_open``. This returns a non zero error code on failure. The 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 230 ``z8530_write_port`` is intended to be all that is required to port 231 this driver layer. 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: