diff --git a/include/nuttx/usb/audio.h b/include/nuttx/usb/audio.h index d7f695beae..25fca69558 100644 --- a/include/nuttx/usb/audio.h +++ b/include/nuttx/usb/audio.h @@ -1,4 +1,4 @@ -/******************************************************************************************** +/**************************************************************************** * include/nuttx/usb/audio.h * Audio Device Class (ADC) definitions * @@ -42,29 +42,31 @@ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * - ********************************************************************************************/ + ****************************************************************************/ #ifndef __INCLUDE_NUTTX_USB_AUDIO_H #define __INCLUDE_NUTTX_USB_AUDIO_H -/******************************************************************************************** +/**************************************************************************** * Included Files - ********************************************************************************************/ + ****************************************************************************/ #include #include -/******************************************************************************************** +/**************************************************************************** * Preprocessor definitions - ********************************************************************************************/ + ****************************************************************************/ + /* Device Descriptor * - * Because audio functionality is always considered to reside at the interface level, this - * class specification does not define a specific audio device descriptor. For both composite - * devices and audio-only devices, the device descriptor must indicate that class information - * is to be found at the interface level. Therefore, the bDeviceClass, bDeviceSubClass and - * bDeviceProtocol fields of the device descriptor must contain the values 0xef, 0x02, and - * 0x01 respectively. + * Because audio functionality is always considered to reside at the + * interface level, this class specification does not define a specific audio + * device descriptor. For both composite devices and audio-only devices, the + * device descriptor must indicate that class information is to be found at + * the interface level. Therefore, the bDeviceClass, bDeviceSubClass and + * bDeviceProtocol fields of the device descriptor must contain the values + * 0xef, 0x02, and 0x01 respectively. */ #define ADC_DEVICE_CLASS USB_CLASS_MISC @@ -470,22 +472,23 @@ /* Encoder Error Codes */ - /* <0: Reserved for vendor extensions */ -#define ADC_ENCODER_SUCCESS 0 /* No Error */ -#define ADC_ENCODER_ERROR_NOMEM 1 /* Out of Memory */ -#define ADC_ENCODER_ERROR_BW 2 /* Out of Bandwidth */ -#define ADC_ENCODER_ERROR_CYCLE 3 /* Out of Processing Cycles */ -#define ADC_ENCODER_ERROR_FRAME 4 /* General Format Frame Error */ -#define ADC_ENCODER_ERROR_TOOSMALL 5 /* Format Frame Too Small */ -#define ADC_ENCODER_ERROR_TOOBIG 6 /* Format Frame Too Large */ -#define ADC_ENCODER_ERROR_BADFORMAT 7 /* Bad Data Format */ -#define ADC_ENCODER_ERROR_NCHAN 8 /* Incorrect Number of Channels */ -#define ADC_ENCODER_ERROR_RATE 9 /* Incorrect Sampling Rate */ -#define ADC_ENCODER_ERROR_BITRATE 10 /* Unable to Meet Target Bitrate */ -#define ADC_ENCODER_ERROR_PARMS 11 /* Inconsistent Set of Parameters */ -#define ADC_ENCODER_ERROR_NOTREADY 12 /* Not Ready */ -#define ADC_ENCODER_ERROR_BUSY 13 /* Busy */ - /* >13: Reserved */ + /* <0: Reserved for vendor extensions */ + +#define ADC_ENCODER_SUCCESS 0 /* No Error */ +#define ADC_ENCODER_ERROR_NOMEM 1 /* Out of Memory */ +#define ADC_ENCODER_ERROR_BW 2 /* Out of Bandwidth */ +#define ADC_ENCODER_ERROR_CYCLE 3 /* Out of Processing Cycles */ +#define ADC_ENCODER_ERROR_FRAME 4 /* General Format Frame Error */ +#define ADC_ENCODER_ERROR_TOOSMALL 5 /* Format Frame Too Small */ +#define ADC_ENCODER_ERROR_TOOBIG 6 /* Format Frame Too Large */ +#define ADC_ENCODER_ERROR_BADFORMAT 7 /* Bad Data Format */ +#define ADC_ENCODER_ERROR_NCHAN 8 /* Incorrect Number of Channels */ +#define ADC_ENCODER_ERROR_RATE 9 /* Incorrect Sampling Rate */ +#define ADC_ENCODER_ERROR_BITRATE 10 /* Unable to Meet Target Bitrate */ +#define ADC_ENCODER_ERROR_PARMS 11 /* Inconsistent Set of Parameters */ +#define ADC_ENCODER_ERROR_NOTREADY 12 /* Not Ready */ +#define ADC_ENCODER_ERROR_BUSY 13 /* Busy */ + /* >13: Reserved */ /* Format Type Codes */ @@ -517,7 +520,6 @@ /* Audio Data Format Type III Bit Allocations */ - #define ADC_FORMAT_TYPEIII_IEC61937_AC3 (1 << 0) #define ADC_FORMAT_TYPEIII_IEC61937_MPEG1_L1 (1 << 1) #define ADC_FORMAT_TYPEIII_IEC61937_MPEG1_L2_3 (1 << 1) @@ -649,9 +651,10 @@ #define ADC_EMBEDTERM_PERCUSSON 0x0716 /* Percussion Instrument */ #define ADC_EMBEDTERM_INSTRUMENT 0x0717 /* Other Musical Instrument */ -/******************************************************************************************** +/**************************************************************************** * Public Types - ********************************************************************************************/ + ****************************************************************************/ + /* Audio Channel Cluster Descriptor */ struct adc_cluster_desc_s @@ -666,7 +669,7 @@ struct adc_cluster_desc_s struct adc_ac_ifdesc_s { - uint8_t ac_len; /* 0: Descriptor length (9)*/ + uint8_t ac_len; /* 0: Descriptor length (9) */ uint8_t ac_type; /* 1: Descriptor type (ADC_CS_INTERFACE) */ uint8_t ac_subtype; /* 2: Descriptor sub-type (ADC_AC_HEADER) */ uint8_t ac_adc[2]; /* 3: ADC spec version in BCD */ @@ -680,7 +683,7 @@ struct adc_ac_ifdesc_s struct adc_clksrc_desc_s { - uint8_t cs_len; /* 0: Descriptor length (8)*/ + uint8_t cs_len; /* 0: Descriptor length (8) */ uint8_t cs_type; /* 1: Descriptor type (ADC_CS_INTERFACE) */ uint8_t cs_subtype; /* 2: Descriptor sub-type (ADC_AC_CLOCK_SOURCE) */ uint8_t cs_clockid; /* 3: Identifies clock source entity */ @@ -695,7 +698,7 @@ struct adc_clksrc_desc_s struct adc_clksel_desc_s { - uint8_t cl_len; /* 0: Descriptor length (7+npins)*/ + uint8_t cl_len; /* 0: Descriptor length (7+npins) */ uint8_t cl_type; /* 1: Descriptor type (ADC_CS_INTERFACE) */ uint8_t cl_subtype; /* 2: Descriptor sub-type (ADC_AC_CLOCK_SELECTOR) */ uint8_t cl_clockid; /* 3: Identifies clock source entity */ @@ -723,7 +726,7 @@ struct adc_clkmult_desc_s uint8_t cm_clockid; /* 3: Identifies clock source entity */ uint8_t cm_csrcid; /* 4: ID of clock input to list pin n */ uint8_t cm_controls; /* 5: Bits 0-1: Clock numerator control, - * Bits 2-3: Clock denominator control */ + * Bits 2-3: Clock denominator control */ uint8_t cm_clkmult; /* 6: Index of clock multiplier name string */ }; #define USB_SIZEOF_ADC_CLKMULT_DESC 7 @@ -779,7 +782,7 @@ struct adc_outterm_desc_s struct adc_mixerunit_desc_s { - uint8_t mu_len; /* 0: Descriptor length (13+npins+nchan)*/ + uint8_t mu_len; /* 0: Descriptor length (13+npins+nchan) */ uint8_t mu_type; /* 1: Descriptor type (ADC_CS_INTERFACE) */ uint8_t mu_subtype; /* 2: Descriptor sub-type (ADC_AC_MIXER_UNIT) */ uint8_t mu_unitid; /* 3: Identifies unit in audio function */ @@ -1105,7 +1108,7 @@ struct adc_extunit_desc_s struct adc_as_ifdesc_s { - uint8_t as_len; /* 0: Descriptor length (9)*/ + uint8_t as_len; /* 0: Descriptor length (9) */ uint8_t as_type; /* 1: Descriptor type (ADC_CS_INTERFACE) */ uint8_t as_subtype; /* 2: Descriptor sub-type (ADC_AS_GENERAL) */ uint8_t as_terminal; /* 3: ID of connected terminal */ @@ -1314,7 +1317,8 @@ struct adc_audio_epdesc_s struct adc_l1_curparm_s { - uint8_t l1_cur; /* 0: Setting of the CUR attribute of the addressed control */ + uint8_t l1_cur; /* 0: Setting of the CUR attribute of the + * addressed control */ }; #define USB_SIZEOF_ADC_LI_CURPARM 1 @@ -1323,15 +1327,15 @@ struct adc_l1_curparm_s begin_packed_struct struct adc_l1_subrange_s { - uint8_t l1_min; /* 0: MIN attribute */ - uint8_t l1_max; /* 1: MAX attribute */ - uint8_t l1_res; /* 2: RES attribute */ + uint8_t l1_min; /* 0: MIN attribute */ + uint8_t l1_max; /* 1: MAX attribute */ + uint8_t l1_res; /* 2: RES attribute */ } end_packed_struct; begin_packed_struct struct adc_l1_rangeparm_s { - uint8_t l1_nranges; /* 0: Number of sub-ranges */ - struct adc_l1_subrange_s l1_subrange[1]; + uint8_t l1_nranges; /* 0: Number of sub-ranges */ + struct adc_l1_subrange_s l1_subrange[1]; } end_packed_struct; #define USB_SIZEOF_ADC_LI_RANGEPARM(nranges) (1+3*(nranges)) @@ -1340,7 +1344,7 @@ begin_packed_struct struct adc_l1_rangeparm_s struct adc_l2_curparm_s { - uint8_t l2_cur[2]; /* 0: Setting of the CUR attribute of the addressed control */ + uint8_t l2_cur[2]; /* 0: Setting of the CUR attribute of the addressed control */ }; #define USB_SIZEOF_ADC_L2_CURPARM 2 @@ -1349,15 +1353,15 @@ struct adc_l2_curparm_s struct adc_l2_subrange_s { - uint8_t l2_min[2]; /* 0: MIN attribute */ - uint8_t l2_max[2]; /* 2: MAX attribute */ - uint8_t l2_res[2]; /* 4: RES attribute */ + uint8_t l2_min[2]; /* 0: MIN attribute */ + uint8_t l2_max[2]; /* 2: MAX attribute */ + uint8_t l2_res[2]; /* 4: RES attribute */ }; struct adc_l2_rangeparm_s { - uint8_t l2_nranges[2]; /* 0: Number of sub-ranges */ - struct adc_l2_subrange_s l2_subrange[1]; + uint8_t l2_nranges[2]; /* 0: Number of sub-ranges */ + struct adc_l2_subrange_s l2_subrange[1]; }; #define USB_SIZEOF_ADC_L2_RANGEPARM(nranges) (2+6*(nranges)) @@ -1366,7 +1370,7 @@ struct adc_l2_rangeparm_s struct adc_l3_curparm_s { - uint8_t l3_cur[4]; /* 0: Setting of the CUR attribute of the addressed control */ + uint8_t l3_cur[4]; /* 0: Setting of the CUR attribute of the addressed control */ }; #define USB_SIZEOF_ADC_L3_CURPARM 4 @@ -1375,15 +1379,15 @@ struct adc_l3_curparm_s struct adc_l3_subrange_s { - uint8_t l3_min[4]; /* 0: MIN attribute */ - uint8_t l3_max[4]; /* 2: MAX attribute */ - uint8_t l3_res[4]; /* 4: RES attribute */ + uint8_t l3_min[4]; /* 0: MIN attribute */ + uint8_t l3_max[4]; /* 2: MAX attribute */ + uint8_t l3_res[4]; /* 4: RES attribute */ }; struct adc_l3_rangeparm_s { - uint8_t l3_nranges[2]; /* 0: Number of sub-ranges */ - struct adc_l3_subrange_s l3_subrange[1]; + uint8_t l3_nranges[2]; /* 0: Number of sub-ranges */ + struct adc_l3_subrange_s l3_subrange[1]; }; #define USB_SIZEOF_ADC_L3_RANGEPARM(nranges) (2+12*(nranges)) @@ -1424,15 +1428,15 @@ struct adc_equalizer_curparm_s begin_packed_struct struct adc_eq_subrange_s { - uint8_t eq_min; /* 0: MIN attribute */ - uint8_t eq_max; /* 1: MAX attribute */ - uint8_t eq_res; /* 2: RES attribute */ + uint8_t eq_min; /* 0: MIN attribute */ + uint8_t eq_max; /* 1: MAX attribute */ + uint8_t eq_res; /* 2: RES attribute */ } end_packed_struct; begin_packed_struct struct adc_equalizer_rangeparm_s { - uint8_t eq_nranges; /* 0: Number of sub-ranges */ - struct adc_eq_subrange_s eq_subrange[1]; + uint8_t eq_nranges; /* 0: Number of sub-ranges */ + struct adc_eq_subrange_s eq_subrange[1]; } end_packed_struct; #define USB_SIZEOF_ADC_EQUALIZER_RANGEPARM(nranges) (1+3*(nranges)) @@ -1451,23 +1455,23 @@ struct adc_altsettings_curparm_s struct adc_hilo_curparm_s { - uint8_t hl_lo; /* 0: CUR value of the low level scaling control */ - uint8_t hl_hi; /* 0: CUR value of the high level scaling control */ + uint8_t hl_lo; /* 0: CUR value of the low level scaling control */ + uint8_t hl_hi; /* 0: CUR value of the high level scaling control */ }; /* High/Low Scaling Control RANGE Parameter Block */ begin_packed_struct struct adc_hl_subrange_s { - uint8_t hl_min; /* 0: MIN attribute */ - uint8_t hl_max; /* 1: MAX attribute */ - uint8_t hl_res; /* 2: RES attribute */ + uint8_t hl_min; /* 0: MIN attribute */ + uint8_t hl_max; /* 1: MAX attribute */ + uint8_t hl_res; /* 2: RES attribute */ } end_packed_struct; begin_packed_struct struct adc_hilo_rangeparm_s { - uint8_t hl_nranges[2]; /* 0: Number of sub-ranges */ - struct adc_hl_subrange_s hl_subrange[1]; + uint8_t hl_nranges[2]; /* 0: Number of sub-ranges */ + struct adc_hl_subrange_s hl_subrange[1]; } end_packed_struct; #define USB_SIZEOF_ADC_HILO_RANGEPARM(nranges) (2+3*(nranges)) @@ -1510,7 +1514,7 @@ struct adc_t2_format_desc_s uint8_t t2_subtype; /* 2: Descriptor sub-type (ADC_AS_FORMAT_TYPE) */ uint8_t t2_fmttype; /* 3: Identifies the format type (ADC_FORMAT_TYPEII) */ uint8_t t2_bitrate[2]; /* 4 Maximum number of bits per second */ - uint8_t t2_slotsperframe[2]; /* 6: Number of PCM audio slots in one encoded audio frame*/ + uint8_t t2_slotsperframe[2]; /* 6: Number of PCM audio slots in one encoded audio frame */ }; #define USB_SIZEOF_ADC_T2_FORMAT_DESC 8 @@ -1567,7 +1571,7 @@ struct adc_x2_format_desc_s uint8_t x2_subtype; /* 2: Descriptor sub-type (ADC_AS_FORMAT_TYPE) */ uint8_t x2_fmttype; /* 3: Identifies the format type (ADC_FORMAT_TYPEII) */ uint8_t x2_bitrate[2]; /* 4 Maximum number of bits per second */ - uint8_t x2_samperframe[2]; /* 6: Number of PCM audio samples in one encoded audio frame*/ + uint8_t x2_samperframe[2]; /* 6: Number of PCM audio samples in one encoded audio frame */ uint8_t x2_hdrlen; /* 8: Size of packet header (in bytes) */ uint8_t x2_sbproto; /* 9: Sideband protocol used in packet header and ctrl channel */ }; @@ -1590,7 +1594,7 @@ struct adc_x3_format_desc_s #define USB_SIZEOF_ADC_X3_FORMAT_DESC 8 -/* Hi-Res Presentation TimeStamp Layout*/ +/* Hi-Res Presentation TimeStamp Layout */ struct adc_hires_timestamp_s { @@ -1598,9 +1602,9 @@ struct adc_hires_timestamp_s uint8_t hr_nsec[8]; /* Offset in nanoseconds from the beginning of the stream */ }; -/******************************************************************************************** +/**************************************************************************** * Public Function Prototypes - ********************************************************************************************/ + ****************************************************************************/ #undef EXTERN #if defined(__cplusplus) diff --git a/include/nuttx/usb/cdcecm.h b/include/nuttx/usb/cdcecm.h index e398fd556f..7c93bf4e1f 100644 --- a/include/nuttx/usb/cdcecm.h +++ b/include/nuttx/usb/cdcecm.h @@ -1,4 +1,4 @@ -/******************************************************************************* +/**************************************************************************** * include/nuttx/usb/cdcecm.h * * Copyright (C) 2018 Gregory Nutt. All rights reserved. @@ -31,14 +31,14 @@ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * - ******************************************************************************/ + ****************************************************************************/ #ifndef __INCLUDE_NUTTX_USB_CDCECM_H #define __INCLUDE_NUTTX_USB_CDCECM_H -/****************************************************************************** +/**************************************************************************** * Included Files - ******************************************************************************/ + ****************************************************************************/ #include @@ -54,9 +54,9 @@ #define CDCECM_EP_BULKIN_IDX (1) #define CDCECM_EP_BULKOUT_IDX (2) -/****************************************************************************** +/**************************************************************************** * Public Data - ******************************************************************************/ + ****************************************************************************/ #undef EXTERN #if defined(__cplusplus) @@ -67,16 +67,16 @@ extern "C" # define EXTERN extern #endif -/****************************************************************************** - * Public Functions - ******************************************************************************/ +/**************************************************************************** + * Public Functions Definitions + ****************************************************************************/ /**************************************************************************** * Name: cdcecm_initialize * * Description: - * Register CDC/ECM USB device interface. Register the corresponding network - * driver to NuttX and bring up the network. + * Register CDC/ECM USB device interface. Register the corresponding + * network driver to NuttX and bring up the network. * * Input Parameters: * minor - Device minor number. diff --git a/include/nuttx/usb/composite.h b/include/nuttx/usb/composite.h index ada53981c4..0ba2131db1 100644 --- a/include/nuttx/usb/composite.h +++ b/include/nuttx/usb/composite.h @@ -1,4 +1,4 @@ -/************************************************************************************ +/**************************************************************************** * include/nuttx/usb/composite.h * * Copyright (C) 2008-2011, 2015, 2017 Gregory Nutt. All rights reserved. @@ -50,6 +50,7 @@ ****************************************************************************/ /* Configuration ************************************************************/ + /* CONFIG_USBDEV_COMPOSITE * Enables USB composite device support */ @@ -83,7 +84,7 @@ extern "C" struct composite_devdesc_s; /**************************************************************************** - * Public Functions + * Public Functions Definitions ****************************************************************************/ /**************************************************************************** @@ -120,7 +121,8 @@ FAR void *composite_initialize(uint8_t ndevices, * class objects for each of the members of the composite. * * Input Parameters: - * handle - The handle returned by a previous call to composite_initialize(). + * handle - The handle returned by a previous call to + * composite_initialize(). * * Returned Value: * None diff --git a/include/nuttx/usb/dfu.h b/include/nuttx/usb/dfu.h index b9c445daa0..e7c0eb6e7f 100644 --- a/include/nuttx/usb/dfu.h +++ b/include/nuttx/usb/dfu.h @@ -36,16 +36,16 @@ #ifndef __INCLUDE_NUTTX_USB_DFU_H #define __INCLUDE_NUTTX_USB_DFU_H -/************************************************************************************ +/**************************************************************************** * Included Files - ************************************************************************************/ + ****************************************************************************/ #include #include -/************************************************************************************ - * Public Functions - ************************************************************************************/ +/**************************************************************************** + * Public Functions Defintions + ****************************************************************************/ #undef EXTERN #if defined(__cplusplus) diff --git a/include/nuttx/usb/ehci.h b/include/nuttx/usb/ehci.h index c41240e47e..9b5531625a 100644 --- a/include/nuttx/usb/ehci.h +++ b/include/nuttx/usb/ehci.h @@ -1,12 +1,12 @@ -/******************************************************************************************** +/**************************************************************************** * include/nuttx/usb/ehci.h * * Copyright (C) 2013 Gregory Nutt. All rights reserved. * Author: Gregory Nutt * * References: - * "Enhanced Host Controller Interface Specification for Universal Serial - * Bus" Rev 1.0, March 12, 2002, Intel Corporation. + * "Enhanced Host Controller Interface Specification for Universal + * Serial Bus" Rev 1.0, March 12, 2002, Intel Corporation. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -35,23 +35,25 @@ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * - ********************************************************************************************/ + ****************************************************************************/ #ifndef __INCLUDE_NUTTX_USB_EHCI_H #define __INCLUDE_NUTTX_USB_EHCI_H -/******************************************************************************************** +/**************************************************************************** * Included Files - ********************************************************************************************/ + ****************************************************************************/ #include -/******************************************************************************************** +/**************************************************************************** * Pre-processor Definitions - ********************************************************************************************/ -/* General definitions **********************************************************************/ -/* Endpoint speed values as used in endpoint characteristics field. NOTE: These values - * are *NOT* the same as the SPEED definitions in usb.h. + ****************************************************************************/ + +/* General definitions ******************************************************/ + +/* Endpoint speed values as used in endpoint characteristics field. + * NOTE: These values are *NOT* the same as the SPEED definitions in usb.h. */ #define EHCI_FULL_SPEED (0) /* Full-Speed (12Mbs) */ @@ -61,7 +63,8 @@ #define EHCI_DIR_IN (1) /* Direction IN: Peripheral to host */ #define EHCI_DIR_OUT (0) /* Direction OUT: Host to peripheral */ -/* PCI Configuration Space Register Offsets *************************************************/ +/* PCI Configuration Space Register Offsets *********************************/ + /* Paragraph 2.1 */ /* 0x0009-0x000b: Class Code */ @@ -94,7 +97,8 @@ #define EHCI_PCI_USBLEGCTLSTS_OFFSET 0x0004 -/* Host Controller Capability Register Offsets **********************************************/ +/* Host Controller Capability Register Offsets ******************************/ + /* Paragraph 2.2 */ #define EHCI_CAPLENGTH_OFFSET 0x0000 /* Core Capability Register Length */ @@ -104,7 +108,8 @@ #define EHCI_HCCPARAMS_OFFSET 0x0008 /* Core Capability Parameters */ #define EHCI_HCSP_PORTROUTE_OFFSET 0x000c /* Core Companion Port Route Description */ -/* Host Controller Operational Register Offsets *********************************************/ +/* Host Controller Operational Register Offsets *****************************/ + /* Paragraph 2.3 */ #define EHCI_USBCMD_OFFSET 0x0000 /* USB Command */ @@ -136,7 +141,8 @@ #define EHCI_PORTSC14_OFFSET 0x0078 /* Port Status/Control, Port 14 */ #define EHCI_PORTSC15_OFFSET 0x007c /* Port Status/Control, Port 15 */ -/* Debug Register Offsets *******************************************************************/ +/* Debug Register Offsets ***************************************************/ + /* Paragraph C.3 */ #define EHCI_DEBUG_PCS_OFFSET 0x0000 /* Debug Port Control/Status Register */ @@ -145,7 +151,7 @@ #define EHCI_DEBUG_DATA1_OFFSET 0x000c /* Debug Data Buffer 1 Register [63:32] */ #define EHCI_DEBUG_DEVADDR_OFFSET 0x0010 /* Debug Device Address Register */ -/* PCI Configuration Space Register Bit Definitions *****************************************/ +/* PCI Configuration Space Register Bit Definitions *************************/ /* 0x0009-0x000b: Class Code. Paragraph 2.1.2 */ @@ -163,11 +169,14 @@ /* 0x0010-0x0013: Base Address to Memory-mapped Host Controller Register * Space. Paragraph 2.1.3 */ + /* Bit 0: Reserved */ + #define EHCI_PCIUSBBASE_TYPE_SHIFT (0) /* Bits 1-2: Type */ #define EHCI_PCIUSBBASE_TYPE_MASK (3 << EHCI_PCIUSBBASE_TYPE_SHIFT) # define EHCI_PCIUSBBASE_TYPE_32BIT (3 << EHCI_PCIUSBBASE_TYPE_SHIFT) /* 32-bit addressing */ # define EHCI_PCIUSBBASE_TYPE_64BIT (3 << EHCI_PCIUSBBASE_TYPE_SHIFT) /* 64-bit addressing */ + /* Bits 3-7: Reserved */ #define EHCI_PCIUSBBASE_BASE_SHIFT (8) /* Bits 8-31: Base address */ #define EHCI_PCIUSBBASE_BASE_MASK (0xffffff00) @@ -182,11 +191,15 @@ #define EHCI_PCI_FLADJ_MASK (0x3f >> EHCI_PCI_FLADJ_SHIFT) /* Bits 6-7: Reserved */ -/* 0x0062-0x0063: Port wake capabilities register (OPTIONAL). Paragraph 2.1.6 */ +/* 0x0062-0x0063: Port wake capabilities register (OPTIONAL). + * Paragraph 2.1.6 + */ #define EHCI_PCI_PORTWAKECAP_MASK (0xffff) -/* EECP+0x0000: USB Legacy Support EHCI Extended Capability Register. Paragraph 2.1.7 */ +/* EECP+0x0000: USB Legacy Support EHCI Extended Capability Register. + * Paragraph 2.1.7 + */ #define EHCI_PCI_USBLEGSUP_CAPID_SHIFT (0) /* Bits 0-7 Capability ID */ #define EHCI_PCI_USBLEGSUP_CAPID_MASK (0xff << EHCI_PCI_USBLEGSUP_CAPID_SHIFT) @@ -197,7 +210,9 @@ #define EHCI_PCI_USBLEGSUP_OSOWN (1 << 24) /* Bit 24: HC OS Owned Semaphore */ /* Bits 25-31: Reserved */ -/* EECP+0x0000: USB Legacy Support Control and Status Register. Paragraph 2.1.8 */ +/* EECP+0x0000: USB Legacy Support Control and Status Register. + * Paragraph 2.1.8 + */ #define EHCI_PCI_USBLEGCTLSTS_USBCMPEN (1 << 0) /* Bit 0: USB SMI Enable */ #define EHCI_PCI_USBLEGCTLSTS_USBERREN (1 << 1) /* Bit 1: SMI on USB Error Enable */ @@ -220,11 +235,14 @@ #define EHCI_PCI_USBLEGCTLSTS_PC (1 << 30) /* Bit 30: SMI on PCI Command */ #define EHCI_PCI_USBLEGCTLSTS_BAR (1 << 31) /* Bit 31: SMI on BAR */ -/* Host Controller Capability Register Bit Definitions ***************************************/ +/* Host Controller Capability Register Bit Definitions **********************/ + /* Paragraph 2.2 */ /* Core Capability Register Length. Paragraph 2.2.1. 8-bit length. */ + /* Core Interface Version Number. Paragraph 2.2.2. Two byte BCD encoding */ + /* Core Structural Parameters. Paragraph 2.2.3 */ #define EHCI_HCSPARAMS_NPORTS_SHIFT (0) /* Bit 0-3: Number of physical downstream ports */ @@ -254,9 +272,12 @@ #define EHCI_HCCPARAMS_EECP_MASK (0xff << EHCI_HCCPARAMS_EECP_SHIFT) /* Bits 16-31: Reserved */ -/* Core Companion Port Route Description. Paragraph 2.2.5. 15 x 4-bit array (60 bits) */ +/* Core Companion Port Route Description. + * Paragraph 2.2.5. 15 x 4-bit array (60 bits) + */ + +/* Host Controller Operational Register Bit Definitions *********************/ -/* Host Controller Operational Register Bit Definitions *************************************/ /* Paragraph 2.3 */ /* USB Command. Paragraph 2.3.1 */ @@ -268,6 +289,7 @@ # define EHCI_USBCMD_FLSIZE_1024 (0 << EHCI_USBCMD_FLSIZE_SHIFT) /* 1024 elements (4096 bytes) */ # define EHCI_USBCMD_FLSIZE_512 (1 << EHCI_USBCMD_FLSIZE_SHIFT) /* 512 elements (2048 bytes) */ # define EHCI_USBCMD_FLSIZE_256 (2 << EHCI_USBCMD_FLSIZE_SHIFT) /* 256 elements (1024 bytes) */ + #define EHCI_USBCMD_PSEN (1 << 4) /* Bit 4: Periodic Schedule Enable */ #define EHCI_USBCMD_ASEN (1 << 5) /* Bit 5: Asynchronous Schedule Enable */ #define EHCI_USBCMD_IAADB (1 << 6) /* Bit 6: Interrupt on Async Advance Doorbell */ @@ -286,9 +308,11 @@ # define EHCI_USBCMD_ITHRE_16MF (0x10 << EHCI_USBCMD_ITHRE_SHIFT) /* 16 micro-frames (2 ms) */ # define EHCI_USBCMD_ITHRE_32MF (0x20 << EHCI_USBCMD_ITHRE_SHIFT) /* 32 micro-frames (4 ms) */ # define EHCI_USBCMD_ITHRE_64MF (0x40 << EHCI_USBCMD_ITHRE_SHIFT) /* 64 micro-frames (8 ms) */ + /* Bits 24-31: Reserved */ /* USB Status. Paragraph 2.3.2 */ + /* USB Interrupt Enable. Paragraph 2.3.3 */ #define EHCI_INT_USBINT (1 << 0) /* Bit 0: USB Interrupt */ @@ -310,7 +334,10 @@ #define EHCI_FRINDEX_MASK (0x1fff) /* Bits 0-13: Frame index */ /* Bits 14-31: Reserved */ -/* 4G Segment Selector. Paragraph 2.3.5, Bits[64:32] of data structure addresses */ +/* 4G Segment Selector. + * Paragraph 2.3.5, Bits[64:32] of data structure addresses + */ + /* Frame List Base Address. Paragraph 2.3.6 */ /* Bits 0-11: Reserved */ @@ -323,8 +350,8 @@ /* Configured Flag Register. Paragraph 2.3.8 */ -#define EHCI_CONFIGFLAG (1 << 0) /* Bit 0: Configure Flag */ - /* Bits 1-31: Reserved */ +#define EHCI_CONFIGFLAG (1 << 0) /* Bit 0: Configure Flag */ + /* Bits 1-31: Reserved */ /* Port Status/Control, Port 1-n. Paragraph 2.3.9 */ @@ -343,6 +370,7 @@ # define EHCI_PORTSC_LSTATUS_SE0 (0 << EHCI_PORTSC_LSTATUS_SHIFT) /* SE0 Not Low-speed device, perform EHCI reset */ # define EHCI_PORTSC_LSTATUS_KSTATE (1 << EHCI_PORTSC_LSTATUS_SHIFT) /* K-state Low-speed device, release ownership of port */ # define EHCI_PORTSC_LSTATUS_JSTATE (2 << EHCI_PORTSC_LSTATUS_SHIFT) /* J-state Not Low-speed device, perform EHCI reset */ + #define EHCI_PORTSC_PP (1 << 12) /* Bit 12: Port Power */ #define EHCI_PORTSC_OWNER (1 << 13) /* Bit 13: Port Owner */ #define EHCI_PORTSC_PIC_SHIFT (14) /* Bits 14-15: Port Indicator Control */ @@ -350,6 +378,7 @@ # define EHCI_PORTSC_PIC_OFF (0 << EHCI_PORTSC_PIC_SHIFT) /* Port indicators are off */ # define EHCI_PORTSC_PIC_AMBER (1 << EHCI_PORTSC_PIC_SHIFT) /* Amber */ # define EHCI_PORTSC_PIC_GREEN (2 << EHCI_PORTSC_PIC_SHIFT) /* Green */ + #define EHCI_PORTSC_PTC_SHIFT (16) /* Bits 16-19: Port Test Control */ #define EHCI_PORTSC_PTC_MASK (15 << EHCI_PORTSC_PTC_SHIFT) # define EHCI_PORTSC_PTC_DISABLED (0 << EHCI_PORTSC_PTC_SHIFT) /* Test mode not enabled */ @@ -358,6 +387,7 @@ # define EHCI_PORTSC_PTC_SE0NAK (3 << EHCI_PORTSC_PTC_SHIFT) /* Test SE0_NAK */ # define EHCI_PORTSC_PTC_PACKET (4 << EHCI_PORTSC_PTC_SHIFT) /* Test Packet */ # define EHCI_PORTSC_PTC_ENABLE (5 << EHCI_PORTSC_PTC_SHIFT) /* Test FORCE_ENABLE */ + #define EHCI_PORTSC_WKCCNTE (1 << 20) /* Bit 20: Wake on Connect Enable */ #define EHCI_PORTSC_WKDSCNNTE (1 << 21) /* Bit 21: Wake on Disconnect Enable */ #define EHCI_PORTSC_WKOCE (1 << 22) /* Bit 22: Wake on Over-current Enable */ @@ -366,7 +396,7 @@ #define EHCI_PORTSC_ALLINTS (EHCI_PORTSC_CSC | EHCI_PORTSC_PEC | \ EHCI_PORTSC_OCC | EHCI_PORTSC_RESUME) -/* Debug Register Bit Definitions ***********************************************************/ +/* Debug Register Bit Definitions *******************************************/ /* Debug Port Control/Status Register. Paragraph C.3.1 */ @@ -396,7 +426,9 @@ #define EHCI_DEBUG_USBPIDS_RPID_MASK (0xff << EHCI_DEBUG_USBPIDS_RPID_SHIFT) /* Bits 24-31: Reserved */ -/* Debug Data Buffer 0/1 Register [64:0]. Paragreph C.3.3. 64 bits of data. */ +/* Debug Data Buffer 0/1 Register [64:0]. + * Paragreph C.3.3. 64 bits of data. + */ /* Debug Device Address Register. Paragraph C.3.4 */ @@ -407,7 +439,8 @@ #define EHCI_DEBUG_DEVADDR_ADDR_MASK (0x7f << EHCI_DEBUG_DEVADDR_ADDR_SHIFT) /* Bits 15-31: Reserved */ -/* Data Structures **************************************************************************/ +/* Data Structures **********************************************************/ + /* Paragraph 3 */ /* Periodic Frame List. Paragraph 3.1 */ @@ -419,12 +452,16 @@ # define PFL_TYP_QH (1 << PFL_TYP_SHIFT) /* Queue Head */ # define PFL_TYP_SITD (2 << PFL_TYP_SHIFT) /* Split Transaction Isochronous Transfer Descriptor */ # define PFL_TYP_FSTN (3 << PFL_TYP_SHIFT) /* Frame Span Traversal Node */ - /* Bits 3-4: zero */ + + /* Bits 3-4: zero */ #define PFL_MASK (0xffffffe0) /* Bits 5-31: Frame List Link Pointer */ -/* Aysnchronous List Queue Head Pointer. Paragraph 3.2. Circular list of queue heads */ +/* Aysnchronous List Queue Head Pointer. + * Paragraph 3.2. Circular list of queue heads + */ /* Isochronous (High-Speed) Transfer Descriptor (iTD). Paragraph 3.3 */ + /* iTD Next Link Pointer. Paragraph 3.3.1 */ #define ITD_NLP_T (1 << 0) /* Bit 0: Terminate, Link pointer invalid */ @@ -434,7 +471,8 @@ # define ITD_NLP_TYP_QH (1 << ITD_NLP_TYP_SHIFT) /* Queue Head */ # define ITD_NLP_TYP_SITD (2 << ITD_NLP_TYP_SHIFT) /* Split Transaction Isochronous Transfer Descriptor */ # define ITD_NLP_TYP_FSTN (3 << ITD_NLP_TYP_SHIFT) /* Frame Span Traversal Node */ - /* Bits 3-4: zero */ + + /* Bits 3-4: zero */ #define ITD_NLP_MASK (0xffffffe0) /* Bits 5-31: Frame List Link Pointer */ /* iTD Transaction Status and Control List. Paragraph 3.3.2 */ @@ -454,6 +492,7 @@ # define ITD_TRAN_STATUS_ACTIVE (1 << 31) /* Bit 28: Transaction error */ /* iTD Buffer Page Pointer List. Paragraph 3.3.4 */ + /* iTD Buffer Pointer Page 0. Table 3-4 */ #define ITD_BUFPTR0_DEVADDR_SHIFT (0) /* Bits 0-6: Device Address */ @@ -476,14 +515,21 @@ # define ITD_BUFPTR2_MULTI_1 (1 << ITD_BUFPTR2_MULTI_SHIFT) /* One transaction per micro-frame */ # define ITD_BUFPTR2_MULTI_2 (2 << ITD_BUFPTR2_MULTI_SHIFT) /* Two transactions per micro-frame */ # define ITD_BUFPTR2_MULTI_3 (3 << ITD_BUFPTR2_MULTI_SHIFT) /* Three transactions per micro-frame */ + /* Bits 2-11: Reserved */ + /* iTD Buffer Pointer Page 3-6. Table 3-7 */ + /* Bits 0-11: Reserved */ + /* iTD Buffer Pointer All Pages */ #define ITD_BUFPTR_MASK (0xfffff000) /* Bits 12-31: Buffer Pointer */ -/* Split Transaction Isochronous Transfer Descriptor (siTD). Paragraph 3.4 */ +/* Split Transaction Isochronous Transfer Descriptor (siTD). + * Paragraph 3.4 + */ + /* siTD Next Link Pointer. Paragraph 3.4.1 */ #define SITD_NLP_T (1 << 0) /* Bit 0: Terminate, Link pointer invalid */ @@ -493,10 +539,14 @@ # define SITD_NLP_TYP_QH (1 << SITD_NLP_TYP_SHIFT) /* Queue Head */ # define SITD_NLP_TYP_SITD (2 << SITD_NLP_TYP_SHIFT) /* Split Transaction Isochronous Transfer Descriptor */ # define SITD_NLP_TYP_FSTN (3 << SITD_NLP_TYP_SHIFT) /* Frame Span Traversal Node */ - /* Bits 3-4: zero */ + + /* Bits 3-4: zero */ #define SITD_NLP_MASK (0xffffffe0) /* Bits 5-31: Frame List Link Pointer */ -/* siTD Endpoint Capabilities/Characteristics. Paragraph 3.4.2 */ +/* siTD Endpoint Capabilities/Characteristics. + * Paragraph 3.4.2 + */ + /* Endpoint and Transaction Translator Characteristics. Table 3-9 */ #define SITD_EPCHAR_DEVADDR_SHIFT (0) /* Bitx 0-6: Device Address */ @@ -520,6 +570,7 @@ #define SITD_FMSCHED_SCMASK_MASK (0xff << SITD_FMSCHED_SCMASK_SHIFT) # define SITD_FMSCHED_SCMASK(n) ((n) << SITD_FMSCHED_SCMASK_SHIFT) /* Bits 16-31: Reserved */ + /* siTD Transfer State. Paragraph 3.4.3 */ #define SITD_XFRSTATE_STATUS_SHIFT (0) /* Bits 0-7: Status */ @@ -532,7 +583,10 @@ #define SITD_XFRSTATE_P (1 << 30) /* Bit 30: Page Select */ #define SITD_XFRSTATE_IOC (1 << 31) /* Bit 31: Interrupt On Complete */ -/* siTD Buffer Pointer List. Paragraph 3.4.4 */ +/* siTD Buffer Pointer List. + * Paragraph 3.4.4 + */ + /* Page 0 */ #define SITD_BUFPTR0_OFFSET_SHIFT (0) /* Bits 0-11: Current Offset */ @@ -548,27 +602,38 @@ # define SITD_BUFPTR1_TP_BEGIN (1 << SITD_BUFPTR1_TP_SHIFT) /* This is the first data payload */ # define SITD_BUFPTR1_TP_MID (2 << SITD_BUFPTR1_TP_SHIFT) /* This the middle payload */ # define SITD_BUFPTR1_TP_END (3 << SITD_BUFPTR1_TP_SHIFT) /* This is the last payload */ + /* Bits 5-11: Reserved */ + /* All pages */ #define SITD_BUFPTR_MASK (0xfffff000) /* Bits 12-31: Buffer Pointer List */ -/* Queue Element Transfer Descriptor (qTD). Paragraph 3.5 */ -/* Next qTD Pointer. Paragraph 3.5.1 */ +/* Queue Element Transfer Descriptor (qTD). + * Paragraph 3.5 + */ + +/* Next qTD Pointer. + * Paragraph 3.5.1 + */ #define QTD_NQP_T (1 << 0) /* Bit 0: Terminate */ /* Bits 1-4: Reserved */ #define QTD_NQP_NTEP_SHIFT (5) /* Bits 5-31: Next Transfer Element Pointer */ #define QTD_NQP_NTEP_MASK (0xffffffe0) -/* Alternate Next qTD Pointer. Paragraph 3.5.2 */ +/* Alternate Next qTD Pointer. + * Paragraph 3.5.2 + */ #define QTD_AQP_T (1 << 0) /* Bit 0: Terminate */ /* Bits 1-4: Reserved */ #define QTD_AQP_NTEP_SHIFT (5) /* Bits 5-31: Next Transfer Element Pointer */ #define QTD_AQP_NTEP_MASK (0xffffffe0) -/* qTD Token. Paragraph 3.5.3 */ +/* qTD Token. + * Paragraph 3.5.3 + */ #define QTD_TOKEN_STATUS_SHIFT (0) /* Bits 0-7: Status */ #define QTD_TOKEN_STATUS_MASK (0xff << QTD_TOKEN_STATUS_SHIFT) @@ -587,6 +652,7 @@ # define QTD_TOKEN_PID_OUT (0 << QTD_TOKEN_PID_SHIFT) /* OUT Token generates token (E1H) */ # define QTD_TOKEN_PID_IN (1 << QTD_TOKEN_PID_SHIFT) /* IN Token generates token (69H) */ # define QTD_TOKEN_PID_SETUP (2 << QTD_TOKEN_PID_SHIFT) /* SETUP Token generates token (2DH) */ + #define QTD_TOKEN_CERR_SHIFT (10) /* Bits 10-11: Error Counter */ #define QTD_TOKEN_CERR_MASK (3 << QTD_TOKEN_CERR_SHIFT) #define QTD_TOKEN_CPAGE_SHIFT (12) /* Bits 12-14: Current Page */ @@ -597,21 +663,29 @@ #define QTD_TOKEN_TOGGLE_SHIFT (31) /* Bit 31: Data Toggle */ #define QTD_TOKEN_TOGGLE (1 << 31) /* Bit 31: Data Toggle */ -/* qTD Buffer Page Pointer List. Paragraph 3.5.4 */ +/* qTD Buffer Page Pointer List. + * Paragraph 3.5.4 + */ + /* Page 0 */ #define QTD_BUFPTR0_OFFFSET_SHIFT (0) /* Bits 0-11: Current Offset */ #define QTD_BUFPTR0_OFFFSET_MASK (0xfff << QTD_BUFPTR0_OFFFSET_SHIFT) /* Other pages */ + /* Bits 0-11: Reserved */ + /* All pages */ #define QTD_BUFPTR_SHIFT (12) /* Bits 12-31: Buffer Pointer List */ #define QTD_BUFPTR_MASK (0xfffff000) /* Queue Head. Paragraph 3.6 */ -/* Queue Head Horizontal Link Pointer. Paragraph 3.6.1 */ + +/* Queue Head Horizontal Link Pointer. + * Paragraph 3.6.1 + */ #define QH_HLP_T (1 << 0) /* Bit 0: Terminate, QH HL pointer invalid */ #define QH_HLP_TYP_SHIFT (1) /* Bits 1-2: Type */ @@ -620,10 +694,12 @@ # define QH_HLP_TYP_QH (1 << QH_HLP_TYP_SHIFT) /* Queue Head */ # define QH_HLP_TYP_SITD (2 << QH_HLP_TYP_SHIFT) /* Split Transaction Isochronous Transfer Descriptor */ # define QH_HLP_TYP_FSTN (3 << QH_HLP_TYP_SHIFT) /* Frame Span Traversal Node */ - /* Bits 3-4: Reserved */ + + /* Bits 3-4: Reserved */ #define QH_HLP_MASK (0xffffffe0) /* Bits 5-31: Queue Head Horizontal Link Pointer */ /* Endpoint Capabilities/Characteristics. Paragraph 3.6.2 */ + /* Endpoint Characteristics: Queue Head DWord. Table 3-19 */ #define QH_EPCHAR_DEVADDR_SHIFT (0) /* Bitx 0-6: Device Address */ @@ -636,6 +712,7 @@ # define QH_EPCHAR_EPS_FULL (0 << QH_EPCHAR_EPS_SHIFT) /* Full-Speed (12Mbs) */ # define QH_EPCHAR_EPS_LOW (1 << QH_EPCHAR_EPS_SHIFT) /* Low-Speed (1.5Mbs) */ # define QH_EPCHAR_EPS_HIGH (2 << QH_EPCHAR_EPS_SHIFT) /* High-Speed (480 Mb/s) */ + #define QH_EPCHAR_DTC (1 << 14) /* Bit 14: Data Toggle Control */ #define QH_EPCHAR_H (1 << 15) /* Bit 15: Head of Reclamation List Flag */ #define QH_EPCHAR_MAXPKT_SHIFT (16) /* Bitx 16-26: Maximum Packet Length */ @@ -671,8 +748,8 @@ * * NOTES: * 1. Same as the field of the same name in struct ehci_qtd_s - * 2. Similar to the field of the same name in struct ehci_qtd_s, but with some - * additional bitfields. + * 2. Similar to the field of the same name in struct ehci_qtd_s, but with + * some additional bitfields. */ /* Next qTD Pointer (NOTE 1) */ @@ -708,6 +785,7 @@ # define QH_TOKEN_PID_OUT (0 << QH_TOKEN_PID_SHIFT) /* OUT Token generates token (E1H) */ # define QH_TOKEN_PID_IN (1 << QH_TOKEN_PID_SHIFT) /* IN Token generates token (69H) */ # define QH_TOKEN_PID_SETUP (2 << QH_TOKEN_PID_SHIFT) /* SETUP Token generates token (2DH) */ + #define QH_TOKEN_CERR_SHIFT (10) /* Bits 10-11: Error Counter */ #define QH_TOKEN_CERR_MASK (3 << QH_TOKEN_CERR_SHIFT) #define QH_TOKEN_CPAGE_SHIFT (12) /* Bits 12-14: Current Page */ @@ -718,7 +796,8 @@ #define QH_TOKEN_TOGGLE_SHIFT (31) /* Bit 31: Data Toggle */ #define QH_TOKEN_TOGGLE (1 << 31) /* Bit 31: Data Toggle */ -/* Buffer Page Pointer List (NOTE 2) +/* Buffer Page Pointer List (NOTE 2) */ + /* Page 0 */ #define QH_BUFPTR0_OFFFSET_SHIFT (0) /* Bits 0-11: Current Offset */ @@ -729,6 +808,7 @@ #define QH_BUFPTR1_CPROGMASK_SHIFT (0) /* Bits 0-7: Split-transaction Complete-split Progress */ #define QH_BUFPTR1_CPROGMASK_MASK (0xff << QH_BUFPTR1_CPROGMASK_SHIFT) /* Bits 8-11: Reserved */ + /* Page 2. Table 3.22 */ #define QH_BUFPTR2_FRAMETAG_SHIFT (0) /* Bits 0-4: Split-transaction Frame Tag */ @@ -737,13 +817,16 @@ #define QH_BUFPTR2_SBYTES_MASK (0x7f << QH_BUFPTR2_SBYTES_SHIFT) /* Other pages */ + /* Bits 0-11: Reserved */ + /* All pages */ #define QH_BUFPTR_SHIFT (12) /* Bits 12-31: Buffer Pointer List */ #define QH_BUFPTR_MASK (0xfffff000) /* Periodic Frame Span Traversal Node (STN). Paragrap 3.7 */ + /* FSTN Normal Path Pointer. Paragraph 3.7.1 */ #define FSTN_NPP_T (1 << 0) /* Bit 0: Terminate. 1=Link Pointer not valid */ @@ -753,6 +836,7 @@ # define FSTN_NPP_TYP_QH (1 << FSTN_NPP_TYP_SHIFT) /* Queue Head */ # define FSTN_NPP_TYP_SITD (2 << FSTN_NPP_TYP_SHIFT) /* Split Transaction Isochronous Transfer Descriptor */ # define FSTN_NPP_TYP_FSTN (3 << FSTN_NPP_TYP_SHIFT) /* Frame Span Traversal Node */ + /* Bits 3-4: Reserved */ #define FSTN_NPP_NPLP_SHIFT (5) /* Bits 5-31: Normal Path Link Pointer */ #define FSTN_NPP_NPLP_MASK (0xffffffe0) @@ -763,20 +847,24 @@ #define FSTN_BPP_TYP_SHIFT (1) /* Bits 1-2: Type */ #define FSTN_BPP_TYP_MASK (3 << FSTN_BPP_TYP_SHIFT) # define FSTN_BPP_TYP_QH (1 << FSTN_BPP_TYP_SHIFT) /* Queue Head */ + /* Bits 3-4: Reserved */ #define FSTN_BPP_BPLP_SHIFT (5) /* Bits 5-31: Back Path Link Pointer */ #define FSTN_BPP_BPLP_MASK (0xffffffe0) -/******************************************************************************************** +/**************************************************************************** * Public Types - ********************************************************************************************/ -/* Registers ********************************************************************************/ -/* Since the operational registers are not known a compile time, representing register blocks - * with structures is more convenient than using individual register offsets. + ****************************************************************************/ + +/* Registers ****************************************************************/ + +/* Since the operational registers are not known a compile time, representing + * register blocks with structures is more convenient than using individual + * register offsets. */ -/* Host Controller Capability Registers. This register block must be positioned at a well - * known address. +/* Host Controller Capability Registers. + * This register block must be positioned at a well known address. */ struct ehci_hccr_s @@ -789,8 +877,9 @@ struct ehci_hccr_s uint8_t hcspportrt[8]; /* 0x0c: Companion Port Route Description */ }; -/* Host Controller Operational Registers. This register block is positioned at an offset - * of 'caplength' from the beginning of the Host Controller Capability Registers. +/* Host Controller Operational Registers. + * This register block is positioned at an offset of 'caplength' from the + * beginning of the Host Controller Capability Registers. */ struct ehci_hcor_s @@ -807,9 +896,10 @@ struct ehci_hcor_s uint32_t portsc[15]; /* 0x44: Port Status/Control */ }; -/* USB2 Debug Port Register Interface. This register block is normally found via the PCI - * capabalities. In non-PCI implementions, you need apriori information about the location - * of these registers. +/* USB2 Debug Port Register Interface. + * This register block is normally found via the PCI capabalities. + * In non-PCI implementions, you need apriori information about the + * location of these registers. */ struct ehci_debug_s @@ -820,14 +910,20 @@ struct ehci_debug_s uint32_t addr; /* 0x10: Device Address Register */ }; -/* Data Structures **************************************************************************/ +/* Data Structures **********************************************************/ + /* Paragraph 3 */ -/* Periodic Frame List. Paragraph 3.1. An array of pointers. */ -/* Aysnchronous List Queue Head Pointer. Paragraph 3.2. Circular list of queue heads */ +/* Periodic Frame List. + * Paragraph 3.1. An array of pointers. + */ -/* Isochronous (High-Speed) Transfer Descriptor (iTD). Paragraph 3.3. Must be aligned to - * 32-byte boundaries. +/* Aysnchronous List Queue Head Pointer. + * Paragraph 3.2. Circular list of queue heads + */ + +/* Isochronous (High-Speed) Transfer Descriptor (iTD). + * Paragraph 3.3. Must be aligned to 32-byte boundaries. */ struct ehci_itd_s @@ -854,6 +950,7 @@ struct ehci_sitd_s #define SIZEOF_EHCI_SITD_S (28) /* 7*sizeof(uint32_t) */ /* Queue Element Transfer Descriptor (qTD). Paragraph 3.5 */ + /* 32-bit version. See EHCI Appendix B for the 64-bit version. */ struct ehci_qtd_s @@ -870,8 +967,8 @@ struct ehci_qtd_s * * NOTE: * 1. Same as the field of the same name in struct ehci_qtd_s - * 2. Similar to the field of the same name in struct ehci_qtd_s, but with some - * additional bitfields. + * 2. Similar to the field of the same name in struct ehci_qtd_s, + * but with some additional bitfields. */ struct ehci_overlay_s @@ -879,7 +976,7 @@ struct ehci_overlay_s uint32_t nqp; /* 0x00-0x03: Next qTD Pointer (NOTE 1) */ uint32_t alt; /* 0x04-0x07: Alternate Next qTD Pointer (NOTE 2) */ uint32_t token; /* 0x08-0x0b: qTD Token (NOTE 1) */ - uint32_t bpl[5]; /* 0x0c-0x1c: Buffer Page Pointer List (NOTE 2)*/ + uint32_t bpl[5]; /* 0x0c-0x1c: Buffer Page Pointer List (NOTE 2) */ }; #define SIZEOF_EHCI_OVERLAY (32) /* 8*sizeof(uint32_t) */ @@ -905,9 +1002,9 @@ struct ehci_fstn_s #define SIZEOF_EHCI_FSTN_S (8) /* 2*sizeof(uint32_t) */ -/******************************************************************************************** +/**************************************************************************** * Public Data - ********************************************************************************************/ + ****************************************************************************/ #ifdef __cplusplus #define EXTERN extern "C" @@ -917,9 +1014,9 @@ extern "C" #define EXTERN extern #endif -/******************************************************************************************** +/**************************************************************************** * Public Function Prototypes - ********************************************************************************************/ + ****************************************************************************/ #undef EXTERN #ifdef __cplusplus diff --git a/include/nuttx/usb/fusb301.h b/include/nuttx/usb/fusb301.h index 12ca8f4281..ea7868668c 100644 --- a/include/nuttx/usb/fusb301.h +++ b/include/nuttx/usb/fusb301.h @@ -37,6 +37,10 @@ #ifndef __INCLUDE_NUTTX_USB_FUSB301_H #define __INCLUDE_NUTTX_USB_FUSB301_H +/**************************************************************************** + * Included Files + ****************************************************************************/ + #include /**************************************************************************** @@ -223,8 +227,10 @@ struct fusb301_config_s * * Input Parameters: * devpath - The full path to the driver to register. E.g., "/dev/usbc0" - * i2c - An instance of the I2C interface to use to communicate with FUSB301 - * addr - The I2C address of the FUSB301. The I2C address of the FUSB301 is 0x25. + * i2c - An instance of the I2C interface to use to communicate with + * FUSB301 + * addr - The I2C address of the FUSB301. + * The I2C address of the FUSB301 is 0x25. * config - Pointer to FUSB301 configuration * * Returned Value: diff --git a/include/nuttx/usb/fusb303.h b/include/nuttx/usb/fusb303.h index d6d8fe889a..7b26b08f20 100644 --- a/include/nuttx/usb/fusb303.h +++ b/include/nuttx/usb/fusb303.h @@ -37,6 +37,10 @@ #ifndef __INCLUDE_NUTTX_USB_FUSB303_H #define __INCLUDE_NUTTX_USB_FUSB303_H +/**************************************************************************** + * Included Files + ****************************************************************************/ + #include /**************************************************************************** @@ -115,6 +119,7 @@ enum fusb303_mode_e MODE_TRY_SNK = (1 << 4), /* For DRP only */ MODE_TRY_SRC = (1 << 5), /* For DRP only */ MODE_ORIENTDEB = (1 << 6), + /* Bit 7 reserved */ }; @@ -169,6 +174,7 @@ enum fusb303_manual_e MANUAL_UNATT_SNK = (1 << 3), MANUAL_FORCE_SNK = (1 << 4), MANUAL_FORCE_SRC = (1 << 5), + /* Bits 6:7 reserved */ }; @@ -190,6 +196,7 @@ enum fusb303_int_mask_e INT_MASK_VBUS_CHG = (1 << 4), INT_MASK_FAULT = (1 << 5), INT_MASK_ORIENT = (1 << 6), + /* Bit 7 reserved */ }; @@ -200,10 +207,13 @@ enum fusb303_int_mask1_e INT_MASK1_REMEDY = (1 << 0), INT_MASK1_FRC_SUCC = (1 << 1), INT_MASK1_FRC_FAIL = (1 << 2), + /* Bit 4 reserved */ + INT_MASK1_REM_FAIL = (1 << 3), INT_MASK1_REM_VBON = (1 << 5), INT_MASK1_REM_VBOFF = (1 << 6), + /* Bit 7 reserved */ }; @@ -244,6 +254,7 @@ enum fusb303_type_e TYPE_SINK = (1 << 4), TYPE_DEBUGSNK = (1 << 5), TYPE_DEBUGSRC = (1 << 6), + /* Bit 7 reserved */ }; @@ -258,6 +269,7 @@ enum fusb303_interrupt_e INTERRUPT_VBUS_CHG = (1 << 4), INTERRUPT_FAULT = (1 << 5), INTERRUPT_ORIENT = (1 << 6), + /* Bit 7 reserved */ }; @@ -269,9 +281,12 @@ enum fusb303_interrupt1_e INTERRUPT1_FRC_SUCC = (1 << 1), INTERRUPT1_FRC_FAIL = (1 << 2), INTERRUPT1_REM_FAIL = (1 << 3), + /* Bit 4 reserved */ + INTERRUPT1_REM_VBON = (1 << 5), INTERRUPT1_REM_VBOFF = (1 << 6), + /* Bit 7 reserved */ }; diff --git a/include/nuttx/usb/hid.h b/include/nuttx/usb/hid.h index a635d7d3e3..45088e8bbf 100644 --- a/include/nuttx/usb/hid.h +++ b/include/nuttx/usb/hid.h @@ -56,6 +56,7 @@ ****************************************************************************/ /* Subclass and Protocol ****************************************************/ + /* Subclass codes (HID 4.2) */ #define USBHID_SUBCLASS_NONE 0 /* No subclass */ @@ -71,6 +72,7 @@ #define USBHID_PROTOCOL_MOUSE 2 /* Descriptor Requests ******************************************************/ + /* "When a Get_Descriptor(Configuration) request is issued, it returns the * Configuration descriptor, all Interface descriptors, all Endpoint * descriptors, and the HID descriptor for each interface." @@ -79,7 +81,8 @@ /* Standard Requests (HID 7.1) * GET_DESCRIPTOR (HID 7.1.1): * - * bmRequestType (USB_REQ_DIR_IN | USB_REQ_TYPE_STANDARD | USB_REQ_RECIPIENT_INTERFACE) + * bmRequestType (USB_REQ_DIR_IN | USB_REQ_TYPE_STANDARD | + * USB_REQ_RECIPIENT_INTERFACE) * bRequest (USB_REQ_GETDESCRIPTOR) * wValue Descriptor Type (MS) and Descriptor Index (LS) * wIndex Interface Number @@ -104,8 +107,9 @@ /* Class-specific requests (HID 7.2) * - * bmRequestType ( USB_REQ_TYPE_CLASS | USB_REQ_RECIPIENT_INTERFACE) -or- - * (USB_REQ_DIR_IN | USB_REQ_TYPE_CLASS | USB_REQ_RECIPIENT_INTERFACE) + * bmRequestType (USB_REQ_TYPE_CLASS | USB_REQ_RECIPIENT_INTERFACE) -or- + * (USB_REQ_DIR_IN | USB_REQ_TYPE_CLASS | + * USB_REQ_RECIPIENT_INTERFACE) * bRequest Class-specific request * wValue Varies according to request * wIndex Varies according to request @@ -262,7 +266,7 @@ #define USBHID_LOCAL_STRINGIDX_PREFIX 0x78 /* String Index */ #define USBHID_LOCAL_STRINGMIN_PREFIX 0x88 /* String Minimum */ #define USBHID_LOCAL_STRINGMAX_PREFIX 0x98 /* xx */ -#define USBHID_LOCAL_DELIMITER_PREFIX 0xa8 /*Delimiter */ +#define USBHID_LOCAL_DELIMITER_PREFIX 0xa8 /* Delimiter */ /* Modifier Keys (HID 8.3) */ @@ -627,6 +631,7 @@ /**************************************************************************** * Public Types ****************************************************************************/ + /* HID Descriptor (HID 6.2.1) ***********************************************/ struct usbhid_descriptor_s @@ -652,6 +657,7 @@ struct usbhid_optdesc_s }; /* Standard Reports *********************************************************/ + /* Keyboard input report (8 bytes) (HID B.1) */ struct usbhid_kbdreport_s @@ -661,7 +667,9 @@ struct usbhid_kbdreport_s uint8_t key[6]; /* Keycode 1-6 */ }; -/* Keyboard output report (1 byte) (HID B.1), see USBHID_KBDOUT_* definitions */ +/* Keyboard output report (1 byte) (HID B.1), + * see USBHID_KBDOUT_* definitions + */ /* Mouse input report (HID B.2) */ diff --git a/include/nuttx/usb/hub.h b/include/nuttx/usb/hub.h index de2d5101dd..117b2c2873 100644 --- a/include/nuttx/usb/hub.h +++ b/include/nuttx/usb/hub.h @@ -1,4 +1,4 @@ -/************************************************************************************ +/**************************************************************************** * include/nuttx/usb/hub.h * * Copyright (C) 2015 Gregory Nutt. All rights reserved. @@ -31,21 +31,21 @@ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * - ************************************************************************************/ + ****************************************************************************/ #ifndef __INCLUDE_NUTTX_USB_HUB_H #define __INCLUDE_NUTTX_USB_HUB_H -/************************************************************************************ +/**************************************************************************** * Included Files - ************************************************************************************/ + ****************************************************************************/ #include #include -/************************************************************************************ +/**************************************************************************** * Pre-processor Definitions - ************************************************************************************/ + ****************************************************************************/ /* Hub request types */ @@ -150,9 +150,9 @@ #define USBHUB_MAX_PORTS (7) -/************************************************************************************ +/**************************************************************************** * Public Types - ************************************************************************************/ + ****************************************************************************/ /* Hub descriptor */ diff --git a/include/nuttx/usb/max3421e.h b/include/nuttx/usb/max3421e.h index 8bfab87901..4680b66c7b 100644 --- a/include/nuttx/usb/max3421e.h +++ b/include/nuttx/usb/max3421e.h @@ -55,7 +55,8 @@ * Pre-processor Definitions ****************************************************************************/ -/* Configuration ***************************************************************/ +/* Configuration ************************************************************/ + /* MAX3421E USB Host Driver Support * * Pre-requisites @@ -74,6 +75,7 @@ */ /* Host Mode Register Addresses *********************************************/ + /* The command byte contains the register address, a direction bit, and an * ACKSTAT bit: * @@ -108,6 +110,7 @@ #define MAX3421E_USBHOST_HRSL (31 << 3) /* Peripheral Mode Register Addresses ***************************************/ + /* The command byte contains the register address, a direction bit, and an * ACKSTAT bit: * diff --git a/include/nuttx/usb/ohci.h b/include/nuttx/usb/ohci.h index fbac33355c..b65e80b43f 100644 --- a/include/nuttx/usb/ohci.h +++ b/include/nuttx/usb/ohci.h @@ -51,6 +51,7 @@ ****************************************************************************/ /* Register offsets *********************************************************/ + /* Control and status registers (section 7.1) */ #define OHCI_HCIREV_OFFSET 0x0000 /* HcRevision: Version of HCI specification */ @@ -154,6 +155,7 @@ #define OHCI_INT_OC (1 << 30) /* Bit 30: Ownership change */ #define OHCI_INT_MIE (1 << 31) /* Bit 31: Master interrupt enable * (Enable/disable only) */ + /* HcHCCA: HC communication area (7.2.1): * * 32-bits aligned to 256 byte boundary. @@ -190,16 +192,19 @@ #define OHCI_FMNO_FI_SHIFT (0) /* Bits 0-15: Frame number */ #define OHCI_FMNO_FI_MASK (0xffff << OHCI_FMINT_FI_SHIFT) /* Bits 16-31: Reserved */ + /* HcPeriodicStart: Time to start processing periodic list (7.3.4) */ #define OHCI_PERSTART_SHIFT (0) /* Bits 0-13: Periodic start */ #define OHCI_PERSTART_MASK (0x3fff << OHCI_PERSTART_SHIFT) /* Bits 14-31: Reserved */ + /* HcLSThreshold: Commit to transfer threshold (7.3.5) */ #define OHCI_LSTHRES_SHIFT (0) /* Bits 0-11: LS threshold */ #define OHCI_LSTHRES_MASK (0x0fff << OHCI_PERSTART_SHIFT) /* Bits 12-31: Reserved */ + /* HcRhDescriptorN: Describes root hub (part A) (7.4.1) */ #define OHCI_RHDESCA_NDP_SHIFT (0) /* Bits 0-7: Number downstream ports */ @@ -254,6 +259,7 @@ /* Bits 21-31: Reserved */ /* Transfer Descriptors *****************************************************/ + /* Endpoint Descriptor Offsets (4.2.1) */ #define ED_CONTROL_OFFSET (0x00) /* ED status/control bits */ @@ -273,6 +279,7 @@ # define ED_CONTROL_D_OUT (1 << ED_CONTROL_D_SHIFT) /* OUT */ # define ED_CONTROL_D_IN (2 << ED_CONTROL_D_SHIFT) /* IN */ # define ED_CONTROL_D_TD2 (3 << ED_CONTROL_D_SHIFT) /* Get direction from TD */ + #define ED_CONTROL_S (1 << 13) /* Bit 13: Speed (low) */ #define ED_CONTROL_K (1 << 14) /* Bit 14: Skip */ #define ED_CONTROL_F (1 << 15) /* Bit 15: Format (isochronous) */ @@ -292,13 +299,16 @@ #define GTD_BE_OFFSET (0x0c) /* Buffer End (BE) */ /* General Transfer Descriptor Bit Definitions */ + /* Bits 0-17: Reserved */ + #define GTD_STATUS_R (1 << 18) /* Bit 18: Buffer rounding */ #define GTD_STATUS_DP_SHIFT (19) /* Bits 19-20: Direction/PID */ #define GTD_STATUS_DP_MASK (3 << GTD_STATUS_DP_SHIFT) # define GTD_STATUS_DP_SETUP (0 << GTD_STATUS_DP_SHIFT) /* To endpoint */ # define GTD_STATUS_DP_OUT (1 << GTD_STATUS_DP_SHIFT) /* To endpoint */ # define GTD_STATUS_DP_IN (2 << GTD_STATUS_DP_SHIFT) /* From endpoint */ + #define GTD_STATUS_DI_SHIFT (21) /* Bits 21-23: Delay input */ #define GTD_STATUS_DI_MASK (7 << GTD_STATUS_DI_SHIFT) #define GTD_STATUS_T_SHIFT (24) /* Bits 24-25: Data Toggle */ @@ -434,8 +444,8 @@ struct ohci_hcca_s volatile uint16_t pad1; /* HccaDoneHead: When the HC reaches the end of a frame and its deferred - * interrupt register is 0, it writes the current value of its HcDoneHead to - * this location and generates an interrupt. + * interrupt register is 0, it writes the current value of its HcDoneHead + * to this location and generates an interrupt. */ volatile uint32_t donehead; @@ -459,7 +469,6 @@ extern "C" * Public Function Prototypes ****************************************************************************/ - #undef EXTERN #ifdef __cplusplus } diff --git a/include/nuttx/usb/pl2303.h b/include/nuttx/usb/pl2303.h index 2f4ef13716..b7bbf6c810 100644 --- a/include/nuttx/usb/pl2303.h +++ b/include/nuttx/usb/pl2303.h @@ -1,4 +1,4 @@ -/************************************************************************************ +/**************************************************************************** * include/nuttx/usb/pl2303.h * * Copyright (C) 2008-2010, 2012 Gregory Nutt. All rights reserved. @@ -37,28 +37,28 @@ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * - ************************************************************************************/ + ****************************************************************************/ #ifndef __INCLUDE_NUTTX_USB_PL2303_H #define __INCLUDE_NUTTX_USB_PL2303_H -/************************************************************************************ +/**************************************************************************** * Included Files - ************************************************************************************/ + ****************************************************************************/ #include -/************************************************************************************ +/**************************************************************************** * Pre-processor Definitions - ************************************************************************************/ + ****************************************************************************/ -/************************************************************************************ +/**************************************************************************** * Public Types - ************************************************************************************/ + ****************************************************************************/ - /************************************************************************************ +/**************************************************************************** * Public Data - ************************************************************************************/ + ****************************************************************************/ #undef EXTERN #if defined(__cplusplus) @@ -69,17 +69,18 @@ extern "C" # define EXTERN extern #endif -/************************************************************************************ - * Public Functions - ************************************************************************************/ +/**************************************************************************** + * Public Functions Definitions + ****************************************************************************/ -/************************************************************************************ +/**************************************************************************** * Name: usbdev_serialinit * * Description: - * Register PL2303 USB serial port (and USB serial console if so configured). + * Register PL2303 USB serial port + * (and USB serial console if so configured). * - ************************************************************************************/ + ****************************************************************************/ int usbdev_serialinitialize(int minor); diff --git a/include/nuttx/usb/rndis.h b/include/nuttx/usb/rndis.h index e817f87b90..aa637faae8 100644 --- a/include/nuttx/usb/rndis.h +++ b/include/nuttx/usb/rndis.h @@ -1,9 +1,9 @@ -/************************************************************************************ +/**************************************************************************** * include/nuttx/usb/rndis.h * * Copyright (C) 2011-2018 Gregory Nutt. All rights reserved. * Authors: Sakari Kapanen , - Petteri Aimonen + * Petteri Aimonen * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -32,14 +32,14 @@ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * - ************************************************************************************/ + ****************************************************************************/ #ifndef __INCLUDE_NUTTX_USB_RNDIS_H #define __INCLUDE_NUTTX_USB_RNDIS_H -/************************************************************************************ +/**************************************************************************** * Included Files - ************************************************************************************/ + ****************************************************************************/ #include #include @@ -48,13 +48,15 @@ * Preprocessor definitions ****************************************************************************/ -/* Indexes for devinfo.epno[] array. Used for composite device configuration. */ +/* Indexes for devinfo.epno[] array. + * Used for composite device configuration. + */ #define RNDIS_EP_INTIN_IDX (0) #define RNDIS_EP_BULKIN_IDX (1) #define RNDIS_EP_BULKOUT_IDX (2) -/* Endpoint configuration ****************************************************/ +/* Endpoint configuration ***************************************************/ #define RNDIS_MKEPINTIN(desc) (USB_DIR_IN | (desc)->epno[RNDIS_EP_INTIN_IDX]) #define RNDIS_EPINTIN_ATTR (USB_EP_ATTR_XFER_INT) @@ -89,9 +91,9 @@ # define CONFIG_RNDIS_EPBULKOUT_HSSIZE 512 #endif -/************************************************************************************ +/**************************************************************************** * Public Data - ************************************************************************************/ + ****************************************************************************/ #undef EXTERN #if defined(__cplusplus) @@ -102,25 +104,26 @@ extern "C" # define EXTERN extern #endif -/************************************************************************************ - * Public Functions - ************************************************************************************/ +/**************************************************************************** + * Public Functions Definitions + ****************************************************************************/ -/************************************************************************************ +/**************************************************************************** * Name: usbdev_rndis_initialize * * Description: - * Register RNDIS USB device interface. Register the corresponding network driver - * to NuttX and bring up the network. + * Register RNDIS USB device interface. + * Register the corresponding network driver to NuttX and bring up the + * network. * * Input Parameters: - * mac_address: an array of 6 bytes which make the MAC address of the host side - * of the network. + * mac_address: an array of 6 bytes which make the MAC address of the host + * side of the network. * * Returned Value: * 0 on success; -errno on failure * - ************************************************************************************/ + ****************************************************************************/ #ifndef CONFIG_RNDIS_COMPOSITE int usbdev_rndis_initialize(FAR const uint8_t *mac_address); diff --git a/include/nuttx/usb/storage.h b/include/nuttx/usb/storage.h index 479301d896..b36103a61f 100644 --- a/include/nuttx/usb/storage.h +++ b/include/nuttx/usb/storage.h @@ -1,4 +1,4 @@ -/************************************************************************************ +/**************************************************************************** * include/nuttx/usb/storage.h * * Copyright (C) 2008-2011 Gregory Nutt. All rights reserved. @@ -38,21 +38,21 @@ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * - ************************************************************************************/ + ****************************************************************************/ #ifndef __INCLUDE_NUTTX_USB_STORAGE_H #define __INCLUDE_NUTTX_USB_STORAGE_H -/************************************************************************************ +/**************************************************************************** * Included Files - ************************************************************************************/ + ****************************************************************************/ #include #include -/************************************************************************************ +/**************************************************************************** * Pre-processor Definitions - ************************************************************************************/ + ****************************************************************************/ /* Mass storage requests */ @@ -93,9 +93,9 @@ #define USBMSC_CSWSTATUS_FAIL (1) #define USBMSC_CSWSTATUS_PHASEERROR (2) -/************************************************************************************ +/**************************************************************************** * Public Types - ************************************************************************************/ + ****************************************************************************/ /* Command Block Wrapper (CBW) */ @@ -120,12 +120,12 @@ struct usbmsc_csw_s uint8_t status; /* Status of transfer */ }; -/************************************************************************************ +/**************************************************************************** * Public Data - ************************************************************************************/ + ****************************************************************************/ -/************************************************************************************ - * Public Functions - ************************************************************************************/ +/**************************************************************************** + * Public Functions Definitions + ****************************************************************************/ #endif /* __INCLUDE_NUTTX_USB_STORAGE_H */ diff --git a/include/nuttx/usb/usb.h b/include/nuttx/usb/usb.h index c728c7761d..3df3b182b3 100644 --- a/include/nuttx/usb/usb.h +++ b/include/nuttx/usb/usb.h @@ -1,7 +1,8 @@ -/************************************************************************************ +/**************************************************************************** * include/nuttx/usb/usb.h * - * Copyright (C) 2008, 2009-2010, 2012, 2008 Gregory Nutt. All rights reserved. + * Copyright (C) 2008, 2009-2010, 2012, 2008 Gregory Nutt. + * All rights reserved. * Author: Gregory Nutt * * Redistribution and use in source and binary forms, with or without @@ -31,26 +32,27 @@ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * - ************************************************************************************/ + ****************************************************************************/ #ifndef __INCLUDE_NUTTX_USB_USB_H #define __INCLUDE_NUTTX_USB_USB_H -/************************************************************************************ +/**************************************************************************** * Included Files - ************************************************************************************/ + ****************************************************************************/ #include #include -/************************************************************************************ +/**************************************************************************** * Pre-processor Definitions - ************************************************************************************/ + ****************************************************************************/ -/* A packet identifier (PID) immediately follows the SYNC field of every USB packet. - * A PID consists of a four-bit packet type field followed by a four-bit check field - * USB Tokens (See Table 8-1 in the USB specification) +/* A packet identifier (PID) immediately follows the SYNC field of every USB + * packet. + * A PID consists of a four-bit packet type field followed by a four-bit + * check field USB Tokens (See Table 8-1 in the USB specification) */ #define USB_PID_OUT_TOKEN (0x01) /* Tokens */ @@ -267,9 +269,9 @@ #define MSFTOSDESC_INDEX_FUNCTION 4 #define MSFTOSDESC_INDEX_EXTPROP 5 -/************************************************************************************ +/**************************************************************************** * Public Types - ************************************************************************************/ + ****************************************************************************/ /* This structure is used to send control requests to a USB device. */ @@ -412,12 +414,12 @@ struct usb_qualdesc_s /* Interface association descriptor * - * The Universal Serial Bus Specification, revision 2.0, does not support grouping - * more than one interface of a composite device within a single function. However, - * the USB Device Working Group (DWG) created USB device classes that allow for - * functions with multiple interfaces, and the USB Implementor's Forum issued an - * Engineering Change Notification (ECN) that defines a mechanism for grouping - * interfaces. + * The Universal Serial Bus Specification, revision 2.0, does not support + * grouping more than one interface of a composite device within a single + * function. However, the USB Device Working Group (DWG) created USB device + * classes that allow for functions with multiple interfaces, and the USB + * Implementor's Forum issued an Engineering Change Notification (ECN) that + * defines a mechanism for grouping interfaces. */ struct usb_iaddesc_s @@ -435,15 +437,17 @@ struct usb_iaddesc_s #define USB_SIZEOF_IADDESC 8 /* Microsoft OS function descriptor. - * This can be used to request a specific driver (such as WINUSB) to be loaded - * on Windows. Unlike other descriptors, it is requested by a special request - * USB_REQ_GETMSFTOSDESCRIPTOR. - * More details: https://msdn.microsoft.com/en-us/windows/hardware/gg463179 - * And excellent explanation: https://github.com/pbatard/libwdi/wiki/WCID-Devices + * This can be used to request a specific driver (such as WINUSB) to be + * loaded on Windows. Unlike other descriptors, it is requested by a special + * request USB_REQ_GETMSFTOSDESCRIPTOR. + * More details: + * https://msdn.microsoft.com/en-us/windows/hardware/gg463179 + * And excellent explanation: + * https://github.com/pbatard/libwdi/wiki/WCID-Devices * * The device will have exactly one "Extended Compat ID Feature Descriptor", - * which may contain multiple "Function Descriptors" associated with different - * interfaces. + * which may contain multiple "Function Descriptors" associated with + * different interfaces. */ struct usb_msft_os_function_desc_s @@ -466,11 +470,12 @@ struct usb_msft_os_feature_desc_s }; /* Microsoft OS extended property descriptor. - * This can be used to set specific registry values, such as interface GUID for - * a device. It is requested per-interface by special request USB_REQ_GETMSFTOSDESCRIPTOR. + * This can be used to set specific registry values, such as interface GUID + * for a device. It is requested per-interface by special request + * USB_REQ_GETMSFTOSDESCRIPTOR. * - * The interface will have one extended properties descriptor, which may contain - * multiple properties inside it. + * The interface will have one extended properties descriptor, which may + * contain multiple properties inside it. */ struct usb_msft_os_extprop_hdr_s @@ -490,12 +495,12 @@ struct usb_msft_os_extprop_hdr_s */ }; -/************************************************************************************ +/**************************************************************************** * Public Data - ************************************************************************************/ + ****************************************************************************/ -/************************************************************************************ - * Public Functions - ************************************************************************************/ +/**************************************************************************** + * Public Functions Definitions + ****************************************************************************/ #endif /* __INCLUDE_NUTTX_USB_USB_H */ diff --git a/include/nuttx/usb/usbdev.h b/include/nuttx/usb/usbdev.h index 96ebee0fba..c0a316e851 100644 --- a/include/nuttx/usb/usbdev.h +++ b/include/nuttx/usb/usbdev.h @@ -1,7 +1,8 @@ -/************************************************************************************ +/**************************************************************************** * include/nuttx/usb/usbdev.h * - * Copyright (C) 2008-2010, 2012-2013, 2017 Gregory Nutt. All rights reserved. + * Copyright (C) 2008-2010, 2012-2013, 2017 Gregory Nutt. + * All rights reserved. * Author: Gregory Nutt * * NOTE: This interface was inspired by the Linux gadget interface by @@ -37,14 +38,14 @@ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * - ************************************************************************************/ + ****************************************************************************/ #ifndef __INCLUDE_NUTTX_USB_USBDEV_H #define __INCLUDE_NUTTX_USB_USBDEV_H -/************************************************************************************ +/**************************************************************************** * Included Files - ************************************************************************************/ + ****************************************************************************/ #include @@ -57,19 +58,21 @@ #include #include -/************************************************************************************ +/**************************************************************************** * Pre-processor Definitions - ************************************************************************************/ + ****************************************************************************/ -/* Endpoint helpers *****************************************************************/ +/* Endpoint helpers *********************************************************/ -/* Configure endpoint, making it usable. The class driver may deallocate or re-use - * the 'desc' structure after returning: +/* Configure endpoint, making it usable. + * The class driver may deallocate or re-use the 'desc' structure after + * returning: * * ep - the struct usbdev_ep_s instance obtained from allocep() * desc - A struct usb_epdesc_s instance describing the endpoint - * last - true if this is the last endpoint to be configured. Some hardware needs - * to take special action when all of the endpoints have been configured. + * last - true if this is the last endpoint to be configured. Some hardware + * needs to take special action when all of the endpoints have been + * configured. */ #define EP_CONFIGURE(ep,desc,last) (ep)->ops->configure(ep,desc,last) @@ -78,12 +81,16 @@ #define EP_DISABLE(ep) (ep)->ops->disable(ep) -/* Allocate/free I/O requests. Should not be called from interrupt processing! */ +/* Allocate/free I/O requests. + * Should not be called from interrupt processing! + */ #define EP_ALLOCREQ(ep) (ep)->ops->allocreq(ep) #define EP_FREEREQ(ep,req) (ep)->ops->freereq(ep,req) -/* Allocate/free an I/O buffer. Should not be called from interrupt processing! */ +/* Allocate/free an I/O buffer. + * Should not be called from interrupt processing! + */ #ifdef CONFIG_USBDEV_DMA # define EP_ALLOCBUFFER(ep,nb) (ep)->ops->allocbuffer(ep,nb) @@ -106,16 +113,17 @@ #define EP_STALL(ep) (ep)->ops->stall(ep,false) #define EP_RESUME(ep) (ep)->ops->stall(ep,true) -/* USB Device Driver Helpers ********************************************************/ +/* USB Device Driver Helpers ************************************************/ /* Allocate an endpoint: * - * ep - 7-bit logical endpoint number (direction bit ignored). Zero means - * that any endpoint matching the other requirements will suffice. The - * assigned endpoint can be found in the eplog field. + * ep - 7-bit logical endpoint number (direction bit ignored). + * Zero means that any endpoint matching the other requirements + * will suffice. + * The assigned endpoint can be found in the eplog field. * in - true: IN (device-to-host) endpoint requested - * eptype - Endpoint type. One of {USB_EP_ATTR_XFER_ISOC, USB_EP_ATTR_XFER_BULK, - * USB_EP_ATTR_XFER_INT} + * eptype - Endpoint type. One of {USB_EP_ATTR_XFER_ISOC, + * USB_EP_ATTR_XFER_BULK, USB_EP_ATTR_XFER_INT} */ #define DEV_ALLOCEP(dev,ep,in,type) (dev)->ops->allocep(dev,ep,in,type) @@ -140,9 +148,9 @@ #define DEV_CLRSELFPOWERED(dev) (dev)->ops->selfpowered(dev, false) -/* Software-controlled connect to USB host. All USB class drivers need to call - * DEV_CONNECT() when they are ready to be enumerated. That is, (1) initially when - * bound to the USB driver, and (2) after a USB reset. +/* Software-controlled connect to USB host. All USB class drivers need to + * call DEV_CONNECT() when they are ready to be enumerated. That is, (1) + * initially when bound to the USB driver, and (2) after a USB reset. */ #define DEV_CONNECT(dev) (dev)->ops->pullup ? (dev)->ops->pullup(dev,true) : -EOPNOTSUPP @@ -151,9 +159,11 @@ #define DEV_DISCONNECT(dev) (dev)->ops->pullup ? (dev)->ops->pullup(dev,false) : -EOPNOTSUPP -/* USB Class Driver Helpers *********************************************************/ +/* USB Class Driver Helpers *************************************************/ -/* All may be called from interrupt handling logic except bind() and unbind() */ +/* All may be called from interrupt handling logic except bind() and + * unbind() + */ /* Invoked when the driver is bound to a USB device driver. */ @@ -163,7 +173,9 @@ #define CLASS_UNBIND(drvr,dev) (drvr)->ops->unbind(drvr,dev) -/* Invoked after all transfers have been stopped, when the host is disconnected. */ +/* Invoked after all transfers have been stopped, when the host is + * disconnected. + */ #define CLASS_DISCONNECT(drvr,dev) (drvr)->ops->disconnect(drvr,dev) @@ -191,11 +203,11 @@ #define USBDEV_REQFLAGS_NULLPKT 1 /* Bit 0: Terminate w/short packet; null packet if necessary */ /* Bits 1-7: Available */ -/************************************************************************************ +/**************************************************************************** * Public Types - ************************************************************************************/ + ****************************************************************************/ -/* USB Controller Structures ********************************************************/ +/* USB Controller Structures ************************************************/ /* usbdev_devinfo_s - describes the low level bindings of an usb device */ @@ -257,7 +269,8 @@ struct usbdev_req_s /* Callback when the transfer completes */ - CODE void (*callback)(FAR struct usbdev_ep_s *ep, FAR struct usbdev_req_s *req); + CODE void (*callback)(FAR struct usbdev_ep_s *ep, + FAR struct usbdev_req_s *req); FAR void *priv; /* Used only by callee */ }; @@ -341,7 +354,7 @@ struct usbdev_s uint8_t dualspeed:1; /* 1:supports high and full speed operation */ }; -/* USB Device Class Implementations *************************************************/ +/* USB Device Class Implementations *****************************************/ struct usbdevclass_driver_s; struct usbdevclass_driverops_s @@ -367,9 +380,9 @@ struct usbdevclass_driver_s uint8_t speed; /* Highest speed that the driver handles */ }; -/************************************************************************************ +/**************************************************************************** * Public Data - ************************************************************************************/ + ****************************************************************************/ #undef EXTERN #if defined(__cplusplus) @@ -380,34 +393,35 @@ extern "C" # define EXTERN extern #endif -/************************************************************************************ +/**************************************************************************** * Public Function Prototypes - ************************************************************************************/ + ****************************************************************************/ -/************************************************************************************ +/**************************************************************************** * Name: usbdevclass_register * * Description: - * Register a USB device class driver. The class driver's bind() method will be - * called to bind it to a USB device driver. + * Register a USB device class driver. The class driver's bind() method + * will be called to bind it to a USB device driver. * - ************************************************************************************/ + ****************************************************************************/ int usbdev_register(FAR struct usbdevclass_driver_s *driver); -/************************************************************************************ +/**************************************************************************** * Name: usbdev_unregister * * Description: - * Un-register usbdev class driver.If the USB device is connected to a USB host, - * it will first disconnect(). The driver is also requested to unbind() and clean - * up any device state, before this procedure finally returns. + * Un-register usbdev class driver.If the USB device is connected to a USB + * host, it will first disconnect(). + * The driver is also requested to unbind() and clean up any device state, + * before this procedure finally returns. * - ************************************************************************************/ + ****************************************************************************/ int usbdev_unregister(FAR struct usbdevclass_driver_s *driver); -/************************************************************************************ +/**************************************************************************** * Name: usbdev_dma_alloc and usbdev_dma_free * * Description: @@ -431,7 +445,7 @@ int usbdev_unregister(FAR struct usbdevclass_driver_s *driver); * does require the size of the allocation to be freed; that would need * to be managed in the board-specific logic. * - ************************************************************************************/ + ****************************************************************************/ #if defined(CONFIG_USBDEV_DMA) && defined(CONFIG_USBDEV_DMAMEMORY) FAR void *usbdev_dma_alloc(size_t size); diff --git a/include/nuttx/usb/usbdev_trace.h b/include/nuttx/usb/usbdev_trace.h index dc32b5e30e..cb977bc07c 100644 --- a/include/nuttx/usb/usbdev_trace.h +++ b/include/nuttx/usb/usbdev_trace.h @@ -1,7 +1,8 @@ /**************************************************************************** * include/nuttx/usb/usbdev_trace.h * - * Copyright (C) 2008, 2009-2010, 2012-2013, 2017 Gregory Nutt. All rights reserved. + * Copyright (C) 2008, 2009-2010, 2012-2013, 2017 Gregory Nutt. + * All rights reserved. * Author: Gregory Nutt * * Redistribution and use in source and binary forms, with or without @@ -54,7 +55,7 @@ #define TRACE_ID(event) ((event) & 0xff00) #define TRACE_DATA(event) ((event) & 0x00ff) -/* Events ******************************************************************/ +/* Events *******************************************************************/ /* Event class IDs */ @@ -144,7 +145,7 @@ #define TRACE_CLASSSTATE(id) TRACE_EVENT(TRACE_CLASSSTATE_ID, id) -/* USB device controller interrupt events. The 'id' is specific to the driver. +/* USB device controller interrupt events.The 'id' is specific to the driver. * Particular values for 'id' are unique for a given implementation of a * controller driver */ @@ -175,6 +176,7 @@ #define TRACE_CLSERROR(id) TRACE_EVENT(TRACE_CLSERROR_ID, id) /* Event string descriptions ************************************************/ + /* Macros for defining the string arrays for display of the traces. */ #ifdef CONFIG_USBDEV_TRACE_STRINGS @@ -183,7 +185,9 @@ #endif /* USB Serial driver class events *******************************************/ + /* Used by both the CDC/ACM and the PL2303 serial class drivers */ + /* UART interface API calls */ #define USBSER_TRACECLASSAPI_SETUP 0x0001 @@ -467,11 +471,12 @@ EXTERN const struct trace_msg_t g_usb_trace_strings_intdecode[]; * Name: usbtrace_enable * * Description: - * Enable/disable tracing per trace ID. The initial state is all IDs enabled. + * Enable/disable tracing per trace ID. + * The initial state is all IDs enabled. * * Input Parameters: - * idset - The bitset of IDs to be masked. TRACE_ALLIDS enables all IDS; zero - * masks all IDs. + * idset - The bitset of IDs to be masked. + * TRACE_ALLIDS enables all IDS; zero masks all IDs. * * Returned Value: * The previous idset value. diff --git a/include/nuttx/usb/usbhost.h b/include/nuttx/usb/usbhost.h index 4a4e060f40..709e923b6c 100644 --- a/include/nuttx/usb/usbhost.h +++ b/include/nuttx/usb/usbhost.h @@ -1,4 +1,4 @@ -/************************************************************************************ +/**************************************************************************** * include/nuttx/usb/usbhost.h * * Licensed to the Apache Software Foundation (ASF) under one or more @@ -16,7 +16,7 @@ * License for the specific language governing permissions and limitations * under the License. * - ************************************************************************************/ + ****************************************************************************/ /* References: * "Universal Serial Bus Mass Storage Class, Specification Overview," @@ -29,9 +29,9 @@ #ifndef __INCLUDE_NUTTX_USB_USBHOST_H #define __INCLUDE_NUTTX_USB_USBHOST_H -/************************************************************************************ +/**************************************************************************** * Included Files - ************************************************************************************/ + ****************************************************************************/ #include @@ -45,17 +45,17 @@ #include -/************************************************************************************ +/**************************************************************************** * Pre-processor Definitions - ************************************************************************************/ + ****************************************************************************/ -/************************************************************************************ +/**************************************************************************** * Name: ROOTHUB * * Description: * Check if a hub instance is the root hub. * - ************************************************************************************/ + ****************************************************************************/ #ifdef CONFIG_USBHOST_HUB # define ROOTHUB(hub) ((hub)->parent == NULL) @@ -63,48 +63,49 @@ # define ROOTHUB(hub) true #endif -/************************************************************************************ +/**************************************************************************** * Name: CLASS_CREATE * * Description: * This macro will call the create() method of struct usbhost_registry_s. - * The create() method is a callback into the class implementation. It is used - * to (1) create a new instance of the USB host class state and to (2) bind a - * USB host driver "session" to the class instance. Use of this create() method - * will support environments where there may be multiple USB ports and multiple - * USB devices simultaneously connected. + * The create() method is a callback into the class implementation. + * It is used to (1) create a new instance of the USB host class state and + * to (2) bind a USB host driver "session" to the class instance. + * Use of this create() method will support environments where there may be + * multiple USB ports and multiple USB devices simultaneously connected. * * Input Parameters: - * reg - The USB host class registry entry previously obtained from a call to - * usbhost_findclass(). + * reg - The USB host class registry entry previously obtained from a call + * to usbhost_findclass(). * hport - The hub hat manages the new class instance. - * id - In the case where the device supports multiple base classes, subclasses, or - * protocols, this specifies which to configure for. + * id - In the case where the device supports multiple base classes, + * subclasses, or protocols, this specifies which to configure for. * * Returned Value: * On success, this function will return a non-NULL instance of struct - * usbhost_class_s that can be used by the USB host driver to communicate with the - * USB host class. NULL is returned on failure; this function will fail only if - * the drvr input parameter is NULL or if there are insufficient resources to - * create another USB host class instance. + * usbhost_class_s that can be used by the USB host driver to communicate + * with the USB host class. NULL is returned on failure; this function + * will fail only if the drvr input parameter is NULL or if there are + * insufficient resources to create another USB host class instance. * * Assumptions: - * If this function is called from an interrupt handler, it will be unable to - * allocate memory and CONFIG_USBHOST_NPREALLOC should be defined to be a value - * greater than zero specify a number of pre-allocated class structures. + * If this function is called from an interrupt handler, it will be unable + * to allocate memory and CONFIG_USBHOST_NPREALLOC should be defined to be + * a value greater than zero specify a number of pre-allocated class + * structures. * - ************************************************************************************/ + ****************************************************************************/ #define CLASS_CREATE(reg,hport,id) ((reg)->create(hport,id)) -/************************************************************************************ +/**************************************************************************** * Name: CLASS_CONNECT * * Description: - * This macro will call the connect() method of struct usbhost_class_s. This - * method is a callback into the devclass implementation. It is used to provide - * the device's configuration descriptor to the devclass so that the devclass may - * initialize properly. + * This macro will call the connect() method of struct usbhost_class_s. + * This method is a callback into the devclass implementation. + * It is used to providethe device's configuration descriptor to the + * devclass so that the devclass may initialize properly. * * Input Parameters: * devclass - The USB host class entry previously obtained from a call @@ -114,56 +115,59 @@ * desclen - The length in bytes of the configuration descriptor. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure * - * NOTE that the class instance remains valid upon return with a failure. It is - * the responsibility of the higher level enumeration logic to call + * NOTE that the class instance remains valid upon return with a failure. + * It is the responsibility of the higher level enumeration logic to call * CLASS_DISCONNECTED to free up the class driver resources. * * Assumptions: - * - This function is probably called on the same thread that called the driver - * enumerate() method. This function will *not* be called from an interrupt - * handler. + * - This function is probably called on the same thread that called the + * driver enumerate() method. This function will *not* be called from an + * interrupt handler. * - If this function returns an error, the USB host controller driver * must call to DISCONNECTED method to recover from the error * - ************************************************************************************/ + ****************************************************************************/ #define CLASS_CONNECT(devclass,configdesc,desclen) \ ((devclass)->connect(devclass,configdesc,desclen)) -/************************************************************************************ +/**************************************************************************** * Name: CLASS_DISCONNECTED * * Description: - * This macro will call the disconnected() method of struct usbhost_class_s. This - * method is a callback into the class implementation. It is used to inform the - * class that the USB device has been disconnected. + * This macro will call the disconnected() method of struct + * usbhost_class_s. + * This method is a callback into the class implementation. + * It is used to inform the class that the USB device has been + * disconnected. * * Input Parameters: - * devclass - The USB host class entry previously obtained from a call to create(). + * devclass - The USB host class entry previously obtained from a call to + * create(). * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure * * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define CLASS_DISCONNECTED(devclass) ((devclass)->disconnected(devclass)) -/************************************************************************************ +/**************************************************************************** * Name: CONN_WAIT * * Description: * Wait for a device to be connected or disconnected to/from a hub port. * * Input Parameters: - * conn - The USB host connection instance obtained as a parameter from the call to - * the USB driver initialization logic. + * conn - The USB host connection instance obtained as a parameter from the + * call to the USB driver initialization logic. * hport - The location to return the hub port descriptor that detected the * connection related event. * @@ -178,11 +182,11 @@ * - Called from a single thread so no mutual exclusion is required. * - Never called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define CONN_WAIT(conn,hport) ((conn)->wait(conn,hport)) -/************************************************************************************ +/**************************************************************************** * Name: CONN_ENUMERATE * * Description: @@ -202,17 +206,17 @@ * device. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure * * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define CONN_ENUMERATE(conn,rhpndx) ((conn)->enumerate(conn,rhpndx)) -/************************************************************************************ +/**************************************************************************** * Name: DRVR_EP0CONFIGURE * * Description: @@ -221,246 +225,256 @@ * an external implementation of the enumeration logic. * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. * ep0 - The (opaque) EP0 endpoint instance - * funcaddr - The USB address of the function containing the endpoint that EP0 - * controls + * funcaddr - The USB address of the function containing the endpoint + * that EP0 controls * speed - The speed of the port USB_SPEED_LOW, _FULL, or _HIGH * mps (maxpacketsize) - The maximum number of bytes that can be sent to or * received from the endpoint in a single data packet * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure * * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define DRVR_EP0CONFIGURE(drvr,ep0,funcaddr,speed,mps) \ ((drvr)->ep0configure(drvr,ep0,funcaddr,speed,mps)) -/************************************************************************************ +/**************************************************************************** * Name: DRVR_GETDEVINFO * * Description: * Get information about the connected device. * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. - * devinfo - A pointer to memory provided by the caller in which to return the - * device information. + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. + * devinfo - A pointer to memory provided by the caller in which to return + * the device information. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure * * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define DRVR_GETDEVINFO(drvr,devinfo) ((drvr)->getdevinfo(drvr,devinfo)) -/************************************************************************************ +/**************************************************************************** * Name: DRVR_EPALLOC * * Description: * Allocate and configure one endpoint. * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. * epdesc - Describes the endpoint to be allocated. * ep - A memory location provided by the caller in which to receive the * allocated endpoint descriptor. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure * * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define DRVR_EPALLOC(drvr,epdesc,ep) ((drvr)->epalloc(drvr,epdesc,ep)) -/************************************************************************************ +/**************************************************************************** * Name: DRVR_EPFREE * * Description: * Free and endpoint previously allocated by DRVR_EPALLOC. * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. * ep - The endpoint to be freed. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure * * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define DRVR_EPFREE(drvr,ep) ((drvr)->epfree(drvr,ep)) -/************************************************************************************ +/**************************************************************************** * Name: DRVR_ALLOC * * Description: - * Some hardware supports special memory in which request and descriptor data can - * be accessed more efficiently. This method provides a mechanism to allocate - * the request/descriptor memory. If the underlying hardware does not support - * such "special" memory, this functions may simply map to kmm_malloc. + * Some hardware supports special memory in which request and descriptor + * data can be accessed more efficiently. This method provides a mechanism + * to allocate the request/descriptor memory. If the underlying hardware + * does not support such "special" memory, this functions may simply map to + * kmm_malloc. * - * This interface was optimized under a particular assumption. It was assumed - * that the driver maintains a pool of small, pre-allocated buffers for descriptor - * traffic. NOTE that size is not an input, but an output: The size of the + * This interface was optimized under a particular assumption. + * It was assumed that the driver maintains a pool of small, pre-allocated + * buffers for descriptor traffic. + * NOTE that size is not an input, but an output: The size of the * pre-allocated buffer is returned. * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. - * buffer - The address of a memory location provided by the caller in which to - * return the allocated buffer memory address. - * maxlen - The address of a memory location provided by the caller in which to - * return the maximum size of the allocated buffer memory. + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. + * buffer - The address of a memory location provided by the caller in + * which to return the allocated buffer memory address. + * maxlen - The address of a memory location provided by the caller in + * which to return the maximum size of the allocated buffer memory. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure * * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define DRVR_ALLOC(drvr,buffer,maxlen) ((drvr)->alloc(drvr,buffer,maxlen)) -/************************************************************************************ +/**************************************************************************** * Name: DRVR_FREE * * Description: - * Some hardware supports special memory in which request and descriptor data can - * be accessed more efficiently. This method provides a mechanism to free that - * request/descriptor memory. If the underlying hardware does not support - * such "special" memory, this functions may simply map to kmm_free(). + * Some hardware supports special memory in which request and descriptor + * data can be accessed more efficiently. This method provides a mechanism + * to free that request/descriptor memory. If the underlying hardware does + * not support such "special" memory, this functions may simply map to + * kmm_free(). * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. * buffer - The address of the allocated buffer memory to be freed. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure * * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define DRVR_FREE(drvr,buffer) ((drvr)->free(drvr,buffer)) -/************************************************************************************ +/**************************************************************************** * Name: DRVR_IOALLOC * * Description: * Some hardware supports special memory in which larger IO buffers can - * be accessed more efficiently. This method provides a mechanism to allocate - * the request/descriptor memory. If the underlying hardware does not support - * such "special" memory, this functions may simply map to kmm_malloc. + * be accessed more efficiently. + * This method provides a mechanism to allocate the request/descriptor + * memory. + * If the underlying hardware does not support such "special" memory, + * this functions may simply map to kmm_malloc. * - * This interface differs from DRVR_ALLOC in that the buffers are variable-sized. + * This interface differs from DRVR_ALLOC in that the buffers are + * variable-sized. * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. - * buffer - The address of a memory location provided by the caller in which to - * return the allocated buffer memory address. + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. + * buffer - The address of a memory location provided by the caller in + * which to return the allocated buffer memory address. * buflen - The size of the buffer required. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure * * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define DRVR_IOALLOC(drvr,buffer,buflen) ((drvr)->ioalloc(drvr,buffer,buflen)) -/************************************************************************************ +/**************************************************************************** * Name: DRVR_IOFREE * * Description: - * Some hardware supports special memory in which IO data can be accessed more - * efficiently. This method provides a mechanism to free that IO buffer - * memory. If the underlying hardware does not support such "special" memory, + * Some hardware supports special memory in which IO data can be accessed + * more efficiently. + * This method provides a mechanism to free that IO buffer memory. + * If the underlying hardware does not support such "special" memory, * this functions may simply map to kmm_free(). * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. * buffer - The address of the allocated buffer memory to be freed. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno + * value is returned indicating the nature of the failure * * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define DRVR_IOFREE(drvr,buffer) ((drvr)->iofree(drvr,buffer)) -/************************************************************************************ +/**************************************************************************** * Name: DRVR_CTRLIN and DRVR_CTRLOUT * * Description: - * Process a IN or OUT request on the control endpoint. These methods - * will enqueue the request and wait for it to complete. Only one transfer may be - * queued; Neither these methods nor the transfer() method can be called again - * until the control transfer functions returns. + * Process a IN or OUT request on the control endpoint. + * These methods will enqueue the request and wait for it to complete. + * Only one transfer may be queued; Neither these methods nor the + * transfer() method can be called again until the control transfer + * functions returns. * * These are blocking methods; these functions will not return until the * control transfer has completed. * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. * ep0 - The control endpoint to send/receive the control request. * req - Describes the request to be sent. This request must lie in memory * created by DRVR_ALLOC. * buffer - A buffer used for sending the request and for returning any * responses. This buffer must be large enough to hold the length value - * in the request description. buffer must have been allocated using DRVR_ALLOC. + * in the request description. buffer must have been allocated using + * DRVR_ALLOC. + * + * NOTE: On an IN transaction, req and buffer may refer to the same + * allocated memory. * - * NOTE: On an IN transaction, req and buffer may refer to the same allocated - * memory. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure * * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define DRVR_CTRLIN(drvr,ep0,req,buffer) ((drvr)->ctrlin(drvr,ep0,req,buffer)) #define DRVR_CTRLOUT(drvr,ep0,req,buffer) ((drvr)->ctrlout(drvr,ep0,req,buffer)) -/************************************************************************************ +/**************************************************************************** * Name: DRVR_TRANSFER * * Description: @@ -473,18 +487,19 @@ * transfer has completed. * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. - * ep - The IN or OUT endpoint descriptor for the device endpoint on which to - * perform the transfer. - * buffer - A buffer containing the data to be sent (OUT endpoint) or received - * (IN endpoint). buffer must have been allocated using DRVR_ALLOC + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. + * ep - The IN or OUT endpoint descriptor for the device endpoint on + * which to perform the transfer. + * buffer - A buffer containing the data to be sent (OUT endpoint) or + * received (IN endpoint). Buffer must have been allocated using + * DRVR_ALLOC * buflen - The length of the data to be sent or received. * * Returned Value: * On success, a non-negative value is returned that indicates the number - * of bytes successfully transferred. On a failure, a negated errno value is - * returned that indicates the nature of the failure: + * of bytes successfully transferred. On a failure, a negated errno value + * is returned that indicates the nature of the failure: * * EAGAIN - If devices NAKs the transfer (or NYET or other error where * it may be appropriate to restart the entire transaction). @@ -495,12 +510,12 @@ * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define DRVR_TRANSFER(drvr,ep,buffer,buflen) \ ((drvr)->transfer(drvr,ep,buffer,buflen)) -/************************************************************************************ +/**************************************************************************** * Name: DRVR_ASYNCH * * Description: @@ -515,32 +530,33 @@ * infrequently. * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. - * ep - The IN or OUT endpoint descriptor for the device endpoint on which to - * perform the transfer. - * buffer - A buffer containing the data to be sent (OUT endpoint) or received - * (IN endpoint). buffer must have been allocated using DRVR_ALLOC + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. + * ep - The IN or OUT endpoint descriptor for the device endpoint on + * which to perform the transfer. + * buffer - A buffer containing the data to be sent (OUT endpoint) or + * received (IN endpoint). buffer must have been allocated using + * DRVR_ALLOC * buflen - The length of the data to be sent or received. * callback - This function will be called when the transfer completes. - * arg - The arbitrary parameter that will be passed to the callback function - * when the transfer completes. + * arg - The arbitrary parameter that will be passed to the callback + * function when the transfer completes. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure. + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure. * * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #ifdef CONFIG_USBHOST_ASYNCH # define DRVR_ASYNCH(drvr,ep,buffer,buflen,callback,arg) \ ((drvr)->asynch(drvr,ep,buffer,buflen,callback,arg)) #endif -/************************************************************************************ +/**************************************************************************** * Name: DRVR_CANCEL * * Description: @@ -548,20 +564,20 @@ * asynchronous transfer will complete normally with the error -ESHUTDOWN. * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. - * ep - The IN or OUT endpoint descriptor for the device endpoint on which an - * asynchronous transfer should be transferred. + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. + * ep - The IN or OUT endpoint descriptor for the device endpoint on + * which an asynchronous transfer should be transferred. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure. + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure. * - ************************************************************************************/ + ****************************************************************************/ #define DRVR_CANCEL(drvr,ep) ((drvr)->cancel(drvr,ep)) -/************************************************************************************ +/**************************************************************************** * Name: DRVR_CONNECT * * Description: @@ -570,38 +586,39 @@ * and port description to the system. * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. * hport - The descriptor of the hub port that detected the connection * related event * connected - True: device connected; false: device disconnected * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure. + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure. * - ************************************************************************************/ + ****************************************************************************/ #ifdef CONFIG_USBHOST_HUB # define DRVR_CONNECT(drvr,hport,connected) \ ((drvr)->connect(drvr,hport,connected)) #endif -/************************************************************************************ +/**************************************************************************** * Name: DRVR_DISCONNECT * * Description: - * Called by the class when an error occurs and driver has been disconnected. - * The USB host driver should discard the handle to the class instance (it is - * stale) and not attempt any further interaction with the class driver instance - * (until a new instance is received from the create() method). The driver - * should not called the class' disconnected() method. + * Called by the class when an error occurs and driver has been + * disconnected. + * The USB host driver should discard the handle to the class instance + * (it is stale) and not attempt any further interaction with the class + * driver instance (until a new instance is received from the create() + * method). The driver should not called the class' disconnected() method. * * Input Parameters: - * drvr - The USB host driver instance obtained as a parameter from the call to - * the class create() method. - * hport - The port from which the device is being disconnected. Might be a port - * on a hub. + * drvr - The USB host driver instance obtained as a parameter from the + * call to the class create() method. + * hport - The port from which the device is being disconnected. + * Might be a port on a hub. * * Returned Value: * None @@ -609,16 +626,16 @@ * Assumptions: * This function will *not* be called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ #define DRVR_DISCONNECT(drvr, hport) ((drvr)->disconnect(drvr, hport)) -/************************************************************************************ +/**************************************************************************** * Public Types - ************************************************************************************/ + ****************************************************************************/ -/* This struct contains all of the information that is needed to associate a device - * this is connected via a USB port to a class. +/* This struct contains all of the information that is needed to associate a + * device this is connected via a USB port to a class. */ struct usbhost_id_s @@ -630,35 +647,38 @@ struct usbhost_id_s uint16_t pid; /* Product ID (for vendor/product specific devices) */ }; -/* The struct usbhost_registry_s type describes information that is kept in the - * USB host registry. USB host class implementations register this information so - * that USB host drivers can later find the class that matches the device that is - * connected to the USB port. +/* The struct usbhost_registry_s type describes information that is kept in + * the USB host registry. USB host class implementations register this + * information so that USB host drivers can later find the class that matches + * the device that is connected to the USB port. */ struct usbhost_hubport_s; /* Forward reference to the hub state structure */ struct usbhost_class_s; /* Forward reference to the class state structure */ struct usbhost_registry_s { - /* This field is used to implement a singly-link registry structure. Because of - * the presence of this link, provides of struct usbhost_registry_s instances must - * provide those instances in write-able memory (RAM). + /* This field is used to implement a singly-link registry structure. + * Because of the presence of this link, provides of struct + * usbhost_registry_s instances must provide those instances in write-able + * memory (RAM). */ FAR struct usbhost_registry_s *flink; - /* This is a callback into the class implementation. It is used to (1) create - * a new instance of the USB host class state and to (2) bind a USB host driver - * "session" to the class instance. Use of this create() method will support - * environments where there may be multiple USB ports and multiple USB devices - * simultaneously connected (see the CLASS_CREATE() macro above). + /* This is a callback into the class implementation. It is used to (1) + * create a new instance of the USB host class state and to (2) bind a + * USB host driver "session" to the class instance. Use of this create() + * method will support environments where there may be multiple USB ports + * and multiple USB devices simultaneously connected + * (see the CLASS_CREATE() macro above). */ - CODE FAR struct usbhost_class_s *(*create)(FAR struct usbhost_hubport_s *hub, - FAR const struct usbhost_id_s *id); + CODE FAR struct usbhost_class_s *(*create) + (FAR struct usbhost_hubport_s *hub, + FAR const struct usbhost_id_s *id); - /* This information uniquely identifies the USB host class implementation that - * goes with a specific USB device. + /* This information uniquely identifies the USB host class implementation + * that goes with a specific USB device. */ uint8_t nids; /* Number of IDs in the id[] array */ @@ -738,7 +758,9 @@ struct usbhost_class_s FAR const uint8_t *configdesc, int desclen); - /* This method informs the class that the USB device has been disconnected. */ + /* This method informs the class that the USB device has been + * disconnected. + */ CODE int (*disconnected)(FAR struct usbhost_class_s *devclass); }; @@ -759,9 +781,9 @@ struct usbhost_epdesc_s uint16_t mxpacketsize; /* Max packetsize */ }; -/* struct usbhost_connection_s provides as interface between platform-specific - * connection monitoring and the USB host driver connection and enumeration - * logic. +/* struct usbhost_connection_s provides as interface between + * platform-specific connection monitoring and the USB host driver + * connection and enumeration logic. */ struct usbhost_connection_s @@ -775,10 +797,10 @@ struct usbhost_connection_s * enumeration process, the driver will (1) get the device's configuration * descriptor, (2) extract the class ID info from the configuration * descriptor, (3) call usbhost_findclass() to find the class that supports - * this device, (4) call the create() method on the struct usbhost_registry_s - * interface to get a class instance, and finally (5) call the connect() - * method of the struct usbhost_class_s interface. After that, the class is - * in charge of the sequence of operations. + * this device, (4) call the create() method on the struct + * usbhost_registry_s interface to get a class instance, and finally (5) + * call the connect() method of the struct usbhost_class_s interface. + * After that, the class is in charge of the sequence of operations. */ CODE int (*enumerate)(FAR struct usbhost_connection_s *conn, @@ -822,22 +844,25 @@ struct usbhost_driver_s * hardware does not support such "special" memory, these functions may * simply map to kmm_malloc and kmm_free. * - * This interface was optimized under a particular assumption. It was assumed - * that the driver maintains a pool of small, pre-allocated buffers for descriptor - * traffic. NOTE that size is not an input, but an output: The size of the - * pre-allocated buffer is returned. + * This interface was optimized under a particular assumption. It was + * assumed that the driver maintains a pool of small, pre-allocated buffers + * for descriptor traffic. + * NOTE that size is not an input, but an output: + * The size of the pre-allocated buffer is returned. */ CODE int (*alloc)(FAR struct usbhost_driver_s *drvr, FAR uint8_t **buffer, FAR size_t *maxlen); CODE int (*free)(FAR struct usbhost_driver_s *drvr, FAR uint8_t *buffer); - /* Some hardware supports special memory in which larger IO buffers can - * be accessed more efficiently. This method provides a mechanism to allocate - * the request/descriptor memory. If the underlying hardware does not support - * such "special" memory, this functions may simply map to kmm_malloc. + /* Some hardware supports special memory in which larger IO buffers can + * be accessed more efficiently. This method provides a mechanism to + * allocate the request/descriptor memory. If the underlying hardware + * does not support such "special" memory, this functions may simply map + * to kmm_malloc. * - * This interface differs from DRVR_ALLOC in that the buffers are variable-sized. + * This interface differs from DRVR_ALLOC in that the buffers are + * variable-sized. */ CODE int (*ioalloc)(FAR struct usbhost_driver_s *drvr, @@ -846,9 +871,9 @@ struct usbhost_driver_s FAR uint8_t *buffer); /* Process a IN or OUT request on the control endpoint. These methods - * will enqueue the request and wait for it to complete. Only one transfer may - * be queued; Neither these methods nor the transfer() method can be called again - * until the control transfer methods returns. + * will enqueue the request and wait for it to complete. Only one transfer + * may be queued; Neither these methods nor the transfer() method can be + * called again until the control transfer methods returns. * * These are blocking methods; these methods will not return until the * control transfer has completed. @@ -891,7 +916,9 @@ struct usbhost_driver_s usbhost_asynch_t callback, FAR void *arg); #endif - /* Cancel any pending syncrhonous or asynchronous transfer on an endpoint */ + /* Cancel any pending syncrhonous or asynchronous transfer on an + * endpoint + */ CODE int (*cancel)(FAR struct usbhost_driver_s *drvr, usbhost_ep_t ep); @@ -906,19 +933,20 @@ struct usbhost_driver_s bool connected); #endif - /* Called by the class when an error occurs and driver has been disconnected. - * The USB host driver should discard the handle to the class instance (it is - * stale) and not attempt any further interaction with the class driver instance - * (until a new instance is received from the create() method). + /* Called by the class when an error occurs and driver has been + * disconnected. The USB host driver should discard the handle to the class + * instance (it is stale) and not attempt any further interaction with the + * class driver instance (until a new instance is received from the + * create() method). */ CODE void (*disconnect)(FAR struct usbhost_driver_s *drvr, FAR struct usbhost_hubport_s *hport); }; -/************************************************************************************ +/**************************************************************************** * Public Data - ************************************************************************************/ + ****************************************************************************/ #undef EXTERN #if defined(__cplusplus) @@ -929,57 +957,58 @@ extern "C" #define EXTERN extern #endif -/************************************************************************************ +/**************************************************************************** * Public Function Prototypes - ************************************************************************************/ + ****************************************************************************/ -/************************************************************************************ +/**************************************************************************** * Name: usbhost_registerclass * * Description: - * Register a USB host class implementation. The caller provides an instance of - * struct usbhost_registry_s that contains all of the information that will be - * needed later to (1) associate the USB host class implementation with a connected - * USB device, and (2) to obtain and bind a struct usbhost_class_s instance for - * the device. + * Register a USB host class implementation. The caller provides an + * instance of struct usbhost_registry_s that contains all of the + * information that will be needed later to (1) associate the USB host + * class implementation with a connected USB device, and (2) to obtain and + * bind a struct usbhost_class_s instance for the device. * * Input Parameters: - * devclass - An write-able instance of struct usbhost_registry_s that will be - * maintained in a registry. + * devclass - An write-able instance of struct usbhost_registry_s that will + * be maintained in a registry. * * Returned Value: - * On success, this function will return zero (OK). Otherwise, a negated errno - * value is returned. + * On success, this function will return zero (OK). Otherwise, a negated + * errno value is returned. * - ************************************************************************************/ + ****************************************************************************/ int usbhost_registerclass(FAR struct usbhost_registry_s *devclass); -/************************************************************************************ +/**************************************************************************** * Name: usbhost_findclass * * Description: * Find a USB host class implementation previously registered by - * usbhost_registerclass(). On success, an instance of struct usbhost_registry_s - * will be returned. That instance will contain all of the information that will - * be needed to obtain and bind a struct usbhost_class_s instance for the device. + * usbhost_registerclass(). On success, an instance of struct + * usbhost_registry_s will be returned. That instance will contain all of + * the information that will be needed to obtain and bind a struct + * usbhost_class_s instance for the device. * * Input Parameters: * id - Identifies the USB device class that has connect to the USB host. * * Returned Value: * On success this function will return a non-NULL instance of struct - * usbhost_registry_s. NULL will be returned on failure. This function can only - * fail if (1) id is NULL, or (2) no USB host class is registered that matches the - * device class ID. + * usbhost_registry_s. NULL will be returned on failure. This function + * can only fail if (1) id is NULL, or (2) no USB host class is registered + * that matches the device class ID. * - ************************************************************************************/ + ****************************************************************************/ const struct usbhost_registry_s * usbhost_findclass(FAR const struct usbhost_id_s *id); #ifdef CONFIG_USBHOST_HUB -/************************************************************************************ +/**************************************************************************** * Name: usbhost_hub_initialize * * Description: @@ -994,13 +1023,13 @@ const struct usbhost_registry_s * * On success this function will return zero (OK); A negated errno value * will be returned on failure. * - ************************************************************************************/ + ****************************************************************************/ int usbhost_hub_initialize(void); #endif #ifdef CONFIG_USBHOST_MSC -/************************************************************************************ +/**************************************************************************** * Name: usbhost_msc_initialize * * Description: @@ -1015,12 +1044,12 @@ int usbhost_hub_initialize(void); * On success this function will return zero (OK); A negated errno value * will be returned on failure. * - ************************************************************************************/ + ****************************************************************************/ int usbhost_msc_initialize(void); # ifdef CONFIG_USBHOST_MSC_NOTIFIER -/************************************************************************************ +/**************************************************************************** * Name: usbhost_msc_notifier_setup * * Description: @@ -1044,12 +1073,12 @@ int usbhost_msc_initialize(void); * returned value is a negated errno value that indicates the * nature of the failure. * - ************************************************************************************/ + ****************************************************************************/ int usbhost_msc_notifier_setup(worker_t worker, uint8_t event, char sdchar, FAR void *arg); -/************************************************************************************ +/**************************************************************************** * Name: usbhost_msc_notifier_teardown * * Description: @@ -1067,11 +1096,11 @@ int usbhost_msc_notifier_setup(worker_t worker, uint8_t event, char sdchar, * Zero (OK) is returned on success; a negated errno value is returned on * any failure. * - ************************************************************************************/ + ****************************************************************************/ int usbhost_msc_notifier_teardown(int key); -/************************************************************************************ +/**************************************************************************** * Name: usbhost_msc_notifier_signal * * Description: @@ -1085,7 +1114,7 @@ int usbhost_msc_notifier_teardown(int key); * Returned Value: * None. * - ************************************************************************************/ + ****************************************************************************/ void usbhost_msc_notifier_signal(uint8_t event, char sdchar); @@ -1093,7 +1122,7 @@ void usbhost_msc_notifier_signal(uint8_t event, char sdchar); #endif #ifdef CONFIG_USBHOST_CDCACM -/************************************************************************************ +/**************************************************************************** * Name: usbhost_cdcacm_initialize * * Description: @@ -1108,13 +1137,13 @@ void usbhost_msc_notifier_signal(uint8_t event, char sdchar); * On success this function will return zero (OK); A negated errno value * will be returned on failure. * - ************************************************************************************/ + ****************************************************************************/ int usbhost_cdcacm_initialize(void); #endif #ifdef CONFIG_USBHOST_FT232R -/************************************************************************************ +/**************************************************************************** * Name: usbhost_ft232r_initialize * * Description: @@ -1129,13 +1158,13 @@ int usbhost_cdcacm_initialize(void); * On success this function will return zero (OK); A negated errno value * will be returned on failure. * - ************************************************************************************/ + ****************************************************************************/ int usbhost_ft232r_initialize(void); #endif #ifdef CONFIG_USBHOST_HIDKBD -/************************************************************************************ +/**************************************************************************** * Name: usbhost_kbdinit * * Description: @@ -1150,13 +1179,13 @@ int usbhost_ft232r_initialize(void); * On success this function will return zero (OK); A negated errno value * will be returned on failure. * - ************************************************************************************/ + ****************************************************************************/ int usbhost_kbdinit(void); #endif #ifdef CONFIG_USBHOST_HIDMOUSE -/************************************************************************************ +/**************************************************************************** * Name: usbhost_mouse_init * * Description: @@ -1171,13 +1200,13 @@ int usbhost_kbdinit(void); * On success this function will return zero (OK); A negated errno value * will be returned on failure. * - ************************************************************************************/ + ****************************************************************************/ int usbhost_mouse_init(void); #endif #ifdef CONFIG_USBHOST_XBOXCONTROLLER -/************************************************************************************ +/**************************************************************************** * Name: usbhost_xboxcontroller_init * * Description: @@ -1192,12 +1221,12 @@ int usbhost_mouse_init(void); * On success this function will return zero (OK); A negated errno value * will be returned on failure. * - ************************************************************************************/ + ****************************************************************************/ int usbhost_xboxcontroller_init(void); #endif -/************************************************************************************ +/**************************************************************************** * Name: usbhost_wlaninit * * Description: @@ -1212,17 +1241,17 @@ int usbhost_xboxcontroller_init(void); * On success this function will return zero (OK); A negated errno value * will be returned on failure. * - ************************************************************************************/ + ****************************************************************************/ int usbhost_wlaninit(void); -/************************************************************************************ +/**************************************************************************** * Name: usbhost_enumerate * * Description: * This is a share-able implementation of most of the logic required by the - * driver enumerate() method. This logic within this method should be common - * to all USB host drivers. + * driver enumerate() method. This logic within this method should be + * common to all USB host drivers. * * Enumerate the connected device. As part of this enumeration process, * the driver will (1) get the device's configuration descriptor, (2) @@ -1240,15 +1269,15 @@ int usbhost_wlaninit(void); * this caller-provided memory location. * * Returned Value: - * On success, zero (OK) is returned. On a failure, a negated errno value is - * returned indicating the nature of the failure + * On success, zero (OK) is returned. On a failure, a negated errno value + * is returned indicating the nature of the failure * * Assumptions: * - Only a single class bound to a single device is supported. * - Called from a single thread so no mutual exclusion is required. * - Never called from an interrupt handler. * - ************************************************************************************/ + ****************************************************************************/ int usbhost_enumerate(FAR struct usbhost_hubport_s *hub, FAR struct usbhost_class_s **devclass); diff --git a/include/nuttx/usb/usbhost_devaddr.h b/include/nuttx/usb/usbhost_devaddr.h index 9909141431..cda39285ff 100644 --- a/include/nuttx/usb/usbhost_devaddr.h +++ b/include/nuttx/usb/usbhost_devaddr.h @@ -87,7 +87,7 @@ extern "C" #endif /**************************************************************************** - * Public Functions + * Public Functions Definitions ****************************************************************************/ struct usbhost_hubport_s; /* Forward reference */ @@ -133,12 +133,12 @@ int usbhost_devaddr_create(FAR struct usbhost_hubport_s *hport); * Name: usbhost_devaddr_destroy * * Description: - * Release a device address previously assigned by usbhost_devaddr_create(). + * Release a device address previously assigned by usbhost_devaddr_create(). * * Input Parameters: - * hport - A reference to a hub port structure from which a device has been + * hport - A reference to a hub port structure from which a device has been * disconnected and so no longer needs the function address. - * devaddr - The address to be released. + * devaddr - The address to be released. * * Returned Value: * None diff --git a/include/nuttx/usb/usbhost_trace.h b/include/nuttx/usb/usbhost_trace.h index 61db2d16dc..4116b5ecff 100644 --- a/include/nuttx/usb/usbhost_trace.h +++ b/include/nuttx/usb/usbhost_trace.h @@ -45,7 +45,9 @@ /**************************************************************************** * Pre-processor definitions ****************************************************************************/ + /* Configuration ************************************************************/ + /* Debug/Trace-related definitions */ #ifndef CONFIG_DEBUG_FEATURES @@ -57,7 +59,9 @@ # undef CONFIG_USBHOST_TRACE_VERBOSE #endif -/* Trace support is needed if either USB host tracing or USB debug output is enabled */ +/* Trace support is needed if either USB host tracing or USB debug output is + * enabled + */ #if defined(CONFIG_USBHOST_TRACE) || defined(CONFIG_DEBUG_USB) # define HAVE_USBHOST_TRACE 1 @@ -101,7 +105,7 @@ extern "C" #endif /**************************************************************************** - * Public Functions + * Public Functions Definitions ****************************************************************************/ /**************************************************************************** diff --git a/include/nuttx/usb/usbmsc.h b/include/nuttx/usb/usbmsc.h index dd5796c580..e96d6dd3f9 100644 --- a/include/nuttx/usb/usbmsc.h +++ b/include/nuttx/usb/usbmsc.h @@ -85,7 +85,7 @@ extern "C" #endif /**************************************************************************** - * Public Functions + * Public Functions Definitions ****************************************************************************/ /**************************************************************************** @@ -133,8 +133,12 @@ int usbmsc_configure(unsigned int nluns, FAR void **handle); * ****************************************************************************/ -int usbmsc_bindlun(FAR void *handle, FAR const char *drvrpath, unsigned int lunno, - off_t startsector, size_t nsectors, bool readonly); +int usbmsc_bindlun(FAR void *handle, + FAR const char *drvrpath, + unsigned int lunno, + off_t startsector, + size_t nsectors, + bool readonly); /**************************************************************************** * Name: usbmsc_unbindlun @@ -187,7 +191,8 @@ int usbmsc_exportluns(FAR void *handle); #if defined(CONFIG_USBDEV_COMPOSITE) && defined(CONFIG_USBMSC_COMPOSITE) struct usbdevclass_driver_s; -int usbmsc_classobject(FAR void *handle, FAR struct usbdev_devinfo_s *devinfo, +int usbmsc_classobject(FAR void *handle, + FAR struct usbdev_devinfo_s *devinfo, FAR struct usbdevclass_driver_s **classdev); #endif @@ -214,8 +219,8 @@ void usbmsc_uninitialize(FAR void *handle); * Name: usbmsc_get_composite_devdesc * * Description: - * Helper function to fill in some constants into the composite configuration - * structure. + * Helper function to fill in some constants into the composite + * configuration structure. * * Input Parameters: * dev - Pointer to the configuration struct we should fill