1 | // SPDX-License-Identifier: GPL-2.0 |
2 | /* |
3 | * USB Serial Converter stuff |
4 | * |
5 | * Copyright (C) 1999 - 2012 |
6 | * Greg Kroah-Hartman (greg@kroah.com) |
7 | */ |
8 | |
9 | #ifndef __LINUX_USB_SERIAL_H |
10 | #define __LINUX_USB_SERIAL_H |
11 | |
12 | #include <linux/kref.h> |
13 | #include <linux/mutex.h> |
14 | #include <linux/serial.h> |
15 | #include <linux/kfifo.h> |
16 | |
17 | /* The maximum number of ports one device can grab at once */ |
18 | #define MAX_NUM_PORTS 16 |
19 | |
20 | /* USB serial flags */ |
21 | #define USB_SERIAL_WRITE_BUSY 0 |
22 | #define USB_SERIAL_THROTTLED 1 |
23 | |
24 | /** |
25 | * usb_serial_port: structure for the specific ports of a device. |
26 | * @serial: pointer back to the struct usb_serial owner of this port. |
27 | * @port: pointer to the corresponding tty_port for this port. |
28 | * @lock: spinlock to grab when updating portions of this structure. |
29 | * @minor: the minor number of the port |
30 | * @port_number: the struct usb_serial port number of this port (starts at 0) |
31 | * @interrupt_in_buffer: pointer to the interrupt in buffer for this port. |
32 | * @interrupt_in_urb: pointer to the interrupt in struct urb for this port. |
33 | * @interrupt_in_endpointAddress: endpoint address for the interrupt in pipe |
34 | * for this port. |
35 | * @interrupt_out_buffer: pointer to the interrupt out buffer for this port. |
36 | * @interrupt_out_size: the size of the interrupt_out_buffer, in bytes. |
37 | * @interrupt_out_urb: pointer to the interrupt out struct urb for this port. |
38 | * @interrupt_out_endpointAddress: endpoint address for the interrupt out pipe |
39 | * for this port. |
40 | * @bulk_in_buffer: pointer to the bulk in buffer for this port. |
41 | * @bulk_in_size: the size of the bulk_in_buffer, in bytes. |
42 | * @read_urb: pointer to the bulk in struct urb for this port. |
43 | * @bulk_in_endpointAddress: endpoint address for the bulk in pipe for this |
44 | * port. |
45 | * @bulk_in_buffers: pointers to the bulk in buffers for this port |
46 | * @read_urbs: pointers to the bulk in urbs for this port |
47 | * @read_urbs_free: status bitmap the for bulk in urbs |
48 | * @bulk_out_buffer: pointer to the bulk out buffer for this port. |
49 | * @bulk_out_size: the size of the bulk_out_buffer, in bytes. |
50 | * @write_urb: pointer to the bulk out struct urb for this port. |
51 | * @write_fifo: kfifo used to buffer outgoing data |
52 | * @bulk_out_buffers: pointers to the bulk out buffers for this port |
53 | * @write_urbs: pointers to the bulk out urbs for this port |
54 | * @write_urbs_free: status bitmap the for bulk out urbs |
55 | * @icount: interrupt counters |
56 | * @tx_bytes: number of bytes currently in host stack queues |
57 | * @bulk_out_endpointAddress: endpoint address for the bulk out pipe for this |
58 | * port. |
59 | * @flags: usb serial port flags |
60 | * @work: work queue entry for the line discipline waking up. |
61 | * @dev: pointer to the serial device |
62 | * |
63 | * This structure is used by the usb-serial core and drivers for the specific |
64 | * ports of a device. |
65 | */ |
66 | struct usb_serial_port { |
67 | struct usb_serial *serial; |
68 | struct tty_port port; |
69 | spinlock_t lock; |
70 | u32 minor; |
71 | u8 port_number; |
72 | |
73 | unsigned char *interrupt_in_buffer; |
74 | struct urb *interrupt_in_urb; |
75 | __u8 interrupt_in_endpointAddress; |
76 | |
77 | unsigned char *interrupt_out_buffer; |
78 | int interrupt_out_size; |
79 | struct urb *interrupt_out_urb; |
80 | __u8 interrupt_out_endpointAddress; |
81 | |
82 | unsigned char *bulk_in_buffer; |
83 | int bulk_in_size; |
84 | struct urb *read_urb; |
85 | __u8 bulk_in_endpointAddress; |
86 | |
87 | unsigned char *bulk_in_buffers[2]; |
88 | struct urb *read_urbs[2]; |
89 | unsigned long read_urbs_free; |
90 | |
91 | unsigned char *bulk_out_buffer; |
92 | int bulk_out_size; |
93 | struct urb *write_urb; |
94 | struct kfifo write_fifo; |
95 | |
96 | unsigned char *bulk_out_buffers[2]; |
97 | struct urb *write_urbs[2]; |
98 | unsigned long write_urbs_free; |
99 | __u8 bulk_out_endpointAddress; |
100 | |
101 | struct async_icount icount; |
102 | int tx_bytes; |
103 | |
104 | unsigned long flags; |
105 | struct work_struct work; |
106 | unsigned long sysrq; /* sysrq timeout */ |
107 | struct device dev; |
108 | }; |
109 | #define to_usb_serial_port(d) container_of(d, struct usb_serial_port, dev) |
110 | |
111 | /* get and set the port private data pointer helper functions */ |
112 | static inline void *usb_get_serial_port_data(struct usb_serial_port *port) |
113 | { |
114 | return dev_get_drvdata(dev: &port->dev); |
115 | } |
116 | |
117 | static inline void usb_set_serial_port_data(struct usb_serial_port *port, |
118 | void *data) |
119 | { |
120 | dev_set_drvdata(dev: &port->dev, data); |
121 | } |
122 | |
123 | /** |
124 | * usb_serial - structure used by the usb-serial core for a device |
125 | * @dev: pointer to the struct usb_device for this device |
126 | * @type: pointer to the struct usb_serial_driver for this device |
127 | * @interface: pointer to the struct usb_interface for this device |
128 | * @sibling: pointer to the struct usb_interface of any sibling interface |
129 | * @suspend_count: number of suspended (sibling) interfaces |
130 | * @num_ports: the number of ports this device has |
131 | * @num_interrupt_in: number of interrupt in endpoints we have |
132 | * @num_interrupt_out: number of interrupt out endpoints we have |
133 | * @num_bulk_in: number of bulk in endpoints we have |
134 | * @num_bulk_out: number of bulk out endpoints we have |
135 | * @port: array of struct usb_serial_port structures for the different ports. |
136 | * @private: place to put any driver specific information that is needed. The |
137 | * usb-serial driver is required to manage this data, the usb-serial core |
138 | * will not touch this. Use usb_get_serial_data() and |
139 | * usb_set_serial_data() to access this. |
140 | */ |
141 | struct usb_serial { |
142 | struct usb_device *dev; |
143 | struct usb_serial_driver *type; |
144 | struct usb_interface *interface; |
145 | struct usb_interface *sibling; |
146 | unsigned int suspend_count; |
147 | unsigned char disconnected:1; |
148 | unsigned char attached:1; |
149 | unsigned char minors_reserved:1; |
150 | unsigned char num_ports; |
151 | unsigned char num_port_pointers; |
152 | unsigned char num_interrupt_in; |
153 | unsigned char num_interrupt_out; |
154 | unsigned char num_bulk_in; |
155 | unsigned char num_bulk_out; |
156 | struct usb_serial_port *port[MAX_NUM_PORTS]; |
157 | struct kref kref; |
158 | struct mutex disc_mutex; |
159 | void *private; |
160 | }; |
161 | #define to_usb_serial(d) container_of(d, struct usb_serial, kref) |
162 | |
163 | /* get and set the serial private data pointer helper functions */ |
164 | static inline void *usb_get_serial_data(struct usb_serial *serial) |
165 | { |
166 | return serial->private; |
167 | } |
168 | |
169 | static inline void usb_set_serial_data(struct usb_serial *serial, void *data) |
170 | { |
171 | serial->private = data; |
172 | } |
173 | |
174 | struct usb_serial_endpoints { |
175 | unsigned char num_bulk_in; |
176 | unsigned char num_bulk_out; |
177 | unsigned char num_interrupt_in; |
178 | unsigned char num_interrupt_out; |
179 | struct usb_endpoint_descriptor *bulk_in[MAX_NUM_PORTS]; |
180 | struct usb_endpoint_descriptor *bulk_out[MAX_NUM_PORTS]; |
181 | struct usb_endpoint_descriptor *interrupt_in[MAX_NUM_PORTS]; |
182 | struct usb_endpoint_descriptor *interrupt_out[MAX_NUM_PORTS]; |
183 | }; |
184 | |
185 | /** |
186 | * usb_serial_driver - describes a usb serial driver |
187 | * @description: pointer to a string that describes this driver. This string |
188 | * used in the syslog messages when a device is inserted or removed. |
189 | * @id_table: pointer to a list of usb_device_id structures that define all |
190 | * of the devices this structure can support. |
191 | * @num_ports: the number of different ports this device will have. |
192 | * @num_bulk_in: minimum number of bulk-in endpoints |
193 | * @num_bulk_out: minimum number of bulk-out endpoints |
194 | * @num_interrupt_in: minimum number of interrupt-in endpoints |
195 | * @num_interrupt_out: minimum number of interrupt-out endpoints |
196 | * @bulk_in_size: minimum number of bytes to allocate for bulk-in buffer |
197 | * (0 = end-point size) |
198 | * @bulk_out_size: bytes to allocate for bulk-out buffer (0 = end-point size) |
199 | * @calc_num_ports: pointer to a function to determine how many ports this |
200 | * device has dynamically. It can also be used to verify the number of |
201 | * endpoints or to modify the port-endpoint mapping. It will be called |
202 | * after the probe() callback is called, but before attach(). |
203 | * @probe: pointer to the driver's probe function. |
204 | * This will be called when the device is inserted into the system, |
205 | * but before the device has been fully initialized by the usb_serial |
206 | * subsystem. Use this function to download any firmware to the device, |
207 | * or any other early initialization that might be needed. |
208 | * Return 0 to continue on with the initialization sequence. Anything |
209 | * else will abort it. |
210 | * @attach: pointer to the driver's attach function. |
211 | * This will be called when the struct usb_serial structure is fully |
212 | * set up. Do any local initialization of the device, or any private |
213 | * memory structure allocation at this point in time. |
214 | * @disconnect: pointer to the driver's disconnect function. This will be |
215 | * called when the device is unplugged or unbound from the driver. |
216 | * @release: pointer to the driver's release function. This will be called |
217 | * when the usb_serial data structure is about to be destroyed. |
218 | * @usb_driver: pointer to the struct usb_driver that controls this |
219 | * device. This is necessary to allow dynamic ids to be added to |
220 | * the driver from sysfs. |
221 | * |
222 | * This structure is defines a USB Serial driver. It provides all of |
223 | * the information that the USB serial core code needs. If the function |
224 | * pointers are defined, then the USB serial core code will call them when |
225 | * the corresponding tty port functions are called. If they are not |
226 | * called, the generic serial function will be used instead. |
227 | * |
228 | * The driver.owner field should be set to the module owner of this driver. |
229 | * The driver.name field should be set to the name of this driver (remember |
230 | * it will show up in sysfs, so it needs to be short and to the point. |
231 | * Using the module name is a good idea.) |
232 | */ |
233 | struct usb_serial_driver { |
234 | const char *description; |
235 | const struct usb_device_id *id_table; |
236 | |
237 | struct list_head driver_list; |
238 | struct device_driver driver; |
239 | struct usb_driver *usb_driver; |
240 | struct usb_dynids dynids; |
241 | |
242 | unsigned char num_ports; |
243 | |
244 | unsigned char num_bulk_in; |
245 | unsigned char num_bulk_out; |
246 | unsigned char num_interrupt_in; |
247 | unsigned char num_interrupt_out; |
248 | |
249 | size_t bulk_in_size; |
250 | size_t bulk_out_size; |
251 | |
252 | int (*probe)(struct usb_serial *serial, const struct usb_device_id *id); |
253 | int (*attach)(struct usb_serial *serial); |
254 | int (*calc_num_ports)(struct usb_serial *serial, |
255 | struct usb_serial_endpoints *epds); |
256 | |
257 | void (*disconnect)(struct usb_serial *serial); |
258 | void (*release)(struct usb_serial *serial); |
259 | |
260 | int (*port_probe)(struct usb_serial_port *port); |
261 | void (*port_remove)(struct usb_serial_port *port); |
262 | |
263 | int (*suspend)(struct usb_serial *serial, pm_message_t message); |
264 | int (*resume)(struct usb_serial *serial); |
265 | int (*reset_resume)(struct usb_serial *serial); |
266 | |
267 | /* serial function calls */ |
268 | /* Called by console and by the tty layer */ |
269 | int (*open)(struct tty_struct *tty, struct usb_serial_port *port); |
270 | void (*close)(struct usb_serial_port *port); |
271 | int (*write)(struct tty_struct *tty, struct usb_serial_port *port, |
272 | const unsigned char *buf, int count); |
273 | /* Called only by the tty layer */ |
274 | unsigned int (*write_room)(struct tty_struct *tty); |
275 | int (*ioctl)(struct tty_struct *tty, |
276 | unsigned int cmd, unsigned long arg); |
277 | void (*get_serial)(struct tty_struct *tty, struct serial_struct *ss); |
278 | int (*set_serial)(struct tty_struct *tty, struct serial_struct *ss); |
279 | void (*set_termios)(struct tty_struct *tty, struct usb_serial_port *port, |
280 | const struct ktermios *old); |
281 | int (*break_ctl)(struct tty_struct *tty, int break_state); |
282 | unsigned int (*chars_in_buffer)(struct tty_struct *tty); |
283 | void (*wait_until_sent)(struct tty_struct *tty, long timeout); |
284 | bool (*tx_empty)(struct usb_serial_port *port); |
285 | void (*throttle)(struct tty_struct *tty); |
286 | void (*unthrottle)(struct tty_struct *tty); |
287 | int (*tiocmget)(struct tty_struct *tty); |
288 | int (*tiocmset)(struct tty_struct *tty, |
289 | unsigned int set, unsigned int clear); |
290 | int (*tiocmiwait)(struct tty_struct *tty, unsigned long arg); |
291 | int (*get_icount)(struct tty_struct *tty, |
292 | struct serial_icounter_struct *icount); |
293 | /* Called by the tty layer for port level work. There may or may not |
294 | be an attached tty at this point */ |
295 | void (*dtr_rts)(struct usb_serial_port *port, int on); |
296 | int (*carrier_raised)(struct usb_serial_port *port); |
297 | /* Called by the usb serial hooks to allow the user to rework the |
298 | termios state */ |
299 | void (*init_termios)(struct tty_struct *tty); |
300 | /* USB events */ |
301 | void (*read_int_callback)(struct urb *urb); |
302 | void (*write_int_callback)(struct urb *urb); |
303 | void (*read_bulk_callback)(struct urb *urb); |
304 | void (*write_bulk_callback)(struct urb *urb); |
305 | /* Called by the generic read bulk callback */ |
306 | void (*process_read_urb)(struct urb *urb); |
307 | /* Called by the generic write implementation */ |
308 | int (*prepare_write_buffer)(struct usb_serial_port *port, |
309 | void *dest, size_t size); |
310 | }; |
311 | #define to_usb_serial_driver(d) \ |
312 | container_of(d, struct usb_serial_driver, driver) |
313 | |
314 | int usb_serial_register_drivers(struct usb_serial_driver *const serial_drivers[], |
315 | const char *name, const struct usb_device_id *id_table); |
316 | void usb_serial_deregister_drivers(struct usb_serial_driver *const serial_drivers[]); |
317 | void usb_serial_port_softint(struct usb_serial_port *port); |
318 | |
319 | int usb_serial_suspend(struct usb_interface *intf, pm_message_t message); |
320 | int usb_serial_resume(struct usb_interface *intf); |
321 | |
322 | /* USB Serial console functions */ |
323 | #ifdef CONFIG_USB_SERIAL_CONSOLE |
324 | void usb_serial_console_init(int minor); |
325 | void usb_serial_console_exit(void); |
326 | void usb_serial_console_disconnect(struct usb_serial *serial); |
327 | #else |
328 | static inline void usb_serial_console_init(int minor) { } |
329 | static inline void usb_serial_console_exit(void) { } |
330 | static inline void usb_serial_console_disconnect(struct usb_serial *serial) {} |
331 | #endif |
332 | |
333 | /* Functions needed by other parts of the usbserial core */ |
334 | struct usb_serial_port *usb_serial_port_get_by_minor(unsigned int minor); |
335 | void usb_serial_put(struct usb_serial *serial); |
336 | |
337 | int usb_serial_claim_interface(struct usb_serial *serial, struct usb_interface *intf); |
338 | |
339 | int usb_serial_generic_open(struct tty_struct *tty, struct usb_serial_port *port); |
340 | int usb_serial_generic_write_start(struct usb_serial_port *port, gfp_t mem_flags); |
341 | int usb_serial_generic_write(struct tty_struct *tty, struct usb_serial_port *port, |
342 | const unsigned char *buf, int count); |
343 | void usb_serial_generic_close(struct usb_serial_port *port); |
344 | int usb_serial_generic_resume(struct usb_serial *serial); |
345 | unsigned int usb_serial_generic_write_room(struct tty_struct *tty); |
346 | unsigned int usb_serial_generic_chars_in_buffer(struct tty_struct *tty); |
347 | void usb_serial_generic_wait_until_sent(struct tty_struct *tty, long timeout); |
348 | void usb_serial_generic_read_bulk_callback(struct urb *urb); |
349 | void usb_serial_generic_write_bulk_callback(struct urb *urb); |
350 | void usb_serial_generic_throttle(struct tty_struct *tty); |
351 | void usb_serial_generic_unthrottle(struct tty_struct *tty); |
352 | int usb_serial_generic_tiocmiwait(struct tty_struct *tty, unsigned long arg); |
353 | int usb_serial_generic_get_icount(struct tty_struct *tty, struct serial_icounter_struct *icount); |
354 | int usb_serial_generic_register(void); |
355 | void usb_serial_generic_deregister(void); |
356 | int usb_serial_generic_submit_read_urbs(struct usb_serial_port *port, gfp_t mem_flags); |
357 | void usb_serial_generic_process_read_urb(struct urb *urb); |
358 | int usb_serial_generic_prepare_write_buffer(struct usb_serial_port *port, void *dest, size_t size); |
359 | |
360 | #if defined(CONFIG_USB_SERIAL_CONSOLE) && defined(CONFIG_MAGIC_SYSRQ) |
361 | int usb_serial_handle_sysrq_char(struct usb_serial_port *port, unsigned int ch); |
362 | int usb_serial_handle_break(struct usb_serial_port *port); |
363 | #else |
364 | static inline int usb_serial_handle_sysrq_char(struct usb_serial_port *port, unsigned int ch) |
365 | { |
366 | return 0; |
367 | } |
368 | static inline int usb_serial_handle_break(struct usb_serial_port *port) |
369 | { |
370 | return 0; |
371 | } |
372 | #endif |
373 | |
374 | void usb_serial_handle_dcd_change(struct usb_serial_port *usb_port, |
375 | struct tty_struct *tty, unsigned int status); |
376 | |
377 | |
378 | int usb_serial_bus_register(struct usb_serial_driver *device); |
379 | void usb_serial_bus_deregister(struct usb_serial_driver *device); |
380 | |
381 | extern const struct bus_type usb_serial_bus_type; |
382 | extern struct tty_driver *usb_serial_tty_driver; |
383 | |
384 | static inline void usb_serial_debug_data(struct device *dev, |
385 | const char *function, int size, |
386 | const unsigned char *data) |
387 | { |
388 | dev_dbg(dev, "%s - length = %d, data = %*ph\n" , |
389 | function, size, size, data); |
390 | } |
391 | |
392 | /* |
393 | * Macro for reporting errors in write path to avoid infinite loop |
394 | * when port is used as a console. |
395 | */ |
396 | #define dev_err_console(usport, fmt, ...) \ |
397 | do { \ |
398 | static bool __print_once; \ |
399 | struct usb_serial_port *__port = (usport); \ |
400 | \ |
401 | if (!__port->port.console || !__print_once) { \ |
402 | __print_once = true; \ |
403 | dev_err(&__port->dev, fmt, ##__VA_ARGS__); \ |
404 | } \ |
405 | } while (0) |
406 | |
407 | /* |
408 | * module_usb_serial_driver() - Helper macro for registering a USB Serial driver |
409 | * @__serial_drivers: list of usb_serial drivers to register |
410 | * @__ids: all device ids that @__serial_drivers bind to |
411 | * |
412 | * Helper macro for USB serial drivers which do not do anything special |
413 | * in module init/exit. This eliminates a lot of boilerplate. Each |
414 | * module may only use this macro once, and calling it replaces |
415 | * module_init() and module_exit() |
416 | * |
417 | */ |
418 | #define usb_serial_module_driver(__name, __serial_drivers, __ids) \ |
419 | static int __init usb_serial_module_init(void) \ |
420 | { \ |
421 | return usb_serial_register_drivers(__serial_drivers, \ |
422 | __name, __ids); \ |
423 | } \ |
424 | module_init(usb_serial_module_init); \ |
425 | static void __exit usb_serial_module_exit(void) \ |
426 | { \ |
427 | usb_serial_deregister_drivers(__serial_drivers); \ |
428 | } \ |
429 | module_exit(usb_serial_module_exit); |
430 | |
431 | #define module_usb_serial_driver(__serial_drivers, __ids) \ |
432 | usb_serial_module_driver(KBUILD_MODNAME, __serial_drivers, __ids) |
433 | |
434 | #endif /* __LINUX_USB_SERIAL_H */ |
435 | |
436 | |