From owner-p4-projects@FreeBSD.ORG Tue Feb 19 20:25:34 2008 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 9960816A41A; Tue, 19 Feb 2008 20:25:34 +0000 (UTC) Delivered-To: perforce@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 460BF16A417 for ; Tue, 19 Feb 2008 20:25:34 +0000 (UTC) (envelope-from hselasky@FreeBSD.org) Received: from repoman.freebsd.org (repoman.freebsd.org [IPv6:2001:4f8:fff6::29]) by mx1.freebsd.org (Postfix) with ESMTP id 3615813C468 for ; Tue, 19 Feb 2008 20:25:34 +0000 (UTC) (envelope-from hselasky@FreeBSD.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.14.1/8.14.1) with ESMTP id m1JKPYX1011697 for ; Tue, 19 Feb 2008 20:25:34 GMT (envelope-from hselasky@FreeBSD.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.14.1/8.14.1/Submit) id m1JKPXJa011694 for perforce@freebsd.org; Tue, 19 Feb 2008 20:25:33 GMT (envelope-from hselasky@FreeBSD.org) Date: Tue, 19 Feb 2008 20:25:33 GMT Message-Id: <200802192025.m1JKPXJa011694@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to hselasky@FreeBSD.org using -f From: Hans Petter Selasky To: Perforce Change Reviews Cc: Subject: PERFORCE change 135742 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 19 Feb 2008 20:25:35 -0000 http://perforce.freebsd.org/chv.cgi?CH=135742 Change 135742 by hselasky@hselasky_laptop001 on 2008/02/19 20:24:34 Add more documentation. Affected files ... .. //depot/projects/usb/src/sys/dev/usb/usb.c#33 edit Differences ... ==== //depot/projects/usb/src/sys/dev/usb/usb.c#33 (text+ko) ==== @@ -65,7 +65,8 @@ MALLOC_DEFINE(M_USBDEV, "USBdev", "USB device"); MALLOC_DEFINE(M_USBHC, "USBHC", "USB host controller"); -/* define this unconditionally in case a kernel module is loaded that +/* + * Define this unconditionally in case a kernel module is loaded that * has been compiled with debugging options. */ SYSCTL_NODE(_hw, OID_AUTO, usb, CTLFLAG_RW, 0, "USB debugging"); @@ -86,6 +87,8 @@ static uint8_t usb_post_init_called = 0; +/* prototypes */ + static device_probe_t usb_probe; static device_attach_t usb_attach; static device_detach_t usb_detach; @@ -134,6 +137,9 @@ .d_name = "usb_dummy_cdev", }; +/*------------------------------------------------------------------------* + * usb_dummy_open + *------------------------------------------------------------------------*/ static int usb_dummy_open(struct cdev *dev, int oflags, int devtype, struct thread *td) { @@ -141,7 +147,9 @@ } /*------------------------------------------------------------------------* - * usb_event_thread - explore the device tree from the root + * usb_event_thread + * + * This function is used to explore the device tree from the root. *------------------------------------------------------------------------*/ static void usb_event_thread(struct usbd_bus *bus) @@ -211,8 +219,7 @@ /*------------------------------------------------------------------------* * usb_needs_explore * - * This functions is called when the USB event thread - * needs to be explored. + * This functions is called when the USB event thread needs run. *------------------------------------------------------------------------*/ void usb_needs_explore(struct usbd_bus *bus, uint8_t what) @@ -297,6 +304,11 @@ return; } +/*------------------------------------------------------------------------* + * usb_create_event_thread + * + * This function will simply create the event thread for an USB bus. + *------------------------------------------------------------------------*/ static void usb_create_event_thread(struct usbd_bus *bus) { @@ -308,8 +320,11 @@ return; } -/* called from "{ehci,ohci,uhci}_pci_attach()" */ - +/*------------------------------------------------------------------------* + * usb_probe + * + * This function is called from "{ehci,ohci,uhci}_pci_attach()". + *------------------------------------------------------------------------*/ static int usb_probe(device_t dev) { @@ -317,6 +332,14 @@ return (0); } +/*------------------------------------------------------------------------* + * usb_attach_sub + * + * This function is the real USB bus attach code. It is factored out, + * hence it can be called at two different places in time. During + * bootup this function is called from "usb_post_init". During + * hot-plug it is called directly from the "usb_attach()" method. + *------------------------------------------------------------------------*/ static void usb_attach_sub(device_t dev, struct usbd_bus *bus) { @@ -399,6 +422,9 @@ return; } +/*------------------------------------------------------------------------* + * usb_attach + *------------------------------------------------------------------------*/ static int usb_attach(device_t dev) { @@ -414,6 +440,12 @@ return (0); /* return success */ } +/*------------------------------------------------------------------------* + * usb_post_init + * + * This function is called to attach all USB busses that were found + * during bootup. + *------------------------------------------------------------------------*/ static void usb_post_init(void *arg) { @@ -450,6 +482,9 @@ SYSINIT(usb_post_init, SI_SUB_KICK_SCHEDULER, SI_ORDER_ANY, usb_post_init, NULL); +/*------------------------------------------------------------------------* + * usb_detach + *------------------------------------------------------------------------*/ static int usb_detach(device_t dev) { @@ -500,6 +535,11 @@ return (0); } +/*------------------------------------------------------------------------* + * usb_clone_sub + * + * This function will create a dynamic "/dev/usbX.Y" device file. + *------------------------------------------------------------------------*/ static struct usbd_clone * usb_clone_sub(struct usbd_bus *bus) { @@ -563,6 +603,11 @@ return (NULL); } +/*------------------------------------------------------------------------* + * usb_clone_remove + * + * This function will cleanup all the "/dev/usbX.Y" kernel files. + *------------------------------------------------------------------------*/ static void usb_clone_remove(struct usbd_bus *bus) { @@ -615,6 +660,11 @@ return; } +/*------------------------------------------------------------------------* + * usb_clone + * + * This function is the kernel clone callback for "/dev/usbX.Y". + *------------------------------------------------------------------------*/ static void usb_clone(void *arg, USB_UCRED char *name, int namelen, struct cdev **dev) { @@ -637,6 +687,11 @@ return; } +/*------------------------------------------------------------------------* + * usb_ioctl + * + * This function handles all IOCTL's on "/dev/usbX.Y". + *------------------------------------------------------------------------*/ static int usb_ioctl(struct usb_cdev *dev, u_long cmd, caddr_t addr, int32_t fflags, struct thread *td) @@ -794,6 +849,12 @@ #endif +/*------------------------------------------------------------------------* + * usb_init + * + * This function is called before the USB system is started, and is + * used to initialise global mutexes, if any. + *------------------------------------------------------------------------*/ static void usb_init(void *arg) { @@ -807,6 +868,9 @@ SYSINIT(usb_init, SI_SUB_DRIVERS, SI_ORDER_FIRST, usb_init, NULL); +/*------------------------------------------------------------------------* + * usb_uninit + *------------------------------------------------------------------------*/ static void usb_uninit(void *arg) {