Index: uspace/lib/usb/include/usb/classes/classes.h =================================================================== --- uspace/lib/usb/include/usb/classes/classes.h (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/include/usb/classes/classes.h (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -31,5 +31,5 @@ */ /** @file - * @brief USB device classes and subclasses. + * USB device classes (generic constants and functions). */ #ifndef LIBUSB_CLASSES_H_ Index: uspace/lib/usb/include/usb/debug.h =================================================================== --- uspace/lib/usb/include/usb/debug.h (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/include/usb/debug.h (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -31,5 +31,5 @@ */ /** @file - * @brief Debugging related functions. + * Debugging related functions. */ #ifndef LIBUSB_DEBUG_H_ @@ -39,7 +39,4 @@ #include -void usb_dprintf(const char *tag, int level, const char *format, ...); -void usb_dprintf_enable(const char *tag, int level); - void usb_dump_standard_descriptor(FILE *, const char *, const char *, const uint8_t *, size_t); @@ -47,10 +44,36 @@ /** Logging level. */ typedef enum { + /** Fatal, unrecoverable, error. + * Such error prevents the driver from working at all. + */ USB_LOG_LEVEL_FATAL, + + /** Serious but recoverable error + * Shall be used for errors fatal for single device but not for + * driver itself. + */ USB_LOG_LEVEL_ERROR, + + /** Warning. + * Problems from which the driver is able to recover gracefully. + */ USB_LOG_LEVEL_WARNING, + + /** Information message. + * This should be the last level that is printed by default to + * the screen. + * Typical usage is to inform that new device was found and what + * are its capabilities. + * Do not use for repetitive actions (such as device polling). + */ USB_LOG_LEVEL_INFO, + + /** Debugging message. */ USB_LOG_LEVEL_DEBUG, + + /** More detailed debugging message. */ USB_LOG_LEVEL_DEBUG2, + + /** Terminating constant for logging levels. */ USB_LOG_LEVEL_MAX } usb_log_level_t; @@ -61,19 +84,25 @@ void usb_log_printf(usb_log_level_t, const char *, ...); +/** Log fatal error. */ #define usb_log_fatal(format, ...) \ usb_log_printf(USB_LOG_LEVEL_FATAL, format, ##__VA_ARGS__) +/** Log normal (recoverable) error. */ #define usb_log_error(format, ...) \ usb_log_printf(USB_LOG_LEVEL_ERROR, format, ##__VA_ARGS__) +/** Log warning. */ #define usb_log_warning(format, ...) \ usb_log_printf(USB_LOG_LEVEL_WARNING, format, ##__VA_ARGS__) +/** Log informational message. */ #define usb_log_info(format, ...) \ usb_log_printf(USB_LOG_LEVEL_INFO, format, ##__VA_ARGS__) +/** Log debugging message. */ #define usb_log_debug(format, ...) \ usb_log_printf(USB_LOG_LEVEL_DEBUG, format, ##__VA_ARGS__) +/** Log verbose debugging message. */ #define usb_log_debug2(format, ...) \ usb_log_printf(USB_LOG_LEVEL_DEBUG2, format, ##__VA_ARGS__) Index: uspace/lib/usb/include/usb/descriptor.h =================================================================== --- uspace/lib/usb/include/usb/descriptor.h (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/include/usb/descriptor.h (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -31,5 +31,5 @@ */ /** @file - * @brief Standard USB descriptors. + * Standard USB descriptors. */ #ifndef LIBUSB_DESCRIPTOR_H_ @@ -83,5 +83,5 @@ /** Product descriptor index. */ uint8_t str_product; - /** Device serial number desriptor index. */ + /** Device serial number descriptor index. */ uint8_t str_serial_number; /** Number of possible configurations. */ @@ -167,7 +167,4 @@ } __attribute__ ((packed)) usb_standard_endpoint_descriptor_t; - -/* TODO: string descriptors. */ - #endif /** Index: uspace/lib/usb/include/usb/dp.h =================================================================== --- uspace/lib/usb/include/usb/dp.h (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/include/usb/dp.h (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -31,5 +31,5 @@ */ /** @file - * @brief USB descriptor parser. + * USB descriptor parser. */ #ifndef LIBUSB_DP_H_ @@ -40,6 +40,15 @@ #include +/** USB descriptors nesting. + * The nesting describes the logical tree USB descriptors form + * (e.g. that endpoint descriptor belongs to interface or that + * interface belongs to configuration). + * + * See usb_descriptor_type_t for descriptor constants. + */ typedef struct { + /** Child descriptor id. */ int child; + /** Parent descriptor id. */ int parent; } usb_dp_descriptor_nesting_t; @@ -47,11 +56,17 @@ extern usb_dp_descriptor_nesting_t usb_dp_standard_descriptor_nesting[]; +/** Descriptor parser structure. */ typedef struct { + /** Used descriptor nesting. */ usb_dp_descriptor_nesting_t *nesting; } usb_dp_parser_t; +/** Descriptor parser data. */ typedef struct { + /** Data to be parsed. */ uint8_t *data; + /** Size of input data in bytes. */ size_t size; + /** Custom argument. */ void *arg; } usb_dp_parser_data_t; Index: uspace/lib/usb/include/usb/hub.h =================================================================== --- uspace/lib/usb/include/usb/hub.h (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/include/usb/hub.h (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -32,4 +32,6 @@ /** @file * Functions needed by hub drivers. + * + * For class specific requests, see usb/classes/hub.h. */ #ifndef LIBUSB_HUB_H_ Index: uspace/lib/usb/include/usb/pipes.h =================================================================== --- uspace/lib/usb/include/usb/pipes.h (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/include/usb/pipes.h (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -43,6 +43,5 @@ #include -/** - * Abstraction of a physical connection to the device. +/** Abstraction of a physical connection to the device. * This type is an abstraction of the USB wire that connects the host and * the function (device). @@ -55,6 +54,5 @@ } usb_device_connection_t; -/** - * Abstraction of a logical connection to USB device endpoint. +/** Abstraction of a logical connection to USB device endpoint. * It encapsulates endpoint attributes (transfer type etc.) as well * as information about currently running sessions. @@ -111,5 +109,5 @@ /** Found descriptor fitting the description. */ usb_standard_endpoint_descriptor_t *descriptor; - /** Interface the endpoint belongs to. */ + /** Interface descriptor the endpoint belongs to. */ usb_standard_interface_descriptor_t *interface; /** Whether the endpoint was actually found. */ Index: uspace/lib/usb/include/usb/request.h =================================================================== --- uspace/lib/usb/include/usb/request.h (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/include/usb/request.h (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -72,5 +72,5 @@ union { uint16_t value; - /* FIXME: add #ifdefs according to host endianess */ + /* FIXME: add #ifdefs according to host endianness */ struct { uint8_t value_low; Index: uspace/lib/usb/include/usb/usb.h =================================================================== --- uspace/lib/usb/include/usb/usb.h (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/include/usb/usb.h (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -31,5 +31,5 @@ */ /** @file - * @brief Base USB types. + * Common USB types and functions. */ #ifndef LIBUSB_USB_H_ @@ -121,4 +121,10 @@ } usb_target_t; +/** Compare USB targets (addresses and endpoints). + * + * @param a First target. + * @param b Second target. + * @return Whether @p a and @p b points to the same pipe on the same device. + */ static inline int usb_target_same(usb_target_t a, usb_target_t b) { Index: uspace/lib/usb/src/debug.c =================================================================== --- uspace/lib/usb/src/debug.c (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/src/debug.c (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -31,5 +31,5 @@ */ /** @file - * @brief Debugging support. + * Debugging and logging support. */ #include @@ -40,126 +40,16 @@ #include -/** Debugging tag. */ -typedef struct { - /** Linked list member. */ - link_t link; - /** Tag name. - * We always have a private copy of the name. - */ - char *tag; - /** Enabled level of debugging. */ - int level; -} usb_debug_tag_t; - -/** Get instance of usb_debug_tag_t from link_t. */ -#define USB_DEBUG_TAG_INSTANCE(iterator) \ - list_get_instance(iterator, usb_debug_tag_t, link) - -/** List of all known tags. */ -static LIST_INITIALIZE(tag_list); -/** Mutex guard for the list of all tags. */ -static FIBRIL_MUTEX_INITIALIZE(tag_list_guard); - /** Level of logging messages. */ static usb_log_level_t log_level = USB_LOG_LEVEL_WARNING; + /** Prefix for logging messages. */ static const char *log_prefix = "usb"; + /** Serialization mutex for logging functions. */ static FIBRIL_MUTEX_INITIALIZE(log_serializer); + +/** File where to store the log. */ static FILE *log_stream = NULL; -/** Find or create new tag with given name. - * - * @param tagname Tag name. - * @return Debug tag structure. - * @retval NULL Out of memory. - */ -static usb_debug_tag_t *get_tag(const char *tagname) -{ - link_t *link; - for (link = tag_list.next; \ - link != &tag_list; \ - link = link->next) { - usb_debug_tag_t *tag = USB_DEBUG_TAG_INSTANCE(link); - if (str_cmp(tag->tag, tagname) == 0) { - return tag; - } - } - - /* - * Tag not found, we will create a new one. - */ - usb_debug_tag_t *new_tag = malloc(sizeof(usb_debug_tag_t)); - int rc = asprintf(&new_tag->tag, "%s", tagname); - if (rc < 0) { - free(new_tag); - return NULL; - } - list_initialize(&new_tag->link); - new_tag->level = 1; - - /* - * Append it to the end of known tags. - */ - list_append(&new_tag->link, &tag_list); - - return new_tag; -} - -/** Print debugging information. - * If the tag is used for the first time, its structures are automatically - * created and initial verbosity level is set to 1. - * - * @param tagname Tag name. - * @param level Level (verbosity) of the message. - * @param format Formatting string for printf(). - */ -void usb_dprintf(const char *tagname, int level, const char *format, ...) -{ - fibril_mutex_lock(&tag_list_guard); - usb_debug_tag_t *tag = get_tag(tagname); - if (tag == NULL) { - printf("USB debug: FATAL ERROR - failed to create tag.\n"); - goto leave; - } - - if (tag->level < level) { - goto leave; - } - - va_list args; - va_start(args, format); - - printf("[%s:%d]: ", tagname, level); - vprintf(format, args); - - va_end(args); - -leave: - fibril_mutex_unlock(&tag_list_guard); -} - -/** Enable debugging prints for given tag. - * - * Setting level to n will cause that only printing messages - * with level lower or equal to n will be printed. - * - * @param tagname Tag name. - * @param level Enabled level. - */ -void usb_dprintf_enable(const char *tagname, int level) -{ - fibril_mutex_lock(&tag_list_guard); - usb_debug_tag_t *tag = get_tag(tagname); - if (tag == NULL) { - printf("USB debug: FATAL ERROR - failed to create tag.\n"); - goto leave; - } - - tag->level = level; - -leave: - fibril_mutex_unlock(&tag_list_guard); -} /** Enable logging. @@ -182,5 +72,9 @@ } - +/** Get log level name prefix. + * + * @param level Log level. + * @return String prefix for the message. + */ static const char *log_level_name(usb_log_level_t level) { @@ -256,6 +150,12 @@ /* string + terminator + number width (enough for 4GB)*/ #define REMAINDER_STR_LEN (5 + 1 + 10) + +/** How many bytes to group together. */ #define BUFFER_DUMP_GROUP_SIZE 4 + +/** Size of the string for buffer dumps. */ #define BUFFER_DUMP_LEN 240 /* Ought to be enough for everybody ;-). */ + +/** Fibril local storage for the dumped buffer. */ static fibril_local char buffer_dump[BUFFER_DUMP_LEN]; @@ -265,5 +165,5 @@ * in a static fibril local string. * That means that you do not have to deallocate the string (actually, you - * can not do that) and you do not have to save it agains concurrent + * can not do that) and you do not have to guard it against concurrent * calls to it. * The only limitation is that each call rewrites the buffer again. Index: uspace/lib/usb/src/dp.c =================================================================== --- uspace/lib/usb/src/dp.c (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/src/dp.c (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -32,5 +32,12 @@ /** * @file - * @brief USB descriptor parser (implementation). + * USB descriptor parser (implementation). + * + * The descriptor parser is a generic parser for structure, where individual + * items are stored in single buffer and each item begins with length followed + * by type. These types are organized into tree hierarchy. + * + * The parser is able of only two actions: find first child and find next + * sibling. */ #include Index: uspace/lib/usb/src/dump.c =================================================================== --- uspace/lib/usb/src/dump.c (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/src/dump.c (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -31,5 +31,5 @@ */ /** @file - * @brief Descriptor dumping. + * Descriptor dumping. */ #include @@ -43,6 +43,9 @@ #include +/** Mapping between descriptor id and dumping function. */ typedef struct { + /** Descriptor id. */ int id; + /** Dumping function. */ void (*dump)(FILE *, const char *, const char *, const uint8_t *, size_t); @@ -66,4 +69,5 @@ const uint8_t *, size_t); +/** Descriptor dumpers mapping. */ static descriptor_dump_t descriptor_dumpers[] = { { USB_DESCTYPE_DEVICE, usb_dump_descriptor_device }, @@ -273,4 +277,5 @@ const uint8_t *descriptor, size_t descriptor_length) { + /* TODO */ } @@ -279,4 +284,5 @@ const uint8_t *descriptor, size_t descriptor_length) { + /* TODO */ } Index: uspace/lib/usb/src/hcdhubd_private.h =================================================================== --- uspace/lib/usb/src/hcdhubd_private.h (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ (revision ) @@ -1,77 +1,0 @@ -/* - * Copyright (c) 2010 Vojtech Horky - * All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * - * - Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * - Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * - The name of the author may not be used to endorse or promote products - * derived from this software without specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR - * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. - * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, - * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF - * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - */ - -/** @addtogroup libusb - * @{ - */ -/** @file - * @brief Common definitions for both HC driver and hub driver. - */ -#ifndef LIBUSB_HCDHUBD_PRIVATE_H_ -#define LIBUSB_HCDHUBD_PRIVATE_H_ - -#define USB_HUB_DEVICE_NAME "usbhub" -#define USB_KBD_DEVICE_NAME "hid" - -extern link_t hc_list; -extern usb_hc_driver_t *hc_driver; - -extern usbhc_iface_t usbhc_interface; - -usb_address_t usb_get_address_by_handle(devman_handle_t); -int usb_add_hc_device(device_t *); - -/** lowest allowed usb address */ -extern int usb_lowest_address; - -/** highest allowed usb address */ -extern int usb_highest_address; - -/** - * @brief initialize address list of given hcd - * - * This function should be used only for hcd initialization. - * It creates interval list of free addresses, thus it is initialized as - * list with one interval with whole address space. Using an address shrinks - * the interval, freeing an address extends an interval or creates a - * new one. - * - * @param hcd - * @return - */ -void usb_create_address_list(usb_hc_device_t * hcd); - - - - - - -#endif -/** - * @} - */ Index: uspace/lib/usb/src/hub.c =================================================================== --- uspace/lib/usb/src/hub.c (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/src/hub.c (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -144,5 +144,5 @@ /** Wrapper for registering attached device to the hub. * - * The @p enable_port function is expected to enable singalling on given + * The @p enable_port function is expected to enable signaling on given * port. * The two arguments to it can have arbitrary meaning @@ -152,5 +152,5 @@ * * If the @p enable_port fails (i.e. does not return EOK), the device - * addition is cancelled. + * addition is canceled. * The return value is then returned (it is good idea to use different * error codes than those listed as return codes by this function itself). @@ -159,5 +159,5 @@ * @param connection Opened connection to host controller. * @param dev_speed New device speed. - * @param enable_port Function for enabling signalling through the port the + * @param enable_port Function for enabling signaling through the port the * device is attached to. * @param port_no Port number (passed through to @p enable_port). @@ -201,5 +201,5 @@ /* - * Enable the port (i.e. allow signalling through this port). + * Enable the port (i.e. allow signaling through this port). */ rc = enable_port(port_no, arg); Index: uspace/lib/usb/src/recognise.c =================================================================== --- uspace/lib/usb/src/recognise.c (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/src/recognise.c (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -31,5 +31,5 @@ */ /** @file - * @brief Functions for recognising kind of attached devices. + * Functions for recognition of attached devices. */ #include @@ -44,15 +44,22 @@ #include +/** Index to append after device name for uniqueness. */ static size_t device_name_index = 0; +/** Mutex guard for device_name_index. */ static FIBRIL_MUTEX_INITIALIZE(device_name_index_mutex); +/** DDF operations of child devices. */ ddf_dev_ops_t child_ops = { .interfaces[USB_DEV_IFACE] = &usb_iface_hub_child_impl }; +/** Get integer part from BCD coded number. */ #define BCD_INT(a) (((unsigned int)(a)) / 256) +/** Get fraction part from BCD coded number (as an integer, no less). */ #define BCD_FRAC(a) (((unsigned int)(a)) % 256) +/** Format for BCD coded number to be used in printf. */ #define BCD_FMT "%x.%x" +/** Arguments to printf for BCD coded number. */ #define BCD_ARGS(a) BCD_INT((a)), BCD_FRAC((a)) @@ -113,4 +120,11 @@ } +/** Add match id to list or return with error code. + * + * @param match_ids List of match ids. + * @param score Match id score. + * @param format Format of the matching string + * @param ... Arguments for the format. + */ #define ADD_MATCHID_OR_RETURN(match_ids, score, format, ...) \ do { \ Index: uspace/lib/usb/src/request.c =================================================================== --- uspace/lib/usb/src/request.c (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/src/request.c (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -110,5 +110,5 @@ * (must be in USB endianness). * @param data Buffer where to store data accepted during the DATA stage. - * (they will come in USB endianess). + * (they will come in USB endianness). * @param data_size Size of the @p data buffer * (in native endianness). @@ -161,10 +161,4 @@ * the new address. * - * @see usb_drv_reserve_default_address - * @see usb_drv_release_default_address - * @see usb_drv_request_address - * @see usb_drv_release_address - * @see usb_drv_bind_address - * * @param pipe Control endpoint pipe (session must be already started). * @param new_address New USB address to be set (in native endianness). @@ -528,5 +522,5 @@ return EEMPTY; } - /* Substract first 2 bytes (length and descriptor type). */ + /* Subtract first 2 bytes (length and descriptor type). */ string_descriptor_size -= 2; @@ -548,5 +542,5 @@ size_t i; for (i = 0; i < langs_count; i++) { - /* Language code from the descriptor is in USB endianess. */ + /* Language code from the descriptor is in USB endianness. */ /* FIXME: is this really correct? */ uint16_t lang_code = (string_descriptor[2 + 2 * i + 1] << 8) @@ -569,7 +563,7 @@ * * @param[in] pipe Control endpoint pipe (session must be already started). - * @param[in] index String index (in native endianess), + * @param[in] index String index (in native endianness), * first index has number 1 (index from descriptors can be used directly). - * @param[in] lang String language (in native endianess). + * @param[in] lang String language (in native endianness). * @param[out] string_ptr Where to store allocated string in native encoding. * @return Error code. @@ -613,5 +607,5 @@ goto leave; } - /* Substract first 2 bytes (length and descriptor type). */ + /* Subtract first 2 bytes (length and descriptor type). */ string_size -= 2; Index: uspace/lib/usb/src/usb.c =================================================================== --- uspace/lib/usb/src/usb.c (revision 1efe89b1e7ca890cc3565fca0d6e6e03e52481e1) +++ uspace/lib/usb/src/usb.c (revision 960bee9b5ba3efcc8c5c9d486ebeaad527f1f223) @@ -31,5 +31,5 @@ */ /** @file - * @brief Base USB types. + * Common USB functions. */ #include @@ -37,5 +37,9 @@ -/** String representation for USB transfer type. */ +/** String representation for USB transfer type. + * + * @param t Transfer type. + * @return Transfer type as a string (in English). + */ const char * usb_str_transfer_type(usb_transfer_type_t t) {