About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / serial / driver




Custom Search

Based on kernel version 4.1. Page generated on 2015-06-28 12:14 EST.

1	
2				Low Level Serial API
3				--------------------
4	
5	
6	This document is meant as a brief overview of some aspects of the new serial
7	driver.  It is not complete, any questions you have should be directed to
8	<rmk@arm.linux.org.uk>
9	
10	The reference implementation is contained within amba_pl011.c.
11	
12	
13	
14	Low Level Serial Hardware Driver
15	--------------------------------
16	
17	The low level serial hardware driver is responsible for supplying port
18	information (defined by uart_port) and a set of control methods (defined
19	by uart_ops) to the core serial driver.  The low level driver is also
20	responsible for handling interrupts for the port, and providing any
21	console support.
22	
23	
24	Console Support
25	---------------
26	
27	The serial core provides a few helper functions.  This includes identifing
28	the correct port structure (via uart_get_console) and decoding command line
29	arguments (uart_parse_options).
30	
31	There is also a helper function (uart_write_console) which performs a
32	character by character write, translating newlines to CRLF sequences.
33	Driver writers are recommended to use this function rather than implementing
34	their own version.
35	
36	
37	Locking
38	-------
39	
40	It is the responsibility of the low level hardware driver to perform the
41	necessary locking using port->lock.  There are some exceptions (which
42	are described in the uart_ops listing below.)
43	
44	There are three locks.  A per-port spinlock, a per-port tmpbuf semaphore,
45	and an overall semaphore.
46	
47	From the core driver perspective, the port->lock locks the following
48	data:
49	
50		port->mctrl
51		port->icount
52		info->xmit.head (circ->head)
53		info->xmit.tail (circ->tail)
54	
55	The low level driver is free to use this lock to provide any additional
56	locking.
57	
58	The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded
59	access to the info->tmpbuf bouncebuffer used for port writes.
60	
61	The port_sem semaphore is used to protect against ports being added/
62	removed or reconfigured at inappropriate times. Since v2.6.27, this
63	semaphore has been the 'mutex' member of the tty_port struct, and
64	commonly referred to as the port mutex (or port->mutex).
65	
66	
67	uart_ops
68	--------
69	
70	The uart_ops structure is the main interface between serial_core and the
71	hardware specific driver.  It contains all the methods to control the
72	hardware.
73	
74	  tx_empty(port)
75		This function tests whether the transmitter fifo and shifter
76		for the port described by 'port' is empty.  If it is empty,
77		this function should return TIOCSER_TEMT, otherwise return 0.
78		If the port does not support this operation, then it should
79		return TIOCSER_TEMT.
80	
81		Locking: none.
82		Interrupts: caller dependent.
83		This call must not sleep
84	
85	  set_mctrl(port, mctrl)
86		This function sets the modem control lines for port described
87		by 'port' to the state described by mctrl.  The relevant bits
88		of mctrl are:
89			- TIOCM_RTS	RTS signal.
90			- TIOCM_DTR	DTR signal.
91			- TIOCM_OUT1	OUT1 signal.
92			- TIOCM_OUT2	OUT2 signal.
93			- TIOCM_LOOP	Set the port into loopback mode.
94		If the appropriate bit is set, the signal should be driven
95		active.  If the bit is clear, the signal should be driven
96		inactive.
97	
98		Locking: port->lock taken.
99		Interrupts: locally disabled.
100		This call must not sleep
101	
102	  get_mctrl(port)
103		Returns the current state of modem control inputs.  The state
104		of the outputs should not be returned, since the core keeps
105		track of their state.  The state information should include:
106			- TIOCM_CAR	state of DCD signal
107			- TIOCM_CTS	state of CTS signal
108			- TIOCM_DSR	state of DSR signal
109			- TIOCM_RI	state of RI signal
110		The bit is set if the signal is currently driven active.  If
111		the port does not support CTS, DCD or DSR, the driver should
112		indicate that the signal is permanently active.  If RI is
113		not available, the signal should not be indicated as active.
114	
115		Locking: port->lock taken.
116		Interrupts: locally disabled.
117		This call must not sleep
118	
119	  stop_tx(port)
120		Stop transmitting characters.  This might be due to the CTS
121		line becoming inactive or the tty layer indicating we want
122		to stop transmission due to an XOFF character.
123	
124		The driver should stop transmitting characters as soon as
125		possible.
126	
127		Locking: port->lock taken.
128		Interrupts: locally disabled.
129		This call must not sleep
130	
131	  start_tx(port)
132		Start transmitting characters.
133	
134		Locking: port->lock taken.
135		Interrupts: locally disabled.
136		This call must not sleep
137	
138	  send_xchar(port,ch)
139		Transmit a high priority character, even if the port is stopped.
140		This is used to implement XON/XOFF flow control and tcflow().  If
141		the serial driver does not implement this function, the tty core
142		will append the character to the circular buffer and then call
143		start_tx() / stop_tx() to flush the data out.
144	
145		Do not transmit if ch == '\0' (__DISABLED_CHAR).
146	
147		Locking: none.
148		Interrupts: caller dependent.
149	
150	  stop_rx(port)
151		Stop receiving characters; the port is in the process of
152		being closed.
153	
154		Locking: port->lock taken.
155		Interrupts: locally disabled.
156		This call must not sleep
157	
158	  enable_ms(port)
159		Enable the modem status interrupts.
160	
161		This method may be called multiple times.  Modem status
162		interrupts should be disabled when the shutdown method is
163		called.
164	
165		Locking: port->lock taken.
166		Interrupts: locally disabled.
167		This call must not sleep
168	
169	  break_ctl(port,ctl)
170		Control the transmission of a break signal.  If ctl is
171		nonzero, the break signal should be transmitted.  The signal
172		should be terminated when another call is made with a zero
173		ctl.
174	
175		Locking: none.
176		Interrupts: caller dependent.
177		This call must not sleep
178	
179	  startup(port)
180		Grab any interrupt resources and initialise any low level driver
181		state.  Enable the port for reception.  It should not activate
182		RTS nor DTR; this will be done via a separate call to set_mctrl.
183	
184		This method will only be called when the port is initially opened.
185	
186		Locking: port_sem taken.
187		Interrupts: globally disabled.
188	
189	  shutdown(port)
190		Disable the port, disable any break condition that may be in
191		effect, and free any interrupt resources.  It should not disable
192		RTS nor DTR; this will have already been done via a separate
193		call to set_mctrl.
194	
195		Drivers must not access port->info once this call has completed.
196	
197		This method will only be called when there are no more users of
198		this port.
199	
200		Locking: port_sem taken.
201		Interrupts: caller dependent.
202	
203	  flush_buffer(port)
204		Flush any write buffers, reset any DMA state and stop any
205		ongoing DMA transfers.
206	
207		This will be called whenever the port->info->xmit circular
208		buffer is cleared.
209	
210		Locking: port->lock taken.
211		Interrupts: locally disabled.
212		This call must not sleep
213	
214	  set_termios(port,termios,oldtermios)
215		Change the port parameters, including word length, parity, stop
216		bits.  Update read_status_mask and ignore_status_mask to indicate
217		the types of events we are interested in receiving.  Relevant
218		termios->c_cflag bits are:
219			CSIZE	- word size
220			CSTOPB	- 2 stop bits
221			PARENB	- parity enable
222			PARODD	- odd parity (when PARENB is in force)
223			CREAD	- enable reception of characters (if not set,
224				  still receive characters from the port, but
225				  throw them away.
226			CRTSCTS	- if set, enable CTS status change reporting
227			CLOCAL	- if not set, enable modem status change
228				  reporting.
229		Relevant termios->c_iflag bits are:
230			INPCK	- enable frame and parity error events to be
231				  passed to the TTY layer.
232			BRKINT
233			PARMRK	- both of these enable break events to be
234				  passed to the TTY layer.
235	
236			IGNPAR	- ignore parity and framing errors
237			IGNBRK	- ignore break errors,  If IGNPAR is also
238				  set, ignore overrun errors as well.
239		The interaction of the iflag bits is as follows (parity error
240		given as an example):
241		Parity error	INPCK	IGNPAR
242		n/a		0	n/a	character received, marked as
243						TTY_NORMAL
244		None		1	n/a	character received, marked as
245						TTY_NORMAL
246		Yes		1	0	character received, marked as
247						TTY_PARITY
248		Yes		1	1	character discarded
249	
250		Other flags may be used (eg, xon/xoff characters) if your
251		hardware supports hardware "soft" flow control.
252	
253		Locking: caller holds port->mutex
254		Interrupts: caller dependent.
255		This call must not sleep
256	
257	  pm(port,state,oldstate)
258		Perform any power management related activities on the specified
259		port.  State indicates the new state (defined by
260		enum uart_pm_state), oldstate indicates the previous state.
261	
262		This function should not be used to grab any resources.
263	
264		This will be called when the port is initially opened and finally
265		closed, except when the port is also the system console.  This
266		will occur even if CONFIG_PM is not set.
267	
268		Locking: none.
269		Interrupts: caller dependent.
270	
271	  type(port)
272		Return a pointer to a string constant describing the specified
273		port, or return NULL, in which case the string 'unknown' is
274		substituted.
275	
276		Locking: none.
277		Interrupts: caller dependent.
278	
279	  release_port(port)
280		Release any memory and IO region resources currently in use by
281		the port.
282	
283		Locking: none.
284		Interrupts: caller dependent.
285	
286	  request_port(port)
287		Request any memory and IO region resources required by the port.
288		If any fail, no resources should be registered when this function
289		returns, and it should return -EBUSY on failure.
290	
291		Locking: none.
292		Interrupts: caller dependent.
293	
294	  config_port(port,type)
295		Perform any autoconfiguration steps required for the port.  `type`
296		contains a bit mask of the required configuration.  UART_CONFIG_TYPE
297		indicates that the port requires detection and identification.
298		port->type should be set to the type found, or PORT_UNKNOWN if
299		no port was detected.
300	
301		UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal,
302		which should be probed using standard kernel autoprobing techniques.
303		This is not necessary on platforms where ports have interrupts
304		internally hard wired (eg, system on a chip implementations).
305	
306		Locking: none.
307		Interrupts: caller dependent.
308	
309	  verify_port(port,serinfo)
310		Verify the new serial port information contained within serinfo is
311		suitable for this port type.
312	
313		Locking: none.
314		Interrupts: caller dependent.
315	
316	  ioctl(port,cmd,arg)
317		Perform any port specific IOCTLs.  IOCTL commands must be defined
318		using the standard numbering system found in <asm/ioctl.h>
319	
320		Locking: none.
321		Interrupts: caller dependent.
322	
323	  poll_init(port)
324		Called by kgdb to perform the minimal hardware initialization needed
325		to support poll_put_char() and poll_get_char().  Unlike ->startup()
326		this should not request interrupts.
327	
328		Locking: tty_mutex and tty_port->mutex taken.
329		Interrupts: n/a.
330	
331	  poll_put_char(port,ch)
332		Called by kgdb to write a single character directly to the serial
333		port.  It can and should block until there is space in the TX FIFO.
334	
335		Locking: none.
336		Interrupts: caller dependent.
337		This call must not sleep
338	
339	  poll_get_char(port)
340		Called by kgdb to read a single character directly from the serial
341		port.  If data is available, it should be returned; otherwise
342		the function should return NO_POLL_CHAR immediately.
343	
344		Locking: none.
345		Interrupts: caller dependent.
346		This call must not sleep
347	
348	Other functions
349	---------------
350	
351	uart_update_timeout(port,cflag,baud)
352		Update the FIFO drain timeout, port->timeout, according to the
353		number of bits, parity, stop bits and baud rate.
354	
355		Locking: caller is expected to take port->lock
356		Interrupts: n/a
357	
358	uart_get_baud_rate(port,termios,old,min,max)
359		Return the numeric baud rate for the specified termios, taking
360		account of the special 38400 baud "kludge".  The B0 baud rate
361		is mapped to 9600 baud.
362	
363		If the baud rate is not within min..max, then if old is non-NULL,
364		the original baud rate will be tried.  If that exceeds the
365		min..max constraint, 9600 baud will be returned.  termios will
366		be updated to the baud rate in use.
367	
368		Note: min..max must always allow 9600 baud to be selected.
369	
370		Locking: caller dependent.
371		Interrupts: n/a
372	
373	uart_get_divisor(port,baud)
374		Return the divsor (baud_base / baud) for the specified baud
375		rate, appropriately rounded.
376	
377		If 38400 baud and custom divisor is selected, return the
378		custom divisor instead.
379	
380		Locking: caller dependent.
381		Interrupts: n/a
382	
383	uart_match_port(port1,port2)
384		This utility function can be used to determine whether two
385		uart_port structures describe the same port.
386	
387		Locking: n/a
388		Interrupts: n/a
389	
390	uart_write_wakeup(port)
391		A driver is expected to call this function when the number of
392		characters in the transmit buffer have dropped below a threshold.
393	
394		Locking: port->lock should be held.
395		Interrupts: n/a
396	
397	uart_register_driver(drv)
398		Register a uart driver with the core driver.  We in turn register
399		with the tty layer, and initialise the core driver per-port state.
400	
401		drv->port should be NULL, and the per-port structures should be
402		registered using uart_add_one_port after this call has succeeded.
403	
404		Locking: none
405		Interrupts: enabled
406	
407	uart_unregister_driver()
408		Remove all references to a driver from the core driver.  The low
409		level driver must have removed all its ports via the
410		uart_remove_one_port() if it registered them with uart_add_one_port().
411	
412		Locking: none
413		Interrupts: enabled
414	
415	uart_suspend_port()
416	
417	uart_resume_port()
418	
419	uart_add_one_port()
420	
421	uart_remove_one_port()
422	
423	Other notes
424	-----------
425	
426	It is intended some day to drop the 'unused' entries from uart_port, and
427	allow low level drivers to register their own individual uart_port's with
428	the core.  This will allow drivers to use uart_port as a pointer to a
429	structure containing both the uart_port entry with their own extensions,
430	thus:
431	
432		struct my_port {
433			struct uart_port	port;
434			int			my_stuff;
435		};
436	
437	Modem control lines via GPIO
438	----------------------------
439	
440	Some helpers are provided in order to set/get modem control lines via GPIO.
441	
442	mctrl_gpio_init(dev, idx):
443		This will get the {cts,rts,...}-gpios from device tree if they are
444		present and request them, set direction etc, and return an
445		allocated structure. devm_* functions are used, so there's no need
446		to call mctrl_gpio_free().
447	
448	mctrl_gpio_free(dev, gpios):
449		This will free the requested gpios in mctrl_gpio_init().
450		As devm_* function are used, there's generally no need to call
451		this function.
452	
453	mctrl_gpio_to_gpiod(gpios, gidx)
454		This returns the gpio structure associated to the modem line index.
455	
456	mctrl_gpio_set(gpios, mctrl):
457		This will sets the gpios according to the mctrl state.
458	
459	mctrl_gpio_get(gpios, mctrl):
460		This will update mctrl with the gpios values.
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.