1 /* 2 * Copyright (c) 2015, Freescale Semiconductor, Inc. 3 * Copyright 2016,2019 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 #ifndef _USB_DEVICE_CDC_ACM_H_ 9 #define _USB_DEVICE_CDC_ACM_H_ 10 11 /*! 12 * @addtogroup cdc_acm 13 * @{ 14 */ 15 16 /******************************************************************************* 17 * Definitions 18 ******************************************************************************/ 19 #define USB_DEVICE_CONFIG_CDC_ACM_MAX_INSTANCE (1U) /*!< The maximum number of CDC device instance. */ 20 #define USB_DEVICE_CONFIG_CDC_COMM_CLASS_CODE (0x02U) /*!< The CDC communication class code. */ 21 #define USB_DEVICE_CONFIG_CDC_DATA_CLASS_CODE (0x0AU) /*!< The CDC data class code. */ 22 23 #define USB_DEVICE_CDC_REQUEST_SEND_ENCAPSULATED_COMMAND \ 24 (0x00U) /*!< The CDC class request code for SEND_ENCAPSULATED_COMMAND. */ 25 #define USB_DEVICE_CDC_REQUEST_GET_ENCAPSULATED_RESPONSE \ 26 (0x01U) /*!< The CDC class request code for GET_ENCAPSULATED_RESPONSE. */ 27 #define USB_DEVICE_CDC_REQUEST_SET_COMM_FEATURE (0x02U) /*!< The CDC class request code for SET_COMM_FEATURE. */ 28 #define USB_DEVICE_CDC_REQUEST_GET_COMM_FEATURE (0x03U) /*!< The CDC class request code for GET_COMM_FEATURE. */ 29 #define USB_DEVICE_CDC_REQUEST_CLEAR_COMM_FEATURE (0x04U) /*!< The CDC class request code for CLEAR_COMM_FEATURE. */ 30 #define USB_DEVICE_CDC_REQUEST_SET_AUX_LINE_STATE (0x10U) /*!< The CDC class request code for SET_AUX_LINE_STATE. */ 31 #define USB_DEVICE_CDC_REQUEST_SET_HOOK_STATE (0x11U) /*!< The CDC class request code for SET_HOOK_STATE. */ 32 #define USB_DEVICE_CDC_REQUEST_PULSE_SETUP (0x12U) /*!< The CDC class request code for PULSE_SETUP. */ 33 #define USB_DEVICE_CDC_REQUEST_SEND_PULSE (0x13U) /*!< The CDC class request code for SEND_PULSE. */ 34 #define USB_DEVICE_CDC_REQUEST_SET_PULSE_TIME (0x14U) /*!< The CDC class request code for SET_PULSE_TIME. */ 35 #define USB_DEVICE_CDC_REQUEST_RING_AUX_JACK (0x15U) /*!< The CDC class request code for RING_AUX_JACK. */ 36 #define USB_DEVICE_CDC_REQUEST_SET_LINE_CODING (0x20U) /*!< The CDC class request code for SET_LINE_CODING. */ 37 #define USB_DEVICE_CDC_REQUEST_GET_LINE_CODING (0x21U) /*!< The CDC class request code for GET_LINE_CODING. */ 38 #define USB_DEVICE_CDC_REQUEST_SET_CONTROL_LINE_STATE \ 39 (0x22U) /*!< The CDC class request code for SET_CONTROL_LINE_STATE. */ 40 #define USB_DEVICE_CDC_REQUEST_SEND_BREAK (0x23U) /*!< The CDC class request code for SEND_BREAK. */ 41 #define USB_DEVICE_CDC_REQUEST_SET_RINGER_PARAMS (0x30U) /*!< The CDC class request code for SET_RINGER_PARAMS. */ 42 #define USB_DEVICE_CDC_REQUEST_GET_RINGER_PARAMS (0x31U) /*!< The CDC class request code for GET_RINGER_PARAMS. */ 43 #define USB_DEVICE_CDC_REQUEST_SET_OPERATION_PARAM (0x32U) /*!< The CDC class request code for SET_OPERATION_PARAM. */ 44 #define USB_DEVICE_CDC_REQUEST_GET_OPERATION_PARAM (0x33U) /*!< The CDC class request code for GET_OPERATION_PARAM. */ 45 #define USB_DEVICE_CDC_REQUEST_SET_LINE_PARAMS (0x34U) /*!< The CDC class request code for SET_LINE_PARAMS. */ 46 #define USB_DEVICE_CDC_REQUEST_GET_LINE_PARAMS (0x35U) /*!< The CDC class request code for GET_LINE_PARAMS. */ 47 #define USB_DEVICE_CDC_REQUEST_DIAL_DIGITS (0x36U) /*!< The CDC class request code for DIAL_DIGITS. */ 48 #define USB_DEVICE_CDC_REQUEST_SET_UNIT_PARAMETER (0x37U) /*!< The CDC class request code for SET_UNIT_PARAMETER. */ 49 #define USB_DEVICE_CDC_REQUEST_GET_UNIT_PARAMETER (0x38U) /*!< The CDC class request code for GET_UNIT_PARAMETER. */ 50 #define USB_DEVICE_CDC_REQUEST_CLEAR_UNIT_PARAMETER \ 51 (0x39U) /*!< The CDC class request code for CLEAR_UNIT_PARAMETER. */ 52 #define USB_DEVICE_CDC_REQUEST_SET_ETHERNET_MULTICAST_FILTERS \ 53 (0x40U) /*!< The CDC class request code for SET_ETHERNET_MULTICAST_FILTERS. */ 54 #define USB_DEVICE_CDC_REQUEST_SET_ETHERNET_POW_PATTER_FILTER \ 55 (0x41U) /*!< The CDC class request code for SET_ETHERNET_POW_PATTER_FILTER. */ 56 #define USB_DEVICE_CDC_REQUEST_GET_ETHERNET_POW_PATTER_FILTER \ 57 (0x42U) /*!< The CDC class request code for GET_ETHERNET_POW_PATTER_FILTER. */ 58 #define USB_DEVICE_CDC_REQUEST_SET_ETHERNET_PACKET_FILTER \ 59 (0x43U) /*!< The CDC class request code for SET_ETHERNET_PACKET_FILTER. */ 60 #define USB_DEVICE_CDC_REQUEST_GET_ETHERNET_STATISTIC \ 61 (0x44U) /*!< The CDC class request code for GET_ETHERNET_STATISTIC. */ 62 #define USB_DEVICE_CDC_REQUEST_SET_ATM_DATA_FORMAT (0x50U) /*!< The CDC class request code for SET_ATM_DATA_FORMAT. */ 63 #define USB_DEVICE_CDC_REQUEST_GET_ATM_DEVICE_STATISTICS \ 64 (0x51) /*!< The CDC class request code for GET_ATM_DEVICE_STATISTICS. */ 65 #define USB_DEVICE_CDC_REQUEST_SET_ATM_DEFAULT_VC (0x52U) /*!< The CDC class request code for SET_ATM_DEFAULT_VC. */ 66 #define USB_DEVICE_CDC_REQUEST_GET_ATM_VC_STATISTICS \ 67 (0x53U) /*!< The CDC class request code for GET_ATM_VC_STATISTICS. */ 68 #define USB_DEVICE_CDC_REQUEST_MDLM_SPECIFIC_REQUESTS_MASK \ 69 (0x7FU) /*!< The CDC class request code for MDLM_SPECIFIC_REQUESTS_MASK. */ 70 71 #define USB_DEVICE_CDC_NOTIF_NETWORK_CONNECTION (0x00U) /*!< The CDC class notify code for NETWORK_CONNECTION. */ 72 #define USB_DEVICE_CDC_NOTIF_RESPONSE_AVAIL (0x01U) /*!< The CDC class notify code for RESPONSE_AVAIL. */ 73 #define USB_DEVICE_CDC_NOTIF_AUX_JACK_HOOK_STATE (0x08U) /*!< The CDC class notify code for AUX_JACK_HOOK_STATE. */ 74 #define USB_DEVICE_CDC_NOTIF_RING_DETECT (0x09U) /*!< The CDC class notify code for RING_DETECT. */ 75 #define USB_DEVICE_CDC_NOTIF_SERIAL_STATE (0x20U) /*!< The CDC class notify code for SERIAL_STATE. */ 76 #define USB_DEVICE_CDC_NOTIF_CALL_STATE_CHANGE (0x28U) /*!< The CDC class notify code for CALL_STATE_CHANGE. */ 77 #define USB_DEVICE_CDC_NOTIF_LINE_STATE_CHANGE (0x29U) /*!< The CDC class notify code for LINE_STATE_CHANGE. */ 78 #define USB_DEVICE_CDC_NOTIF_CONNECTION_SPEED_CHANGE \ 79 (0x2AU) /*!< The CDC class notify code for CONNECTION_SPEED_CHANGE. */ 80 81 #define USB_DEVICE_CDC_FEATURE_ABSTRACT_STATE (0x01U) /*!< The CDC class feature select code for ABSTRACT_STATE. */ 82 #define USB_DEVICE_CDC_FEATURE_COUNTRY_SETTING (0x02U) /*!< The CDC class feature select code for COUNTRY_SETTING. */ 83 84 #define USB_DEVICE_CDC_CONTROL_SIG_BITMAP_CARRIER_ACTIVATION \ 85 (0x02U) /*!< The CDC class control signal bitmap value for CARRIER_ACTIVATION. */ 86 #define USB_DEVICE_CDC_CONTROL_SIG_BITMAP_DTE_PRESENCE \ 87 (0x01U) /*!< The CDC class control signal bitmap value for DTE_PRESENCE. */ 88 #define USB_DEVICE_CDC_UART_STATE_RX_CARRIER (0x01U) /*!< The UART state bitmap value of RX_CARRIER. */ 89 #define USB_DEVICE_CDC_UART_STATE_TX_CARRIER (0x02U) /*!< The UART state bitmap value of TX_CARRIER. */ 90 #define USB_DEVICE_CDC_UART_STATE_BREAK (0x04U) /*!< The UART state bitmap value of BREAK. */ 91 #define USB_DEVICE_CDC_UART_STATE_RING_SIGNAL (0x08U) /*!< The UART state bitmap value of RING_SIGNAL. */ 92 #define USB_DEVICE_CDC_UART_STATE_FRAMING (0x10U) /*!< The UART state bitmap value of FRAMING. */ 93 #define USB_DEVICE_CDC_UART_STATE_PARITY (0x20U) /*!< The UART state bitmap value of PARITY. */ 94 #define USB_DEVICE_CDC_UART_STATE_OVERRUN (0x40U) /*!< The UART state bitmap value of OVERRUN. */ 95 96 /*! @brief Definition of CDC class event. */ 97 typedef enum _usb_device_cdc_acm_event 98 { 99 kUSB_DeviceCdcEventSendResponse = 0x01, /*!< This event indicates the bulk send transfer is complete or cancelled etc. */ 100 kUSB_DeviceCdcEventRecvResponse, /*!< This event indicates the bulk receive transfer is complete or cancelled etc.. */ 101 kUSB_DeviceCdcEventSerialStateNotif, /*!< This event indicates the serial state has been sent to the host. */ 102 kUSB_DeviceCdcEventSendEncapsulatedCommand, /*!< This event indicates the device received the 103 SEND_ENCAPSULATED_COMMAND request. */ 104 kUSB_DeviceCdcEventGetEncapsulatedResponse, /*!< This event indicates the device received the 105 GET_ENCAPSULATED_RESPONSE request. */ 106 kUSB_DeviceCdcEventSetCommFeature, /*!< This event indicates the device received the SET_COMM_FEATURE request. */ 107 kUSB_DeviceCdcEventGetCommFeature, /*!< This event indicates the device received the GET_COMM_FEATURE request. */ 108 kUSB_DeviceCdcEventClearCommFeature, /*!< This event indicates the device received the CLEAR_COMM_FEATURE request. 109 */ 110 kUSB_DeviceCdcEventGetLineCoding, /*!< This event indicates the device received the GET_LINE_CODING request. */ 111 kUSB_DeviceCdcEventSetLineCoding, /*!< This event indicates the device received the SET_LINE_CODING request. */ 112 kUSB_DeviceCdcEventSetControlLineState, /*!< This event indicates the device received the SET_CONTRL_LINE_STATE 113 request. */ 114 kUSB_DeviceCdcEventSendBreak /*!< This event indicates the device received the SEND_BREAK request. */ 115 } usb_device_cdc_acm_event_t; 116 117 /*! @brief Definition of parameters for CDC ACM request. */ 118 typedef struct _usb_device_cdc_acm_request_param_struct 119 { 120 uint8_t **buffer; /*!< The pointer to the address of the buffer for CDC class request. */ 121 uint32_t *length; /*!< The pointer to the length of the buffer for CDC class request. */ 122 uint16_t interfaceIndex; /*!< The interface index of the setup packet. */ 123 uint16_t setupValue; /*!< The wValue field of the setup packet. */ 124 uint8_t isSetup; /*!< The flag indicates if it is a setup packet, 1: yes, 0: no. */ 125 } usb_device_cdc_acm_request_param_struct_t; 126 127 /*! @brief Definition of pipe structure. */ 128 typedef struct _usb_device_cdc_acm_pipe 129 { 130 osa_mutex_handle_t mutex; /*!< The mutex of the pipe. */ 131 uint32_t mutexBuffer[(OSA_MUTEX_HANDLE_SIZE + 3)/4]; 132 uint8_t *pipeDataBuffer; /*!< pipe data buffer backup when stall */ 133 uint32_t pipeDataLen; /*!< pipe data length backup when stall */ 134 uint8_t pipeStall; /*!< pipe is stall */ 135 uint8_t ep; /*!< The endpoint number of the pipe. */ 136 uint8_t isBusy; /*!< 1: The pipe is transferring packet, 0: The pipe is idle. */ 137 } usb_device_cdc_acm_pipe_t; 138 139 /*! @brief Definition of structure for CDC ACM device. */ 140 typedef struct _usb_device_cdc_acm_struct 141 { 142 usb_device_handle handle; /*!< The handle of the USB device. */ 143 usb_device_class_config_struct_t *configStruct; /*!< The class configure structure. */ 144 usb_device_interface_struct_t *commInterfaceHandle; /*!< The CDC communication interface handle. */ 145 usb_device_interface_struct_t *dataInterfaceHandle; /*!< The CDC data interface handle. */ 146 usb_device_cdc_acm_pipe_t bulkIn; /*!< The bulk in pipe for sending packet to host. */ 147 usb_device_cdc_acm_pipe_t bulkOut; /*!< The bulk out pipe for receiving packet from host. */ 148 usb_device_cdc_acm_pipe_t interruptIn; /*!< The interrupt in pipe for notifying the device state to host. */ 149 uint8_t configuration; /*!< The current configuration value. */ 150 uint8_t interfaceNumber; /*!< The current interface number. */ 151 uint8_t alternate; /*!< The alternate setting value of the interface. */ 152 uint8_t hasSentState; /*!< 1: The device has primed the state in interrupt pipe, 0: Not primed the state. */ 153 } usb_device_cdc_acm_struct_t; 154 155 /******************************************************************************* 156 * API 157 ******************************************************************************/ 158 159 #if defined(__cplusplus) 160 extern "C" { 161 #endif 162 163 /*! 164 * @name USB CDC ACM Class Driver 165 * @{ 166 */ 167 /*! 168 * @brief Initializes the USB CDC ACM class. 169 * 170 * This function obtains a USB device handle according to the controller ID, initializes the CDC ACM class 171 * with the class configure parameters and creates the mutex for each pipe. 172 * 173 * @param controllerId The ID of the controller. The value can be chosen from the kUSB_ControllerKhci0, 174 * kUSB_ControllerKhci1, kUSB_ControllerEhci0, or kUSB_ControllerEhci1. 175 * @param config The user configuration structure of type usb_device_class_config_struct_t. The user 176 * populates the members of this structure and passes the pointer of this structure 177 * into this function. 178 * @param handle It is out parameter. The class handle of the CDC ACM class. 179 * @return A USB error code or kStatus_USB_Success. 180 * @retval kStatus_USB_Success The CDC ACM class is initialized successfully. 181 * @retval kStatus_USB_Busy No CDC ACM device handle available for allocation. 182 * @retval kStatus_USB_InvalidHandle The CDC ACM device handle allocation failure. 183 * @retval kStatus_USB_InvalidParameter The USB device handle allocation failure. 184 */ 185 extern usb_status_t USB_DeviceCdcAcmInit(uint8_t controllerId, 186 usb_device_class_config_struct_t *config, 187 class_handle_t *handle); 188 /*! 189 * @brief Deinitializes the USB CDC ACM class. 190 * 191 * This function destroys the mutex for each pipe, deinitializes each endpoint of the CDC ACM class and frees 192 * the CDC ACM class handle. 193 * 194 * @param handle The class handle of the CDC ACM class. 195 * @return A USB error code or kStatus_USB_Success. 196 * @retval kStatus_USB_Success The CDC ACM class is de-initialized successfully. 197 * @retval kStatus_USB_Error The endpoint deinitialization failure. 198 * @retval kStatus_USB_InvalidHandle The CDC ACM device handle or the CDC ACM class handle is invalid. 199 * @retval kStatus_USB_InvalidParameter The endpoint number of the CDC ACM class handle is invalid. 200 */ 201 extern usb_status_t USB_DeviceCdcAcmDeinit(class_handle_t handle); 202 /*! 203 * @brief Handles the CDC ACM class event. 204 * 205 * This function responds to various events including the common device events and the class-specific events. 206 * For class-specific events, it calls the class callback defined in the application to deal with the class-specific 207 * event. 208 * 209 * @param handle The class handle of the CDC ACM class. 210 * @param event The event type. 211 * @param param The class handle of the CDC ACM class. 212 * @return A USB error code or kStatus_USB_Success. 213 * @retval kStatus_USB_Success The CDC ACM class is de-initialized successfully. 214 * @retval kStatus_USB_Error The configure structure of the CDC ACM class handle is invalid. 215 * @retval kStatus_USB_InvalidHandle The CDC ACM device handle or the CDC ACM class handle is invalid. 216 * @retval kStatus_USB_InvalidParameter The endpoint number of the CDC ACM class handle is invalid. 217 * @retval Others The error code returned by class callback in application. 218 */ 219 extern usb_status_t USB_DeviceCdcAcmEvent(void *handle, uint32_t event, void *param); 220 221 /*! 222 * @brief Primes the endpoint to send packet to host. 223 * 224 * This function checks whether the endpoint is sending packet, then it primes the endpoint 225 * with the buffer address and the buffer length if the pipe is not busy. Otherwise, it ignores this transfer by 226 * returning an error code. 227 * 228 * @param handle The class handle of the CDC ACM class. 229 * @param ep The endpoint number of the transfer. 230 * @param buffer The pointer to the buffer to be transferred. 231 * @param length The length of the buffer to be transferred. 232 * @return A USB error code or kStatus_USB_Success. 233 * @retval kStatus_USB_Success Prime to send packet successfully. 234 * @retval kStatus_USB_Busy The endpoint is busy in transferring. 235 * @retval kStatus_USB_InvalidHandle The CDC ACM device handle or the CDC ACM class handle is invalid. 236 * @retval kStatus_USB_ControllerNotFound The controller interface is invalid. 237 * 238 * @note The function can only be called in the same context. 239 */ 240 extern usb_status_t USB_DeviceCdcAcmSend(class_handle_t handle, uint8_t ep, uint8_t *buffer, uint32_t length); 241 /*! 242 * @brief Primes the endpoint to receive packet from host. 243 * 244 * This function checks whether the endpoint is receiving packet, then it primes the endpoint 245 * with the buffer address and the buffer length if the pipe is not busy. Otherwise, it ignores this transfer by 246 * returning an error code. 247 * 248 * @param handle The class handle of the CDC ACM class. 249 * @param ep The endpoint number of the transfer. 250 * @param buffer The pointer to the buffer to be transferred. 251 * @param length The length of the buffer to be transferred. 252 * @return A USB error code or kStatus_USB_Success. 253 * @retval kStatus_USB_Success Prime to receive packet successfully. 254 * @retval kStatus_USB_Busy The endpoint is busy in transferring. 255 * @retval kStatus_USB_InvalidHandle The CDC ACM device handle or the CDC ACM class handle is invalid. 256 * @retval kStatus_USB_ControllerNotFound The controller interface is invalid. 257 * 258 * @note The function can only be called in the same context. 259 */ 260 extern usb_status_t USB_DeviceCdcAcmRecv(class_handle_t handle, uint8_t ep, uint8_t *buffer, uint32_t length); 261 262 /*! @}*/ 263 264 #if defined(__cplusplus) 265 } 266 #endif 267 268 /*! @}*/ 269 270 #endif /* _USB_DEVICE_CDC_ACM_H_ */ 271
