Date: Fri, 15 Feb 2008 20:39:38 GMT From: Hans Petter Selasky <hselasky@FreeBSD.org> To: Perforce Change Reviews <perforce@FreeBSD.org> Subject: PERFORCE change 135460 for review Message-ID: <200802152039.m1FKdcRr017736@repoman.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://perforce.freebsd.org/chv.cgi?CH=135460 Change 135460 by hselasky@hselasky_laptop001 on 2008/02/15 20:38:43 Add documentation to all function is "usb_subr.c". Affected files ... .. //depot/projects/usb/src/sys/dev/usb/usb_subr.c#96 edit Differences ... ==== //depot/projects/usb/src/sys/dev/usb/usb_subr.c#96 (text+ko) ==== @@ -118,6 +118,12 @@ #include "usbdevs_data.h" #endif /* USBVERBOSE */ +/*------------------------------------------------------------------------* + * usbd_trim_spaces + * + * This function removes spaces at the beginning and the end of the string + * pointed to by the "p" argument. + *------------------------------------------------------------------------*/ static void usbd_trim_spaces(char *p) { @@ -136,6 +142,12 @@ return; } +/*------------------------------------------------------------------------* + * usbd_finish_vp_info + * + * This function checks the manufacturer and product strings and will + * fill in defaults for missing strings. + *------------------------------------------------------------------------*/ static void usbd_finish_vp_info(struct usbd_device *udev) { @@ -210,6 +222,13 @@ return; } +/*------------------------------------------------------------------------* + * usbd_printBCD + * + * This function will print the version number "bcd" to the string + * pointed to by "p" having a maximum length of "p_len" bytes + * including the terminating zero. + *------------------------------------------------------------------------*/ static void usbd_printBCD(char *p, uint16_t p_len, uint16_t bcd) { @@ -219,6 +238,14 @@ return; } +/*------------------------------------------------------------------------* + * usbd_devinfo + * + * This function will dump information from the device descriptor + * belonging to the USB device pointed to by "udev", to the string + * pointed to by "dst_ptr" having a maximum length of "dst_len" bytes + * including the terminating zero. + *------------------------------------------------------------------------*/ void usbd_devinfo(struct usbd_device *udev, char *dst_ptr, uint16_t dst_len) { @@ -246,6 +273,11 @@ return; } +/*------------------------------------------------------------------------* + * usbd_errstr + * + * This function converts an USB error code into a string. + *------------------------------------------------------------------------*/ const char * usbd_errstr(usbd_status_t err) { @@ -256,7 +288,12 @@ USBD_STATUS_DESC[err] : "unknown error!"; } -/* Delay for a certain number of ms */ +/*------------------------------------------------------------------------* + * usb_delay_ms + * + * This function will delay the code by the passed number of + * milliseconds. + *------------------------------------------------------------------------*/ void usb_delay_ms(struct usbd_bus *bus, uint32_t ms) { @@ -271,7 +308,12 @@ #endif } -/* Delay given a device handle. */ +/*------------------------------------------------------------------------* + * usbd_delay_ms + * + * This function will delay the code by the passed number of + * milliseconds. + *------------------------------------------------------------------------*/ void usbd_delay_ms(struct usbd_device *udev, uint32_t ms) { @@ -281,7 +323,10 @@ /*------------------------------------------------------------------------* * usbd_pause_mtx - factored out code * - * NOTE: number of milliseconds per second is 1024 for sake of optimisation + * This function will delay the code by the passed number of + * milliseconds. The passed mutex "mtx" will be dropped while + * waiting. The number of milliseconds per second is 1024 for sake of + * optimisation. *------------------------------------------------------------------------*/ void usbd_pause_mtx(struct mtx *mtx, uint32_t ms) @@ -303,6 +348,18 @@ return; } +/*------------------------------------------------------------------------* + * usbd_desc_foreach + * + * This function is the safe way to iterate across the USB config + * descriptor. It contains several checks against invalid + * descriptors. If the "desc" argument passed to this function is + * "NULL" the first descriptor, if any, will be returned. + * + * Return values: + * NULL: End of descriptors + * Else: Next descriptor after "desc" + *------------------------------------------------------------------------*/ usb_descriptor_t * usbd_desc_foreach(usb_config_descriptor_t *cd, usb_descriptor_t *desc) { @@ -325,6 +382,16 @@ (desc->bLength >= sizeof(*desc))) ? desc : NULL); } +/*------------------------------------------------------------------------* + * usbd_find_idesc + * + * This function will return the interface descriptor, if any, that + * has index "iface_index" and alternate index "alt_index". + * + * Return values: + * NULL: End of descriptors + * Else: A valid interface descriptor + *------------------------------------------------------------------------*/ usb_interface_descriptor_t * usbd_find_idesc(usb_config_descriptor_t *cd, uint8_t iface_index, uint8_t alt_index) @@ -363,6 +430,16 @@ return (NULL); } +/*------------------------------------------------------------------------* + * usbd_find_edesc + * + * This function will return the endpoint descriptor for the passed + * interface index, alternate index and endpoint index. + * + * Return values: + * NULL: End of descriptors + * Else: A valid endpoint descriptor + *------------------------------------------------------------------------*/ usb_endpoint_descriptor_t * usbd_find_edesc(usb_config_descriptor_t *cd, uint8_t iface_index, uint8_t alt_index, uint8_t ep_index) @@ -403,12 +480,17 @@ /*------------------------------------------------------------------------* * usbd_find_descriptor * - * This function will lookup the first descriptor that matches - * the criteria given by the arguments "type" and "subtype". Descriptors - * will only be searched within the interface having the index "iface_index". - * It is possible to specify the last descriptor returned by this function - * as the "id" argument. That way one can search for multiple descriptors - * matching the same criteria. + * This function will lookup the first descriptor that matches the + * criteria given by the arguments "type" and "subtype". Descriptors + * will only be searched within the interface having the index + * "iface_index". If the "id" argument points to an USB descriptor, + * it will be skipped before the search is started. This allows + * searching for multiple descriptors using the same criteria. Else + * the search is started after the interface descriptor. + * + * Return values: + * NULL: End of descriptors + * Else: A descriptor matching the criteria *------------------------------------------------------------------------*/ void * usbd_find_descriptor(struct usbd_device *udev, void *id, uint8_t iface_index, @@ -448,6 +530,15 @@ return (NULL); } +/*------------------------------------------------------------------------* + * usbd_get_no_alts + * + * Return value: + * Number of alternate settings for the given "ifaceno". + * + * NOTE: The returned can be larger than the actual number of + * alternate settings. + *------------------------------------------------------------------------*/ uint16_t usbd_get_no_alts(usb_config_descriptor_t *cd, uint8_t ifaceno) { @@ -468,6 +559,12 @@ return (n); } +/*------------------------------------------------------------------------* + * usbd_fill_pipe_data + * + * This function will initialize the USB pipe structure pointed to by + * the "pipe" argument. + *------------------------------------------------------------------------*/ static void usbd_fill_pipe_data(struct usbd_device *udev, uint8_t iface_index, usb_endpoint_descriptor_t *edesc, struct usbd_pipe *pipe) @@ -516,6 +613,12 @@ * */ +/*------------------------------------------------------------------------* + * usbd_find_best_slot + * + * Return value: + * The best Transaction Translation slot for an interrupt endpoint. + *------------------------------------------------------------------------*/ static uint8_t usbd_find_best_slot(uint32_t *ptr, uint8_t start, uint8_t end) { @@ -536,6 +639,18 @@ return (y); } +/*------------------------------------------------------------------------* + * usbd_intr_schedule_adjust + * + * This function will update the bandwith usage for the microframe + * having index "slot" by "len" bytes. "len" can be negative. If the + * "slot" argument is greater or equal to "USB_HS_MICRO_FRAMES_MAX" + * the "slot" argument will be replaced by the slot having least used + * bandwidth. + * + * Returns: + * The slot on which the bandwidth update was done. + *------------------------------------------------------------------------*/ uint8_t usbd_intr_schedule_adjust(struct usbd_device *udev, int16_t len, uint8_t slot) { @@ -572,6 +687,12 @@ return (slot); } +/*------------------------------------------------------------------------* + * usbd_fs_isoc_schedule_init_sub + * + * This function initialises an USB FULL speed isochronous schedule + * entry. + *------------------------------------------------------------------------*/ static void usbd_fs_isoc_schedule_init_sub(struct usbd_fs_isoc_schedule *fss) { @@ -582,6 +703,12 @@ return; } +/*------------------------------------------------------------------------* + * usbd_fs_isoc_schedule_init_all + * + * This function will reset the complete USB FULL speed isochronous + * bandwidth schedule. + *------------------------------------------------------------------------*/ void usbd_fs_isoc_schedule_init_all(struct usbd_fs_isoc_schedule *fss) { @@ -594,6 +721,21 @@ return; } +/*------------------------------------------------------------------------* + * usbd_fs_isoc_schedule_isoc_time_expand + * + * This function does multiple things. First of all it will expand the + * passed isochronous time, which is the return value. Then it will + * store where the current FULL speed isochronous schedule is + * positioned in time and where the end is. See "pp_start" and + * "pp_end" arguments. + * + * Returns: + * Expanded version of "isoc_time". + * + * NOTE: This function depends on being called regularly with + * intervals less than "USB_ISOC_TIME_MAX". + *------------------------------------------------------------------------*/ uint16_t usbd_fs_isoc_schedule_isoc_time_expand(struct usbd_device *udev, struct usbd_fs_isoc_schedule **pp_start, @@ -641,6 +783,16 @@ return (isoc_time); } + +/*------------------------------------------------------------------------* + * usbd_fs_isoc_schedule_alloc + * + * This function will allocate bandwidth for the isochronous FULL + * speed schedule. + * + * Returns: + * Microframe slot where the transaction will start. + *------------------------------------------------------------------------*/ uint8_t usbd_fs_isoc_schedule_alloc(struct usbd_fs_isoc_schedule *fss, uint16_t len) { @@ -674,8 +826,12 @@ /*------------------------------------------------------------------------* * usbd_free_pipe_data * - * NOTE: The interface pipes should not be in use when - * this function is called ! + * This function will free USB pipe data for the given interface + * index. Hence we do not have any dynamic allocations we simply clear + * "pipe->edesc" to indicate that the USB pipe structure can be + * reused. The pipes belonging to the given interface should not be in + * use when this function is called and no check is performed to + * prevent this. *------------------------------------------------------------------------*/ static void usbd_free_pipe_data(struct usbd_device *udev, @@ -696,6 +852,11 @@ /*------------------------------------------------------------------------* * usbd_fill_iface_data + * + * This function will fill in interface data and allocate USB pipes + * for all the endpoints that belong to the given interface. This + * function is typically called when setting the configuration or when + * setting an alternate interface. *------------------------------------------------------------------------*/ usbd_status_t usbd_fill_iface_data(struct usbd_device *udev, @@ -784,6 +945,12 @@ return (USBD_ERR_INVAL); } +/*------------------------------------------------------------------------* + * usbd_free_iface_data + * + * This function will free all USB interfaces and USB pipes belonging + * to an USB device. + *------------------------------------------------------------------------*/ static void usbd_free_iface_data(struct usbd_device *udev) { @@ -821,9 +988,9 @@ * usbd_set_config_no * * This function will search all the configuration descriptors for a - * matching configuration number. It is recommended to use - * the function "usbd_set_config_index()" when the configuration - * number does not matter. + * matching configuration number. It is recommended to use the + * function "usbd_set_config_index()" when the configuration number + * does not matter. * * - USB config 0 * - USB interfaces @@ -864,6 +1031,9 @@ /*------------------------------------------------------------------------* * usbd_set_config_index + * + * This function selects configuration by index, independent of the + * actual configuration number. *------------------------------------------------------------------------*/ usbd_status_t usbd_set_config_index(struct usbd_device *udev, uint8_t index, uint8_t msg) @@ -1014,6 +1184,14 @@ return (err); } +/*------------------------------------------------------------------------* + * usbd_set_alt_interface_index + * + * This function will select an alternate interface index for the + * given interface index. The interface should not be in use when this + * function is called. That means there should be no open USB + * transfers. Else an error is returned. + *------------------------------------------------------------------------*/ usbd_status_t usbd_set_alt_interface_index(struct usbd_device *udev, uint8_t iface_index, uint8_t alt_index) @@ -1037,6 +1215,13 @@ return (err); } +/*------------------------------------------------------------------------* + * usbd_fill_deviceinfo + * + * This function dumps information about an USB device to the + * structure pointed to by the "di" argument. It is used by some + * IOCTLs. + *------------------------------------------------------------------------*/ int usbd_fill_deviceinfo(struct usbd_device *udev, struct usb_device_info *di) { @@ -1117,6 +1302,12 @@ return (0); } +/*------------------------------------------------------------------------* + * usbd_reset_probed + * + * This function will reset the "udev->probed" variable to its default + * value, typically when drivers have been unloaded. + *------------------------------------------------------------------------*/ static void usbd_reset_probed(struct usbd_device *udev) { @@ -1125,6 +1316,12 @@ return; } +/*------------------------------------------------------------------------* + * usbd_detach_device_sub + * + * This function will try to detach an USB device. If it fails a panic + * will result. + *------------------------------------------------------------------------*/ static void usbd_detach_device_sub(struct usbd_device *udev, device_t *ppdev, uint8_t free_subdev) @@ -1480,6 +1677,9 @@ /*------------------------------------------------------------------------* * usbd_suspend_resume_sub + * + * This function is called when the suspend or resume methods should + * be executed on an USB device. *------------------------------------------------------------------------*/ static void usbd_suspend_resume_sub(struct usbd_device *udev, device_t dev, uint8_t do_suspend) @@ -1842,7 +2042,7 @@ /*------------------------------------------------------------------------* * usbd_free_device * - * This function is NULL safe. + * This function is NULL safe and will free an USB device. *------------------------------------------------------------------------*/ void usbd_free_device(struct usbd_device *udev) @@ -1893,6 +2093,17 @@ return; } +/*------------------------------------------------------------------------* + * usbd_ref_device + * + * This function increments the reference count on the USB device at + * index "index" so that it cannot be freed before the reference count + * reaches zero. + * + * Return values: + * NULL: USB device not present. + * Else: Refcount incremented on the given USB device. + *------------------------------------------------------------------------*/ struct usbd_device * usbd_ref_device(struct usbd_bus *bus, uint8_t index) { @@ -1917,6 +2128,12 @@ return (udev); } +/*------------------------------------------------------------------------* + * usbd_unref_device + * + * This function will release the reference count by one unit for the + * given USB device. + *------------------------------------------------------------------------*/ void usbd_unref_device(struct usbd_device *udev) { @@ -1946,6 +2163,16 @@ return; } +/*------------------------------------------------------------------------* + * usbd_get_iface + * + * This function is the safe way to get the USB interface structure + * pointer by interface index. + * + * Return values: + * NULL: Interface not present. + * Else: Pointer to USB interface structure. + *------------------------------------------------------------------------*/ struct usbd_interface * usbd_get_iface(struct usbd_device *udev, uint8_t iface_index) { @@ -1960,6 +2187,12 @@ return (iface); } +/*------------------------------------------------------------------------* + * usbd_set_device_desc + * + * This function can be called at probe or attach to set the USB + * device supplied textual description for the given device. + *------------------------------------------------------------------------*/ void usbd_set_device_desc(device_t dev) { @@ -2006,9 +2239,11 @@ } /*------------------------------------------------------------------------* - * allocate mbufs to an usbd interface queue + * usbd_alloc_mbufs - allocate mbufs to an usbd interface queue * - * returns a pointer that eventually should be passed to "free()" + * Returns: + * A pointer that should be passed to "free()" when the buffer(s) + * should be released. *------------------------------------------------------------------------*/ void * usbd_alloc_mbufs(struct malloc_type *type, struct usbd_ifqueue *ifq, @@ -2295,7 +2530,7 @@ } /*------------------------------------------------------------------------* - * usbd_pc_alloc_mem_cb + * usbd_pc_alloc_mem_cb - BUS-DMA callback function *------------------------------------------------------------------------*/ static void usbd_pc_alloc_mem_cb(void *arg, bus_dma_segment_t *segs, @@ -2536,7 +2771,7 @@ } /*------------------------------------------------------------------------* - * usbd_pc_dmamap_create + * usbd_pc_dmamap_create - create a DMA map * * Returns: * 0: Success @@ -2637,7 +2872,7 @@ } /*------------------------------------------------------------------------* - * usbd_pc_alloc_mem_cb + * usbd_pc_alloc_mem_cb - BUS-DMA callback function *------------------------------------------------------------------------*/ static void usbd_pc_alloc_mem_cb(struct usbd_page_cache *pc, bus_dma_segment_t *segs, @@ -2902,7 +3137,7 @@ } /*------------------------------------------------------------------------* - * usbd_pc_dmamap_create + * usbd_pc_dmamap_create - create a DMA map * * Returns: * 0: Success @@ -3034,7 +3269,9 @@ /*------------------------------------------------------------------------* - * usbd_config_thread + * usbd_config_thread + * + * This function is the dispatcher in the USB config thread system. *------------------------------------------------------------------------*/ static void usbd_config_td_thread(void *arg) @@ -3140,7 +3377,7 @@ } /*------------------------------------------------------------------------* - * usbd_config_td_setup + * usbd_config_td_setup * * NOTE: the structure pointed to by "ctd" must be zeroed before calling * this function! @@ -3188,7 +3425,7 @@ } /*------------------------------------------------------------------------* - * usbd_config_td_dummy_cmd + * usbd_config_td_dummy_cmd - a NOP *------------------------------------------------------------------------*/ static void usbd_config_td_dummy_cmd(struct usbd_config_td_softc *sc, @@ -3199,7 +3436,10 @@ } /*------------------------------------------------------------------------* - * usbd_config_td_stop + * usbd_config_td_stop + * + * This function will tear down an USB config thread, waiting for the + * currently executing command to return. * * NOTE: If the structure pointed to by "ctd" is all zero, * this function does nothing. @@ -3243,7 +3483,7 @@ } /*------------------------------------------------------------------------* - * usbd_config_td_unsetup + * usbd_config_td_unsetup * * NOTE: If the structure pointed to by "ctd" is all zero, * this function does nothing. @@ -3261,7 +3501,18 @@ } /*------------------------------------------------------------------------* - * usbd_config_td_queue_command + * usbd_config_td_queue_command + * + * This function will enter a command into the config thread queue for + * execution. The "command_qcount" gives the maximum number of + * equivalent commands that will be kept on the queue before queueing + * the next command. "command_ref" is the reference count for the + * current command which is passed on to the "command_post_func" + * function. This parameter can be used to make a command + * unique. "command_pre_func" is called from this function when we + * have the final queue element. "command_post_func" is called from + * the USB config thread when the command reaches the beginning of the + * USB config thread queue. *------------------------------------------------------------------------*/ void usbd_config_td_queue_command(struct usbd_config_td *ctd, @@ -3350,7 +3601,7 @@ } /*------------------------------------------------------------------------* - * usbd_config_td_is_gone + * usbd_config_td_is_gone * * Return values: * 0: config thread is running @@ -3365,7 +3616,7 @@ } /*------------------------------------------------------------------------* - * usbd_config_td_sleep + * usbd_config_td_sleep * * NOTE: this function can only be called from the config thread * @@ -3402,7 +3653,7 @@ } /*------------------------------------------------------------------------* - * usbd_ether_get_mbuf - get a new ethernet mbuf + * usbd_ether_get_mbuf - get a new ethernet aligned mbuf *------------------------------------------------------------------------*/ struct mbuf * usbd_ether_get_mbuf(void) @@ -3441,7 +3692,12 @@ } /*------------------------------------------------------------------------* - * usbd_isoc_time_expand - expand time counter from 7-bit to 16-bit + * usbd_isoc_time_expand + * + * This function will expand the time counter from 7-bit to 16-bit. + * + * Returns: + * 16-bit isochronous time counter. *------------------------------------------------------------------------*/ uint16_t usbd_isoc_time_expand(struct usbd_bus *bus, uint16_t isoc_time_curr)
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200802152039.m1FKdcRr017736>