[deliverable/linux.git] / Documentation / serial / driver


			Low Level Serial API
			--------------------


   $Id: driver,v 1.10 2002/07/22 15:27:30 rmk Exp $


This document is meant as a brief overview of some aspects of the new serial
driver.  It is not complete, any questions you have should be directed to
<rmk@arm.linux.org.uk>

The reference implementation is contained within serial_amba.c.


Low Level Serial Hardware Driver
--------------------------------

The low level serial hardware driver is responsible for supplying port
information (defined by uart_port) and a set of control methods (defined
by uart_ops) to the core serial driver.  The low level driver is also
responsible for handling interrupts for the port, and providing any
console support.


Console Support
---------------

The serial core provides a few helper functions.  This includes identifing
the correct port structure (via uart_get_console) and decoding command line
arguments (uart_parse_options).


Locking
-------

It is the responsibility of the low level hardware driver to perform the
necessary locking using port->lock.  There are some exceptions (which
are described in the uart_ops listing below.)

There are three locks.  A per-port spinlock, a per-port tmpbuf semaphore,
and an overall semaphore.

From the core driver perspective, the port->lock locks the following
data:

	port->mctrl
	port->icount
	info->xmit.head (circ->head)
	info->xmit.tail (circ->tail)

The low level driver is free to use this lock to provide any additional
locking.

The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded
access to the info->tmpbuf bouncebuffer used for port writes.

The port_sem semaphore is used to protect against ports being added/
removed or reconfigured at inappropriate times.


uart_ops
--------

The uart_ops structure is the main interface between serial_core and the
hardware specific driver.  It contains all the methods to control the
hardware.

  tx_empty(port)
	This function tests whether the transmitter fifo and shifter
	for the port described by 'port' is empty.  If it is empty,
	this function should return TIOCSER_TEMT, otherwise return 0.
	If the port does not support this operation, then it should
	return TIOCSER_TEMT.

	Locking: none.
	Interrupts: caller dependent.
	This call must not sleep

  set_mctrl(port, mctrl)
	This function sets the modem control lines for port described
	by 'port' to the state described by mctrl.  The relevant bits
	of mctrl are:
		- TIOCM_RTS	RTS signal.
		- TIOCM_DTR	DTR signal.
		- TIOCM_OUT1	OUT1 signal.
		- TIOCM_OUT2	OUT2 signal.
	If the appropriate bit is set, the signal should be driven
	active.  If the bit is clear, the signal should be driven
	inactive.

	Locking: port->lock taken.
	Interrupts: locally disabled.
	This call must not sleep

  get_mctrl(port)
	Returns the current state of modem control inputs.  The state
	of the outputs should not be returned, since the core keeps
	track of their state.  The state information should include:
		- TIOCM_DCD	state of DCD signal
		- TIOCM_CTS	state of CTS signal
		- TIOCM_DSR	state of DSR signal
		- TIOCM_RI	state of RI signal
	The bit is set if the signal is currently driven active.  If
	the port does not support CTS, DCD or DSR, the driver should
	indicate that the signal is permanently active.  If RI is
	not available, the signal should not be indicated as active.

	Locking: none.
	Interrupts: caller dependent.
	This call must not sleep

  stop_tx(port,tty_stop)
	Stop transmitting characters.  This might be due to the CTS
	line becoming inactive or the tty layer indicating we want
	to stop transmission.

	tty_stop: 1 if this call is due to the TTY layer issuing a
	          TTY stop to the driver (equiv to rs_stop).

	Locking: port->lock taken.
	Interrupts: locally disabled.
	This call must not sleep

  start_tx(port,tty_start)
	start transmitting characters.  (incidentally, nonempty will
	always be nonzero, and shouldn't be used - it will be dropped).

	tty_start: 1 if this call was due to the TTY layer issuing
	           a TTY start to the driver (equiv to rs_start)

	Locking: port->lock taken.
	Interrupts: locally disabled.
	This call must not sleep

  stop_rx(port)
	Stop receiving characters; the port is in the process of
	being closed.

	Locking: port->lock taken.
	Interrupts: locally disabled.
	This call must not sleep

  enable_ms(port)
	Enable the modem status interrupts.

	Locking: port->lock taken.
	Interrupts: locally disabled.
	This call must not sleep

  break_ctl(port,ctl)
	Control the transmission of a break signal.  If ctl is
	nonzero, the break signal should be transmitted.  The signal
	should be terminated when another call is made with a zero
	ctl.

	Locking: none.
	Interrupts: caller dependent.
	This call must not sleep

  startup(port)
	Grab any interrupt resources and initialise any low level driver
	state.  Enable the port for reception.  It should not activate
	RTS nor DTR; this will be done via a separate call to set_mctrl.

	Locking: port_sem taken.
	Interrupts: globally disabled.

  shutdown(port)
	Disable the port, disable any break condition that may be in
	effect, and free any interrupt resources.  It should not disable
	RTS nor DTR; this will have already been done via a separate
	call to set_mctrl.

	Locking: port_sem taken.
	Interrupts: caller dependent.

  set_termios(port,termios,oldtermios)
	Change the port parameters, including word length, parity, stop
	bits.  Update read_status_mask and ignore_status_mask to indicate
	the types of events we are interested in receiving.  Relevant
	termios->c_cflag bits are:
		CSIZE	- word size
		CSTOPB	- 2 stop bits
		PARENB	- parity enable
		PARODD	- odd parity (when PARENB is in force)
		CREAD	- enable reception of characters (if not set,
			  still receive characters from the port, but
			  throw them away.
		CRTSCTS	- if set, enable CTS status change reporting
		CLOCAL	- if not set, enable modem status change
			  reporting.
	Relevant termios->c_iflag bits are:
		INPCK	- enable frame and parity error events to be
			  passed to the TTY layer.
		BRKINT
		PARMRK	- both of these enable break events to be
			  passed to the TTY layer.

		IGNPAR	- ignore parity and framing errors
		IGNBRK	- ignore break errors,  If IGNPAR is also
			  set, ignore overrun errors as well.
	The interaction of the iflag bits is as follows (parity error
	given as an example):
	Parity error	INPCK	IGNPAR
	None		n/a	n/a	character received
	Yes		n/a	0	character discarded
	Yes		0	1	character received, marked as
					TTY_NORMAL
	Yes		1	1	character received, marked as
					TTY_PARITY

	Other flags may be used (eg, xon/xoff characters) if your
	hardware supports hardware "soft" flow control.

	Locking: none.
	Interrupts: caller dependent.
	This call must not sleep

  pm(port,state,oldstate)
	Perform any power management related activities on the specified
	port.  State indicates the new state (defined by ACPI D0-D3),
	oldstate indicates the previous state.  Essentially, D0 means
	fully on, D3 means powered down.

	This function should not be used to grab any resources.

	This will be called when the port is initially opened and finally
	closed, except when the port is also the system console.  This
	will occur even if CONFIG_PM is not set.

	Locking: none.
	Interrupts: caller dependent.

  type(port)
	Return a pointer to a string constant describing the specified
	port, or return NULL, in which case the string 'unknown' is
	substituted.

	Locking: none.
	Interrupts: caller dependent.

  release_port(port)
	Release any memory and IO region resources currently in use by
	the port.

	Locking: none.
	Interrupts: caller dependent.

  request_port(port)
	Request any memory and IO region resources required by the port.
	If any fail, no resources should be registered when this function
	returns, and it should return -EBUSY on failure.

	Locking: none.
	Interrupts: caller dependent.

  config_port(port,type)
	Perform any autoconfiguration steps required for the port.  `type`
	contains a bit mask of the required configuration.  UART_CONFIG_TYPE
	indicates that the port requires detection and identification.
	port->type should be set to the type found, or PORT_UNKNOWN if
	no port was detected.

	UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal,
	which should be probed using standard kernel autoprobing techniques.
	This is not necessary on platforms where ports have interrupts
	internally hard wired (eg, system on a chip implementations).

	Locking: none.
	Interrupts: caller dependent.

  verify_port(port,serinfo)
	Verify the new serial port information contained within serinfo is
	suitable for this port type.

	Locking: none.
	Interrupts: caller dependent.

  ioctl(port,cmd,arg)
	Perform any port specific IOCTLs.  IOCTL commands must be defined
	using the standard numbering system found in <asm/ioctl.h>

	Locking: none.
	Interrupts: caller dependent.

Other functions
---------------

uart_update_timeout(port,cflag,quot)
	Update the FIFO drain timeout, port->timeout, according to the
	number of bits, parity, stop bits and quotient.

	Locking: caller is expected to take port->lock
	Interrupts: n/a

uart_get_baud_rate(port,termios)
	Return the numeric baud rate for the specified termios, taking
	account of the special 38400 baud "kludge".  The B0 baud rate
	is mapped to 9600 baud.

	Locking: caller dependent.
	Interrupts: n/a

uart_get_divisor(port,termios,oldtermios)
	Return the divsor (baud_base / baud) for the selected baud rate
	specified by termios.  If the baud rate is out of range, try
	the original baud rate specified by oldtermios (if non-NULL).
	If that fails, try 9600 baud.

	If 38400 baud and custom divisor is selected, return the
	custom divisor instead.

	Locking: caller dependent.
	Interrupts: n/a

Other notes
-----------

It is intended some day to drop the 'unused' entries from uart_port, and
allow low level drivers to register their own individual uart_port's with
the core.  This will allow drivers to use uart_port as a pointer to a
structure containing both the uart_port entry with their own extensions,
thus:

	struct my_port {
		struct uart_port	port;
		int			my_stuff;
	};
Commit	Line	Data
1da177e4 LT	1
	2	Low Level Serial API
	3	--------------------
	4
	5
	6	$Id: driver,v 1.10 2002/07/22 15:27:30 rmk Exp $
	7
	8
	9	This document is meant as a brief overview of some aspects of the new serial
	10	driver. It is not complete, any questions you have should be directed to
	11	<rmk@arm.linux.org.uk>
	12
	13	The reference implementation is contained within serial_amba.c.
	14
	15
	16
	17	Low Level Serial Hardware Driver
	18	--------------------------------
	19
	20	The low level serial hardware driver is responsible for supplying port
	21	information (defined by uart_port) and a set of control methods (defined
	22	by uart_ops) to the core serial driver. The low level driver is also
	23	responsible for handling interrupts for the port, and providing any
	24	console support.
	25
	26
	27	Console Support
	28	---------------
	29
	30	The serial core provides a few helper functions. This includes identifing
	31	the correct port structure (via uart_get_console) and decoding command line
	32	arguments (uart_parse_options).
	33
	34
	35	Locking
	36	-------
	37
	38	It is the responsibility of the low level hardware driver to perform the
	39	necessary locking using port->lock. There are some exceptions (which
	40	are described in the uart_ops listing below.)
	41
	42	There are three locks. A per-port spinlock, a per-port tmpbuf semaphore,
	43	and an overall semaphore.
	44
	45	From the core driver perspective, the port->lock locks the following
	46	data:
	47
	48	port->mctrl
	49	port->icount
	50	info->xmit.head (circ->head)
	51	info->xmit.tail (circ->tail)
	52
	53	The low level driver is free to use this lock to provide any additional
	54	locking.
	55
	56	The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded
	57	access to the info->tmpbuf bouncebuffer used for port writes.
	58
	59	The port_sem semaphore is used to protect against ports being added/
	60	removed or reconfigured at inappropriate times.
	61
	62
	63	uart_ops
	64	--------
65
66	The uart_ops structure is the main interface between serial_core and the
67	hardware specific driver. It contains all the methods to control the
68	hardware.
69
70	tx_empty(port)
71	This function tests whether the transmitter fifo and shifter
72	for the port described by 'port' is empty. If it is empty,
73	this function should return TIOCSER_TEMT, otherwise return 0.
74	If the port does not support this operation, then it should
75	return TIOCSER_TEMT.
76
77	Locking: none.
78	Interrupts: caller dependent.
79	This call must not sleep
80
81	set_mctrl(port, mctrl)
82	This function sets the modem control lines for port described
83	by 'port' to the state described by mctrl. The relevant bits
84	of mctrl are:
85	- TIOCM_RTS RTS signal.
86	- TIOCM_DTR DTR signal.
87	- TIOCM_OUT1 OUT1 signal.
88	- TIOCM_OUT2 OUT2 signal.
89	If the appropriate bit is set, the signal should be driven
90	active. If the bit is clear, the signal should be driven
91	inactive.
92
93	Locking: port->lock taken.
94	Interrupts: locally disabled.
95	This call must not sleep
96
97	get_mctrl(port)
98	Returns the current state of modem control inputs. The state
99	of the outputs should not be returned, since the core keeps
100	track of their state. The state information should include:
101	- TIOCM_DCD state of DCD signal
102	- TIOCM_CTS state of CTS signal
103	- TIOCM_DSR state of DSR signal
104	- TIOCM_RI state of RI signal
105	The bit is set if the signal is currently driven active. If
106	the port does not support CTS, DCD or DSR, the driver should
107	indicate that the signal is permanently active. If RI is
108	not available, the signal should not be indicated as active.
109
110	Locking: none.
111	Interrupts: caller dependent.
112	This call must not sleep
113
114	stop_tx(port,tty_stop)
115	Stop transmitting characters. This might be due to the CTS
116	line becoming inactive or the tty layer indicating we want
117	to stop transmission.
118
119	tty_stop: 1 if this call is due to the TTY layer issuing a
120	TTY stop to the driver (equiv to rs_stop).
121
122	Locking: port->lock taken.
123	Interrupts: locally disabled.
124	This call must not sleep
125
126	start_tx(port,tty_start)
127	start transmitting characters. (incidentally, nonempty will
128	always be nonzero, and shouldn't be used - it will be dropped).
129
130	tty_start: 1 if this call was due to the TTY layer issuing
131	a TTY start to the driver (equiv to rs_start)
132
133	Locking: port->lock taken.
134	Interrupts: locally disabled.
135	This call must not sleep
136
137	stop_rx(port)
138	Stop receiving characters; the port is in the process of
139	being closed.
140
141	Locking: port->lock taken.
142	Interrupts: locally disabled.
143	This call must not sleep
144
145	enable_ms(port)
146	Enable the modem status interrupts.
147
148	Locking: port->lock taken.
149	Interrupts: locally disabled.
150	This call must not sleep
151
152	break_ctl(port,ctl)
153	Control the transmission of a break signal. If ctl is
154	nonzero, the break signal should be transmitted. The signal
155	should be terminated when another call is made with a zero
156	ctl.
157
158	Locking: none.
159	Interrupts: caller dependent.
160	This call must not sleep
161
162	startup(port)
163	Grab any interrupt resources and initialise any low level driver
164	state. Enable the port for reception. It should not activate
165	RTS nor DTR; this will be done via a separate call to set_mctrl.
166
167	Locking: port_sem taken.
168	Interrupts: globally disabled.
169
170	shutdown(port)
171	Disable the port, disable any break condition that may be in
172	effect, and free any interrupt resources. It should not disable
173	RTS nor DTR; this will have already been done via a separate
174	call to set_mctrl.
175
176	Locking: port_sem taken.
177	Interrupts: caller dependent.
178
179	set_termios(port,termios,oldtermios)
180	Change the port parameters, including word length, parity, stop
181	bits. Update read_status_mask and ignore_status_mask to indicate
182	the types of events we are interested in receiving. Relevant
183	termios->c_cflag bits are:
184	CSIZE - word size
185	CSTOPB - 2 stop bits
186	PARENB - parity enable
187	PARODD - odd parity (when PARENB is in force)
188	CREAD - enable reception of characters (if not set,
189	still receive characters from the port, but
190	throw them away.
191	CRTSCTS - if set, enable CTS status change reporting
192	CLOCAL - if not set, enable modem status change
193	reporting.
194	Relevant termios->c_iflag bits are:
195	INPCK - enable frame and parity error events to be
196	passed to the TTY layer.
197	BRKINT
198	PARMRK - both of these enable break events to be
199	passed to the TTY layer.
200
201	IGNPAR - ignore parity and framing errors
202	IGNBRK - ignore break errors, If IGNPAR is also
203	set, ignore overrun errors as well.
204	The interaction of the iflag bits is as follows (parity error
205	given as an example):
206	Parity error INPCK IGNPAR
207	None n/a n/a character received
208	Yes n/a 0 character discarded
209	Yes 0 1 character received, marked as
210	TTY_NORMAL
211	Yes 1 1 character received, marked as
212	TTY_PARITY
213
214	Other flags may be used (eg, xon/xoff characters) if your
215	hardware supports hardware "soft" flow control.
216
217	Locking: none.
218	Interrupts: caller dependent.
219	This call must not sleep
220
221	pm(port,state,oldstate)
222	Perform any power management related activities on the specified
223	port. State indicates the new state (defined by ACPI D0-D3),
224	oldstate indicates the previous state. Essentially, D0 means
225	fully on, D3 means powered down.
226
227	This function should not be used to grab any resources.
228
229	This will be called when the port is initially opened and finally
230	closed, except when the port is also the system console. This
231	will occur even if CONFIG_PM is not set.
232
233	Locking: none.
234	Interrupts: caller dependent.
235
236	type(port)
237	Return a pointer to a string constant describing the specified
238	port, or return NULL, in which case the string 'unknown' is
239	substituted.
240
241	Locking: none.
242	Interrupts: caller dependent.
243
244	release_port(port)
245	Release any memory and IO region resources currently in use by
246	the port.
247
248	Locking: none.
249	Interrupts: caller dependent.
250
251	request_port(port)
252	Request any memory and IO region resources required by the port.
253	If any fail, no resources should be registered when this function
254	returns, and it should return -EBUSY on failure.
255
256	Locking: none.
257	Interrupts: caller dependent.
258
259	config_port(port,type)
260	Perform any autoconfiguration steps required for the port. `type`
261	contains a bit mask of the required configuration. UART_CONFIG_TYPE
262	indicates that the port requires detection and identification.
263	port->type should be set to the type found, or PORT_UNKNOWN if
264	no port was detected.
265
266	UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal,
267	which should be probed using standard kernel autoprobing techniques.
268	This is not necessary on platforms where ports have interrupts
269	internally hard wired (eg, system on a chip implementations).
270
271	Locking: none.
272	Interrupts: caller dependent.
273
274	verify_port(port,serinfo)
275	Verify the new serial port information contained within serinfo is
276	suitable for this port type.
277
278	Locking: none.
279	Interrupts: caller dependent.
280
281	ioctl(port,cmd,arg)
282	Perform any port specific IOCTLs. IOCTL commands must be defined
283	using the standard numbering system found in <asm/ioctl.h>
284
285	Locking: none.
286	Interrupts: caller dependent.
287
288	Other functions
289	---------------
290
291	uart_update_timeout(port,cflag,quot)
292	Update the FIFO drain timeout, port->timeout, according to the
293	number of bits, parity, stop bits and quotient.
294
295	Locking: caller is expected to take port->lock
296	Interrupts: n/a
297
298	uart_get_baud_rate(port,termios)
299	Return the numeric baud rate for the specified termios, taking
300	account of the special 38400 baud "kludge". The B0 baud rate
301	is mapped to 9600 baud.
302
303	Locking: caller dependent.
304	Interrupts: n/a
305
306	uart_get_divisor(port,termios,oldtermios)
307	Return the divsor (baud_base / baud) for the selected baud rate
308	specified by termios. If the baud rate is out of range, try
309	the original baud rate specified by oldtermios (if non-NULL).
310	If that fails, try 9600 baud.
311
312	If 38400 baud and custom divisor is selected, return the
313	custom divisor instead.
314
315	Locking: caller dependent.
316	Interrupts: n/a
317
318	Other notes
319	-----------
320
321	It is intended some day to drop the 'unused' entries from uart_port, and
322	allow low level drivers to register their own individual uart_port's with
323	the core. This will allow drivers to use uart_port as a pointer to a
324	structure containing both the uart_port entry with their own extensions,
325	thus:
326
327	struct my_port {
328	struct uart_port port;
329	int my_stuff;
330	};