1 /* 2 * Copyright (c) 2021-2025, STMicroelectronics - All Rights Reserved 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef USB_DEVICE_H 8 #define USB_DEVICE_H 9 10 #include <stdbool.h> 11 #include <stdint.h> 12 13 #include <lib/utils_def.h> 14 15 /* Define for EP address */ 16 #define EP_DIR_MASK BIT(7) 17 #define EP_DIR_IN BIT(7) 18 #define EP_NUM_MASK GENMASK(3, 0) 19 20 #define EP0_IN (0U | EP_DIR_IN) 21 #define EP0_OUT 0U 22 23 /* USB address between 1 through 127 = 0x7F mask */ 24 #define ADDRESS_MASK GENMASK(6, 0) 25 26 #define USBD_MAX_NUM_INTERFACES 1U 27 #define USBD_MAX_NUM_CONFIGURATION 1U 28 29 #define USB_LEN_DEV_QUALIFIER_DESC 0x0AU 30 #define USB_LEN_DEV_DESC 0x12U 31 #define USB_LEN_CFG_DESC 0x09U 32 #define USB_LEN_IF_DESC 0x09U 33 #define USB_LEN_EP_DESC 0x07U 34 #define USB_LEN_OTG_DESC 0x03U 35 #define USB_LEN_LANGID_STR_DESC 0x04U 36 #define USB_LEN_OTHER_SPEED_DESC_SIZ 0x09U 37 38 #define USBD_IDX_LANGID_STR 0x00U 39 #define USBD_IDX_MFC_STR 0x01U 40 #define USBD_IDX_PRODUCT_STR 0x02U 41 #define USBD_IDX_SERIAL_STR 0x03U 42 #define USBD_IDX_CONFIG_STR 0x04U 43 #define USBD_IDX_INTERFACE_STR 0x05U 44 #define USBD_IDX_USER0_STR 0x06U 45 46 #define USB_REQ_TYPE_STANDARD 0x00U 47 #define USB_REQ_TYPE_CLASS 0x20U 48 #define USB_REQ_TYPE_VENDOR 0x40U 49 #define USB_REQ_TYPE_MASK 0x60U 50 51 #define USB_REQ_RECIPIENT_DEVICE 0x00U 52 #define USB_REQ_RECIPIENT_INTERFACE 0x01U 53 #define USB_REQ_RECIPIENT_ENDPOINT 0x02U 54 #define USB_REQ_RECIPIENT_MASK 0x1FU 55 56 #define USB_REQ_DIRECTION 0x80U 57 58 #define USB_REQ_GET_STATUS 0x00U 59 #define USB_REQ_CLEAR_FEATURE 0x01U 60 #define USB_REQ_SET_FEATURE 0x03U 61 #define USB_REQ_SET_ADDRESS 0x05U 62 #define USB_REQ_GET_DESCRIPTOR 0x06U 63 #define USB_REQ_SET_DESCRIPTOR 0x07U 64 #define USB_REQ_GET_CONFIGURATION 0x08U 65 #define USB_REQ_SET_CONFIGURATION 0x09U 66 #define USB_REQ_GET_INTERFACE 0x0AU 67 #define USB_REQ_SET_INTERFACE 0x0BU 68 #define USB_REQ_SYNCH_FRAME 0x0CU 69 70 #define USB_DESC_TYPE_DEVICE 0x01U 71 #define USB_DESC_TYPE_CONFIGURATION 0x02U 72 #define USB_DESC_TYPE_STRING 0x03U 73 #define USB_DESC_TYPE_INTERFACE 0x04U 74 #define USB_DESC_TYPE_ENDPOINT 0x05U 75 #define USB_DESC_TYPE_DEVICE_QUALIFIER 0x06U 76 #define USB_DESC_TYPE_OTHER_SPEED_CONFIGURATION 0x07U 77 #define USB_DESC_TYPE_BOS 0x0FU 78 79 #define USB_CONFIG_REMOTE_WAKEUP 2U 80 #define USB_CONFIG_SELF_POWERED 1U 81 82 #define USB_MAX_EP0_SIZE 64U 83 84 /* Device Status */ 85 #define USBD_STATE_DEFAULT 1U 86 #define USBD_STATE_ADDRESSED 2U 87 #define USBD_STATE_CONFIGURED 3U 88 #define USBD_STATE_SUSPENDED 4U 89 90 /* EP0 State */ 91 #define USBD_EP0_IDLE 0U 92 #define USBD_EP0_SETUP 1U 93 #define USBD_EP0_DATA_IN 2U 94 #define USBD_EP0_DATA_OUT 3U 95 #define USBD_EP0_STATUS_IN 4U 96 #define USBD_EP0_STATUS_OUT 5U 97 #define USBD_EP0_STALL 6U 98 99 #define USBD_EP_TYPE_CTRL 0U 100 #define USBD_EP_TYPE_ISOC 1U 101 #define USBD_EP_TYPE_BULK 2U 102 #define USBD_EP_TYPE_INTR 3U 103 104 #define USBD_OUT_EPNUM_MASK GENMASK(15, 0) 105 #define USBD_OUT_COUNT_MASK GENMASK(31, 16) 106 #define USBD_OUT_COUNT_SHIFT 16U 107 108 /* Number of EP supported, allow to reduce footprint: default max = 15 */ 109 #ifndef CONFIG_USBD_EP_NB 110 #define USBD_EP_NB 15U 111 #else 112 #define USBD_EP_NB CONFIG_USBD_EP_NB 113 #endif 114 115 #define LOBYTE(x) ((uint8_t)((x) & 0x00FF)) 116 #define HIBYTE(x) ((uint8_t)(((x) & 0xFF00) >> 8)) 117 118 struct usb_setup_req { 119 uint8_t bm_request; 120 uint8_t b_request; 121 uint16_t value; 122 uint16_t index; 123 uint16_t length; 124 }; 125 126 struct usb_handle; 127 128 struct usb_class { 129 uint8_t (*init)(struct usb_handle *pdev, uint8_t cfgidx); 130 uint8_t (*de_init)(struct usb_handle *pdev, uint8_t cfgidx); 131 /* Control Endpoints */ 132 uint8_t (*setup)(struct usb_handle *pdev, struct usb_setup_req *req); 133 uint8_t (*ep0_tx_sent)(struct usb_handle *pdev); 134 uint8_t (*ep0_rx_ready)(struct usb_handle *pdev); 135 /* Class Specific Endpoints */ 136 uint8_t (*data_in)(struct usb_handle *pdev, uint8_t epnum); 137 uint8_t (*data_out)(struct usb_handle *pdev, uint8_t epnum); 138 uint8_t (*sof)(struct usb_handle *pdev); 139 uint8_t (*iso_in_incomplete)(struct usb_handle *pdev, uint8_t epnum); 140 uint8_t (*iso_out_incomplete)(struct usb_handle *pdev, uint8_t epnum); 141 }; 142 143 /* Following USB Device status */ 144 enum usb_status { 145 USBD_OK = 0U, 146 USBD_BUSY, 147 USBD_FAIL, 148 USBD_TIMEOUT 149 }; 150 151 /* Action to do after IT handling */ 152 enum usb_action { 153 USB_NOTHING = 0U, 154 USB_DATA_OUT, 155 USB_DATA_IN, 156 USB_SETUP, 157 USB_ENUM_DONE, 158 USB_READ_DATA_PACKET, 159 USB_READ_SETUP_PACKET, 160 USB_RESET, 161 USB_RESUME, 162 USB_SUSPEND, 163 USB_LPM, 164 USB_SOF, 165 USB_DISCONNECT, 166 USB_WRITE_EMPTY 167 }; 168 169 /* USB Device descriptors structure */ 170 struct usb_desc { 171 uint8_t *(*get_device_desc)(uint16_t *length); 172 uint8_t *(*get_lang_id_desc)(uint16_t *length); 173 uint8_t *(*get_manufacturer_desc)(uint16_t *length); 174 uint8_t *(*get_product_desc)(uint16_t *length); 175 uint8_t *(*get_serial_desc)(uint16_t *length); 176 uint8_t *(*get_configuration_desc)(uint16_t *length); 177 uint8_t *(*get_interface_desc)(uint16_t *length); 178 uint8_t *(*get_usr_desc)(uint8_t index, uint16_t *length); 179 uint8_t *(*get_config_desc)(uint16_t *length); 180 uint8_t *(*get_device_qualifier_desc)(uint16_t *length); 181 /* optional: high speed capable device operating at its other speed */ 182 uint8_t *(*get_other_speed_config_desc)(uint16_t *length); 183 }; 184 185 /* USB Device handle structure */ 186 struct usb_endpoint { 187 uint32_t status; 188 uint32_t total_length; 189 uint32_t rem_length; 190 uint32_t maxpacket; 191 }; 192 193 /* 194 * EndPoint descriptor 195 * num : Endpoint number, between 0 and 15 (limited by USBD_EP_NB) 196 * is_in: Endpoint direction 197 * type : Endpoint type 198 * maxpacket: Endpoint Max packet size: between 0 and 64KB 199 * xfer_buff: Pointer to transfer buffer 200 * xfer_len: Current transfer lengt 201 * hxfer_count: Partial transfer length in case of multi packet transfer 202 */ 203 struct usbd_ep { 204 uint8_t num; 205 bool is_in; 206 uint8_t type; 207 uint32_t maxpacket; 208 uint8_t *xfer_buff; 209 uint32_t xfer_len; 210 uint32_t xfer_count; 211 }; 212 213 enum pcd_lpm_state { 214 LPM_L0 = 0x00U, /* on */ 215 LPM_L1 = 0x01U, /* LPM L1 sleep */ 216 LPM_L2 = 0x02U, /* suspend */ 217 LPM_L3 = 0x03U, /* off */ 218 }; 219 220 /* USB Device descriptors structure */ 221 struct usb_driver { 222 enum usb_status (*ep0_out_start)(void *handle); 223 enum usb_status (*ep_start_xfer)(void *handle, struct usbd_ep *ep); 224 enum usb_status (*ep0_start_xfer)(void *handle, struct usbd_ep *ep); 225 enum usb_status (*write_packet)(void *handle, uint8_t *src, 226 uint8_t ch_ep_num, uint16_t len); 227 void *(*read_packet)(void *handle, uint8_t *dest, uint16_t len); 228 enum usb_status (*ep_set_stall)(void *handle, struct usbd_ep *ep); 229 enum usb_status (*start_device)(void *handle); 230 enum usb_status (*stop_device)(void *handle); 231 enum usb_status (*set_address)(void *handle, uint8_t address); 232 enum usb_status (*write_empty_tx_fifo)(void *handle, 233 uint32_t epnum, uint32_t xfer_len, 234 uint32_t *xfer_count, 235 uint32_t maxpacket, 236 uint8_t **xfer_buff); 237 enum usb_action (*it_handler)(void *handle, uint32_t *param); 238 }; 239 240 /* USB Peripheral Controller Drivers */ 241 struct pcd_handle { 242 void *instance; /* Register base address */ 243 struct usbd_ep in_ep[USBD_EP_NB]; /* IN endpoint parameters */ 244 struct usbd_ep out_ep[USBD_EP_NB]; /* OUT endpoint parameters */ 245 uint32_t setup[12]; /* Setup packet buffer */ 246 enum pcd_lpm_state lpm_state; /* LPM State */ 247 }; 248 249 /* USB Device handle structure */ 250 struct usb_handle { 251 uint8_t id; 252 uint32_t dev_config; 253 uint32_t dev_config_status; 254 struct usb_endpoint ep_in[USBD_EP_NB]; 255 struct usb_endpoint ep_out[USBD_EP_NB]; 256 uint32_t ep0_state; 257 uint32_t ep0_data_len; 258 uint8_t dev_state; 259 uint8_t dev_old_state; 260 uint8_t dev_address; 261 uint32_t dev_remote_wakeup; 262 struct usb_setup_req request; 263 const struct usb_desc *desc; 264 struct usb_class *class; 265 void *class_data; 266 void *user_data; 267 struct pcd_handle *data; 268 const struct usb_driver *driver; 269 }; 270 271 enum usb_status usb_core_handle_it(struct usb_handle *pdev); 272 enum usb_status usb_core_receive(struct usb_handle *pdev, uint8_t ep_addr, 273 uint8_t *p_buf, uint32_t len); 274 enum usb_status usb_core_transmit(struct usb_handle *pdev, uint8_t ep_addr, 275 uint8_t *p_buf, uint32_t len); 276 enum usb_status usb_core_receive_ep0(struct usb_handle *pdev, uint8_t *p_buf, 277 uint32_t len); 278 enum usb_status usb_core_transmit_ep0(struct usb_handle *pdev, uint8_t *p_buf, 279 uint32_t len); 280 void usb_core_ctl_error(struct usb_handle *pdev); 281 enum usb_status usb_core_start(struct usb_handle *pdev); 282 enum usb_status usb_core_stop(struct usb_handle *pdev); 283 enum usb_status register_usb_driver(struct usb_handle *pdev, 284 struct pcd_handle *pcd_handle, 285 const struct usb_driver *driver, 286 void *driver_handle); 287 enum usb_status register_platform(struct usb_handle *pdev, 288 const struct usb_desc *plat_call_back); 289 290 #endif /* USB_DEVICE_H */ 291