Index: uspace/lib/usbhost/src/iface.c =================================================================== --- uspace/lib/usbhost/src/iface.c (revision 2582d8f229da75fae68a1b3cd05680387df5112d) +++ uspace/lib/usbhost/src/iface.c (revision 5dd4294b7c1909ed090c0e8b544a44d7c8a5b4f6) @@ -39,4 +39,14 @@ #include +/** Prepare generic usb_transfer_batch and schedule it. + * @param fun DDF fun + * @param target address and endpoint number. + * @param setup_data Data to use in setup stage (Control communication type) + * @param in Callback for device to host communication. + * @param out Callback for host to device communication. + * @param arg Callback parameter. + * @param name Communication identifier (for nicer output). + * @return Error code. + */ static inline int send_batch( ddf_fun_t *fun, usb_target_t target, usb_direction_t direction, @@ -89,4 +99,9 @@ } /*----------------------------------------------------------------------------*/ +/** Calls ep_add_hook upon endpoint registration. + * @param ep Endpoint to be registered. + * @param arg hcd_t in disguise. + * @return Error code. + */ static int register_helper(endpoint_t *ep, void *arg) { @@ -99,4 +114,8 @@ } /*----------------------------------------------------------------------------*/ +/** Calls ep_remove_hook upon endpoint removal. + * @param ep Endpoint to be unregistered. + * @param arg hcd_t in disguise. + */ static void unregister_helper(endpoint_t *ep, void *arg) { @@ -108,4 +127,8 @@ } /*----------------------------------------------------------------------------*/ +/** Calls ep_remove_hook upon endpoint removal. Prints warning. + * @param ep Endpoint to be unregistered. + * @param arg hcd_t in disguise. + */ static void unregister_helper_warn(endpoint_t *ep, void *arg) { @@ -119,9 +142,11 @@ } /*----------------------------------------------------------------------------*/ -/** Request address interface function +/** Request address interface function. * * @param[in] fun DDF function that was called. + * @param[in] address Pointer to preferred USB address. + * @param[out] address Place to write a new address. + * @param[in] strict Fail if the preferred address is not available. * @param[in] speed Speed to associate with the new default address. - * @param[out] address Place to write a new address. * @return Error code. */ @@ -140,5 +165,5 @@ } /*----------------------------------------------------------------------------*/ -/** Bind address interface function +/** Bind address interface function. * * @param[in] fun DDF function that was called. @@ -148,5 +173,5 @@ */ static int bind_address( - ddf_fun_t *fun, usb_address_t address, devman_handle_t handle) + ddf_fun_t *fun, usb_address_t address, devman_handle_t handle) { assert(fun); @@ -176,5 +201,5 @@ } /*----------------------------------------------------------------------------*/ -/** Release address interface function +/** Release address interface function. * * @param[in] fun DDF function that was called. @@ -194,8 +219,18 @@ } /*----------------------------------------------------------------------------*/ +/** Register endpoint interface function. + * @param fun DDF function. + * @param address USB address of the device. + * @param endpoint USB endpoint number to be registered. + * @param transfer_type Endpoint's transfer type. + * @param direction USB communication direction the endpoint is capable of. + * @param max_packet_size Maximu size of packets the endpoint accepts. + * @param interval Preferred timeout between communication. + * @return Error code. + */ static int register_endpoint( ddf_fun_t *fun, usb_address_t address, usb_endpoint_t endpoint, usb_transfer_type_t transfer_type, usb_direction_t direction, - size_t max_packet_size, unsigned int interval) + size_t max_packet_size, unsigned interval) { assert(fun); @@ -220,4 +255,11 @@ } /*----------------------------------------------------------------------------*/ +/** Unregister endpoint interface function. + * @param fun DDF function. + * @param address USB address of the endpoint. + * @param endpoint USB endpoint number. + * @param direction Communication direction of the enpdoint to unregister. + * @return Error code. + */ static int unregister_endpoint( ddf_fun_t *fun, usb_address_t address, @@ -233,4 +275,14 @@ } /*----------------------------------------------------------------------------*/ +/** Inbound communication interface function. + * @param fun DDF function. + * @param target Communication target. + * @param setup_data Data to use in setup stage (control transfers). + * @param data Pointer to data buffer. + * @param size Size of the data buffer. + * @param callback Function to call on communication end. + * @param arg Argument passed to the callback function. + * @return Error code. + */ static int usb_read(ddf_fun_t *fun, usb_target_t target, uint64_t setup_data, uint8_t *data, size_t size, usbhc_iface_transfer_in_callback_t callback, @@ -241,4 +293,14 @@ } /*----------------------------------------------------------------------------*/ +/** Outbound communication interface function. + * @param fun DDF function. + * @param target Communication target. + * @param setup_data Data to use in setup stage (control transfers). + * @param data Pointer to data buffer. + * @param size Size of the data buffer. + * @param callback Function to call on communication end. + * @param arg Argument passed to the callback function. + * @return Error code. + */ static int usb_write(ddf_fun_t *fun, usb_target_t target, uint64_t setup_data, const uint8_t *data, size_t size, @@ -249,4 +311,5 @@ } /*----------------------------------------------------------------------------*/ +/** usbhc Interface implementation using hcd_t from libusbhost library. */ usbhc_iface_t hcd_iface = { .request_address = request_address, Index: uspace/lib/usbhost/src/usb_device_manager.c =================================================================== --- uspace/lib/usbhost/src/usb_device_manager.c (revision 2582d8f229da75fae68a1b3cd05680387df5112d) +++ uspace/lib/usbhost/src/usb_device_manager.c (revision 5dd4294b7c1909ed090c0e8b544a44d7c8a5b4f6) @@ -26,5 +26,4 @@ * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ - /** @addtogroup libusbhost * @{ @@ -41,5 +40,4 @@ * * @param[in] instance Device manager structure to use. - * @param[in] speed Speed of the device requiring address. * @return Free address, or error code. */ @@ -133,4 +131,5 @@ * @param[in] handle Devman handle of the device. * @return Error code. + * @note Won't accept binding for default address. */ int usb_device_manager_bind_address(usb_device_manager_t *instance, @@ -184,5 +183,5 @@ } /*----------------------------------------------------------------------------*/ -/** Find USB address associated with the device +/** Find USB address associated with the device. * * @param[in] instance Device manager structure to use. @@ -208,5 +207,4 @@ /*----------------------------------------------------------------------------*/ /** Find devman handle and speed assigned to USB address. - * Intentionally refuse to work on default address. * * @param[in] instance Device manager structure to use. Index: uspace/lib/usbhost/src/usb_endpoint_manager.c =================================================================== --- uspace/lib/usbhost/src/usb_endpoint_manager.c (revision 2582d8f229da75fae68a1b3cd05680387df5112d) +++ uspace/lib/usbhost/src/usb_endpoint_manager.c (revision 5dd4294b7c1909ed090c0e8b544a44d7c8a5b4f6) @@ -26,4 +26,10 @@ * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** @addtogroup libusbhost + * @{ + */ +/** @file + * HC Endpoint management. + */ #include @@ -56,5 +62,5 @@ } /*----------------------------------------------------------------------------*/ -/** Get list that holds endpints for given address. +/** Get list that holds endpoints for given address. * @param instance usb_endpoint_manager structure, non-null. * @param addr USB address, must be >= 0. @@ -75,4 +81,5 @@ * @return Pointer to endpoint_t structure representing given communication * target, NULL if there is no such endpoint registered. + * @note Assumes that the internal mutex is locked. */ static endpoint_t * find_locked(usb_endpoint_manager_t *instance, @@ -169,4 +176,5 @@ * * Really ugly one. Resets toggle bit on all endpoints that need it. + * @TODO Use tools from libusbdev requests.h */ void usb_endpoint_manager_reset_eps_if_need(usb_endpoint_manager_t *instance, @@ -184,4 +192,5 @@ case 0x01: /* Clear Feature -- resets only cleared ep */ /* Recipient is endpoint, value is zero (ENDPOINT_STALL) */ + // TODO Use macros in libusbdev requests.h if (((data[0] & 0xf) == 1) && ((data[2] | data[3]) == 0)) { fibril_mutex_lock(&instance->guard); @@ -202,5 +211,7 @@ /* Recipient must be device, this resets all endpoints, * In fact there should be no endpoints but EP 0 registered - * as different interfaces use different endpoints. */ + * as different interfaces use different endpoints, + * unless you're changing configuration or alternative + * interface of an already setup device. */ if ((data[0] & 0xf) == 0) { fibril_mutex_lock(&instance->guard); @@ -385,4 +396,13 @@ } /*----------------------------------------------------------------------------*/ +/** Unregister and destroy all endpoints using given address. + * @param instance usb_endpoint_manager structure, non-null. + * @param address USB address. + * @param endpoint USB endpoint number. + * @param direction Communication direction. + * @param callback Function to call after unregister, before destruction. + * @arg Argument to pass to the callback function. + * @return Error code. + */ void usb_endpoint_manager_remove_address(usb_endpoint_manager_t *instance, usb_address_t address, void (*callback)(endpoint_t *, void *), void *arg) @@ -403,2 +423,5 @@ fibril_mutex_unlock(&instance->guard); } +/** + * @} + */ Index: uspace/lib/usbhost/src/usb_transfer_batch.c =================================================================== --- uspace/lib/usbhost/src/usb_transfer_batch.c (revision 2582d8f229da75fae68a1b3cd05680387df5112d) +++ uspace/lib/usbhost/src/usb_transfer_batch.c (revision 5dd4294b7c1909ed090c0e8b544a44d7c8a5b4f6) @@ -48,4 +48,5 @@ * @param func_in callback on IN transfer completion. * @param func_out callback on OUT transfer completion. + * @param fun DDF function (passed to callback function). * @param arg Argument to pass to the callback function. * @param private_data driver specific per batch data.