video_in_hal/power_hal/hal_api/power_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 power_hal.h
  19  * @brief Interface and struct define for power_hal
  20  */
  21
  22 #ifndef HAL_API_POWER_HAL_H_
  23 #define HAL_API_POWER_HAL_H_
  24
  25 #include <native_service/frameworkunified_types.h>
  26
  27 /** @addtogroup system_manager
  28  *  @{
  29  */
  30 /** @addtogroup power_hal
  31  *  @ingroup system_manager
  32  *  @{
  33  */
  34 /** @}*/  // end of power_hal
  35 /** @}*/  // end of system_manager
  36
  37 /** @addtogroup power_supply_manager_shadow
  38  *  @{
  39  */
  40 /** @addtogroup power_hal
  41  *  @ingroup power_supply_manager_shadow
  42  *  @{
  43  */
  44
  45 /**
  46  * \~english Definition of program update is not occured
  47  */
  48 #define PWR_PROGUPDATE_STATE_NONE         (0x0)
  49
  50 /**
  51  * \~english Bit position of program update
  52  */
  53 #define PWR_PROGUPDATE_STATE_UPDATED         (0x01)
  54
  55 /**
  56  * \~english Bit position of map update
  57  */
  58 #define PWR_PROGUPDATE_STATE_MAP_UPDATED     (0x02)
  59
  60 /**
  61  * \~english Bit position of map difference update
  62  */
  63 #define PWR_PROGUPDATE_STATE_MAPDIFF_UPDATED (0x04)
  64
  65 /**
  66  * \~english None reset state
  67  */
  68 #define PWR_DATA_RESET_STATE_NONE       0
  69
  70 /**
  71  * \~english Reset state for initialization of user information
  72  */
  73 #define PWR_DATA_RESET_STATE_USER       1
  74
  75 /**
  76  * \~english Reset state for factory initialization
  77  */
  78 #define PWR_DATA_RESET_STATE_FACTORY    2
  79
  80 /*
  81  * @~english
  82  * @brief Command ID  power_hal -> User
  83  */
  84 /*! @~english power_hal command receive notification */
  85 #define CID_PWR_CMD_RCV      0x0103
  86
  87 /*! @~english power_hal command send result notification */
  88 #define CID_PWR_CMD_SND_STS  0x0104
  89
  90 /**
  91  * \~english DRAM backup status
  92  */
  93 enum PsmSysupDramT {
  94   /**
  95    * \~english normal value
  96    */
  97   PSM_SYSUP_DRAM_NORMAL,
  98
  99   /**
 100    * \~english abnormal Soft Reset(software abnormality)
 101    */
 102   PSM_SYSUP_DRAM_SFTERRSR,
 103
 104   /**
 105    * \~english need to discard backup dram
 106    */
 107   PSM_SYSUP_DRAM_DISCARD,
 108
 109   /**
 110    * \~english max value
 111    */
 112   PSM_SYSUP_DRAM_MAX,
 113 };
 114
 115 /**
 116  * \~english Start Status
 117  */
 118 enum PsmStartStatusT {
 119   /**
 120    * \~english cold start
 121    */
 122   PSM_START_STATUS_FACTRESET,
 123
 124   /**
 125    * \~english hot start
 126    */
 127   PSM_START_STATUS_NORMAL,
 128
 129   /**
 130    * \~english max value
 131    */
 132   PSM_START_STATUS_MAX,
 133 };
 134
 135 /**
 136  * \~english Communication state
 137  */
 138 enum PsmComStsT {
 139   /**
 140    * \~english Communication normal
 141    */
 142   PSM_COM_STS_NORMAL,
 143
 144   /**
 145    * \~english Communication abnormal
 146    */
 147   PSM_COM_STS_ABNORMAL,
 148
 149   /**
 150    * \~english max value
 151    */
 152   PSM_COM_STS_MAX,
 153 };
 154
 155 /**
 156  * \~english DRAM power supply abnormality check result
 157  */
 158 enum PsmDramStsT {
 159   /**
 160    * \~english DRAM power supply abnormality check result normal
 161    */
 162   PSM_DRAM_STS_NORMAL,
 163
 164   /**
 165    * \~english DRAM power supply abnormality check result abnormal
 166    */
 167   PSM_DRAM_STS_ABNORMAL,
 168
 169   /**
 170    * \~english max value
 171    */
 172   PSM_DRAM_STS_MAX,
 173 };
 174
 175 /**
 176  * \~english ACC customize setting.
 177  */
 178 enum PsmAccCustomizeT {
 179   /**
 180    * \~english ACC customize setting OFF.
 181    */
 182   PSM_ACC_CUSTOMIZE_OFF,
 183   /**
 184    * \~english ACC customize setting ON.
 185    */
 186   PSM_ACC_CUSTOMIZE_ON
 187 };
 188
 189 /**
 190  * \~english Reset history recording flag.
 191  */
 192 #define PSM_RESET_HISTORY   (0x10000000)
 193
 194 /**
 195  * \~english Reset(Start-up) factor.
 196  */
 197 enum PsmFactorT {
 198   /**
 199    * \~english none
 200    */
 201   PSM_FACTOR_NONE,
 202   /**
 203    * \~english Restart due to AGL.
 204    */
 205   PSM_FACTOR_AGL,
 206   /**
 207    * \~english Restart due to Tier1.
 208    */
 209   PSM_FACTOR_TIER1,
 210   /**
 211    * \~english Restart due to user.
 212    */
 213   PSM_FACTOR_USER,
 214   /**
 215    * \~english Restart due to AGL(Need to record reset history).
 216    */
 217   PSM_FACTOR_AGL_WITH_HISTORY = (PSM_RESET_HISTORY | PSM_FACTOR_AGL),
 218   /**
 219    * \~english Restart due to Tier1(Need to record reset history).
 220    */
 221   PSM_FACTOR_TIER1_WITH_HISTORY = (PSM_RESET_HISTORY | PSM_FACTOR_TIER1),
 222   /**
 223    * \~english Restart due to user(Need to record reset history).
 224    */
 225   PSM_FACTOR_USER_WITH_HISTORY = (PSM_RESET_HISTORY | PSM_FACTOR_USER)
 226 };
 227
 228 /**
 229  * \~english Reset information type.
 230  */
 231 enum PowerHalResetInfoId {
 232   /**
 233    * \~english Count of error log.
 234    */
 235   AGL_ERRLOG_COUNTER = 0,
 236   /**
 237    * \~english Abnormal reset count detected by AGL.
 238    */
 239   AGL_RESET_COUNTER,
 240   /**
 241    * \~english State of program update.
 242    */
 243   AGL_PROGUPDATE_STATE,
 244   /**
 245    * \~english Data reset state.
 246    */
 247   AGL_DATARESET_STATE,
 248   /**
 249    * \~english Flag of abnormal reset.
 250    */
 251   AGL_ILLRESET_FLAG,
 252   /**
 253    * \~english Max of reset information type.
 254    */
 255   AGL_RESERVED_LIMIT = 32
 256 };
 257
 258 /**
 259  * \ingroup PsmNaviResetPower
 260  * \~english @par Brief
 261  *         API to do navi reset that is forced reset if end sequence of MainSoC is not completed.
 262  * \~english @param [in] h_app Handle for Application
 263  * \~english @param [in] reset_factor Reset factor
 264  * \~english @retval 0   :  Ok
 265  * \~english @retval -1 :  Failed
 266  * \~english @par Prerequisite
 267  *        - None
 268  * \~english @par Change of internal state
 269  *        - Change of internal state according to the API does not occur.
 270  * \~english @par Conditions of processing failure
 271  *        - Internal IO error. [-1]
 272  * \~english @par Detail
 273  *        - do navi reset process.
 274  *        - The API can only be used by 1 process
 275  * \~english @par Classification
 276  *        Public
 277  * \~english @par Type
 278  *        Sync
 279  * \~english @see
 280  *        None
 281  */
 282 int PsmNaviResetPower(HANDLE h_app, PsmFactorT reset_factor);
 283
 284 /**
 285  * \ingroup PsmClrRamJudgeFlgPower
 286  * \~english @par Brief
 287  *         API to do ram judge flag clear
 288  * \~english @param [in] h_app Handle for Application
 289  * \~english @retval 0   :  Ok
 290  * \~english @retval -1 :  Failed
 291  * \~english @par Prerequisite
 292  *        - None
 293  * \~english @par Change of internal state
 294  *        - Change of internal state according to the API does not occur.
 295  * \~english @par Conditions of processing failure
 296  *        - Internal IO error. [-1]
 297  * \~english @par Detail
 298  *        - do ram judge flag clear process.
 299  *        - The API can only be used by 1 process
 300  * \~english @par Classification
 301  *        Public
 302  * \~english @par Type
 303  *        Sync
 304  * \~english @see
 305  *        None
 306  */
 307 int PsmClrRamJudgeFlgPower(HANDLE h_app);
 308
 309 /**
 310  * \ingroup PsmGetDramBackupStatusPower
 311  * \~english @par Brief
 312  *         API to do get dram backup status
 313  * \~english @param [in] h_app Handle for Application
 314  * \~english @param [out] p_dram1 DRAM1 BackUp Status
 315  * \~english @param [out] p_dram2 DRAM2 BackUp Status
 316  * \~english @param [out] p_dram3 DRAM3 BackUp Status
 317  * \~english @retval 0   :  Ok
 318  * \~english @retval -1 :  Failed
 319  * \~english @par Prerequisite
 320  *        - None
 321  * \~english @par Change of internal state
 322  *        - Change of internal state according to the API does not occur.
 323  * \~english @par Conditions of processing failure
 324  *        - Internal IO error. [-1]
 325  * \~english @par Detail
 326  *        - do get dram backup status process.
 327  *        - The API can only be used by 1 process
 328  * \~english @par Classification
 329  *        Public
 330  * \~english @par Type
 331  *        Sync
 332  * \~english @see
 333  *        None
 334  */
 335 int PsmGetDramBackupStatusPower(HANDLE h_app, PsmSysupDramT *p_dram1, PsmSysupDramT *p_dram2, PsmSysupDramT *p_dram3);
 336
 337 /**
 338  * \ingroup PsmGetStartStatusPower
 339  * \~english @par Brief
 340  *         API to do get start status
 341  * \~english @param [in] h_app Handle for Application
 342  * \~english @param [out] p_start_sts start status
 343  * \~english @retval 0   :  Ok
 344  * \~english @retval -1 :  Failed
 345  * \~english @par Prerequisite
 346  *        - None
 347  * \~english @par Change of internal state
 348  *        - Change of internal state according to the API does not occur.
 349  * \~english @par Conditions of processing failure
 350  *        - Internal IO error. [-1]
 351  * \~english @par Detail
 352  *        - do get startup state process.
 353  *        - The API can only be used by 1 process
 354  * \~english @par Classification
 355  *        Public
 356  * \~english @par Type
 357  *        Sync
 358  * \~english @see
 359  *        None
 360  */
 361 int PsmGetStartStatusPower(HANDLE h_app, PsmStartStatusT *p_start_sts);
 362
 363 /**
 364  * \ingroup PsmGetSyscomStatusPower
 365  * \~english @par Brief
 366  *         API to do get communication status between mainsoc-sys
 367  * \~english @param [in] h_app Handle for Application
 368  * \~english @param [out] p_com_sts communication status between mainsoc-sys
 369  * \~english @retval 0   :  Ok
 370  * \~english @retval -1 :  Failed
 371  * \~english @par Prerequisite
 372  *        - None
 373  * \~english @par Change of internal state
 374  *        - Change of internal state according to the API does not occur.
 375  * \~english @par Conditions of processing failure
 376  *        - Internal IO error. [-1]
 377  * \~english @par Detail
 378  *        - do get communication status between mainsoc-sys process.
 379  *        - The API can only be used by 1 process
 380  * \~english @par Classification
 381  *        Public
 382  * \~english @par Type
 383  *        Sync
 384  * \~english @see
 385  *        None
 386  */
 387 int PsmGetSyscomStatusPower(HANDLE h_app, PsmComStsT *p_com_sts);
 388
 389 /**
 390  * \ingroup PsmGetDramPowerSupplyAbnormalityCheckResultPower
 391  * \~english @par Brief
 392  *         API to do get dram power supply abnormality check result
 393  * \~english @param [in] h_app Handle for Application
 394  * \~english @param [out] p_dram_sts DRAM power supply abnormality check result
 395  * \~english @retval 0   :  Ok
 396  * \~english @retval -1 :  Failed
 397  * \~english @par Prerequisite
 398  *        - None
 399  * \~english @par Change of internal state
 400  *        - Change of internal state according to the API does not occur.
 401  * \~english @par Conditions of processing failure
 402  *        - Internal IO error. [-1]
 403  * \~english @par Detail
 404  *        - do get dram power supply abnormality check result process.
 405  *        - The API can only be used by 1 process
 406  * \~english @par Classification
 407  *        Public
 408  * \~english @par Type
 409  *        Sync
 410  * \~english @see
 411  *        None
 412  */
 413 int PsmGetDramPowerSupplyAbnormalityCheckResultPower(HANDLE h_app, PsmDramStsT *p_dram_sts);
 414
 415 /**
 416  * \ingroup PsmGetAccCustomizeSetting
 417  * \~english @par Brief
 418  *         API to do get ACC customize setting
 419  * \~english @param [in] h_app Handle for Application
 420  * \~english @param [out] p_acc_customize ACC customize Setting
 421  * \~english @retval 0   :  Ok
 422  * \~english @retval -1 :  Failed
 423  * \~english @par Prerequisite
 424  *        - None
 425  * \~english @par Change of internal state
 426  *        - Change of internal state according to the API does not occur.
 427  * \~english @par Conditions of processing failure
 428  *        - Internal IO error. [-1]
 429  * \~english @par Detail
 430  *        - do get ACC customize setting.
 431  *        - The API can only be used by 1 process
 432  * \~english @par Classification
 433  *        Public
 434  * \~english @par Type
 435  *        Sync
 436  * \~english @see
 437  *        None
 438  */
 439 int PsmGetAccCustomizeSetting(HANDLE h_app, PsmAccCustomizeT* p_acc_customize);
 440
 441 /**
 442  * \ingroup PsmChgAccCustomizeSetting
 443  * \~english @par Brief
 444  *         API to do change ACC customize setting
 445  * \~english @param [in] h_app Handle for Application
 446  * \~english @param [in] acc_customize ACC customize Setting
 447  * \~english @retval 0   :  Ok
 448  * \~english @retval -1 :  Failed
 449  * \~english @par Prerequisite
 450  *        - None
 451  * \~english @par Change of internal state
 452  *        - Change of internal state according to the API does not occur.
 453  * \~english @par Conditions of processing failure
 454  *        - Internal IO error. [-1]
 455  * \~english @par Detail
 456  *        - do set ACC customize setting.
 457  *        - The API can only be used by 1 process
 458  * \~english @par Classification
 459  *        Public
 460  * \~english @par Type
 461  *        Sync
 462  * \~english @see
 463  *        None
 464  */
 465 int PsmChgAccCustomizeSetting(HANDLE h_app, PsmAccCustomizeT acc_customize);
 466
 467 /**
 468  * \ingroup PsmGetStartupFactor
 469  * \~english @par Brief
 470  *         API to do get start-up factor.
 471  * \~english @param [in] h_app Handle for Application
 472  * \~english @param [out] p_startup_factor Start-up factor
 473  * \~english @retval 0   :  Ok
 474  * \~english @retval -1 :  Failed
 475  * \~english @par Prerequisite
 476  *        - None
 477  * \~english @par Change of internal state
 478  *        - Change of internal state according to the API does not occur.
 479  * \~english @par Conditions of processing failure
 480  *        - Internal IO error. [-1]
 481  * \~english @par Detail
 482  *        - do get Start-up factor.
 483  *        - After the API call, start-up factor is clear.
 484  *        - The API can only be used by 1 process
 485  * \~english @par Classification
 486  *        Public
 487  * \~english @par Type
 488  *        Sync
 489  * \~english @see
 490  *        None
 491  */
 492 int PsmGetStartupFactor(HANDLE h_app, PsmFactorT* p_startup_factor);
 493
 494 /**
 495  * \ingroup PowerHalSetResetInfo
 496  * \~english @par Brief
 497  *         API to do set reset information.
 498  * \~english @param [in] id Reset information type.
 499  * \~english @param [in] val setting value.
 500  * \~english @retval 0   :  Ok
 501  * \~english @retval -1 :  Failed
 502  * \~english @par Prerequisite
 503  *        - None
 504  * \~english @par Change of internal state
 505  *        - Change of internal state according to the API does not occur.
 506  * \~english @par Conditions of processing failure
 507  *        - Internal IO error. [-1]
 508  *        - Save error to non-volatile memory. [-1]
 509  * \~english @par Detail
 510  *        - Do set value to Reset information type(\ref PowerHalResetInfoId).  \n
 511  *          \ref AGL_PROGUPDATE_STATE is not applicable(Only get value used by \ref PowerHalGetResetInfo). \n
 512  *          Domains of each reset information type are as below. \n
 513  *          \ref AGL_ERRLOG_COUNTER : 0 <= val <= UINT32_MAX \n
 514  *          \ref AGL_RESET_COUNTER : 0 <= val <= UINT32_MAX \n
 515  *          \ref AGL_DATARESET_STATE : It is set as below in each state of data reset. \n
 516  *           None reset state == \ref PWR_DATA_RESET_STATE_NONE \n
 517  *           Reset state for initialization of user information == \ref PWR_DATA_RESET_STATE_USER \n
 518  *           Reset state for factory initialization == \ref PWR_DATA_RESET_STATE_FACTORY \n
 519  *          \ref AGL_ILLRESET_FLAG : val = 0 or 1 (Abnormal reset is 1)
 520  *        - When the API is success, setting value is saved as non-volatile data.
 521  *        - Non-volatile memory is allocated \ref AGL_RESERVED_LIMIT for extendability.
 522  *        - Values setting by the API are saved when it is cold start(is_batterydiscon is true of PsmSysMcEVSysResUpChkPrmT notified from power_hal).
 523  *        - The API is completed within 1msec after the API is called.
 524  *        - The API can only be used by 1 process.
 525  * \~english @par Classification
 526  *        Public
 527  * \~english @par Type
 528  *        Sync
 529  * \~english @see
 530  *        PowerHalGetResetInfo
 531  */
 532 int PowerHalSetResetInfo(enum PowerHalResetInfoId id, uint32_t val);
 533
 534 /**
 535  * \ingroup PowerHalGetResetInfo
 536  * \~english @par Brief
 537  *         API to do get setting value of reset information .
 538  * \~english @param [in] id Reset information type.
 539  * \~english @param [out] val Buffer of value.
 540  * \~english @retval 0   :  Ok
 541  * \~english @retval -1 :  Failed
 542  * \~english @par Prerequisite
 543  *        - None
 544  * \~english @par Change of internal state
 545  *        - Change of internal state according to the API does not occur.
 546  * \~english @par Conditions of processing failure
 547  *        - Internal IO error. [-1]
 548  *        - Read fail of value. [-1]
 549  * \~english @par Detail
 550  *        - Do get value from each reset information type(\ref PowerHalResetInfoId).
 551  *        - Value of \ref AGL_PROGUPDATE_STATE, low 3bits are assigned as below, \n
 552  *          and corresponding bit is set if state is updating. \n
 553  *           Low 1bit(\ref PWR_PROGUPDATE_STATE_UPDATED) : Program update \n
 554  *           Low 2bit(\ref PWR_PROGUPDATE_STATE_MAP_UPDATED) : Map update \n
 555  *           Low 3bit(\ref PWR_PROGUPDATE_STATE_MAPDIFF_UPDATED) : Map difference update \n
 556  *        - The API is completed within 1msec after the API is called.
 557  *        - Completeness of data getting by the API is assured by lower layer than power_hal, \n
 558  *          and return -1 as internal IO error when it is occurred abnormal error.
 559  *        - The API can only be used by 1 process.
 560  * \~english @par Classification
 561  *        Public
 562  * \~english @par Type
 563  *        Sync
 564  * \~english @see
 565  *        PowerHalSetResetInfo
 566  */
 567 int PowerHalGetResetInfo(enum PowerHalResetInfoId id, uint32_t *val);
 568
 569 /** @}*/  // end of power_hal
 570 /** @}*/  // end of power_supply_manager_shadow
 571
 572 #endif  // HAL_API_POWER_HAL_H_