video_in_hal/usb_hal/hal_api/usb_hal.h

   1 /*
   2  * @copyright Copyright (c) 2017-2020 TOYOTA MOTOR CORPORATION.
   3  *
   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
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 /**
  18  * @file usb_hal.h
  19  * @brief usb_hal API
  20  */
  21
  22 #ifndef HAL_API_USB_HAL_H_
  23 #define HAL_API_USB_HAL_H_
  24
  25 #include "native_service/frameworkunified_types.h"
  26
  27 /** @addtogroup device_detection_service
  28  *  @{
  29  */
  30 /** @addtogroup usb_hal
  31  *  @ingroup device_detection_service
  32  *  @{
  33  */
  34
  35 /**
  36  * \~english Definition of Host/Function mode of USB OTG port.
  37  */
  38 enum UsbRoleType {
  39   /**
  40    * \~english Host mode
  41    */
  42   USB_ROLE_HOST = 0,
  43   /**
  44    * \~english Function mode
  45    */
  46   USB_ROLE_FUNCTION,
  47 };
  48
  49 /**
  50  * \ingroup GetUsbRoleSwitch
  51  * \~english @par Brief
  52  *       Get USB role
  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
  61  *       - None.
  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
  70  *       Public
  71  * \~english @par Type
  72  *       Sync
  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
  77  */
  78 EFrameworkunifiedStatus GetUsbRoleSwitch(UsbRoleType* usb_role);
  79
  80 /**
  81  * \ingroup SetUsbRoleSwitch
  82  * \~english @par Brief
  83  *       Set USB role.
  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
 101  *       Public
 102  * \~english @par Type
 103  *       Sync
 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
 108  */
 109 EFrameworkunifiedStatus SetUsbRoleSwitch(UsbRoleType usb_role);
 110
 111 /**
 112  * \~english USB authentication error information
 113  */
 114 enum UsbAuthenticationError {
 115   /**
 116    * \~english USB authentication no error
 117    */
 118   USB_AUTHENTICATION_ERROR_NONE = 0,
 119   /**
 120    * \~english The connected device has no response
 121    */
 122   USB_AUTHENTICATION_ERROR_ENUMERATE,
 123   /**
 124    * \~english The device connected to bus-powered HUB is overcurrent
 125    */
 126   USB_AUTHENTICATION_ERROR_HUB_OVERCURRENT,
 127   /**
 128    * \~english HUB tier levels
 129    */
 130   USB_AUTHENTICATION_ERROR_HUB_TIER_LEVELS,
 131   /**
 132    * \~english The number of connected devices is more than supported
 133    */
 134   USB_AUTHENTICATION_ERROR_CONNECTION_EXCESS
 135 };
 136
 137 /**
 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
 149  *       - None.
 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
 158  *       Public
 159  * \~english @par Type
 160  *       Sync
 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.
 165  */
 166 EFrameworkunifiedStatus CheckUsbAuthenticationError(UsbAuthenticationError* usb_auth_error);
 167
 168 /**
 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.
 172  */
 173 enum UsbPortNumber {
 174   /**
 175    * \~english USB0(IF-BOX)
 176    */
 177   USB_PORT_NUMBER_0 = 0,
 178   /**
 179    * \~english USB1(DCM)
 180    */
 181   USB_PORT_NUMBER_1,
 182   /**
 183    * \~english USB2(DSRC/ETC)
 184    */
 185   USB_PORT_NUMBER_2,
 186   /**
 187    * \~english USB3(External deck)
 188    */
 189   USB_PORT_NUMBER_3,
 190   /**
 191    * \~english USB4(Drive recorder)
 192    */
 193   USB_PORT_NUMBER_4,
 194   /**
 195    * \~english Maximum of USB port number.
 196    */
 197   USB_PORT_NUMBER_MAX
 198 };
 199
 200 /**
 201  * \ingroup ResetUsbVbus
 202  * \~english @par Brief
 203  *       USB VBus Reset.
 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
 222  *       Public
 223  * \~english @par Type
 224  *       Sync
 225  * \~english @par Detail
 226  *       - USB VBus Reset.
 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
 230  */
 231 EFrameworkunifiedStatus ResetUsbVbus(UsbPortNumber usb_port_no);
 232
 233 /**
 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
 240  *       bool*\n
 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
 248  *       - None.
 249  * \~english @par Change of internal state
 250  *       - None.
 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
 258  *       Public
 259  * \~english @par Type
 260  *       Sync
 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
 265  */
 266 EFrameworkunifiedStatus IsUsbPortPowered(UsbPortNumber usb_port_no, bool* is_powered);
 267
 268 /**
 269  * \ingroup PowerOnUsbPort
 270  * \~english @par Brief
 271  *       Power on USB port.
 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
 290  *       Public
 291  * \~english @par Type
 292  *       Sync
 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
 297  */
 298 EFrameworkunifiedStatus PowerOnUsbPort(UsbPortNumber usb_port_no);
 299
 300 /**
 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
 310  *       - None.
 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
 319  *       Public
 320  * \~english @par Type
 321  *       Sync
 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
 326  */
 327 EFrameworkunifiedStatus PowerOffUsbPort(UsbPortNumber usb_port_no);
 328
 329 /**
 330  * \~english USB abnormal status
 331  */
 332 enum UsbAbnormalStatus {
 333   /**
 334    * \~english USB is not abnormal
 335    */
 336   USB_ABNORMAL_STATUS_NONE = 0,
 337   /**
 338    * \~english USB is overcurrent
 339    */
 340   USB_ABNORMAL_STATUS_OVERCURRENT
 341 };
 342
 343 /**
 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
 356  *       - None.
 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
 366  *       Public
 367  * \~english @par Type
 368  *       Sync
 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.
 373  */
 374 EFrameworkunifiedStatus CheckUsbAbnormalStatus(UsbPortNumber usb_port_no, UsbAbnormalStatus* usb_abnormal_status);
 375
 376 /** @}*/  // end of usb_hal
 377 /** @}*/  // end of device_detection_service
 378
 379 #endif  // HAL_API_USB_HAL_H_