From: Stanislaw Wadas Date: Thu, 23 Jul 2015 14:39:20 +0000 (+0200) Subject: Add doxygen documentation X-Git-Tag: submit/tizen_common/20160317.155115~40 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=f8af93601b4fc6c155708022031f0a7331d88c6c;p=platform%2Fcore%2Fapi%2Fusb-host.git Add doxygen documentation Change-Id: Ieb67d4889d2a567ee737d5ccc1f920bbd727dfe9 Signed-off-by: Stanislaw Wadas --- diff --git a/include/libhusb.h b/include/libhusb.h index b0edd09..13d6306 100644 --- a/include/libhusb.h +++ b/include/libhusb.h @@ -24,22 +24,59 @@ extern "C" { #include +/** + * @brief Context of library + * @details This structure represents libhusb session. + * Using own session allow to use of library independently. + * For example calling libhusb_exit() will ont destroy resources + * that are being used by another user of library. + * + * To create session there is need to call libhusb_init(), to + * to destroy libhusb_exit(). Each session created by libhusb_init() + * hast to be destroyed using libhusb_exit() + */ struct libhusb_context; typedef struct libhusb_context libhusb_context; +/** + * @brief Structure representing USB device. + * @details This structure represents libhusb device found on USB bus. + * + * Some basic operations can be performed on a device using this struct. + * To perform any I/O a device handle must be obtain by opening device + * using libhusb_open() or libhusb_device_open_with_vid_pid(). + * + */ struct libhusb_device; typedef struct libhusb_device libhusb_device; +/** + * @brief libhusb_device_handle struct + * @details This opaqe type, and represents handle to USB device. + * + * Hendle is used to perform I/O operations, when finished libhusb_close() + * should be called. + */ struct libhusb_device_handle; typedef struct libhusb_device_handle libhusb_device_handle; +/** + * @brief libhusb_cfg_descriptor struct + * @details Structure represents the standard USB configuration descriptor. + * + * All multiple-byte fields are represented in host-endian format. + */ struct libhusb_cfg_descriptor; typedef struct libhusb_cfg_descriptor libhusb_cfg_descriptor; +/** + * @brief libhusb_supported_speed + * @details This field contain speed that USB device can support. + */ enum libhusb_supported_speed { LIBHUSB_SPEED_UNKNOWN = 0, @@ -56,6 +93,10 @@ enum libhusb_supported_speed { LIBHUSB_SPEED_SUPER = 4, }; +/** + * @brief libhusb_device_descriptor struct + * @details This structure presents standard USB device descriptor. + */ struct libhusb_device_descriptor { uint8_t bLength; uint8_t bDescriptorType; @@ -73,6 +114,10 @@ struct libhusb_device_descriptor { uint8_t bNumConfigurations; }; +/** + * @brief libhusb_cfg_descriptor struct + * @details This structure presents standard USB configuration descriptor. + */ struct libhusb_cfg_descriptor { uint8_t bLength; uint8_t bDescriptorType; @@ -87,11 +132,19 @@ struct libhusb_cfg_descriptor { int extra_length; }; +/** + * @brief libhusb_interface struct + * @details This is collection of alternate settings for USB interface. + */ struct libhusb_interface { struct libhusb_interface_descriptor *altsetting; int num_altsetting; }; +/** + * @brief libhusb_interface_descriptor struct + * @details This structure presents standard USB interface descriptor. + */ struct libhusb_interface_descriptor { uint8_t bLength; uint8_t bDescriptorType; @@ -107,6 +160,10 @@ struct libhusb_interface_descriptor { int extra_length; }; +/** + * @brief libhusb_interface_descriptor struct + * @details This structure presents standard USB endpoint descriptor. + */ struct libhusb_endpoint_descriptor { uint8_t bLength; uint8_t bDescriptorType; @@ -120,6 +177,14 @@ struct libhusb_endpoint_descriptor { int extra_length; }; +/** + * @brief usb_device_error + * @details This field contain error codes. + * Library return 0 on success or negative number on error. + * + * libhusb_error_name() can be used to translate error number + * to string representation. + */ enum usb_device_error { LIBHUSB_SUCCESS = 0, LIBHUSB_ERROR_IO = -1, @@ -137,6 +202,10 @@ enum usb_device_error { LIBHUSB_ERROR_OTHER = -99, }; +/** + * @brief usb_device_transfer_status + * @details Transfer status codes. + */ enum usb_device_transfer_status { LIBHUSB_TRANSFER_COMPLETED, LIBHUSB_TRANSFER_ERROR, @@ -147,77 +216,428 @@ enum usb_device_transfer_status { LIBHUSB_TRANSFER_OVERFLOW, }; +/** + * @brief Initalize libhusb. + * @details Function must be called befor any other function. + * @param ctx Context pointer, can`t be NULL. + * @return 0 on success or LIBHUSB_ERROR code on failure. + */ int libhusb_init(libhusb_context **ctx); +/** + * @brief Deinitalize libhusb. + * @details Function must be called after closing all devices + * and before application close. It has to be called to cleanup + * the memory used by library. + * @param ctx context to deinitalize. + */ void libhusb_exit(libhusb_context *ctx); +/** + * @brief Opens device. + * @details Function open device and return device handle. + * Device handle allow to perform operations on USB device. + * @param dev Device to open. + * @return 0 on success + * @return LIBHUSB_ERROR_NO_MEM mem allocation failure + * @return LIBHUSB_ERROR_ACCESS if no proper permission to access device + * @return LIBHUSB_ERROR_NO_DEVICE if there is no device connected + * @return other error on failure + */ libhusb_device_handle *libhusb_open(libhusb_device *dev); +/** + * @brief Close device. + * @details Function should be called before libhusb_exit(). + * It destroy reference that was added by libhusb_open(). + * @param handle Handle to device that should be closed. + */ void libhusb_close(libhusb_device_handle *handle); +/** + * @brief Opens device with vaild idVendor and idProduct + * @details Function can be used to open device with known idVendor and + * idProduct. If two or more devices have same vendor and product id only + * first will be open. + * @param ctx Context + * @param vendor_id idVendor of connected device. + * @param product_id idProduct of connected device. + * @return handle to the first found device, NULL if no device found + * or error occurred. + */ libhusb_device_handle *libhusb_device_open_with_vid_pid(libhusb_context *ctx, uint16_t vendor_id, uint16_t product_id); +/** + * @brief Get device. + * @details Function get elementary device for handle. Function does + * not modify ref count of returned device. User can use returned device + * as long as handle is opened. + * @param handle Device handle. + * @return Elementary device. + */ libhusb_device *libhusb_get_device(libhusb_device_handle *handle); +/** + * @brief Get USB device list. + * @details This function return list of USB devices attached to system. + * To free device list libhusb_free_devices() should be used, this + * function can also unref devices. Do not unref device and + * then open it. + * + * Each devices have reference counter. Functions libhusb_ref_device() and + * libhusb_unref_device() are used to ref or unref device. When ref counter + * reach 0 device will be freed. + * Devices reached by calling libhusb_get_devices() have a reference count of + * 1, and libhusb_free_devices() can optionally decrease the reference count + * on all devices in the list. libhusb_open() adds another reference which is + * later destroyed by libhusb_close(). + * + * @param ctx Context. + * @param devs List of devices. Mus be freed with libhusb_free_devices(). + * @return numbers of connected devices or libhusb_error() code. + */ ssize_t libhusb_get_devices(libhusb_context *ctx, libhusb_device ***devs); +/** + * @brief Free devices list. + * @details Function need to be called to free device list. This + * function can also unref devices if unref_devices is set. + * Do not unref device and then open it. + * @param list List of devices. + * @param unref_devices Set to unref devices. + */ void libhusb_free_devices(libhusb_device **list, int unref_devices); +/** + * @brief Ref a device. + * @details Increment ref count of device. + * @param dev Device to reference. + * @return The same device. + */ libhusb_device *libhusb_ref_device(libhusb_device *dev); +/** + * @brief Unef a device. + * @details Decrement ref count of device. If ref count reach zero, + * device should be destroyed. + * @param dev Device to reference. + */ void libhusb_unref_device(libhusb_device *dev); +/** + * @brief Get max packet size. + * @details Function will retrieve the wMaxPacketSize for particular endpoint + * in active device configuration. + * @param dev Device. + * @param endpoint Address of endpoint. + * @return the wMaxPacketSize value. + * @return LIBHUSB_ERROR_NOT_FOUND if the endpoint does not exist. + * @return LIBHUSB_ERROR_OTHER on other failure. + */ int libhusb_get_max_packet_size(libhusb_device *dev, uint8_t endpoint); +/** + * @brief Get bus number. + * @details Get device bus number. This is number of the bus + * that device is connected to. + * @param dev Device. + * @return Bus number. + */ uint8_t libhusb_get_bus_number(libhusb_device *dev); +/** + * @brief Get address. + * @details Get device addres. This is addres of device on the bus + * that device is connected to. + * @param dev Device. + * @return Device address. + */ uint8_t libhusb_get_address(libhusb_device *dev); +/** + * @brief Get list of port numbers. + * @details Get list of all port numbers from a device. + * @param dev Device. + * @param port_numbers Array containing port numbers. + * @param port_numbers_len Max lenght of array. + * @return Number of elements. + */ int libhusb_get_port_numbers(libhusb_device *dev, uint8_t *port_numbers, int port_numbers_len); +/** + * @brief Get device descriptor. + * @details Get device descriptor for a device. + * @param dev Device. + * @param desc Location for descriptor data. + * @return 0 on success or a LIBHUSB_ERROR code on failure. + */ int libhusb_get_device_descriptor(libhusb_device *dev, struct libhusb_device_descriptor *desc); +/** + * @brief Get active config. + * @details Get bConfigurationValue of active configuration. + * Function will return 0 value in configparameter + * if device is unconfigured. + * @param handle Device handle + * @param config Location for bConfigurationValue (valid on ret 0) + * @return 0 on success + * @return LIBHUSB_ERROR_NO_DEVICE if the dev has been disconnected + * @return another LIBHUSB_ERROR code on other failure + */ int libhusb_get_active_config(libhusb_device_handle *handle, int *config); +/** + * @brief Set configuration. + * @details Set active configuration for a device. + * @param handle Device handle. + * @param configuration bConfigurationValue of configuration to active. + * @return 0 on success + * @return LIBHUSB_ERROR_NOT_FOUND if the req configuration does not exist + * @return LIBHUSB_ERROR_BUSY if interfaces are currently claimed + * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected + * @return another LIBHUSB_ERROR code on other failure + */ int libhusb_set_config(libhusb_device_handle *handle, int configuration); +/** + * @brief Claim interface. + * @details Claim interface on a device handle. + * To perform I/O operations on interface user has to claim it. + * Remember to call libhusb_release_interface() when communication + * with the device is finished. + * @param handle Device Handle + * @param interface_number The bInterfaceNumber of interface to claim. + * @param force Set force to auto detach kernel driver. + * @return 0 on success. + * @return LIBHUSB_ERROR_NOT_FOUND if the requested interface does not exist. + * @return LIBHUSB_ERROR_BUSY if another program or driver has claimed the + * interface. + * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected. + * @return a LIBHUSB_ERROR code on other failure + */ int libhusb_claim_interface(libhusb_device_handle *handle, int interface_number, int force); +/** + * @brief Release interface. + * @details Release interface previously claimed by libhusb_claim_interface(). + * This is a blocking function. + * @param handle Device handle. + * @param interface_number The bInterfaceNumber of interface to release. + * @return 0 on success + * @return LIBHUSB_ERROR_NOT_FOUND if the interface was not claimed + * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected + * @return another LIBHUSB_ERROR code on other failure + */ int libhusb_release_interface(libhusb_device_handle *handle, int interface_number); +/** + * @brief Clear the halt/stall condition. + * @details Clear the halt/stall condition for an endpoint. + * @param handle Device handle. + * @param endpoint The endpoint to clear halt status. + * @return 0 on success + * @return LIBHUSB_ERROR_NOT_FOUND if the endpoint does not exist + * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected + * @return another LIBHUSB_ERROR code on other failure + */ int libhusb_clear_halt(libhusb_device_handle *handle, uint8_t endpoint); +/** + * @brief Reset a device. + * @details Reset USB port to reinitalize a device. + * This is a blocking function. + * @param handle Device handle. + * @return 0 on success. + * @return LIBHUSB_ERROR_NOT_FOUND if re-enumeration is required, or if the + * device has been disconnected. + * @return another LIBHUSB_ERROR code on other failure. + */ int libhusb_reset_device(libhusb_device_handle *handle); +/** + * @brief Determine active kernel driver. + * @details Determine if a kernel driver is active on an interface. + * Interface can't be claimed if driver is active unless force + * option is used. + * @param handle Device handle. + * @param interface_number number of interface to check + * @return 0 if no kernel driver is active + * @return 1 if a kernel driver is active + * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected. + * @return LIBHUSB_ERROR_NOT_SUPPORTED on platforms where the functionality + * is not available. + * @return another LIBHUSB_ERROR code on other failure. + * @see libhusb_detach_kernel_driver() + */ int libhusb_kernel_driver_active(libhusb_device_handle *handle, int interface_number); +/** + * @brief Detach kernel driver. + * @details Detach a kernel driver from an interface. + * @param handle Device handle. + * @param interface_number Number of interface on which detach kernel driver. + * @return 0 on success + * @return LIBHUSB_ERROR_NOT_FOUND if no kernel driver was active + * @return LIBHUSB_ERROR_INVALID_PARAM if the interface does not exist + * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected + * @return LIBHUSB_ERROR_NOT_SUPPORTED on platforms where the functionality + * is not available + * @return another LIBHUSB_ERROR code on other failure + * @see libhusb_kernel_driver_active() + */ int libhusb_detach_kernel_driver(libhusb_device_handle *handle, int interface_number); +/** + * @brief Attach kernel driver + * @details Re-attach an interface's kernel driver, which was previously detached + * using libhusb_detach_kernel_driver(). + * @param handle Device handle. + * @param interface_number Interface to attach the driver. + * @return 0 on success. + * @return LIBHUSB_ERROR_NOT_FOUND if no kernel driver was active. + * @return LIBHUSB_ERROR_INVALID_PARAM if the interface does not exist. + * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected. + * @return LIBHUSB_ERROR_NOT_SUPPORTED on platforms where the functionality + * is not available. + * @return LIBHUSB_ERROR_BUSY if the driver cannot be attached because the + * interface is claimed by a program or driver. + * @return another LIBHUSB_ERROR code on other failure + * @see libhusb_kernel_driver_active() + */ int libhusb_attach_kernel_driver(libhusb_device_handle *handle, int interface_number); +/** + * @brief Get config descriptor. + * @details Get a USB configuration descriptor. + * @param dev Device + * @param config_index index of configuration to retrieve. + * @param config Output location for USB configuration descriptor. + * Must be freed with libhusb_free_config_descriptor(). + * @return 0 on success + * @return LIBHUSB_ERROR_NOT_FOUND if the configuration does not exist. + * @return another LIBHUSB_ERROR code on error. + */ int libhusb_get_config_descriptor(libhusb_device *dev, uint8_t config_index, struct libhusb_cfg_descriptor **config); +/** + * @brief Free config descriptor. + * @details Free configuration descriptor obtained from + * libhusb_get_config_descriptor(). + * @param config Configuration to free. + */ void libhusb_free_config_descriptor(struct libhusb_cfg_descriptor *config); +/** + * @brief Get string descriptor. + * @details Retrieve a string descriptor in ASCII. + * @param handle Device handle. + * @param desc_index Index of descriptor to retrieve. + * @param data Out buffer for ASCII string descriptor. + * @param length Data bufer size. + * @return number of bytes returned in data, or LIBHUSB_ERROR code on failure. + */ int libhusb_get_string_descriptor_ascii(libhusb_device_handle *handle, uint8_t desc_index, unsigned char *data, int length); /* sync IO */ +/** + * @brief Perform USB control transfer. + * @details + * + * The wValue, wIndex and wLength fields values should be given in host-endian + * byte order + * + * @param handle Device handle. + * @param request_type Request type field for the setup packet + * @param bRequest Request field for the setup packet + * @param wValue Value field for the setup packet + * @param wIndex Index field for the setup packet + * @param data Suitably-sized data buffer for either input or output + * (depending on direction bits within bmRequestType) + * @param wLength Length field for the setup packet. The data buffer should + * be at least this size. + * @param timeout Timeout (in millseconds) that this function should wait + * before giving up due to no response being received. For an unlimited + * timeout, 0 value should be used. + * @return on success, the number of bytes actually transferred + * @return LIBHUSB_ERROR_TIMEOUT if the transfer timed out + * @return LIBHUSB_ERROR_PIPE if the control request was not supported by the + * device + * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected + * @return another LIBHUSB_ERROR code on other failures + */ int libhusb_control_transfer(libhusb_device_handle *handle, uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, unsigned char *data, uint16_t wLength, unsigned int timeout); +/** + * @brief Perform a bulk transfer. + * @details Perform a USB bulk transfer. The direction of the transfer is inferred from + * the direction bits of the endpoint address. + * + * @param handle Device handle. + * @param endpoint Address of a valid endpoint to communicate with + * @param data Suitably-sized data buffer for either input or output + * (depending on endpoint) + * @param length For bulk writes, the number of bytes from data to be sent. for + * bulk reads, the maximum number of bytes to receive into the data buffer. + * @param transferred Output location for the number of bytes actually + * transferred. + * @param timeout Timeout (in millseconds) that this function should wait + * before giving up due to no response being received. For an unlimited + * timeout, 0 value should be used. + * @return 0 on success (and populates transferred) + * @return LIBHUSB_ERROR_TIMEOUT if the transfer timed out (and populates + * transferred) + * @return LIBHUSB_ERROR_PIPE if the endpoint halted + * @return LIBHUSB_ERROR_OVERFLOW if the device offered more data + * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected + * @return another LIBHUSB_ERROR code on other failures + */ int libhusb_bulk_transfer(libhusb_device_handle *handle, uint8_t endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout); +/** + * @brief Perform interrupt transfer. + * @details Perform a USB interrupt transfer. The direction of the transfer is inferred + * from the direction bits of the endpoint address. + * + * @param handle Device handle. + * @param endpoint Address of a valid endpoint to communicate with + * @param data Suitably-sized data buffer for either input or output + * (depending on endpoint) + * @param length For bulk writes, the number of bytes from data to be sent. for + * bulk reads, the maximum number of bytes to receive into the data buffer. + * @param transferred Output location for the number of bytes actually + * transferred. + * @param timeout Timeout (in millseconds) that this function should wait + * before giving up due to no response being received. For an unlimited + * timeout, 0 value should be used. + * @return 0 on success (and populates transferred) + * @return LIBHUSB_ERROR_TIMEOUT if the transfer timed out (and populates + * transferred) + * @return 0 on success (and populates transferred) + * @return LIBHUSB_ERROR_TIMEOUT if the transfer timed out + * @return LIBHUSB_ERROR_PIPE if the endpoint halted + * @return LIBHUSB_ERROR_OVERFLOW if the device offered more data + * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected + * @return another LIBHUSB_ERROR code on other error + */ int libhusb_interrupt_transfer(libhusb_device_handle *handle, uint8_t endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout); +/** + * @brief Translate error name + * @details Translates error code to NULL terminated libhusb + * error or status code. + * @param error_code Error code to translate. + * @return Error name + */ const char *libhusb_error_name(int error_code); #ifdef __cplusplus