1
2			Low Level Serial API
3			--------------------
4
5
6This document is meant as a brief overview of some aspects of the new serial
7driver.  It is not complete, any questions you have should be directed to
8<rmk@arm.linux.org.uk>
9
10The reference implementation is contained within amba_pl011.c.
11
12
13
14Low Level Serial Hardware Driver
15--------------------------------
16
17The low level serial hardware driver is responsible for supplying port
18information (defined by uart_port) and a set of control methods (defined
19by uart_ops) to the core serial driver.  The low level driver is also
20responsible for handling interrupts for the port, and providing any
21console support.
22
23
24Console Support
25---------------
26
27The serial core provides a few helper functions.  This includes identifing
28the correct port structure (via uart_get_console) and decoding command line
29arguments (uart_parse_options).
30
31There is also a helper function (uart_console_write) which performs a
32character by character write, translating newlines to CRLF sequences.
33Driver writers are recommended to use this function rather than implementing
34their own version.
35
36
37Locking
38-------
39
40It is the responsibility of the low level hardware driver to perform the
41necessary locking using port->lock.  There are some exceptions (which
42are described in the uart_ops listing below.)
43
44There are two locks.  A per-port spinlock, and an overall semaphore.
45
46From the core driver perspective, the port->lock locks the following
47data:
48
49	port->mctrl
50	port->icount
51	port->state->xmit.head (circ_buf->head)
52	port->state->xmit.tail (circ_buf->tail)
53
54The low level driver is free to use this lock to provide any additional
55locking.
56
57The port_sem semaphore is used to protect against ports being added/
58removed or reconfigured at inappropriate times. Since v2.6.27, this
59semaphore has been the 'mutex' member of the tty_port struct, and
60commonly referred to as the port mutex.
61
62
63uart_ops
64--------
65
66The uart_ops structure is the main interface between serial_core and the
67hardware specific driver.  It contains all the methods to control the
68hardware.
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		- 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.
93
94	Locking: port->lock taken.
95	Interrupts: locally disabled.
96	This call must not sleep
97
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.
110
111	Locking: port->lock taken.
112	Interrupts: locally disabled.
113	This call must not sleep
114
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.
119
120	The driver should stop transmitting characters as soon as
121	possible.
122
123	Locking: port->lock taken.
124	Interrupts: locally disabled.
125	This call must not sleep
126
127  start_tx(port)
128	Start transmitting characters.
129
130	Locking: port->lock taken.
131	Interrupts: locally disabled.
132	This call must not sleep
133
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.
139
140	Locking: serialized with .unthrottle() and termios modification by the
141		 tty layer.
142
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.
148
149	Locking: serialized with .throttle() and termios modification by the
150		 tty layer.
151
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.
158
159	Do not transmit if ch == '\0' (__DISABLED_CHAR).
160
161	Locking: none.
162	Interrupts: caller dependent.
163
164  stop_rx(port)
165	Stop receiving characters; the port is in the process of
166	being closed.
167
168	Locking: port->lock taken.
169	Interrupts: locally disabled.
170	This call must not sleep
171
172  enable_ms(port)
173	Enable the modem status interrupts.
174
175	This method may be called multiple times.  Modem status
176	interrupts should be disabled when the shutdown method is
177	called.
178
179	Locking: port->lock taken.
180	Interrupts: locally disabled.
181	This call must not sleep
182
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.
188
189	Locking: caller holds tty_port->mutex
190
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.
195
196	This method will only be called when the port is initially opened.
197
198	Locking: port_sem taken.
199	Interrupts: globally disabled.
200
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.
206
207	Drivers must not access port->state once this call has completed.
208
209	This method will only be called when there are no more users of
210	this port.
211
212	Locking: port_sem taken.
213	Interrupts: caller dependent.
214
215  flush_buffer(port)
216	Flush any write buffers, reset any DMA state and stop any
217	ongoing DMA transfers.
218
219	This will be called whenever the port->state->xmit circular
220	buffer is cleared.
221
222	Locking: port->lock taken.
223	Interrupts: locally disabled.
224	This call must not sleep
225
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.
247
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
261
262	Other flags may be used (eg, xon/xoff characters) if your
263	hardware supports hardware "soft" flow control.
264
265	Locking: caller holds tty_port->mutex
266	Interrupts: caller dependent.
267	This call must not sleep
268
269  set_ldisc(port,termios)
270	Notifier for discipline change. See Documentation/serial/tty.txt.
271
272	Locking: caller holds tty_port->mutex
273
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.
278
279	This function should not be used to grab any resources.
280
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.
284
285	Locking: none.
286	Interrupts: caller dependent.
287
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.
292
293	Locking: none.
294	Interrupts: caller dependent.
295
296  release_port(port)
297	Release any memory and IO region resources currently in use by
298	the port.
299
300	Locking: none.
301	Interrupts: caller dependent.
302
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.
307
308	Locking: none.
309	Interrupts: caller dependent.
310
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.
317
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).
322
323	Locking: none.
324	Interrupts: caller dependent.
325
326  verify_port(port,serinfo)
327	Verify the new serial port information contained within serinfo is
328	suitable for this port type.
329
330	Locking: none.
331	Interrupts: caller dependent.
332
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>
336
337	Locking: none.
338	Interrupts: caller dependent.
339
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.
344
345	Locking: tty_mutex and tty_port->mutex taken.
346	Interrupts: n/a.
347
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.
351
352	Locking: none.
353	Interrupts: caller dependent.
354	This call must not sleep
355
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.
360
361	Locking: none.
362	Interrupts: caller dependent.
363	This call must not sleep
364
365Other functions
366---------------
367
368uart_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.
371
372	Locking: caller is expected to take port->lock
373	Interrupts: n/a
374
375uart_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.
379
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.
384
385	Note: min..max must always allow 9600 baud to be selected.
386
387	Locking: caller dependent.
388	Interrupts: n/a
389
390uart_get_divisor(port,baud)
391	Return the divisor (baud_base / baud) for the specified baud
392	rate, appropriately rounded.
393
394	If 38400 baud and custom divisor is selected, return the
395	custom divisor instead.
396
397	Locking: caller dependent.
398	Interrupts: n/a
399
400uart_match_port(port1,port2)
401	This utility function can be used to determine whether two
402	uart_port structures describe the same port.
403
404	Locking: n/a
405	Interrupts: n/a
406
407uart_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.
410
411	Locking: port->lock should be held.
412	Interrupts: n/a
413
414uart_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.
417
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.
420
421	Locking: none
422	Interrupts: enabled
423
424uart_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().
428
429	Locking: none
430	Interrupts: enabled
431
432uart_suspend_port()
433
434uart_resume_port()
435
436uart_add_one_port()
437
438uart_remove_one_port()
439
440Other notes
441-----------
442
443It is intended some day to drop the 'unused' entries from uart_port, and
444allow low level drivers to register their own individual uart_port's with
445the core.  This will allow drivers to use uart_port as a pointer to a
446structure containing both the uart_port entry with their own extensions,
447thus:
448
449	struct my_port {
450		struct uart_port	port;
451		int			my_stuff;
452	};
453
454Modem control lines via GPIO
455----------------------------
456
457Some helpers are provided in order to set/get modem control lines via GPIO.
458
459mctrl_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.
466
467mctrl_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.
471
472mctrl_gpio_to_gpiod(gpios, gidx)
473	This returns the gpio_desc structure associated to the modem line
474	index.
475
476mctrl_gpio_set(gpios, mctrl):
477	This will sets the gpios according to the mctrl state.
478
479mctrl_gpio_get(gpios, mctrl):
480	This will update mctrl with the gpios values.
481
482mctrl_gpio_enable_ms(gpios):
483	Enables irqs and handling of changes to the ms lines.
484
485mctrl_gpio_disable_ms(gpios):
486	Disables irqs and handling of changes to the ms lines.
487