From c899273c62568fdb00fe54b80eab45c6c0917969 Mon Sep 17 00:00:00 2001 From: fenugrec Date: Tue, 13 Oct 2015 14:22:33 -0400 Subject: [PATCH] usb: Improved comments of USB API usbd.h: more comments for bmRequestType and bmAttributes bitfield macros usbd.h: migrated and added API doxyblocks from implementations (*.c) --- include/libopencm3/usb/usbd.h | 68 ++++++++++++++++++++++++++++++++- include/libopencm3/usb/usbstd.h | 22 +++++++---- lib/usb/usb.c | 22 ----------- 3 files changed, 81 insertions(+), 31 deletions(-) diff --git a/include/libopencm3/usb/usbd.h b/include/libopencm3/usb/usbd.h index f81cd237..ec19a3bc 100644 --- a/include/libopencm3/usb/usbd.h +++ b/include/libopencm3/usb/usbd.h @@ -60,6 +60,28 @@ extern const usbd_driver st_usbfs_v2_usb_driver; #define otghs_usb_driver stm32f207_usb_driver /* */ +/** + * Main initialization entry point. + * + * Initialize the USB firmware library to implement the USB device described + * by the descriptors provided. + * + * It is required that the 48MHz USB clock is already available. + * + * @param driver TODO + * @param dev Pointer to USB device descriptor. This must not be changed while + * the device is in use. + * @param conf Pointer to array of USB configuration descriptors. These must + * not be changed while the device is in use. The length of this + * array is determined by the bNumConfigurations field in the + * device descriptor. + * @param strings TODO + * @param control_buffer Pointer to array that would hold the data + * received during control requests with DATA + * stage + * @param control_buffer_size Size of control_buffer + * @return the usb device initialized for use. (currently cannot fail). + */ extern usbd_device * usbd_init(const usbd_driver *driver, const struct usb_device_descriptor *dev, const struct usb_config_descriptor *conf, @@ -67,12 +89,16 @@ extern usbd_device * usbd_init(const usbd_driver *driver, uint8_t *control_buffer, uint16_t control_buffer_size); +/** Registers a reset callback */ extern void usbd_register_reset_callback(usbd_device *usbd_dev, void (*callback)(void)); +/** Registers a suspend callback */ extern void usbd_register_suspend_callback(usbd_device *usbd_dev, void (*callback)(void)); +/** Registers a resume callback */ extern void usbd_register_resume_callback(usbd_device *usbd_dev, void (*callback)(void)); +/** Registers a SOF callback */ extern void usbd_register_sof_callback(usbd_device *usbd_dev, void (*callback)(void)); @@ -91,34 +117,72 @@ typedef void (*usbd_set_altsetting_callback)(usbd_device *usbd_dev, typedef void (*usbd_endpoint_callback)(usbd_device *usbd_dev, uint8_t ep); /* */ +/** Registers a control callback. + * + * The specified callback will be called if (type == (bmRequestType & type_mask)) + * @param type Handled request type + * @param type_mask Mask to apply before matching request type + * @return 0 if successful + */ extern int usbd_register_control_callback(usbd_device *usbd_dev, uint8_t type, uint8_t type_mask, usbd_control_callback callback); /* */ +/** Registers a "Set Config" callback + * @return 0 if successful + */ extern int usbd_register_set_config_callback(usbd_device *usbd_dev, usbd_set_config_callback callback); - +/** Registers a "Set Interface" (alternate setting) callback */ extern void usbd_register_set_altsetting_callback(usbd_device *usbd_dev, usbd_set_altsetting_callback callback); /* Functions to be provided by the hardware abstraction layer */ extern void usbd_poll(usbd_device *usbd_dev); + +/** Disconnect, if supported by the driver */ extern void usbd_disconnect(usbd_device *usbd_dev, bool disconnected); +/** Setup an endpoint + * @param addr Full EP address including direction (e.g. 0x01 or 0x81) + * @param type Value for bmAttributes (USB_ENDPOINT_ATTR_*) + */ extern void usbd_ep_setup(usbd_device *usbd_dev, uint8_t addr, uint8_t type, uint16_t max_size, usbd_endpoint_callback callback); +/** Write a packet + * @param addr EP address (direction is ignored) + * @param len # of bytes + * @return 0 if failed, len if succesful + */ extern uint16_t usbd_ep_write_packet(usbd_device *usbd_dev, uint8_t addr, const void *buf, uint16_t len); +/** Read a packet + * @param addr EP address + * @param len # of bytes + * @return Actual # of bytes read + */ extern uint16_t usbd_ep_read_packet(usbd_device *usbd_dev, uint8_t addr, void *buf, uint16_t len); - +/** Set/clear STALL condition on an endpoint + * @param addr Full EP address (with direction bit) + * @param stall if 0, clear STALL, else set stall. + */ extern void usbd_ep_stall_set(usbd_device *usbd_dev, uint8_t addr, uint8_t stall); + +/** Get STALL status of an endpoint + * @param addr Full EP address (with direction bit) + * @return nonzero if endpoint is stalled + */ extern uint8_t usbd_ep_stall_get(usbd_device *usbd_dev, uint8_t addr); +/** Set an Out endpoint to NAK + * @param addr EP address + * @param nak if nonzero, set NAK + */ extern void usbd_ep_nak_set(usbd_device *usbd_dev, uint8_t addr, uint8_t nak); /* Optional */ diff --git a/include/libopencm3/usb/usbstd.h b/include/libopencm3/usb/usbstd.h index b0df84c2..abfc8b03 100644 --- a/include/libopencm3/usb/usbstd.h +++ b/include/libopencm3/usb/usbstd.h @@ -65,17 +65,20 @@ struct usb_setup_data { #define USB_CLASS_VENDOR 0xFF /* bmRequestType bit definitions */ +/* bit 7 : direction */ +#define USB_REQ_TYPE_DIRECTION 0x80 #define USB_REQ_TYPE_IN 0x80 +/* bits 6..5 : type */ +#define USB_REQ_TYPE_TYPE 0x60 #define USB_REQ_TYPE_STANDARD 0x00 #define USB_REQ_TYPE_CLASS 0x20 #define USB_REQ_TYPE_VENDOR 0x40 +/* bits 4..0 : recipient */ +#define USB_REQ_TYPE_RECIPIENT 0x1F #define USB_REQ_TYPE_DEVICE 0x00 #define USB_REQ_TYPE_INTERFACE 0x01 #define USB_REQ_TYPE_ENDPOINT 0x02 - -#define USB_REQ_TYPE_DIRECTION 0x80 -#define USB_REQ_TYPE_TYPE 0x60 -#define USB_REQ_TYPE_RECIPIENT 0x1F +#define USB_REQ_TYPE_OTHER 0x03 /* USB Standard Request Codes - Table 9-4 */ #define USB_REQ_GET_STATUS 0 @@ -172,6 +175,7 @@ struct usb_config_descriptor { #define USB_DT_CONFIGURATION_SIZE 9 /* USB Configuration Descriptor bmAttributes bit definitions */ +#define USB_CONFIG_ATTR_DEFAULT 0x80 /** always required (USB2.0 table 9-10) */ #define USB_CONFIG_ATTR_SELF_POWERED 0x40 #define USB_CONFIG_ATTR_REMOTE_WAKEUP 0x20 @@ -217,20 +221,24 @@ struct usb_endpoint_descriptor { #define USB_ENDPOINT_ADDR_OUT(x) (x) #define USB_ENDPOINT_ADDR_IN(x) (0x80 | (x)) -/* USB Endpoint Descriptor bmAttributes bit definitions */ +/* USB Endpoint Descriptor bmAttributes bit definitions - Table 9-13 */ +/* bits 1..0 : transfer type */ #define USB_ENDPOINT_ATTR_CONTROL 0x00 #define USB_ENDPOINT_ATTR_ISOCHRONOUS 0x01 #define USB_ENDPOINT_ATTR_BULK 0x02 #define USB_ENDPOINT_ATTR_INTERRUPT 0x03 - +#define USB_ENDPOINT_ATTR_TYPE 0x03 +/* bits 3..2 : Sync type (only if ISOCHRONOUS) */ #define USB_ENDPOINT_ATTR_NOSYNC 0x00 #define USB_ENDPOINT_ATTR_ASYNC 0x04 #define USB_ENDPOINT_ATTR_ADAPTIVE 0x08 #define USB_ENDPOINT_ATTR_SYNC 0x0C - +#define USB_ENDPOINT_ATTR_SYNCTYPE 0x0C +/* bits 5..4 : usage type (only if ISOCHRONOUS) */ #define USB_ENDPOINT_ATTR_DATA 0x00 #define USB_ENDPOINT_ATTR_FEEDBACK 0x10 #define USB_ENDPOINT_ATTR_IMPLICIT_FEEDBACK_DATA 0x20 +#define USB_ENDPOINT_ATTR_USAGETYPE 0x30 /* Table 9-15 specifies String Descriptor Zero. * Table 9-16 specified UNICODE String Descriptor. diff --git a/lib/usb/usb.c b/lib/usb/usb.c index f2ed2772..a073bc76 100644 --- a/lib/usb/usb.c +++ b/lib/usb/usb.c @@ -39,28 +39,6 @@ LGPL License Terms @ref lgpl_license #include #include "usb_private.h" -/** - * Main initialization entry point. - * - * Initialize the USB firmware library to implement the USB device described - * by the descriptors provided. - * - * It is required that the 48MHz USB clock is already available. - * - * @param driver TODO - * @param dev Pointer to USB device descriptor. This must not be changed while - * the device is in use. - * @param conf Pointer to array of USB configuration descriptors. These must - * not be changed while the device is in use. The length of this - * array is determined by the bNumConfigurations field in the - * device descriptor. - * @param strings TODO - * @param control_buffer Pointer to array that would hold the data - * received during control requests with DATA - * stage - * @param control_buffer_size Size of control_buffer - * @return the usb device initialized for use. (currently cannot fail). - */ usbd_device *usbd_init(const usbd_driver *driver, const struct usb_device_descriptor *dev, const struct usb_config_descriptor *conf,