1 /*
2 * USB Serial Converter driver
3 *
4 * Copyright (C) 1999 - 2003
5 * Greg Kroah-Hartman (greg@kroah.com)
6 *
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 * (at your option) any later version.
11 *
12 * See Documentation/usb/usb-serial.txt for more information on using this driver
13 *
14 * (12/03/2001) gkh
15 * removed active from the port structure.
16 * added documentation to the usb_serial_device_type structure
17 *
18 * (10/10/2001) gkh
19 * added vendor and product to serial structure. Needed to determine device
20 * owner when the device is disconnected.
21 *
22 * (05/30/2001) gkh
23 * added sem to port structure and removed port_lock
24 *
25 * (10/05/2000) gkh
26 * Added interrupt_in_endpointAddress and bulk_in_endpointAddress to help
27 * fix bug with urb->dev not being set properly, now that the usb core
28 * needs it.
29 *
30 * (09/11/2000) gkh
31 * Added usb_serial_debug_data function to help get rid of #DEBUG in the
32 * drivers.
33 *
34 * (08/28/2000) gkh
35 * Added port_lock to port structure.
36 *
37 * (08/08/2000) gkh
38 * Added open_count to port structure.
39 *
40 * (07/23/2000) gkh
41 * Added bulk_out_endpointAddress to port structure.
42 *
43 * (07/19/2000) gkh, pberger, and borchers
44 * Modifications to allow usb-serial drivers to be modules.
45 *
46 *
47 */
48
49
50 #ifndef __LINUX_USB_SERIAL_H
51 #define __LINUX_USB_SERIAL_H
52
53 #include <linux/config.h>
54
55 #define SERIAL_TTY_MAJOR 188 /* Nice legal number now */
56 #define SERIAL_TTY_MINORS 255 /* loads of devices :) */
57
58 #define MAX_NUM_PORTS 8 /* The maximum number of ports one device can grab at once */
59
60 #define USB_SERIAL_MAGIC 0x6702 /* magic number for usb_serial struct */
61 #define USB_SERIAL_PORT_MAGIC 0x7301 /* magic number for usb_serial_port struct */
62
63 /* parity check flag */
64 #define RELEVANT_IFLAG(iflag) (iflag & (IGNBRK|BRKINT|IGNPAR|PARMRK|INPCK))
65
66 /**
67 * usb_serial_port: structure for the specific ports of a device.
68 * @magic: magic number for internal validity of this pointer.
69 * @serial: pointer back to the struct usb_serial owner of this port.
70 * @tty: pointer to the corresponding tty for this port.
71 * @number: the number of the port (the minor number).
72 * @interrupt_in_buffer: pointer to the interrupt in buffer for this port.
73 * @interrupt_in_urb: pointer to the interrupt in struct urb for this port.
74 * @interrupt_in_endpointAddress: endpoint address for the interrupt in pipe
75 * for this port.
76 * @bulk_in_buffer: pointer to the bulk in buffer for this port.
77 * @read_urb: pointer to the bulk in struct urb for this port.
78 * @bulk_in_endpointAddress: endpoint address for the bulk in pipe for this
79 * port.
80 * @bulk_out_buffer: pointer to the bulk out buffer for this port.
81 * @bulk_out_size: the size of the bulk_out_buffer, in bytes.
82 * @write_urb: pointer to the bulk out struct urb for this port.
83 * @bulk_out_endpointAddress: endpoint address for the bulk out pipe for this
84 * port.
85 * @write_wait: a wait_queue_head_t used by the port.
86 * @tqueue: task queue for the line discipline waking up.
87 * @open_count: number of times this port has been opened.
88 * @sem: struct semaphore used to lock this structure.
89 * @private: place to put any driver specific information that is needed. The
90 * usb-serial driver is required to manage this data, the usb-serial core
91 * will not touch this.
92 *
93 * This structure is used by the usb-serial core and drivers for the specific
94 * ports of a device.
95 */
96 struct usb_serial_port {
97 int magic;
98 struct usb_serial *serial;
99 struct tty_struct * tty;
100 unsigned char number;
101
102 unsigned char * interrupt_in_buffer;
103 struct urb * interrupt_in_urb;
104 __u8 interrupt_in_endpointAddress;
105
106 unsigned char * bulk_in_buffer;
107 struct urb * read_urb;
108 __u8 bulk_in_endpointAddress;
109
110 unsigned char * bulk_out_buffer;
111 int bulk_out_size;
112 struct urb * write_urb;
113 __u8 bulk_out_endpointAddress;
114 char write_busy; /* URB is active */
115 int write_backlog; /* Fifo used */
116
117 wait_queue_head_t write_wait;
118 struct tq_struct tqueue;
119 int open_count;
120 struct semaphore sem;
121 void * private;
122 };
123 /* get and set the port private data pointer helper functions */
usb_get_serial_port_data(struct usb_serial_port * port)124 static inline void *usb_get_serial_port_data (struct usb_serial_port *port)
125 {
126 return port->private;
127 }
128
usb_set_serial_port_data(struct usb_serial_port * port,void * data)129 static inline void usb_set_serial_port_data (struct usb_serial_port *port, void *data)
130 {
131 port->private = data;
132 }
133
134 /**
135 * usb_serial - structure used by the usb-serial core for a device
136 * @magic: magic number for internal validity of this pointer.
137 * @dev: pointer to the struct usb_device for this device
138 * @type: pointer to the struct usb_serial_device_type for this device
139 * @interface: pointer to the struct usb_interface for this device
140 * @minor: the starting minor number for this device
141 * @num_ports: the number of ports this device has
142 * @num_interrupt_in: number of interrupt in endpoints we have
143 * @num_bulk_in: number of bulk in endpoints we have
144 * @num_bulk_out: number of bulk out endpoints we have
145 * @vendor: vendor id of this device
146 * @product: product id of this device
147 * @port: array of struct usb_serial_port structures for the different ports.
148 * @private: place to put any driver specific information that is needed. The
149 * usb-serial driver is required to manage this data, the usb-serial core
150 * will not touch this.
151 */
152 struct usb_serial {
153 int magic;
154 struct usb_device * dev;
155 struct usb_serial_device_type * type;
156 struct usb_interface * interface;
157 unsigned char minor;
158 unsigned char num_ports;
159 char num_interrupt_in;
160 char num_bulk_in;
161 char num_bulk_out;
162 __u16 vendor;
163 __u16 product;
164 struct usb_serial_port port[MAX_NUM_PORTS];
165 void * private;
166 int ref;
167 };
168
169
170 #define NUM_DONT_CARE (-1)
171
172 /* get and set the serial private data pointer helper functions */
usb_get_serial_data(struct usb_serial * serial)173 static inline void *usb_get_serial_data (struct usb_serial *serial)
174 {
175 return serial->private;
176 }
177
usb_set_serial_data(struct usb_serial * serial,void * data)178 static inline void usb_set_serial_data (struct usb_serial *serial, void *data)
179 {
180 serial->private = data;
181 }
182
183 /**
184 * usb_serial_device_type - a structure that defines a usb serial device
185 * @owner: pointer to the module that owns this device.
186 * @name: pointer to a string that describes this device. This string used
187 * in the syslog messages when a device is inserted or removed.
188 * @id_table: pointer to a list of usb_device_id structures that define all
189 * of the devices this structure can support.
190 * @num_interrupt_in: the number of interrupt in endpoints this device will
191 * have.
192 * @num_bulk_in: the number of bulk in endpoints this device will have.
193 * @num_bulk_out: the number of bulk out endpoints this device will have.
194 * @num_ports: the number of different ports this device will have.
195 * @calc_num_ports: pointer to a function to determine how many ports this
196 * device has dynamically. It will be called after the probe()
197 * callback is called, but before attach()
198 * @startup: pointer to the driver's startup function.
199 * This will be called when the device is inserted into the system,
200 * but before the device has been fully initialized by the usb_serial
201 * subsystem. Use this function to download any firmware to the device,
202 * or any other early initialization that might be needed.
203 * Return 0 to continue on with the initialization sequence. Anything
204 * else will abort it.
205 * @shutdown: pointer to the driver's shutdown function. This will be
206 * called when the device is removed from the system.
207 *
208 * This structure is defines a USB Serial device. It provides all of
209 * the information that the USB serial core code needs. If the function
210 * pointers are defined, then the USB serial core code will call them when
211 * the corresponding tty port functions are called. If they are not
212 * called, the generic serial function will be used instead.
213 */
214 struct usb_serial_device_type {
215 struct module *owner;
216 char *name;
217 const struct usb_device_id *id_table;
218 char num_interrupt_in;
219 char num_bulk_in;
220 char num_bulk_out;
221 char num_ports;
222
223 struct list_head driver_list;
224
225 int (*startup) (struct usb_serial *serial);
226
227 void (*shutdown) (struct usb_serial *serial);
228
229 /* serial function calls */
230 int (*open) (struct usb_serial_port *port, struct file * filp);
231 void (*close) (struct usb_serial_port *port, struct file * filp);
232 int (*write) (struct usb_serial_port *port, int from_user, const unsigned char *buf, int count);
233 int (*write_room) (struct usb_serial_port *port);
234 int (*ioctl) (struct usb_serial_port *port, struct file * file, unsigned int cmd, unsigned long arg);
235 void (*set_termios) (struct usb_serial_port *port, struct termios * old);
236 void (*break_ctl) (struct usb_serial_port *port, int break_state);
237 int (*chars_in_buffer) (struct usb_serial_port *port);
238 void (*throttle) (struct usb_serial_port *port);
239 void (*unthrottle) (struct usb_serial_port *port);
240
241 void (*read_int_callback)(struct urb *urb);
242 void (*read_bulk_callback)(struct urb *urb);
243 void (*write_bulk_callback)(struct urb *urb);
244 };
245
246 extern int usb_serial_register(struct usb_serial_device_type *new_device);
247 extern void usb_serial_deregister(struct usb_serial_device_type *device);
248
249 /* determine if we should include the EzUSB loader functions */
250 #undef USES_EZUSB_FUNCTIONS
251 #if defined(CONFIG_USB_SERIAL_KEYSPAN_PDA) || defined(CONFIG_USB_SERIAL_KEYSPAN_PDA_MODULE)
252 #define USES_EZUSB_FUNCTIONS
253 #endif
254 #if defined(CONFIG_USB_SERIAL_XIRCOM) || defined(CONFIG_USB_SERIAL_XIRCOM_MODULE)
255 #define USES_EZUSB_FUNCTIONS
256 #endif
257 #if defined(CONFIG_USB_SERIAL_KEYSPAN) || defined(CONFIG_USB_SERIAL_KEYSPAN_MODULE)
258 #define USES_EZUSB_FUNCTIONS
259 #endif
260 #if defined(CONFIG_USB_SERIAL_WHITEHEAT) || defined(CONFIG_USB_SERIAL_WHITEHEAT_MODULE)
261 #define USES_EZUSB_FUNCTIONS
262 #endif
263 #ifdef USES_EZUSB_FUNCTIONS
264 extern int ezusb_writememory (struct usb_serial *serial, int address, unsigned char *data, int length, __u8 bRequest);
265 extern int ezusb_set_reset (struct usb_serial *serial, unsigned char reset_bit);
266 #endif
267
268
269 /* Inline functions to check the sanity of a pointer that is passed to us */
serial_paranoia_check(struct usb_serial * serial,const char * function)270 static inline int serial_paranoia_check (struct usb_serial *serial, const char *function)
271 {
272 if (!serial) {
273 dbg("%s - serial == NULL", function);
274 return -1;
275 }
276 if (serial->magic != USB_SERIAL_MAGIC) {
277 dbg("%s - bad magic number for serial", function);
278 return -1;
279 }
280 if (!serial->type) {
281 dbg("%s - serial->type == NULL!", function);
282 return -1;
283 }
284
285 return 0;
286 }
287
288
port_paranoia_check(struct usb_serial_port * port,const char * function)289 static inline int port_paranoia_check (struct usb_serial_port *port, const char *function)
290 {
291 if (!port) {
292 dbg("%s - port == NULL", function);
293 return -1;
294 }
295 if (port->magic != USB_SERIAL_PORT_MAGIC) {
296 dbg("%s - bad magic number for port", function);
297 return -1;
298 }
299 if (!port->serial) {
300 dbg("%s - port->serial == NULL", function);
301 return -1;
302 }
303 if (!port->tty) {
304 dbg("%s - port->tty == NULL", function);
305 return -1;
306 }
307
308 return 0;
309 }
310
311 #define get_usb_serial(p, f) usb_serial_get_serial(p, f)
312 extern struct usb_serial *usb_serial_get_serial(struct usb_serial_port *port,
313 const char *function_name);
314
315
usb_serial_debug_data(const char * file,const char * function,int size,const unsigned char * data)316 static inline void usb_serial_debug_data (const char *file, const char *function, int size, const unsigned char *data)
317 {
318 int i;
319
320 if (!debug)
321 return;
322
323 printk (KERN_DEBUG "%s: %s - length = %d, data = ", file, function, size);
324 for (i = 0; i < size; ++i) {
325 printk ("%.2x ", data[i]);
326 }
327 printk ("\n");
328 }
329
330
331 /* Use our own dbg macro */
332 #undef dbg
333 #define dbg(format, arg...) do { if (debug) printk(KERN_DEBUG "%s: " format "\n" , __FILE__ , ## arg); } while (0)
334
335
336
337 #endif /* ifdef __LINUX_USB_SERIAL_H */
338
339