z8530book.tmpl 15 KB

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