1/* 2 * USB Skeleton driver - 0.7 3 * 4 * Copyright (C) 2001 Greg Kroah-Hartman (greg@kroah.com) 5 * 6 * This program is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU General Public License as 8 * published by the Free Software Foundation; either version 2 of 9 * the License, or (at your option) any later version. 10 * 11 * 12 * This driver is to be used as a skeleton driver to be able to create a 13 * USB driver quickly. The design of it is based on the usb-serial and 14 * dc2xx drivers. 15 * 16 * Thanks to Oliver Neukum and David Brownell for their help in debugging 17 * this driver. 18 * 19 * TODO: 20 * - fix urb->status race condition in write sequence 21 * - move minor_table to a dynamic list. 22 * 23 * History: 24 * 25 * 2002_02_12 - 0.7 - zero out dev in probe function for devices that do 26 * not have both a bulk in and bulk out endpoint. 27 * Thanks to Holger Waechtler for the fix. 28 * 2001_11_05 - 0.6 - fix minor locking problem in skel_disconnect. 29 * Thanks to Pete Zaitcev for the fix. 30 * 2001_09_04 - 0.5 - fix devfs bug in skel_disconnect. Thanks to wim delvaux 31 * 2001_08_21 - 0.4 - more small bug fixes. 32 * 2001_05_29 - 0.3 - more bug fixes based on review from linux-usb-devel 33 * 2001_05_24 - 0.2 - bug fixes based on review from linux-usb-devel people 34 * 2001_05_01 - 0.1 - first version 35 * 36 */ 37 38#include <linux/config.h> 39#include <linux/kernel.h> 40#include <linux/sched.h> 41#include <linux/signal.h> 42#include <linux/errno.h> 43#include <linux/poll.h> 44#include <linux/init.h> 45#include <linux/slab.h> 46#include <linux/fcntl.h> 47#include <linux/module.h> 48#include <linux/spinlock.h> 49#include <linux/list.h> 50#include <linux/smp_lock.h> 51#include <linux/devfs_fs_kernel.h> 52#include <linux/usb.h> 53 54#ifdef CONFIG_USB_DEBUG 55 static int debug = 1; 56#else 57 static int debug; 58#endif 59 60/* Use our own dbg macro */ 61#undef dbg 62#define dbg(format, arg...) do { if (debug) printk(KERN_DEBUG __FILE__ ": " format "\n" , ## arg); } while (0) 63 64 65/* Version Information */ 66#define DRIVER_VERSION "v0.4" 67#define DRIVER_AUTHOR "Greg Kroah-Hartman, greg@kroah.com" 68#define DRIVER_DESC "USB Skeleton Driver" 69 70/* Module paramaters */ 71MODULE_PARM(debug, "i"); 72MODULE_PARM_DESC(debug, "Debug enabled or not"); 73 74 75/* Define these values to match your device */ 76#define USB_SKEL_VENDOR_ID 0xfff0 77#define USB_SKEL_PRODUCT_ID 0xfff0 78 79/* table of devices that work with this driver */ 80static struct usb_device_id skel_table [] = { 81 { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) }, 82 { } /* Terminating entry */ 83}; 84 85MODULE_DEVICE_TABLE (usb, skel_table); 86 87 88 89/* Get a minor range for your devices from the usb maintainer */ 90#define USB_SKEL_MINOR_BASE 192 91 92/* we can have up to this number of device plugged in at once */ 93#define MAX_DEVICES 16 94 95/* Structure to hold all of our device specific stuff */ 96struct usb_skel { 97 struct usb_device * udev; /* save off the usb device pointer */ 98 struct usb_interface * interface; /* the interface for this device */ 99 devfs_handle_t devfs; /* devfs device node */ 100 unsigned char minor; /* the starting minor number for this device */ 101 unsigned char num_ports; /* the number of ports this device has */ 102 char num_interrupt_in; /* number of interrupt in endpoints we have */ 103 char num_bulk_in; /* number of bulk in endpoints we have */ 104 char num_bulk_out; /* number of bulk out endpoints we have */ 105 106 unsigned char * bulk_in_buffer; /* the buffer to receive data */ 107 int bulk_in_size; /* the size of the receive buffer */ 108 __u8 bulk_in_endpointAddr; /* the address of the bulk in endpoint */ 109 110 unsigned char * bulk_out_buffer; /* the buffer to send data */ 111 int bulk_out_size; /* the size of the send buffer */ 112 struct urb * write_urb; /* the urb used to send data */ 113 __u8 bulk_out_endpointAddr; /* the address of the bulk out endpoint */ 114 115 struct tq_struct tqueue; /* task queue for line discipline waking up */ 116 int open_count; /* number of times this port has been opened */ 117 struct semaphore sem; /* locks this structure */ 118}; 119 120 121/* the global usb devfs handle */ 122extern devfs_handle_t usb_devfs_handle; 123 124 125/* local function prototypes */ 126static ssize_t skel_read (struct file *file, char *buffer, size_t count, loff_t *ppos); 127static ssize_t skel_write (struct file *file, const char *buffer, size_t count, loff_t *ppos); 128static int skel_ioctl (struct inode *inode, struct file *file, unsigned int cmd, unsigned long arg); 129static int skel_open (struct inode *inode, struct file *file); 130static int skel_release (struct inode *inode, struct file *file); 131 132static void * skel_probe (struct usb_device *dev, unsigned int ifnum, const struct usb_device_id *id); 133static void skel_disconnect (struct usb_device *dev, void *ptr); 134 135static void skel_write_bulk_callback (struct urb *urb); 136 137 138/* array of pointers to our devices that are currently connected */ 139static struct usb_skel *minor_table[MAX_DEVICES]; 140 141/* lock to protect the minor_table structure */ 142static DECLARE_MUTEX (minor_table_mutex); 143 144/* 145 * File operations needed when we register this driver. 146 * This assumes that this driver NEEDS file operations, 147 * of course, which means that the driver is expected 148 * to have a node in the /dev directory. If the USB 149 * device were for a network interface then the driver 150 * would use "struct net_driver" instead, and a serial 151 * device would use "struct tty_driver". 152 */ 153static struct file_operations skel_fops = { 154 /* 155 * The owner field is part of the module-locking 156 * mechanism. The idea is that the kernel knows 157 * which module to increment the use-counter of 158 * BEFORE it calls the device's open() function. 159 * This also means that the kernel can decrement 160 * the use-counter again before calling release() 161 * or should the open() function fail. 162 * 163 * Not all device structures have an "owner" field 164 * yet. "struct file_operations" and "struct net_device" 165 * do, while "struct tty_driver" does not. If the struct 166 * has an "owner" field, then initialize it to the value 167 * THIS_MODULE and the kernel will handle all module 168 * locking for you automatically. Otherwise, you must 169 * increment the use-counter in the open() function 170 * and decrement it again in the release() function 171 * yourself. 172 */ 173 owner: THIS_MODULE, 174 175 read: skel_read, 176 write: skel_write, 177 ioctl: skel_ioctl, 178 open: skel_open, 179 release: skel_release, 180}; 181 182 183/* usb specific object needed to register this driver with the usb subsystem */ 184static struct usb_driver skel_driver = { 185 name: "skeleton", 186 probe: skel_probe, 187 disconnect: skel_disconnect, 188 fops: &skel_fops, 189 minor: USB_SKEL_MINOR_BASE, 190 id_table: skel_table, 191}; 192 193 194 195 196 197/** 198 * usb_skel_debug_data 199 */ 200static inline void usb_skel_debug_data (const char *function, int size, const unsigned char *data) 201{ 202 int i; 203 204 if (!debug) 205 return; 206 207 printk (KERN_DEBUG __FILE__": %s - length = %d, data = ", 208 function, size); 209 for (i = 0; i < size; ++i) { 210 printk ("%.2x ", data[i]); 211 } 212 printk ("\n"); 213} 214 215 216/** 217 * skel_delete 218 */ 219static inline void skel_delete (struct usb_skel *dev) 220{ 221 minor_table[dev->minor] = NULL; 222 if (dev->bulk_in_buffer != NULL) 223 kfree (dev->bulk_in_buffer); 224 if (dev->bulk_out_buffer != NULL) 225 kfree (dev->bulk_out_buffer); 226 if (dev->write_urb != NULL) 227 usb_free_urb (dev->write_urb); 228 kfree (dev); 229} 230 231 232/** 233 * skel_open 234 */ 235static int skel_open (struct inode *inode, struct file *file) 236{ 237 struct usb_skel *dev = NULL; 238 int subminor; 239 int retval = 0; 240 241 dbg(__FUNCTION__); 242 243 subminor = MINOR (inode->i_rdev) - USB_SKEL_MINOR_BASE; 244 if ((subminor < 0) || 245 (subminor >= MAX_DEVICES)) { 246 return -ENODEV; 247 } 248 249 /* Increment our usage count for the module. 250 * This is redundant here, because "struct file_operations" 251 * has an "owner" field. This line is included here soley as 252 * a reference for drivers using lesser structures... ;-) 253 */ 254 MOD_INC_USE_COUNT; 255 256 /* lock our minor table and get our local data for this minor */ 257 down (&minor_table_mutex); 258 dev = minor_table[subminor]; 259 if (dev == NULL) { 260 up (&minor_table_mutex); 261 MOD_DEC_USE_COUNT; 262 return -ENODEV; 263 } 264 265 /* lock this device */ 266 down (&dev->sem); 267 268 /* unlock the minor table */ 269 up (&minor_table_mutex); 270 271 /* increment our usage count for the driver */ 272 ++dev->open_count; 273 274 /* save our object in the file's private structure */ 275 file->private_data = dev; 276 277 /* unlock this device */ 278 up (&dev->sem); 279 280 return retval; 281} 282 283 284/** 285 * skel_release 286 */ 287static int skel_release (struct inode *inode, struct file *file) 288{ 289 struct usb_skel *dev; 290 int retval = 0; 291 292 dev = (struct usb_skel *)file->private_data; 293 if (dev == NULL) { 294 dbg (__FUNCTION__ " - object is NULL"); 295 return -ENODEV; 296 } 297 298 dbg(__FUNCTION__ " - minor %d", dev->minor); 299 300 /* lock our minor table */ 301 down (&minor_table_mutex); 302 303 /* lock our device */ 304 down (&dev->sem); 305 306 if (dev->open_count <= 0) { 307 dbg (__FUNCTION__ " - device not opened"); 308 retval = -ENODEV; 309 goto exit_not_opened; 310 } 311 312 if (dev->udev == NULL) { 313 /* the device was unplugged before the file was released */ 314 up (&dev->sem); 315 skel_delete (dev); 316 up (&minor_table_mutex); 317 MOD_DEC_USE_COUNT; 318 return 0; 319 } 320 321 /* decrement our usage count for the device */ 322 --dev->open_count; 323 if (dev->open_count <= 0) { 324 /* shutdown any bulk writes that might be going on */ 325 usb_unlink_urb (dev->write_urb); 326 dev->open_count = 0; 327 } 328 329 /* decrement our usage count for the module */ 330 MOD_DEC_USE_COUNT; 331 332exit_not_opened: 333 up (&dev->sem); 334 up (&minor_table_mutex); 335 336 return retval; 337} 338 339 340/** 341 * skel_read 342 */ 343static ssize_t skel_read (struct file *file, char *buffer, size_t count, loff_t *ppos) 344{ 345 struct usb_skel *dev; 346 int retval = 0; 347 348 dev = (struct usb_skel *)file->private_data; 349 350 dbg(__FUNCTION__ " - minor %d, count = %d", dev->minor, count); 351 352 /* lock this object */ 353 down (&dev->sem); 354 355 /* verify that the device wasn't unplugged */ 356 if (dev->udev == NULL) { 357 up (&dev->sem); 358 return -ENODEV; 359 } 360 361 /* do an immediate bulk read to get data from the device */ 362 retval = usb_bulk_msg (dev->udev, 363 usb_rcvbulkpipe (dev->udev, 364 dev->bulk_in_endpointAddr), 365 dev->bulk_in_buffer, dev->bulk_in_size, 366 &count, HZ*10); 367 368 /* if the read was successful, copy the data to userspace */ 369 if (!retval) { 370 if (copy_to_user (buffer, dev->bulk_in_buffer, count)) 371 retval = -EFAULT; 372 else 373 retval = count; 374 } 375 376 /* unlock the device */ 377 up (&dev->sem); 378 return retval; 379} 380 381 382/** 383 * skel_write 384 */ 385static ssize_t skel_write (struct file *file, const char *buffer, size_t count, loff_t *ppos) 386{ 387 struct usb_skel *dev; 388 ssize_t bytes_written = 0; 389 int retval = 0; 390 391 dev = (struct usb_skel *)file->private_data; 392 393 dbg(__FUNCTION__ " - minor %d, count = %d", dev->minor, count); 394 395 /* lock this object */ 396 down (&dev->sem); 397 398 /* verify that the device wasn't unplugged */ 399 if (dev->udev == NULL) { 400 retval = -ENODEV; 401 goto exit; 402 } 403 404 /* verify that we actually have some data to write */ 405 if (count == 0) { 406 dbg(__FUNCTION__ " - write request of 0 bytes"); 407 goto exit; 408 } 409 410 /* see if we are already in the middle of a write */ 411 if (dev->write_urb->status == -EINPROGRESS) { 412 dbg (__FUNCTION__ " - already writing"); 413 goto exit; 414 } 415 416 /* we can only write as much as 1 urb will hold */ 417 bytes_written = (count > dev->bulk_out_size) ? 418 dev->bulk_out_size : count; 419 420 /* copy the data from userspace into our urb */ 421 if (copy_from_user(dev->write_urb->transfer_buffer, buffer, 422 bytes_written)) { 423 retval = -EFAULT; 424 goto exit; 425 } 426 427 usb_skel_debug_data (__FUNCTION__, bytes_written, 428 dev->write_urb->transfer_buffer); 429 430 /* set up our urb */ 431 FILL_BULK_URB(dev->write_urb, dev->udev, 432 usb_sndbulkpipe(dev->udev, dev->bulk_out_endpointAddr), 433 dev->write_urb->transfer_buffer, bytes_written, 434 skel_write_bulk_callback, dev); 435 436 /* send the data out the bulk port */ 437 retval = usb_submit_urb(dev->write_urb); 438 if (retval) { 439 err(__FUNCTION__ " - failed submitting write urb, error %d", 440 retval); 441 } else { 442 retval = bytes_written; 443 } 444 445exit: 446 /* unlock the device */ 447 up (&dev->sem); 448 449 return retval; 450} 451 452 453/** 454 * skel_ioctl 455 */ 456static int skel_ioctl (struct inode *inode, struct file *file, unsigned int cmd, unsigned long arg) 457{ 458 struct usb_skel *dev; 459 460 dev = (struct usb_skel *)file->private_data; 461 462 /* lock this object */ 463 down (&dev->sem); 464 465 /* verify that the device wasn't unplugged */ 466 if (dev->udev == NULL) { 467 up (&dev->sem); 468 return -ENODEV; 469 } 470 471 dbg(__FUNCTION__ " - minor %d, cmd 0x%.4x, arg %ld", 472 dev->minor, cmd, arg); 473 474 475 /* fill in your device specific stuff here */ 476 477 /* unlock the device */ 478 up (&dev->sem); 479 480 /* return that we did not understand this ioctl call */ 481 return -ENOTTY; 482} 483 484 485/** 486 * skel_write_bulk_callback 487 */ 488static void skel_write_bulk_callback (struct urb *urb) 489{ 490 struct usb_skel *dev = (struct usb_skel *)urb->context; 491 492 dbg(__FUNCTION__ " - minor %d", dev->minor); 493 494 if ((urb->status != -ENOENT) && 495 (urb->status != -ECONNRESET)) { 496 dbg(__FUNCTION__ " - nonzero write bulk status received: %d", 497 urb->status); 498 return; 499 } 500 501 return; 502} 503 504 505/** 506 * skel_probe 507 * 508 * Called by the usb core when a new device is connected that it thinks 509 * this driver might be interested in. 510 */ 511static void * skel_probe(struct usb_device *udev, unsigned int ifnum, const struct usb_device_id *id) 512{ 513 struct usb_skel *dev = NULL; 514 struct usb_interface *interface; 515 struct usb_interface_descriptor *iface_desc; 516 struct usb_endpoint_descriptor *endpoint; 517 int minor; 518 int buffer_size; 519 int i; 520 char name[10]; 521 522 523 /* See if the device offered us matches what we can accept */ 524 if ((udev->descriptor.idVendor != USB_SKEL_VENDOR_ID) || 525 (udev->descriptor.idProduct != USB_SKEL_PRODUCT_ID)) { 526 return NULL; 527 } 528 529 /* select a "subminor" number (part of a minor number) */ 530 down (&minor_table_mutex); 531 for (minor = 0; minor < MAX_DEVICES; ++minor) { 532 if (minor_table[minor] == NULL) 533 break; 534 } 535 if (minor >= MAX_DEVICES) { 536 info ("Too many devices plugged in, can not handle this device."); 537 goto exit; 538 } 539 540 /* allocate memory for our device state and intialize it */ 541 dev = kmalloc (sizeof(struct usb_skel), GFP_KERNEL); 542 if (dev == NULL) { 543 err ("Out of memory"); 544 goto exit; 545 } 546 memset (dev, 0x00, sizeof (*dev)); 547 minor_table[minor] = dev; 548 549 interface = &udev->actconfig->interface[ifnum]; 550 551 init_MUTEX (&dev->sem); 552 dev->udev = udev; 553 dev->interface = interface; 554 dev->minor = minor; 555 556 /* set up the endpoint information */ 557 /* check out the endpoints */ 558 iface_desc = &interface->altsetting[0]; 559 for (i = 0; i < iface_desc->bNumEndpoints; ++i) { 560 endpoint = &iface_desc->endpoint[i]; 561 562 if ((endpoint->bEndpointAddress & 0x80) && 563 ((endpoint->bmAttributes & 3) == 0x02)) { 564 /* we found a bulk in endpoint */ 565 buffer_size = endpoint->wMaxPacketSize; 566 dev->bulk_in_size = buffer_size; 567 dev->bulk_in_endpointAddr = endpoint->bEndpointAddress; 568 dev->bulk_in_buffer = kmalloc (buffer_size, GFP_KERNEL); 569 if (!dev->bulk_in_buffer) { 570 err("Couldn't allocate bulk_in_buffer"); 571 goto error; 572 } 573 } 574 575 if (((endpoint->bEndpointAddress & 0x80) == 0x00) && 576 ((endpoint->bmAttributes & 3) == 0x02)) { 577 /* we found a bulk out endpoint */ 578 dev->write_urb = usb_alloc_urb(0); 579 if (!dev->write_urb) { 580 err("No free urbs available"); 581 goto error; 582 } 583 buffer_size = endpoint->wMaxPacketSize; 584 dev->bulk_out_size = buffer_size; 585 dev->bulk_out_endpointAddr = endpoint->bEndpointAddress; 586 dev->bulk_out_buffer = kmalloc (buffer_size, GFP_KERNEL); 587 if (!dev->bulk_out_buffer) { 588 err("Couldn't allocate bulk_out_buffer"); 589 goto error; 590 } 591 FILL_BULK_URB(dev->write_urb, udev, 592 usb_sndbulkpipe(udev, 593 endpoint->bEndpointAddress), 594 dev->bulk_out_buffer, buffer_size, 595 skel_write_bulk_callback, dev); 596 } 597 } 598 599 /* initialize the devfs node for this device and register it */ 600 sprintf(name, "skel%d", dev->minor); 601 602 dev->devfs = devfs_register (usb_devfs_handle, name, 603 DEVFS_FL_DEFAULT, USB_MAJOR, 604 USB_SKEL_MINOR_BASE + dev->minor, 605 S_IFCHR | S_IRUSR | S_IWUSR | 606 S_IRGRP | S_IWGRP | S_IROTH, 607 &skel_fops, NULL); 608 609 /* let the user know what node this device is now attached to */ 610 info ("USB Skeleton device now attached to USBSkel%d", dev->minor); 611 goto exit; 612 613error: 614 skel_delete (dev); 615 dev = NULL; 616 617exit: 618 up (&minor_table_mutex); 619 return dev; 620} 621 622 623/** 624 * skel_disconnect 625 * 626 * Called by the usb core when the device is removed from the system. 627 */ 628static void skel_disconnect(struct usb_device *udev, void *ptr) 629{ 630 struct usb_skel *dev; 631 int minor; 632 633 dev = (struct usb_skel *)ptr; 634 635 down (&minor_table_mutex); 636 down (&dev->sem); 637 638 minor = dev->minor; 639 640 /* remove our devfs node */ 641 devfs_unregister(dev->devfs); 642 643 /* if the device is not opened, then we clean up right now */ 644 if (!dev->open_count) { 645 up (&dev->sem); 646 skel_delete (dev); 647 } else { 648 dev->udev = NULL; 649 up (&dev->sem); 650 } 651 652 info("USB Skeleton #%d now disconnected", minor); 653 up (&minor_table_mutex); 654} 655 656 657 658/** 659 * usb_skel_init 660 */ 661static int __init usb_skel_init(void) 662{ 663 int result; 664 665 /* register this driver with the USB subsystem */ 666 result = usb_register(&skel_driver); 667 if (result < 0) { 668 err("usb_register failed for the "__FILE__" driver. Error number %d", 669 result); 670 return -1; 671 } 672 673 info(DRIVER_DESC " " DRIVER_VERSION); 674 return 0; 675} 676 677 678/** 679 * usb_skel_exit 680 */ 681static void __exit usb_skel_exit(void) 682{ 683 /* deregister this driver with the USB subsystem */ 684 usb_deregister(&skel_driver); 685} 686 687 688module_init (usb_skel_init); 689module_exit (usb_skel_exit); 690 691MODULE_AUTHOR(DRIVER_AUTHOR); 692MODULE_DESCRIPTION(DRIVER_DESC); 693MODULE_LICENSE("GPL"); 694 695