Documentation/DocBook/z8530book.tmpl

   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@lxorguk.ukuu.org.uk</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   </chapter>
  73
  74   <chapter id="Driver_Modes">
  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
 105   <chapter id="Using_the_Z85230_driver">
 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 &amp;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
 171   <chapter id="Attaching_Network_Interfaces">
 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
 176         present and in use. In addition to use the generic HDLC
 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
 183         the netdevice field of each channel. The hdlc-&gt; priv field of the
 184         network device points to your private data - you will need to be
 185         able to find your private data from this.
 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
 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.
 193   </para>
 194   <para>
 195         If you wish to use the generic HDLC then you need to register
 196         the HDLC device.
 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
 205   <chapter id="Configuring_And_Activating_The_Port">
 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
 289   <chapter id="Network_Layer_Functions">
 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
 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.
 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
 316   <chapter id="Porting_The_Z8530_Driver">
 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>