Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | Low Level Serial API | |
3 | -------------------- | |
4 | ||
5 | ||
1da177e4 LT |
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 | ||
67ab7f59 | 10 | The reference implementation is contained within amba_pl011.c. |
1da177e4 LT |
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 | ||
67ab7f59 RK |
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 | ||
1da177e4 LT |
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. | |
67ab7f59 | 91 | - TIOCM_LOOP Set the port into loopback mode. |
1da177e4 LT |
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: | |
343fe407 | 104 | - TIOCM_CAR state of DCD signal |
1da177e4 LT |
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 | ||
c5f4644e RK |
113 | Locking: port->lock taken. |
114 | Interrupts: locally disabled. | |
1da177e4 LT |
115 | This call must not sleep |
116 | ||
b129a8cc | 117 | stop_tx(port) |
1da177e4 LT |
118 | Stop transmitting characters. This might be due to the CTS |
119 | line becoming inactive or the tty layer indicating we want | |
b129a8cc | 120 | to stop transmission due to an XOFF character. |
1da177e4 | 121 | |
6a8f8d72 RK |
122 | The driver should stop transmitting characters as soon as |
123 | possible. | |
124 | ||
1da177e4 LT |
125 | Locking: port->lock taken. |
126 | Interrupts: locally disabled. | |
127 | This call must not sleep | |
128 | ||
b129a8cc | 129 | start_tx(port) |
6a8f8d72 | 130 | Start transmitting characters. |
1da177e4 LT |
131 | |
132 | Locking: port->lock taken. | |
133 | Interrupts: locally disabled. | |
134 | This call must not sleep | |
135 | ||
136 | stop_rx(port) | |
137 | Stop receiving characters; the port is in the process of | |
138 | being closed. | |
139 | ||
140 | Locking: port->lock taken. | |
141 | Interrupts: locally disabled. | |
142 | This call must not sleep | |
143 | ||
144 | enable_ms(port) | |
145 | Enable the modem status interrupts. | |
146 | ||
67ab7f59 RK |
147 | This method may be called multiple times. Modem status |
148 | interrupts should be disabled when the shutdown method is | |
149 | called. | |
150 | ||
1da177e4 LT |
151 | Locking: port->lock taken. |
152 | Interrupts: locally disabled. | |
153 | This call must not sleep | |
154 | ||
155 | break_ctl(port,ctl) | |
156 | Control the transmission of a break signal. If ctl is | |
157 | nonzero, the break signal should be transmitted. The signal | |
158 | should be terminated when another call is made with a zero | |
159 | ctl. | |
160 | ||
161 | Locking: none. | |
162 | Interrupts: caller dependent. | |
163 | This call must not sleep | |
164 | ||
165 | startup(port) | |
166 | Grab any interrupt resources and initialise any low level driver | |
167 | state. Enable the port for reception. It should not activate | |
168 | RTS nor DTR; this will be done via a separate call to set_mctrl. | |
169 | ||
67ab7f59 RK |
170 | This method will only be called when the port is initially opened. |
171 | ||
1da177e4 LT |
172 | Locking: port_sem taken. |
173 | Interrupts: globally disabled. | |
174 | ||
175 | shutdown(port) | |
176 | Disable the port, disable any break condition that may be in | |
177 | effect, and free any interrupt resources. It should not disable | |
178 | RTS nor DTR; this will have already been done via a separate | |
179 | call to set_mctrl. | |
180 | ||
67ab7f59 RK |
181 | Drivers must not access port->info once this call has completed. |
182 | ||
183 | This method will only be called when there are no more users of | |
184 | this port. | |
185 | ||
1da177e4 LT |
186 | Locking: port_sem taken. |
187 | Interrupts: caller dependent. | |
188 | ||
6bb0e3a5 HS |
189 | flush_buffer(port) |
190 | Flush any write buffers, reset any DMA state and stop any | |
191 | ongoing DMA transfers. | |
192 | ||
193 | This will be called whenever the port->info->xmit circular | |
194 | buffer is cleared. | |
195 | ||
196 | Locking: port->lock taken. | |
197 | Interrupts: locally disabled. | |
198 | This call must not sleep | |
199 | ||
1da177e4 LT |
200 | set_termios(port,termios,oldtermios) |
201 | Change the port parameters, including word length, parity, stop | |
202 | bits. Update read_status_mask and ignore_status_mask to indicate | |
203 | the types of events we are interested in receiving. Relevant | |
204 | termios->c_cflag bits are: | |
205 | CSIZE - word size | |
206 | CSTOPB - 2 stop bits | |
207 | PARENB - parity enable | |
208 | PARODD - odd parity (when PARENB is in force) | |
209 | CREAD - enable reception of characters (if not set, | |
210 | still receive characters from the port, but | |
211 | throw them away. | |
212 | CRTSCTS - if set, enable CTS status change reporting | |
213 | CLOCAL - if not set, enable modem status change | |
214 | reporting. | |
215 | Relevant termios->c_iflag bits are: | |
216 | INPCK - enable frame and parity error events to be | |
217 | passed to the TTY layer. | |
218 | BRKINT | |
219 | PARMRK - both of these enable break events to be | |
220 | passed to the TTY layer. | |
221 | ||
222 | IGNPAR - ignore parity and framing errors | |
223 | IGNBRK - ignore break errors, If IGNPAR is also | |
224 | set, ignore overrun errors as well. | |
225 | The interaction of the iflag bits is as follows (parity error | |
226 | given as an example): | |
227 | Parity error INPCK IGNPAR | |
89f3da3e | 228 | n/a 0 n/a character received, marked as |
1da177e4 | 229 | TTY_NORMAL |
89f3da3e PK |
230 | None 1 n/a character received, marked as |
231 | TTY_NORMAL | |
232 | Yes 1 0 character received, marked as | |
1da177e4 | 233 | TTY_PARITY |
89f3da3e | 234 | Yes 1 1 character discarded |
1da177e4 LT |
235 | |
236 | Other flags may be used (eg, xon/xoff characters) if your | |
237 | hardware supports hardware "soft" flow control. | |
238 | ||
239 | Locking: none. | |
240 | Interrupts: caller dependent. | |
241 | This call must not sleep | |
242 | ||
243 | pm(port,state,oldstate) | |
244 | Perform any power management related activities on the specified | |
6f538fe3 LW |
245 | port. State indicates the new state (defined by |
246 | enum uart_pm_state), oldstate indicates the previous state. | |
1da177e4 LT |
247 | |
248 | This function should not be used to grab any resources. | |
249 | ||
250 | This will be called when the port is initially opened and finally | |
251 | closed, except when the port is also the system console. This | |
252 | will occur even if CONFIG_PM is not set. | |
253 | ||
254 | Locking: none. | |
255 | Interrupts: caller dependent. | |
256 | ||
257 | type(port) | |
258 | Return a pointer to a string constant describing the specified | |
259 | port, or return NULL, in which case the string 'unknown' is | |
260 | substituted. | |
261 | ||
262 | Locking: none. | |
263 | Interrupts: caller dependent. | |
264 | ||
265 | release_port(port) | |
266 | Release any memory and IO region resources currently in use by | |
267 | the port. | |
268 | ||
269 | Locking: none. | |
270 | Interrupts: caller dependent. | |
271 | ||
272 | request_port(port) | |
273 | Request any memory and IO region resources required by the port. | |
274 | If any fail, no resources should be registered when this function | |
275 | returns, and it should return -EBUSY on failure. | |
276 | ||
277 | Locking: none. | |
278 | Interrupts: caller dependent. | |
279 | ||
280 | config_port(port,type) | |
281 | Perform any autoconfiguration steps required for the port. `type` | |
282 | contains a bit mask of the required configuration. UART_CONFIG_TYPE | |
283 | indicates that the port requires detection and identification. | |
284 | port->type should be set to the type found, or PORT_UNKNOWN if | |
285 | no port was detected. | |
286 | ||
287 | UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal, | |
288 | which should be probed using standard kernel autoprobing techniques. | |
289 | This is not necessary on platforms where ports have interrupts | |
290 | internally hard wired (eg, system on a chip implementations). | |
291 | ||
292 | Locking: none. | |
293 | Interrupts: caller dependent. | |
294 | ||
295 | verify_port(port,serinfo) | |
296 | Verify the new serial port information contained within serinfo is | |
297 | suitable for this port type. | |
298 | ||
299 | Locking: none. | |
300 | Interrupts: caller dependent. | |
301 | ||
302 | ioctl(port,cmd,arg) | |
303 | Perform any port specific IOCTLs. IOCTL commands must be defined | |
304 | using the standard numbering system found in <asm/ioctl.h> | |
305 | ||
306 | Locking: none. | |
307 | Interrupts: caller dependent. | |
308 | ||
309 | Other functions | |
310 | --------------- | |
311 | ||
6a8f8d72 | 312 | uart_update_timeout(port,cflag,baud) |
1da177e4 | 313 | Update the FIFO drain timeout, port->timeout, according to the |
6a8f8d72 | 314 | number of bits, parity, stop bits and baud rate. |
1da177e4 LT |
315 | |
316 | Locking: caller is expected to take port->lock | |
317 | Interrupts: n/a | |
318 | ||
6a8f8d72 | 319 | uart_get_baud_rate(port,termios,old,min,max) |
1da177e4 LT |
320 | Return the numeric baud rate for the specified termios, taking |
321 | account of the special 38400 baud "kludge". The B0 baud rate | |
322 | is mapped to 9600 baud. | |
323 | ||
6a8f8d72 RK |
324 | If the baud rate is not within min..max, then if old is non-NULL, |
325 | the original baud rate will be tried. If that exceeds the | |
326 | min..max constraint, 9600 baud will be returned. termios will | |
327 | be updated to the baud rate in use. | |
328 | ||
329 | Note: min..max must always allow 9600 baud to be selected. | |
330 | ||
1da177e4 LT |
331 | Locking: caller dependent. |
332 | Interrupts: n/a | |
333 | ||
6a8f8d72 RK |
334 | uart_get_divisor(port,baud) |
335 | Return the divsor (baud_base / baud) for the specified baud | |
336 | rate, appropriately rounded. | |
1da177e4 LT |
337 | |
338 | If 38400 baud and custom divisor is selected, return the | |
339 | custom divisor instead. | |
340 | ||
341 | Locking: caller dependent. | |
342 | Interrupts: n/a | |
343 | ||
6a8f8d72 RK |
344 | uart_match_port(port1,port2) |
345 | This utility function can be used to determine whether two | |
346 | uart_port structures describe the same port. | |
347 | ||
348 | Locking: n/a | |
349 | Interrupts: n/a | |
350 | ||
351 | uart_write_wakeup(port) | |
352 | A driver is expected to call this function when the number of | |
353 | characters in the transmit buffer have dropped below a threshold. | |
354 | ||
355 | Locking: port->lock should be held. | |
356 | Interrupts: n/a | |
357 | ||
358 | uart_register_driver(drv) | |
359 | Register a uart driver with the core driver. We in turn register | |
360 | with the tty layer, and initialise the core driver per-port state. | |
361 | ||
362 | drv->port should be NULL, and the per-port structures should be | |
363 | registered using uart_add_one_port after this call has succeeded. | |
364 | ||
365 | Locking: none | |
366 | Interrupts: enabled | |
367 | ||
368 | uart_unregister_driver() | |
369 | Remove all references to a driver from the core driver. The low | |
370 | level driver must have removed all its ports via the | |
371 | uart_remove_one_port() if it registered them with uart_add_one_port(). | |
372 | ||
373 | Locking: none | |
374 | Interrupts: enabled | |
375 | ||
376 | uart_suspend_port() | |
377 | ||
378 | uart_resume_port() | |
379 | ||
380 | uart_add_one_port() | |
381 | ||
382 | uart_remove_one_port() | |
383 | ||
1da177e4 LT |
384 | Other notes |
385 | ----------- | |
386 | ||
387 | It is intended some day to drop the 'unused' entries from uart_port, and | |
388 | allow low level drivers to register their own individual uart_port's with | |
389 | the core. This will allow drivers to use uart_port as a pointer to a | |
390 | structure containing both the uart_port entry with their own extensions, | |
391 | thus: | |
392 | ||
393 | struct my_port { | |
394 | struct uart_port port; | |
395 | int my_stuff; | |
396 | }; |