About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / z8530book.tmpl


Based on kernel version 4.10.8. Page generated on 2017-04-01 14:43 EST.

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>
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog