]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | Low Level Serial API | |
3 | -------------------- | |
4 | ||
5 | ||
6 | $Id: driver,v 1.10 2002/07/22 15:27:30 rmk Exp $ | |
7 | ||
8 | ||
9 | This document is meant as a brief overview of some aspects of the new serial | |
10 | driver. It is not complete, any questions you have should be directed to | |
11 | <rmk@arm.linux.org.uk> | |
12 | ||
13 | The reference implementation is contained within serial_amba.c. | |
14 | ||
15 | ||
16 | ||
17 | Low Level Serial Hardware Driver | |
18 | -------------------------------- | |
19 | ||
20 | The low level serial hardware driver is responsible for supplying port | |
21 | information (defined by uart_port) and a set of control methods (defined | |
22 | by uart_ops) to the core serial driver. The low level driver is also | |
23 | responsible for handling interrupts for the port, and providing any | |
24 | console support. | |
25 | ||
26 | ||
27 | Console Support | |
28 | --------------- | |
29 | ||
30 | The serial core provides a few helper functions. This includes identifing | |
31 | the correct port structure (via uart_get_console) and decoding command line | |
32 | arguments (uart_parse_options). | |
33 | ||
34 | ||
35 | Locking | |
36 | ------- | |
37 | ||
38 | It is the responsibility of the low level hardware driver to perform the | |
39 | necessary locking using port->lock. There are some exceptions (which | |
40 | are described in the uart_ops listing below.) | |
41 | ||
42 | There are three locks. A per-port spinlock, a per-port tmpbuf semaphore, | |
43 | and an overall semaphore. | |
44 | ||
45 | From the core driver perspective, the port->lock locks the following | |
46 | data: | |
47 | ||
48 | port->mctrl | |
49 | port->icount | |
50 | info->xmit.head (circ->head) | |
51 | info->xmit.tail (circ->tail) | |
52 | ||
53 | The low level driver is free to use this lock to provide any additional | |
54 | locking. | |
55 | ||
56 | The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded | |
57 | access to the info->tmpbuf bouncebuffer used for port writes. | |
58 | ||
59 | The port_sem semaphore is used to protect against ports being added/ | |
60 | removed or reconfigured at inappropriate times. | |
61 | ||
62 | ||
63 | uart_ops | |
64 | -------- | |
65 | ||
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. | |
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 | If the appropriate bit is set, the signal should be driven | |
90 | active. If the bit is clear, the signal should be driven | |
91 | inactive. | |
92 | ||
93 | Locking: port->lock taken. | |
94 | Interrupts: locally disabled. | |
95 | This call must not sleep | |
96 | ||
97 | get_mctrl(port) | |
98 | Returns the current state of modem control inputs. The state | |
99 | of the outputs should not be returned, since the core keeps | |
100 | track of their state. The state information should include: | |
101 | - TIOCM_DCD state of DCD signal | |
102 | - TIOCM_CTS state of CTS signal | |
103 | - TIOCM_DSR state of DSR signal | |
104 | - TIOCM_RI state of RI signal | |
105 | The bit is set if the signal is currently driven active. If | |
106 | the port does not support CTS, DCD or DSR, the driver should | |
107 | indicate that the signal is permanently active. If RI is | |
108 | not available, the signal should not be indicated as active. | |
109 | ||
110 | Locking: none. | |
111 | Interrupts: caller dependent. | |
112 | This call must not sleep | |
113 | ||
114 | stop_tx(port,tty_stop) | |
115 | Stop transmitting characters. This might be due to the CTS | |
116 | line becoming inactive or the tty layer indicating we want | |
117 | to stop transmission. | |
118 | ||
119 | tty_stop: 1 if this call is due to the TTY layer issuing a | |
120 | TTY stop to the driver (equiv to rs_stop). | |
121 | ||
122 | Locking: port->lock taken. | |
123 | Interrupts: locally disabled. | |
124 | This call must not sleep | |
125 | ||
126 | start_tx(port,tty_start) | |
127 | start transmitting characters. (incidentally, nonempty will | |
128 | always be nonzero, and shouldn't be used - it will be dropped). | |
129 | ||
130 | tty_start: 1 if this call was due to the TTY layer issuing | |
131 | a TTY start to the driver (equiv to rs_start) | |
132 | ||
133 | Locking: port->lock taken. | |
134 | Interrupts: locally disabled. | |
135 | This call must not sleep | |
136 | ||
137 | stop_rx(port) | |
138 | Stop receiving characters; the port is in the process of | |
139 | being closed. | |
140 | ||
141 | Locking: port->lock taken. | |
142 | Interrupts: locally disabled. | |
143 | This call must not sleep | |
144 | ||
145 | enable_ms(port) | |
146 | Enable the modem status interrupts. | |
147 | ||
148 | Locking: port->lock taken. | |
149 | Interrupts: locally disabled. | |
150 | This call must not sleep | |
151 | ||
152 | break_ctl(port,ctl) | |
153 | Control the transmission of a break signal. If ctl is | |
154 | nonzero, the break signal should be transmitted. The signal | |
155 | should be terminated when another call is made with a zero | |
156 | ctl. | |
157 | ||
158 | Locking: none. | |
159 | Interrupts: caller dependent. | |
160 | This call must not sleep | |
161 | ||
162 | startup(port) | |
163 | Grab any interrupt resources and initialise any low level driver | |
164 | state. Enable the port for reception. It should not activate | |
165 | RTS nor DTR; this will be done via a separate call to set_mctrl. | |
166 | ||
167 | Locking: port_sem taken. | |
168 | Interrupts: globally disabled. | |
169 | ||
170 | shutdown(port) | |
171 | Disable the port, disable any break condition that may be in | |
172 | effect, and free any interrupt resources. It should not disable | |
173 | RTS nor DTR; this will have already been done via a separate | |
174 | call to set_mctrl. | |
175 | ||
176 | Locking: port_sem taken. | |
177 | Interrupts: caller dependent. | |
178 | ||
179 | set_termios(port,termios,oldtermios) | |
180 | Change the port parameters, including word length, parity, stop | |
181 | bits. Update read_status_mask and ignore_status_mask to indicate | |
182 | the types of events we are interested in receiving. Relevant | |
183 | termios->c_cflag bits are: | |
184 | CSIZE - word size | |
185 | CSTOPB - 2 stop bits | |
186 | PARENB - parity enable | |
187 | PARODD - odd parity (when PARENB is in force) | |
188 | CREAD - enable reception of characters (if not set, | |
189 | still receive characters from the port, but | |
190 | throw them away. | |
191 | CRTSCTS - if set, enable CTS status change reporting | |
192 | CLOCAL - if not set, enable modem status change | |
193 | reporting. | |
194 | Relevant termios->c_iflag bits are: | |
195 | INPCK - enable frame and parity error events to be | |
196 | passed to the TTY layer. | |
197 | BRKINT | |
198 | PARMRK - both of these enable break events to be | |
199 | passed to the TTY layer. | |
200 | ||
201 | IGNPAR - ignore parity and framing errors | |
202 | IGNBRK - ignore break errors, If IGNPAR is also | |
203 | set, ignore overrun errors as well. | |
204 | The interaction of the iflag bits is as follows (parity error | |
205 | given as an example): | |
206 | Parity error INPCK IGNPAR | |
207 | None n/a n/a character received | |
208 | Yes n/a 0 character discarded | |
209 | Yes 0 1 character received, marked as | |
210 | TTY_NORMAL | |
211 | Yes 1 1 character received, marked as | |
212 | TTY_PARITY | |
213 | ||
214 | Other flags may be used (eg, xon/xoff characters) if your | |
215 | hardware supports hardware "soft" flow control. | |
216 | ||
217 | Locking: none. | |
218 | Interrupts: caller dependent. | |
219 | This call must not sleep | |
220 | ||
221 | pm(port,state,oldstate) | |
222 | Perform any power management related activities on the specified | |
223 | port. State indicates the new state (defined by ACPI D0-D3), | |
224 | oldstate indicates the previous state. Essentially, D0 means | |
225 | fully on, D3 means powered down. | |
226 | ||
227 | This function should not be used to grab any resources. | |
228 | ||
229 | This will be called when the port is initially opened and finally | |
230 | closed, except when the port is also the system console. This | |
231 | will occur even if CONFIG_PM is not set. | |
232 | ||
233 | Locking: none. | |
234 | Interrupts: caller dependent. | |
235 | ||
236 | type(port) | |
237 | Return a pointer to a string constant describing the specified | |
238 | port, or return NULL, in which case the string 'unknown' is | |
239 | substituted. | |
240 | ||
241 | Locking: none. | |
242 | Interrupts: caller dependent. | |
243 | ||
244 | release_port(port) | |
245 | Release any memory and IO region resources currently in use by | |
246 | the port. | |
247 | ||
248 | Locking: none. | |
249 | Interrupts: caller dependent. | |
250 | ||
251 | request_port(port) | |
252 | Request any memory and IO region resources required by the port. | |
253 | If any fail, no resources should be registered when this function | |
254 | returns, and it should return -EBUSY on failure. | |
255 | ||
256 | Locking: none. | |
257 | Interrupts: caller dependent. | |
258 | ||
259 | config_port(port,type) | |
260 | Perform any autoconfiguration steps required for the port. `type` | |
261 | contains a bit mask of the required configuration. UART_CONFIG_TYPE | |
262 | indicates that the port requires detection and identification. | |
263 | port->type should be set to the type found, or PORT_UNKNOWN if | |
264 | no port was detected. | |
265 | ||
266 | UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal, | |
267 | which should be probed using standard kernel autoprobing techniques. | |
268 | This is not necessary on platforms where ports have interrupts | |
269 | internally hard wired (eg, system on a chip implementations). | |
270 | ||
271 | Locking: none. | |
272 | Interrupts: caller dependent. | |
273 | ||
274 | verify_port(port,serinfo) | |
275 | Verify the new serial port information contained within serinfo is | |
276 | suitable for this port type. | |
277 | ||
278 | Locking: none. | |
279 | Interrupts: caller dependent. | |
280 | ||
281 | ioctl(port,cmd,arg) | |
282 | Perform any port specific IOCTLs. IOCTL commands must be defined | |
283 | using the standard numbering system found in <asm/ioctl.h> | |
284 | ||
285 | Locking: none. | |
286 | Interrupts: caller dependent. | |
287 | ||
288 | Other functions | |
289 | --------------- | |
290 | ||
291 | uart_update_timeout(port,cflag,quot) | |
292 | Update the FIFO drain timeout, port->timeout, according to the | |
293 | number of bits, parity, stop bits and quotient. | |
294 | ||
295 | Locking: caller is expected to take port->lock | |
296 | Interrupts: n/a | |
297 | ||
298 | uart_get_baud_rate(port,termios) | |
299 | Return the numeric baud rate for the specified termios, taking | |
300 | account of the special 38400 baud "kludge". The B0 baud rate | |
301 | is mapped to 9600 baud. | |
302 | ||
303 | Locking: caller dependent. | |
304 | Interrupts: n/a | |
305 | ||
306 | uart_get_divisor(port,termios,oldtermios) | |
307 | Return the divsor (baud_base / baud) for the selected baud rate | |
308 | specified by termios. If the baud rate is out of range, try | |
309 | the original baud rate specified by oldtermios (if non-NULL). | |
310 | If that fails, try 9600 baud. | |
311 | ||
312 | If 38400 baud and custom divisor is selected, return the | |
313 | custom divisor instead. | |
314 | ||
315 | Locking: caller dependent. | |
316 | Interrupts: n/a | |
317 | ||
318 | Other notes | |
319 | ----------- | |
320 | ||
321 | It is intended some day to drop the 'unused' entries from uart_port, and | |
322 | allow low level drivers to register their own individual uart_port's with | |
323 | the core. This will allow drivers to use uart_port as a pointer to a | |
324 | structure containing both the uart_port entry with their own extensions, | |
325 | thus: | |
326 | ||
327 | struct my_port { | |
328 | struct uart_port port; | |
329 | int my_stuff; | |
330 | }; |