About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / z8530book.rst




Custom Search

Based on kernel version 4.13.3. Page generated on 2017-09-23 13:55 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:
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.