About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / serial / driver




Custom Search

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