2 * @copyright Copyright (c) 2017-2020 TOYOTA MOTOR CORPORATION.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
22 #ifndef HAL_API_USB_HAL_H_
23 #define HAL_API_USB_HAL_H_
25 #include "native_service/frameworkunified_types.h"
27 /** @addtogroup device_detection_service
30 /** @addtogroup usb_hal
31 * @ingroup device_detection_service
36 * \~english Definition of Host/Function mode of USB OTG port.
44 * \~english Function mode
50 * \ingroup GetUsbRoleSwitch
51 * \~english @par Brief
53 * \~english @param [out] usb_role
54 * UsbRoleType* - USB role
55 * \~english @retval eFrameworkunifiedStatusOK OK
56 * \~english @retval eFrameworkunifiedStatusNullPointer NULL Pointer
57 * \~english @retval eFrameworkunifiedStatusFail Abnormal Error
58 * \~english @par Prerequisite
59 * - When State value is "status faile", Can not get host/funtcion mode of USB OTG port.
60 * \~english @par Change of internal state
62 * \~english @par Conditions of processing failure
63 * - Input parameter error
64 * - eFrameworkunifiedStatusNullPointer
65 * - Internal process error(open/read)
66 * - eFrameworkunifiedStatusFail
67 * - Internal process error(State value is "status faile")
68 * - eFrameworkunifiedStatusFail
69 * \~english @par Classification
73 * \~english @par Detail
74 * - Get Host/Funtcion mode of USB OTG port.
75 * - The API can not be used by multiple processes, threads at the same time.
76 * \~english @see SetUsbRoleSwitch
78 EFrameworkunifiedStatus GetUsbRoleSwitch(UsbRoleType* usb_role);
81 * \ingroup SetUsbRoleSwitch
82 * \~english @par Brief
84 * \~english @param [in] usb_role
85 * UsbRoleType - USB role
86 * \~english @retval eFrameworkunifiedStatusOK OK
87 * \~english @retval eFrameworkunifiedStatusInvldParam Invalid Parameter
88 * \~english @retval eFrameworkunifiedStatusFail Abnormal Error
89 * \~english @par Prerequisite
90 * - When State value is "status faile", Can not set host/funtcion mode of USB OTG port.
91 * \~english @par Change of internal state
92 * - Change "USB role is host mode"or"USB role is host mode"
93 * \~english @par Conditions of processing failure
94 * - Input parameter error
95 * - eFrameworkunifiedStatusInvldParam
96 * - Internal process error(open/read/write)
97 * - eFrameworkunifiedStatusFail
98 * - Internal process error(State value is "status faile")
99 * - eFrameworkunifiedStatusFail
100 * \~english @par Classification
102 * \~english @par Type
104 * \~english @par Detail
105 * - Set Host/Funtcion mode of USB OTG port.
106 * - The API can not be used by multiple processes, threads at the same time.
107 * \~english @see GetUsbRoleSwitch
109 EFrameworkunifiedStatus SetUsbRoleSwitch(UsbRoleType usb_role);
112 * \~english USB authentication error information
114 enum UsbAuthenticationError {
116 * \~english USB authentication no error
118 USB_AUTHENTICATION_ERROR_NONE = 0,
120 * \~english The connected device has no response
122 USB_AUTHENTICATION_ERROR_ENUMERATE,
124 * \~english The device connected to bus-powered HUB is overcurrent
126 USB_AUTHENTICATION_ERROR_HUB_OVERCURRENT,
128 * \~english HUB tier levels
130 USB_AUTHENTICATION_ERROR_HUB_TIER_LEVELS,
132 * \~english The number of connected devices is more than supported
134 USB_AUTHENTICATION_ERROR_CONNECTION_EXCESS
138 * \ingroup CheckUsbAuthenticationError
139 * \~english @par Brief
140 * Check USB authentication error
141 * \~english @param [out] usb_auth_error
142 * UsbAuthenticationError* - USB authentication error
143 * \~english @retval eFrameworkunifiedStatusOK OK
144 * \~english @retval eFrameworkunifiedStatusNullPointer NULL Pointer
145 * \~english @retval eFrameworkunifiedStatusFail Abnormal Error
146 * \~english @par Prerequisite
147 * - When State value is "status faile", Can not check USB authentication error .
148 * \~english @par Change of internal state
150 * \~english @par Conditions of processing failure
151 * - Input parameter error
152 * - eFrameworkunifiedStatusNullPointer
153 * - Internal process error(open/read)
154 * - eFrameworkunifiedStatusFail
155 * - Internal process error(State value is "status faile")
156 * - eFrameworkunifiedStatusFail
157 * \~english @par Classification
159 * \~english @par Type
161 * \~english @par Detail
162 * - Check USB authentication error information.
163 * - The API can not be used by multiple processes, threads at the same time.
164 * \~english @see None.
166 EFrameworkunifiedStatus CheckUsbAuthenticationError(UsbAuthenticationError* usb_auth_error);
169 * \~english Definition of USB port number.
170 * - The USB port number is defined according to the RefHW,
171 * modification will be necessary if there's any change about USB port.
175 * \~english USB0(IF-BOX)
177 USB_PORT_NUMBER_0 = 0,
179 * \~english USB1(DCM)
183 * \~english USB2(DSRC/ETC)
187 * \~english USB3(External deck)
191 * \~english USB4(Drive recorder)
195 * \~english Maximum of USB port number.
201 * \ingroup ResetUsbVbus
202 * \~english @par Brief
204 * \~english @param [in] usb_port_no
205 * UsbPortNumber - USB port number
206 * \~english @retval eFrameworkunifiedStatusOK OK
207 * \~english @retval eFrameworkunifiedStatusInvldParam Invalid Parameter
208 * \~english @retval eFrameworkunifiedStatusFail Abnormal Error
209 * \~english @par Prerequisite
210 * - When State value is "status faile", Can not USB VBus reset .
211 * \~english @par Change of internal state
212 * - "USB power ON" from the "USB power OFF".
213 * \~english @par Conditions of processing failure
214 * - Input parameter error
215 * - eFrameworkunifiedStatusInvldParam
216 * - Internal process error(open/read/write)
217 * - eFrameworkunifiedStatusFail
218 * - Internal process error(State value is "status faile")
219 * - eFrameworkunifiedStatusFail
220 * - Not change internal state.
221 * \~english @par Classification
223 * \~english @par Type
225 * \~english @par Detail
227 * - The API is a block I/F which costs a while due to the sleep time between power off and power on.
228 * - The API can not be used by multiple processes, threads at the same time.
229 * \~english @see IsUsbPortPowered, PowerOnUsbPort, PowerOffUsbPort
231 EFrameworkunifiedStatus ResetUsbVbus(UsbPortNumber usb_port_no);
234 * \ingroup IsUsbPortPowered
235 * \~english @par Brief
236 * Check the power state of USB port.
237 * \~english @param [in] usb_port_no
238 * UsbPortNumber - USB port number
239 * \~english @param [out] is_powered
241 * - true : Power is on
242 * - false : Power is off
243 * \~english @retval eFrameworkunifiedStatusOK OK
244 * \~english @retval eFrameworkunifiedStatusInvldParam Invalid Parameter
245 * \~english @retval eFrameworkunifiedStatusNullPointer NULL Pointer
246 * \~english @retval eFrameworkunifiedStatusFail Abnormal Error
247 * \~english @par Prerequisite
249 * \~english @par Change of internal state
251 * \~english @par Conditions of processing failure
252 * - Input parameter error
253 * - eFrameworkunifiedStatusInvldParam
254 * - eFrameworkunifiedStatusNullPointer
255 * - Internal process error(open/read)
256 * - eFrameworkunifiedStatusFail
257 * \~english @par Classification
259 * \~english @par Type
261 * \~english @par Detail
262 * - Check the power state of USB port.
263 * - The API can not be used by multiple processes, threads at the same time.
264 * \~english @see ResetUsbVbus, PowerOnUsbPort, PowerOffUsbPort
266 EFrameworkunifiedStatus IsUsbPortPowered(UsbPortNumber usb_port_no, bool* is_powered);
269 * \ingroup PowerOnUsbPort
270 * \~english @par Brief
272 * \~english @param [in] usb_port_no
273 * UsbPortNumber - USB port number
274 * \~english @retval eFrameworkunifiedStatusOK OK
275 * \~english @retval eFrameworkunifiedStatusInvldParam Invalid Parameter
276 * \~english @retval eFrameworkunifiedStatusFail Abnormal Error
277 * \~english @par Prerequisite
278 * - When State value is "status faile", Can not power on USB port.
279 * \~english @par Change of internal state
280 * - Change state "USB power on"
281 * \~english @par Conditions of processing failure
282 * - Input parameter error
283 * - eFrameworkunifiedStatusInvldParam
284 * - Internal process error(open/read/write)
285 * - eFrameworkunifiedStatusFail
286 * - Internal process error(State value is "status faile")
287 * - eFrameworkunifiedStatusFail
288 * - Not change internal state.
289 * \~english @par Classification
291 * \~english @par Type
293 * \~english @par Detail
294 * - Power on USB port.
295 * - The API can not be used by multiple processes, threads at the same time.
296 * \~english @see ResetUsbVbus, IsUsbPortPowered, PowerOffUsbPort
298 EFrameworkunifiedStatus PowerOnUsbPort(UsbPortNumber usb_port_no);
301 * \ingroup PowerOffUsbPort
302 * \~english @par Brief
303 * Power off USB port.
304 * \~english @param [in] usb_port_no
305 * UsbPortNumber - USB port number
306 * \~english @retval eFrameworkunifiedStatusOK OK
307 * \~english @retval eFrameworkunifiedStatusInvldParam Invalid Parameter
308 * \~english @retval eFrameworkunifiedStatusFail Abnormal Error
309 * \~english @par Prerequisite
311 * \~english @par Change of internal state
312 * - Change state "USB power off"
313 * \~english @par Conditions of processing failure
314 * - Input parameter error
315 * - eFrameworkunifiedStatusInvldParam
316 * - Internal process error(open/read/write)
317 * - eFrameworkunifiedStatusFail
318 * \~english @par Classification
320 * \~english @par Type
322 * \~english @par Detail
323 * - Power off USB port.
324 * - The API can not be used by multiple processes, threads at the same time.
325 * \~english @see ResetUsbVbus, IsUsbPortPowered, PowerOnUsbPort
327 EFrameworkunifiedStatus PowerOffUsbPort(UsbPortNumber usb_port_no);
330 * \~english USB abnormal status
332 enum UsbAbnormalStatus {
334 * \~english USB is not abnormal
336 USB_ABNORMAL_STATUS_NONE = 0,
338 * \~english USB is overcurrent
340 USB_ABNORMAL_STATUS_OVERCURRENT
344 * \ingroup CheckUsbAbnormalStatus
345 * \~english @par Brief
346 * Check the abnormal status of USB port
347 * \~english @param [in] usb_port_no
348 * UsbPortNumber - USB port number
349 * \~english @param [out] usb_abnormal_status
350 * UsbAbnormalStatus* - USB abnormal status
351 * \~english @retval eFrameworkunifiedStatusOK OK
352 * \~english @retval eFrameworkunifiedStatusInvldParam Invalid Parameter
353 * \~english @retval eFrameworkunifiedStatusNullPointer NULL Pointer
354 * \~english @retval eFrameworkunifiedStatusFail Abnormal Error
355 * \~english @par Prerequisite
357 * \~english @par Change of internal state
358 * - change state "usb port status faile" or "usb port status ok".
359 * \~english @par Conditions of processing failure
360 * - Input parameter error
361 * - eFrameworkunifiedStatusInvldParam
362 * - eFrameworkunifiedStatusNullPointer
363 * - Internal process error(open/read)
364 * - eFrameworkunifiedStatusFail
365 * \~english @par Classification
367 * \~english @par Type
369 * \~english @par Detail
370 * - Check the abnormal status of USB port, including overcurrent and so on.
371 * - The API can not be used by multiple processes, threads at the same time.
372 * \~english @see None.
374 EFrameworkunifiedStatus CheckUsbAbnormalStatus(UsbPortNumber usb_port_no, UsbAbnormalStatus* usb_abnormal_status);
376 /** @}*/ // end of usb_hal
377 /** @}*/ // end of device_detection_service
379 #endif // HAL_API_USB_HAL_H_