About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / serial / driver

Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:47 EST.

2				Low Level Serial API
3				--------------------
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>
10	The reference implementation is contained within amba_pl011.c.
14	Low Level Serial Hardware Driver
15	--------------------------------
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.
24	Console Support
25	---------------
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).
31	There is also a helper function (uart_console_write) 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.
37	Locking
38	-------
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.)
44	There are two locks.  A per-port spinlock, and an overall semaphore.
46	From the core driver perspective, the port->lock locks the following
47	data:
49		port->mctrl
50		port->icount
51		port->state->xmit.head (circ_buf->head)
52		port->state->xmit.tail (circ_buf->tail)
54	The low level driver is free to use this lock to provide any additional
55	locking.
57	The port_sem semaphore is used to protect against ports being added/
58	removed or reconfigured at inappropriate times. Since v2.6.27, this
59	semaphore has been the 'mutex' member of the tty_port struct, and
60	commonly referred to as the port mutex.
63	uart_ops
64	--------
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.
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.
77		Locking: none.
78		Interrupts: caller dependent.
79		This call must not sleep
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			- TIOCM_LOOP	Set the port into loopback mode.
90		If the appropriate bit is set, the signal should be driven
91		active.  If the bit is clear, the signal should be driven
92		inactive.
94		Locking: port->lock taken.
95		Interrupts: locally disabled.
96		This call must not sleep
98	  get_mctrl(port)
99		Returns the current state of modem control inputs.  The state
100		of the outputs should not be returned, since the core keeps
101		track of their state.  The state information should include:
102			- TIOCM_CAR	state of DCD signal
103			- TIOCM_CTS	state of CTS signal
104			- TIOCM_DSR	state of DSR signal
105			- TIOCM_RI	state of RI signal
106		The bit is set if the signal is currently driven active.  If
107		the port does not support CTS, DCD or DSR, the driver should
108		indicate that the signal is permanently active.  If RI is
109		not available, the signal should not be indicated as active.
111		Locking: port->lock taken.
112		Interrupts: locally disabled.
113		This call must not sleep
115	  stop_tx(port)
116		Stop transmitting characters.  This might be due to the CTS
117		line becoming inactive or the tty layer indicating we want
118		to stop transmission due to an XOFF character.
120		The driver should stop transmitting characters as soon as
121		possible.
123		Locking: port->lock taken.
124		Interrupts: locally disabled.
125		This call must not sleep
127	  start_tx(port)
128		Start transmitting characters.
130		Locking: port->lock taken.
131		Interrupts: locally disabled.
132		This call must not sleep
134	  throttle(port)
135		Notify the serial driver that input buffers for the line discipline are
136		close to full, and it should somehow signal that no more characters
137		should be sent to the serial port.
138		This will be called only if hardware assisted flow control is enabled.
140		Locking: serialized with .unthrottle() and termios modification by the
141			 tty layer.
143	  unthrottle(port)
144		Notify the serial driver that characters can now be sent to the serial
145		port without fear of overrunning the input buffers of the line
146		disciplines.
147		This will be called only if hardware assisted flow control is enabled.
149		Locking: serialized with .throttle() and termios modification by the
150			 tty layer.
152	  send_xchar(port,ch)
153		Transmit a high priority character, even if the port is stopped.
154		This is used to implement XON/XOFF flow control and tcflow().  If
155		the serial driver does not implement this function, the tty core
156		will append the character to the circular buffer and then call
157		start_tx() / stop_tx() to flush the data out.
159		Do not transmit if ch == '\0' (__DISABLED_CHAR).
161		Locking: none.
162		Interrupts: caller dependent.
164	  stop_rx(port)
165		Stop receiving characters; the port is in the process of
166		being closed.
168		Locking: port->lock taken.
169		Interrupts: locally disabled.
170		This call must not sleep
172	  enable_ms(port)
173		Enable the modem status interrupts.
175		This method may be called multiple times.  Modem status
176		interrupts should be disabled when the shutdown method is
177		called.
179		Locking: port->lock taken.
180		Interrupts: locally disabled.
181		This call must not sleep
183	  break_ctl(port,ctl)
184		Control the transmission of a break signal.  If ctl is
185		nonzero, the break signal should be transmitted.  The signal
186		should be terminated when another call is made with a zero
187		ctl.
189		Locking: caller holds tty_port->mutex
191	  startup(port)
192		Grab any interrupt resources and initialise any low level driver
193		state.  Enable the port for reception.  It should not activate
194		RTS nor DTR; this will be done via a separate call to set_mctrl.
196		This method will only be called when the port is initially opened.
198		Locking: port_sem taken.
199		Interrupts: globally disabled.
201	  shutdown(port)
202		Disable the port, disable any break condition that may be in
203		effect, and free any interrupt resources.  It should not disable
204		RTS nor DTR; this will have already been done via a separate
205		call to set_mctrl.
207		Drivers must not access port->state once this call has completed.
209		This method will only be called when there are no more users of
210		this port.
212		Locking: port_sem taken.
213		Interrupts: caller dependent.
215	  flush_buffer(port)
216		Flush any write buffers, reset any DMA state and stop any
217		ongoing DMA transfers.
219		This will be called whenever the port->state->xmit circular
220		buffer is cleared.
222		Locking: port->lock taken.
223		Interrupts: locally disabled.
224		This call must not sleep
226	  set_termios(port,termios,oldtermios)
227		Change the port parameters, including word length, parity, stop
228		bits.  Update read_status_mask and ignore_status_mask to indicate
229		the types of events we are interested in receiving.  Relevant
230		termios->c_cflag bits are:
231			CSIZE	- word size
232			CSTOPB	- 2 stop bits
233			PARENB	- parity enable
234			PARODD	- odd parity (when PARENB is in force)
235			CREAD	- enable reception of characters (if not set,
236				  still receive characters from the port, but
237				  throw them away.
238			CRTSCTS	- if set, enable CTS status change reporting
239			CLOCAL	- if not set, enable modem status change
240				  reporting.
241		Relevant termios->c_iflag bits are:
242			INPCK	- enable frame and parity error events to be
243				  passed to the TTY layer.
244			BRKINT
245			PARMRK	- both of these enable break events to be
246				  passed to the TTY layer.
248			IGNPAR	- ignore parity and framing errors
249			IGNBRK	- ignore break errors,  If IGNPAR is also
250				  set, ignore overrun errors as well.
251		The interaction of the iflag bits is as follows (parity error
252		given as an example):
253		Parity error	INPCK	IGNPAR
254		n/a		0	n/a	character received, marked as
255						TTY_NORMAL
256		None		1	n/a	character received, marked as
257						TTY_NORMAL
258		Yes		1	0	character received, marked as
259						TTY_PARITY
260		Yes		1	1	character discarded
262		Other flags may be used (eg, xon/xoff characters) if your
263		hardware supports hardware "soft" flow control.
265		Locking: caller holds tty_port->mutex
266		Interrupts: caller dependent.
267		This call must not sleep
269	  set_ldisc(port,termios)
270		Notifier for discipline change. See Documentation/serial/tty.txt.
272		Locking: caller holds tty_port->mutex
274	  pm(port,state,oldstate)
275		Perform any power management related activities on the specified
276		port.  State indicates the new state (defined by
277		enum uart_pm_state), oldstate indicates the previous state.
279		This function should not be used to grab any resources.
281		This will be called when the port is initially opened and finally
282		closed, except when the port is also the system console.  This
283		will occur even if CONFIG_PM is not set.
285		Locking: none.
286		Interrupts: caller dependent.
288	  type(port)
289		Return a pointer to a string constant describing the specified
290		port, or return NULL, in which case the string 'unknown' is
291		substituted.
293		Locking: none.
294		Interrupts: caller dependent.
296	  release_port(port)
297		Release any memory and IO region resources currently in use by
298		the port.
300		Locking: none.
301		Interrupts: caller dependent.
303	  request_port(port)
304		Request any memory and IO region resources required by the port.
305		If any fail, no resources should be registered when this function
306		returns, and it should return -EBUSY on failure.
308		Locking: none.
309		Interrupts: caller dependent.
311	  config_port(port,type)
312		Perform any autoconfiguration steps required for the port.  `type`
313		contains a bit mask of the required configuration.  UART_CONFIG_TYPE
314		indicates that the port requires detection and identification.
315		port->type should be set to the type found, or PORT_UNKNOWN if
316		no port was detected.
318		UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal,
319		which should be probed using standard kernel autoprobing techniques.
320		This is not necessary on platforms where ports have interrupts
321		internally hard wired (eg, system on a chip implementations).
323		Locking: none.
324		Interrupts: caller dependent.
326	  verify_port(port,serinfo)
327		Verify the new serial port information contained within serinfo is
328		suitable for this port type.
330		Locking: none.
331		Interrupts: caller dependent.
333	  ioctl(port,cmd,arg)
334		Perform any port specific IOCTLs.  IOCTL commands must be defined
335		using the standard numbering system found in <asm/ioctl.h>
337		Locking: none.
338		Interrupts: caller dependent.
340	  poll_init(port)
341		Called by kgdb to perform the minimal hardware initialization needed
342		to support poll_put_char() and poll_get_char().  Unlike ->startup()
343		this should not request interrupts.
345		Locking: tty_mutex and tty_port->mutex taken.
346		Interrupts: n/a.
348	  poll_put_char(port,ch)
349		Called by kgdb to write a single character directly to the serial
350		port.  It can and should block until there is space in the TX FIFO.
352		Locking: none.
353		Interrupts: caller dependent.
354		This call must not sleep
356	  poll_get_char(port)
357		Called by kgdb to read a single character directly from the serial
358		port.  If data is available, it should be returned; otherwise
359		the function should return NO_POLL_CHAR immediately.
361		Locking: none.
362		Interrupts: caller dependent.
363		This call must not sleep
365	Other functions
366	---------------
368	uart_update_timeout(port,cflag,baud)
369		Update the FIFO drain timeout, port->timeout, according to the
370		number of bits, parity, stop bits and baud rate.
372		Locking: caller is expected to take port->lock
373		Interrupts: n/a
375	uart_get_baud_rate(port,termios,old,min,max)
376		Return the numeric baud rate for the specified termios, taking
377		account of the special 38400 baud "kludge".  The B0 baud rate
378		is mapped to 9600 baud.
380		If the baud rate is not within min..max, then if old is non-NULL,
381		the original baud rate will be tried.  If that exceeds the
382		min..max constraint, 9600 baud will be returned.  termios will
383		be updated to the baud rate in use.
385		Note: min..max must always allow 9600 baud to be selected.
387		Locking: caller dependent.
388		Interrupts: n/a
390	uart_get_divisor(port,baud)
391		Return the divisor (baud_base / baud) for the specified baud
392		rate, appropriately rounded.
394		If 38400 baud and custom divisor is selected, return the
395		custom divisor instead.
397		Locking: caller dependent.
398		Interrupts: n/a
400	uart_match_port(port1,port2)
401		This utility function can be used to determine whether two
402		uart_port structures describe the same port.
404		Locking: n/a
405		Interrupts: n/a
407	uart_write_wakeup(port)
408		A driver is expected to call this function when the number of
409		characters in the transmit buffer have dropped below a threshold.
411		Locking: port->lock should be held.
412		Interrupts: n/a
414	uart_register_driver(drv)
415		Register a uart driver with the core driver.  We in turn register
416		with the tty layer, and initialise the core driver per-port state.
418		drv->port should be NULL, and the per-port structures should be
419		registered using uart_add_one_port after this call has succeeded.
421		Locking: none
422		Interrupts: enabled
424	uart_unregister_driver()
425		Remove all references to a driver from the core driver.  The low
426		level driver must have removed all its ports via the
427		uart_remove_one_port() if it registered them with uart_add_one_port().
429		Locking: none
430		Interrupts: enabled
432	uart_suspend_port()
434	uart_resume_port()
436	uart_add_one_port()
438	uart_remove_one_port()
440	Other notes
441	-----------
443	It is intended some day to drop the 'unused' entries from uart_port, and
444	allow low level drivers to register their own individual uart_port's with
445	the core.  This will allow drivers to use uart_port as a pointer to a
446	structure containing both the uart_port entry with their own extensions,
447	thus:
449		struct my_port {
450			struct uart_port	port;
451			int			my_stuff;
452		};
454	Modem control lines via GPIO
455	----------------------------
457	Some helpers are provided in order to set/get modem control lines via GPIO.
459	mctrl_gpio_init(port, idx):
460		This will get the {cts,rts,...}-gpios from device tree if they are
461		present and request them, set direction etc, and return an
462		allocated structure. devm_* functions are used, so there's no need
463		to call mctrl_gpio_free().
464		As this sets up the irq handling make sure to not handle changes to the
465		gpio input lines in your driver, too.
467	mctrl_gpio_free(dev, gpios):
468		This will free the requested gpios in mctrl_gpio_init().
469		As devm_* functions are used, there's generally no need to call
470		this function.
472	mctrl_gpio_to_gpiod(gpios, gidx)
473		This returns the gpio_desc structure associated to the modem line
474		index.
476	mctrl_gpio_set(gpios, mctrl):
477		This will sets the gpios according to the mctrl state.
479	mctrl_gpio_get(gpios, mctrl):
480		This will update mctrl with the gpios values.
482	mctrl_gpio_enable_ms(gpios):
483		Enables irqs and handling of changes to the ms lines.
485	mctrl_gpio_disable_ms(gpios):
486		Disables irqs and handling of changes to the ms lines.
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.