1 /* 2 * Copyright (c) 2016, Freescale Semiconductor, Inc. 3 * Copyright 2016 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 9 #ifndef __USB_OTG_H__ 10 #define __USB_OTG_H__ 11 12 #include "usb.h" 13 #include "usb_misc.h" 14 #include "usb_spec.h" 15 16 /*! 17 * @addtogroup usb_otg_drv 18 * @{ 19 */ 20 21 /******************************************************************************* 22 * Definitions 23 ******************************************************************************/ 24 /*! @brief USB OTG task message queue count */ 25 #define USB_OTG_MSG_COUNT (8) 26 27 /*! @brief USB OTG host request flag */ 28 #define USB_OTG_STATUS_HOST_REQUEST_FLAG (0x01U) 29 30 /*! @brief USB OTG controller handle type define */ 31 typedef void *usb_otg_controller_handle; 32 33 /*! @brief please reference to 7.4 in OTG spec */ 34 typedef enum _usb_otg_status_type 35 { 36 kOtg_StatusId = 0x0001U, /*! id */ 37 kOtg_StatusAdpChange = 0x0002U, /*! adp_change */ 38 kOtg_StatusSrpDet = 0x0004U, /*! a_srp_det */ 39 kOtg_StatusVbusVld = 0x0008U, /*! a_vbus_vld */ 40 kOtg_StatusAConn = 0x0010U, /*! a_conn */ 41 kOtg_StatusBusResume = 0x0020U, /*! a_bus_resume */ 42 kOtg_StatusBusSuspend = 0x0040U, /*! a_bus_suspend */ 43 kOtg_StatusSe0Srp = 0x0080U, /*! b_se0_srp */ 44 kOtg_StatusSsendSrp = 0x0100U, /*! b_ssend_srp */ 45 kOtg_StatusSessVld = 0x0200U, /*! b_sess_vld */ 46 kOtg_StatusBusDrop = 0x0400U, /*! a_bus_drop */ 47 kOtg_StatusBusReq = 0x0800U, /*! a_bus_req and b_bus_req */ 48 kOtg_StatusPowerUp = 0x1000U, /*! power_up */ 49 kOtg_StatusTimeOut = 0x2000U, /*! all the timeout in the state machine */ 50 kOtg_StatusBConn = 0x4000U, /*! b_conn */ 51 kOtg_StatusClrErr = 0x8000U, /*! a_clr_err */ 52 kOtg_StatusBSrpDone = 0x10000U, /*! b_srp_done */ 53 kOtg_StatusADisconn = 0x20000U, /*! a_conn(non) */ 54 kOtg_StatusBDisconn = 0x40000U, /*! b_conn(non) */ 55 kOtg_StatusVbusInvld = 0x80000U, /*! a_vbus_vld(non) */ 56 kOtg_StatusSessInvld = 0x100000U, /*! b_sess_vld(non) */ 57 kOtg_StatusCheckIdleInAPeripheral = 0x200000U, /*! check the idle timeout when in a_peripheral state */ 58 59 kOtg_StatusBHNPFeature = 0x40000000U, /*! This status is valid when 60 (1) b_hnp_enable feature is sent when A-device works as host; Or 61 (2) b_hnp_enable feature is received when B-device works as device */ 62 kOtg_StatusChange = (int)0x80000000U, /*! there are status change, need call control interface 63 (kOtg_ControlUpdateStatus) to update status */ 64 } usb_otg_status_type_t; 65 66 /*! @brief Please reference to chapter 7 in OTG spec */ 67 typedef enum _usb_otg_device_state 68 { 69 kOtg_State_Start = 0U, /*! state state */ 70 kOtg_State_AIdle, /*! a_idle state */ 71 kOtg_State_AWaitVrise, /*! a_wait_vrise state */ 72 kOtg_State_AWaitBcon, /*! a_wait_bcon state */ 73 kOtg_State_AHost, /*! a_host state */ 74 kOtg_State_AWaitVfall, /*! a_wait_vfall state */ 75 kOtg_State_ASuspend, /*! a_suspend state */ 76 kOtg_State_APeripheral, /*! a_peripheral state */ 77 kOtg_State_AVbusErr, /*! a_vbus_err state */ 78 79 kOtg_State_BIdleEh, /*! b_idle_eh state */ 80 kOtg_State_BIdle, /*! b_idle or bp_idle state, when the device is peripheral-only B-device it means bp_idle */ 81 kOtg_State_BSrpInit, /*! b_srp_init or bp_srp_init state, when the device is peripheral-only B-device it means 82 bp_srp_init */ 83 kOtg_State_BPeripheral, /*! b_peripheral or bp_peripheral state, when the device is peripheral-only B-device it 84 means bp_peripheral */ 85 kOtg_State_BWaitAcon, /*! b_wait_acon state */ 86 kOtg_State_BHost, /*! b_host state */ 87 } usb_otg_device_state_t; 88 89 /*! @brief The event value for callback to applcation when event type is kOtg_EventStackInit */ 90 typedef enum _usb_otg_stack_init_type 91 { 92 kOtg_StackNone = 0U, /*! default state */ 93 kOtg_StackHostInit, /*! notify application to initialize host stack */ 94 kOtg_StackHostDeinit, /*! notify application to de-initialize host stack */ 95 kOtg_StackDeviceInit, /*! notify application to initialize device stack */ 96 kOtg_StackDeviceDeinit, /*! notify application to de-initialize device stack */ 97 } usb_otg_stack_init_type_t; 98 99 /*! @brief The event types for callback to applcation */ 100 typedef enum _usb_otg_event_type 101 { 102 /*! OTG state change event, the event values are #usb_otg_device_state_t */ 103 kOtg_EventStateChange = 0U, 104 /*! host/device stack handle event, the event values are #usb_otg_stack_init_type_t */ 105 kOtg_EventStackInit, 106 } usb_otg_event_type_t; 107 108 /*! @brief USB OTG descriptor */ 109 typedef struct _usb_otg_descriptor 110 { 111 /*! Size of Descriptor */ 112 uint8_t bLength; 113 /*! OTG type = 9 */ 114 uint8_t bDescriptorType; 115 /*! @brief Attribute Fields 116 * 117 * D7..3: Reserved (reset to zero) 118 * D2: ADP support 119 * D1: HNP support 120 * D0: SRP support 121 */ 122 uint8_t bmAttributes; 123 /*! OTG and EH supplement release number in binary-coded decimal */ 124 uint8_t bcdOTG[2]; 125 } usb_otg_descriptor_t; 126 127 /*! 128 * @brief OTG callback function typedef. 129 * 130 * This callback function is used to notify application events, the events include #usb_otg_event_type_t. 131 * This callback pointer is passed when initializing OTG. 132 * 133 * @param param The assigned parameter when initializing OTG. 134 * @param eventType Please reference to #usb_otg_event_type_t. 135 * @param event_code Please reference to #usb_otg_device_state_t and #usb_otg_stack_init_type_t. 136 */ 137 typedef void (*usb_otg_callback_t)(void *param, uint8_t eventType, uint32_t eventValue); 138 139 /******************************************************************************* 140 * API 141 ******************************************************************************/ 142 #ifdef __cplusplus 143 extern "C" { 144 #endif 145 146 /*! 147 * @name USB OTG APIs 148 * @{ 149 */ 150 151 /*! 152 * @brief Initializes the USB OTG stack. 153 * 154 * This function initializes the USB OTG module specified by the controllerId. 155 * 156 * @param[in] controllerId The controller ID of the USB IP. See the enumeration #usb_controller_index_t. 157 * @param[out] otgHandle Return the OTG handle. 158 * @param[in] otgCallbackFn OTG callback function, it is #usb_otg_callback_t. 159 * @param[in] callbackParameter The callback parameter. 160 * 161 * @retval kStatus_USB_Success The OTG is initialized successfully. 162 * @retval kStatus_USB_InvalidHandle The otgHandle is a NULL pointer. 163 * @retval kStatus_USB_AllocFail Allocation memory fail. 164 * @retval kStatus_USB_Error message queue create fail, controller is not fount, controller initialize 165 * fail. 166 */ 167 usb_status_t USB_OtgInit(uint8_t controllerId, 168 usb_otg_handle *otgHandle, 169 usb_otg_callback_t otgCallbackFn, 170 void *callbackParameter); 171 172 /*! 173 * @brief Deinitializes the USB OTG stack. 174 * 175 * This function deinitializes the USB OTG module specified by the otgHandle. 176 * 177 * @param[in] otgHandle the OTG handle. 178 * 179 * @retval kStatus_USB_Success The OTG is initialized successfully. 180 * @retval kStatus_USB_InvalidHandle The otgHandle is a NULL pointer. 181 * @retval kStatus_USB_Error Controller deinitialization fail. 182 */ 183 usb_status_t USB_OtgDeinit(usb_otg_handle otgHandle); 184 185 /*! 186 * @brief OTG stack task function. 187 * 188 * The function implement the OTG stack state machine. 189 * In bare metal environment, this function should be called periodically in the main function. 190 * In the RTOS environment, this function should be used as a function entry to create a task. 191 * 192 * @param[in] otgHandle The OTG handle. 193 */ 194 void USB_OtgTaskFunction(usb_otg_handle otgHandle); 195 196 /*! 197 * @brief OTG KHCI ISR function. 198 * 199 * The function is the KHCI interrupt service routine. 200 * 201 * @param[in] otgHandle The OTG handle. 202 */ 203 void USB_OtgKhciIsrFunction(usb_otg_handle otgHandle); 204 205 /*! 206 * @brief A-device drop bus. 207 * 208 * This function drop the bus. 209 * 210 * @param[in] otgHandle the OTG handle. 211 * @param[in] drop 1 or 0. 212 * 213 * @retval kStatus_USB_Success Success. 214 * @retval kStatus_USB_InvalidHandle The otgHandle is a NULL pointer. 215 * @retval kStatus_USB_Error The device is not A-device or Send message error. 216 */ 217 usb_status_t USB_OtgBusDrop(usb_otg_handle otgHandle, uint8_t drop); 218 219 /*! 220 * @brief bus request. 221 * 222 * This function can be called in the follow situations: 223 * 1. A-device request bus, change from a_idle to a_wait_vrise. 224 * 2. HNP, B-device is in the b_peripheral and request the bus. 225 * 3. A-device is in the a_peripheral and request the bus. 226 * 4. B-device request bus (SRP), change from b_idle to b_srp_init 227 * 5. Poll device status, "host request flag" is set. 228 * 229 * @param[in] otgHandle the OTG handle. 230 * 231 * @retval kStatus_USB_Success Success. 232 * @retval kStatus_USB_InvalidHandle The otgHandle is a NULL pointer. 233 * @retval kStatus_USB_Error Send message error. 234 */ 235 usb_status_t USB_OtgBusRequest(usb_otg_handle otgHandle); 236 237 /*! 238 * @brief bus request. 239 * 240 * This function can be called in the follow situations: 241 * 1. A-device set the bus request false when in a_idle. 242 * 2. A-device release bus when A-device is host (a_host). 243 * 3. B-device release bus when B-device is host (b_host). 244 * 245 * @param[in] otgHandle the OTG handle. 246 * 247 * @retval kStatus_USB_Success Success. 248 * @retval kStatus_USB_InvalidHandle The otgHandle is a NULL pointer. 249 * @retval kStatus_USB_Error Send message error. 250 */ 251 usb_status_t USB_OtgBusRelease(usb_otg_handle otgHandle); 252 253 /*! 254 * @brief clear error. 255 * 256 * This function clears the error. 257 * 258 * @param[in] otgHandle the OTG handle. 259 * 260 * @retval kStatus_USB_Success Success. 261 * @retval kStatus_USB_InvalidHandle The otgHandle is a NULL pointer. 262 * @retval kStatus_USB_Error The device is not in error state or send message error. 263 */ 264 usb_status_t USB_OtgClearError(usb_otg_handle otgHandle); 265 266 /*! 267 * @brief Notify OTG stack about the status changes. 268 * 269 * This function notify the #usb_otg_status_type_t and values. 270 * 271 * @param[in] otgHandle the OTG handle. 272 * @param[in] statusType please reference to #usb_otg_status_type_t 273 * @param[in] statusValue the value is 1 or 0 274 * 275 * @retval kStatus_USB_Success Success. 276 * @retval kStatus_USB_InvalidHandle The otgHandle is a NULL pointer. 277 * @retval kStatus_USB_Error Send message error. 278 */ 279 usb_status_t USB_OtgNotifyChange(usb_otg_handle otgHandle, uint32_t statusType, uint32_t statusValue); 280 281 /*! @}*/ 282 283 #ifdef __cplusplus 284 } 285 #endif 286 287 /*! @}*/ 288 289 #endif /* __USB_OTG_H__ */ 290
