service/system/task_manager/server/include/system_service/tskm.h

   1 /*
   2  * @copyright Copyright (c) 2016-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 tskm.h
  19  * @brief \~english This file contains primary API of task manager
  20  */
  21
  22
  23 /** @addtogroup BaseSystem
  24  *  @{
  25  */
  26 /** @addtogroup system_service
  27  *  @ingroup BaseSystem
  28  *  @{
  29  */
  30 /** @addtogroup task_manager
  31  *  @ingroup system_service
  32  *  @{
  33  */
  34
  35 #ifndef TASK_MANAGER_SERVER_INCLUDE_SYSTEM_SERVICE_TSKM_H_
  36 #define TASK_MANAGER_SERVER_INCLUDE_SYSTEM_SERVICE_TSKM_H_
  37
  38
  39 #include <other_service/rpc.h>
  40 #include "system_service/tskm_type.h"
  41
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 #define TSKM_ID             RPC_ID
  48 /////////////////////////////////////////////////////////////////////////////////////
  49 /// \ingroup TSKM_Init
  50 /// \~english @par Summary:
  51 ///       Creates the resource to communicate with Task_Manager.
  52 /// \~english @param [out] *pID
  53 ///        UINT32   - Unique ID of the automatically allocated program
  54 /// \~english @retval None
  55 /// \~english @par Preconditions:
  56 ///       - None
  57 /// \~english @par Changes of the internal state:
  58 ///       - The internal state is not changed
  59 /// \~english @par Causes of failures:
  60 ///       None
  61 /// \~english @par Classification:
  62 ///       Public
  63 /// \~english @par Type
  64 ///       Sync only
  65 /// \~english @par Detail:
  66 ///       Creates the resource to communicate with Task_Manager.  \n
  67 ///       It is necessary to call this before using the APIs of TSKM_xxxx defined after this. \n
  68 ///       It is necessary to call this by the thread. \n
  69 /// \~english @see  TSKM_End
  70 ////////////////////////////////////////////////////////////////////////////////////
  71 #define TSKM_Init(p_tskmId) RPC_START_CLIENT(p_tskmId)
  72 /////////////////////////////////////////////////////////////////////////////////////
  73 /// \ingroup TSKM_End
  74 /// \~english @par Summary:
  75 ///        Releases the resource created at TSKM_Init.
  76 /// \~english @param [in] ID
  77 ///        UINT32   - ID gotten at TSKM_Init()
  78 /// \~english @retval None
  79 /// \~english @par Preconditions:
  80 ///       - TSKM_Init must be used and initialized
  81 /// \~english @par Changes of the internal stat:
  82 ///       - The internal state is not changed
  83 /// \~english @par Causes of failures:
  84 ///       None
  85 /// \~english @par Classification:
  86 ///       Public
  87 /// \~english @par Type
  88 ///       Sync only
  89 /// \~english @par Detail:
  90 ///       Releases the resource created at TSKM_Init.
  91 /// \~english @see  TSKM_Init
  92 ////////////////////////////////////////////////////////////////////////////////////
  93 #define TSKM_End(tskmId)    RPC_end(tskmId)
  94
  95 /////////////////////////////////////////////////////////////////////////////////////
  96 /// \ingroup TSKM_SvcCtl
  97 // \~english @par Summary:
  98 ///        Run the control for service.
  99 /// \~english @param [in] svcid
 100 ///        TSKM_SVCID_t   - Service ID
 101 /// \~english @param [in] ctl
 102 ///        TSKM_SVC_CTL_t*   - Command
 103 /// \~english @code
 104 ///             typedef struct{
 105 ///               TSKM_SVC_CMD_t cmd;
 106 ///             } TSKM_SVC_CTL_t;
 107 ///            @endcode
 108 /// \~english @retval TSKM_E_OK Succeeded
 109 /// \~english @retval TSKM_E_PAR %Parameter error
 110 /// \~english @retval TSKM_E_STATE State error
 111 /// \~english @retval TSKM_E_NG Error
 112 /// \~english @par Preconditions:
 113 ///       - TSKM_Init must be used and initialized
 114 /// \~english @par Changes of the internal state:
 115 ///       - The internal state is not changed
 116 /// \~english @par Causes of failures:
 117 ///       - Parameters ctl is NULL [TSKM_E_PAR]
 118 ///       - Service context is not found [TSKM_E_PAR]
 119 ///       - Before FrameworkunifiedOnStart of Task_Manager is called [TSKM_E_STATE]
 120 ///       - It is prohibited to run designated service [TSKM_E_STATE]
 121 ///       - Message sending failed [TSKM_E_RETRY]
 122 ///       - When the specified service executes the start prohibition except during
 123 ///         the stop or start prohibition status. [TSKM_E_STATE]
 124 ///       - Maximum numbers to register running reservation service are exceeded [TSKM_E_STATE]
 125 ///       - Anything except for the commands specified as parameters is designated [TSKM_E_PAR]
 126 ///       - Writing in files of running reservation information failed [TSKM_E_NG]
 127 /// \~english @par Classification:
 128 ///       Public
 129 /// \~english @par Type
 130 ///       Sync only
 131 /// \~english @par Detail:
 132 ///       - TSKM_SVC_CMD_EXEC\n
 133 ///         Designated service runs. \n
 134 ///         When designated service already runs, this returns TSKM_E_OK without processing service running. \n
 135 ///         Running equal to local_step=all of request element is done. \n
 136 ///         When designated service designates the service that running is prohibited by
 137 ///         TSKM_SVC_CMD_DISABLE, this returns TSKM_E_STATE. \n
 138 ///         This guarantees that service running finished in API succeeding. \n
 139 ///       - TSKM_SVC_CMD_DISABLE\n
 140 ///         This prohibits to run the designated service. \n
 141 ///         At the prohibited service to run already, this returns TSKM_E_OK without doing anything. \n
 142 ///         When this API uses the service to be run already, this returns TSKM_E_STATE. \n
 143 ///         By this, at resident service, it is necessary to call this before running corresponding service. \n
 144 ///         About the prohibited service, this doesn't decide the wait condition of event completion notice
 145 ///         which service running, phase startup, phase end request, corresponding service control. \n
 146 ///         This command is prepared in consideration of changing the service to run in response to
 147 ///         with or without extended BOX and device configuration. \n
 148 ///         Initial values are running permission. \n
 149 ///       - TSKM_SVC_CMD_ENABLE\n
 150 ///         This permits to run the service to be set as running prohibition. \n
 151 ///         At running permission service, this returns TSKM_E_OK without doing anything. \n
 152 ///       - TSKM_SVC_RESERVE\n
 153 ///         This does the running reservation of non-resident service. \n
 154 ///         In next running, designated service runs automatically after finishing in running resident service. \n
 155 ///         Once this runs automatically, this forgets reservation information. \n
 156 ///         Maximum numbers of service able to do running reservation is the values of TSKM_SVC_RESERVE_MAX. \n
 157 ///         When this reserves over maximum numbers, this returns TSKM_E_STATE. \n
 158 ///         When backup RAM is invalid in running, this does not run automatically and
 159 ///         discards reservation information. \n
 160 /// \~english @see  None
 161 ////////////////////////////////////////////////////////////////////////////////////
 162 TSKM_ERR_t TSKM_SvcCtl(TSKM_SVCID_t svcId, const TSKM_SVC_CTL_t* ctl);
 163 /////////////////////////////////////////////////////////////////////////////////////
 164 /// \ingroup TSKM_SvcGetInfo
 165 // \~english @par Summary:
 166 ///        Gets the information of designated service.
 167 /// \~english @param [in] svcid
 168 ///        TSKM_SVCID_t   - Service ID
 169 /// \~english @param [out] svcInfo
 170 ///        TSKM_SVC_INFO_t*   - Service information
 171 /// \~english @code
 172 ///            typedef struct {
 173 ///              TSKM_SVCID_t   svcId;
 174 ///               TSKM_BOOL_t   isExecDisable;
 175 ///            } TSKM_SVC_INFO_t;
 176 ///              svcId  : Service ID
 177 ///              isExecDisable  : Service running prohibition state
 178 ///                TSKM_TRUE  : Running prohibition
 179 ///                TSKM_FALSE : Running permission
 180 ///            @endcode
 181 /// \~english @retval TSKM_E_OK Succeeded
 182 /// \~english @retval TSKM_E_PAR %Parameter error
 183 /// \~english @par Preconditions:
 184 ///       - TSKM_Init must be used and initialized
 185 /// \~english @par Changes of the internal state:
 186 ///       - The internal state is not changed
 187 /// \~english @par Causes of failures:
 188 ///       - Service context is not found [TSKM_E_PAR]
 189 /// \~english @par Classification:
 190 ///       Public
 191 /// \~english @par Type
 192 ///       Sync only
 193 /// \~english @par Detail:
 194 ///       Gets the information of designated service.
 195 /// \~english @see  None
 196 ////////////////////////////////////////////////////////////////////////////////////
 197 TSKM_ERR_t TSKM_SvcGetInfo(TSKM_SVCID_t svcId, TSKM_SVC_INFO_t* svcInfo);
 198 /////////////////////////////////////////////////////////////////////////////////////
 199 /// \ingroup TSKM_ErrorReboot
 200 /// \~english @par Summary:
 201 ///        Let system do abnormal reboot.
 202 /// \~english @param [in] p_info
 203 ///        TSKM_ERROR_REBOOT_t*   - REBOOT information
 204 /// \~english @code
 205 ///            typedef struct {
 206 ///              TSKM_ERROR_REBOOT_TYPE_t type;
 207 ///              TSKM_LOGGING_ INFO_t   log;
 208 ///            } TSKM_ERROR_REBOOT_t;
 209 ///              type
 210 ///                TSKM_ERROR_REBOOT_NORMAL : Abnormal detection
 211 ///              log  : Log saving information
 212 ///                typedef struct {
 213 ///                  char   messageStr[TSKM_LOGGING_MSG_STR_SIZE];
 214 ///                } TSKM_LOGGING_INFO_ t;
 215 ///                  messageStr : Abnormal message character string
 216 ///            @endcode
 217 /// \~english @retval TSKM_E_OK Succeeded
 218 /// \~english @retval TSKM_E_PAR %Parameter error
 219 /// \~english @par Preconditions:
 220 ///       - TSKM_Init must be used and initialized
 221 /// \~english @par Changes of the internal state:
 222 ///       - The internal state is not changed
 223 /// \~english @par Causes of failures:
 224 ///       - Parameters p_info is NULL [TSKM_E_PAR]
 225 ///       - Reboot factors are except for TSKM_ERROR_REBOOT_NORMAL [TSKM_E_PAR]
 226 /// \~english @par Classification:
 227 ///       Public
 228 /// \~english @par Type
 229 ///       Sync only
 230 /// \~english @par Detail:
 231 ///       Does REBOOT. \n
 232 ///       It is assumed to issue when system is damaged if processing continues any more
 233 ///       such as device trouble and non-volatile data trouble. \n
 234 ///       Access limitation is done to this API by gid and uid. \n
 235 ///       When an application with no authorization calls this, this force-quits the application to have called API. \n
 236 ///       This stores the string designated to messageStr as factors in system information LOG. \n
 237 ///       To link with PSMShadow about trouble factors, this designates abnormal message character string defined
 238 ///       inside ss_error_message.h to messageStr.
 239 /// \~english @see  None
 240 ////////////////////////////////////////////////////////////////////////////////////
 241 TSKM_ERR_t TSKM_ErrorReboot(const TSKM_ERROR_REBOOT_t* p_info);
 242 /////////////////////////////////////////////////////////////////////////////////////
 243 /// \ingroup TSKM_Reboot
 244 /// \~english @par Summary:
 245 ///         Let system do reboot.
 246 /// \~english @param [in] rsv
 247 ///        TSKM_RSV_t*   - Reservation ( This must designate NULL)
 248 /// \~english @retval TSKM_E_OK Succeeded
 249 /// \~english @retval TSKM_E_PAR %Parameter error
 250 /// \~english @par Preconditions:
 251 ///       - TSKM_Init must be used and initialized
 252 /// \~english @par Changes of the internal state:
 253 ///       - The internal state is not changed
 254 /// \~english @par Causes of failures:
 255 ///       - Parameters p_rsv is except for NULL [TSKM_E_PAR]
 256 /// \~english @par Classification:
 257 ///       Public
 258 /// \~english @par Type
 259 ///       Sync x Method
 260 /// \~english @par Detail:
 261 ///       Let system do normal reboot.
 262 /// \~english @see  None
 263 ////////////////////////////////////////////////////////////////////////////////////
 264 TSKM_ERR_t TSKM_Reboot(const TSKM_RSV_t * p_rsv);
 265 /////////////////////////////////////////////////////////////////////////////////////
 266 /// \ingroup TSKM_Logging
 267 /// \~english @par Summary:
 268 ///        Stores LOG in internal non-volatile area.
 269 /// \~english @param [in] p_info
 270 ///        TSKM_LOGGING_INFO_t *   - Log storing information
 271 /// \~english @code
 272 ///            typedef struct{
 273 ///              TSKM_LOGGING_TYPE_NORMAL_t type;
 274 ///              char  messageStr[TSKM_LOGGING_MSG_STR_SIZE];
 275 ///            }TSKM_LOGGING_INFO_t;
 276 ///              type   : Log storing type
 277 ///                TSKM_LOGGING_TYPE_MODULE_LOGS: General LOG storing request from service
 278 ///                TSKM_LOGGING_TYPE_GRP_RELAUNCH: Log collection by Group Relaunch
 279 ///              messageStr : Trouble factors
 280 ///            @endcode
 281 /// \~english @retval TSKM_E_OK Succeeded
 282 /// \~english @retval TSKM_E_PAR %Parameter error
 283 /// \~english @par Preconditions:
 284 ///       - TSKM_Init must be used and initialized
 285 /// \~english @par Changes of the internal state:
 286 ///       - The internal state is not changed
 287 /// \~english @par Causes of failures:
 288 ///       - Parameters p_info is NULL [TSKM_E_PAR]
 289 /// \~english @par Classification:
 290 ///       Public
 291 /// \~english @par Type
 292 ///       Sync only
 293 /// \~english @par Detail:
 294 ///       Collects LOG information and stores it in internal non-volatile area \n
 295 ///       This stores the string designated to messageStr as factors in system information LOG.
 296 /// \~english @see  None
 297 ////////////////////////////////////////////////////////////////////////////////////
 298 TSKM_ERR_t TSKM_Logging(const TSKM_LOGGING_INFO_t* p_info);
 299 /////////////////////////////////////////////////////////////////////////////////////
 300 /// \ingroup TSKM_DataInit
 301 /// \~english @par Summary:
 302 ///        Does the initialization process of service data.
 303 /// \~english @param [in] hApp
 304 ///        HANDLE   - Application handle
 305 /// \~english @param [in] p_info
 306 ///        TSKM_DATAINIT_t *   - Data initialization information
 307 /// \~english @code
 308 ///               typedef struct {
 309 ///                 TSKM_DATAINIT_TYPE_t  type;
 310 ///                 EFrameworkunifiedStatus (*onCompInit)(HANDLE hApp);
 311 ///               } TSKM_DATAINIT_t;
 312 ///                 type  : Data initialization type
 313 ///                   TSKM_DATAINIT_TYPE_USER : User data initialization
 314 ///                 onCompInit  : Initialization complete Callback
 315 ///            @endcode
 316 /// \~english @retval TSKM_E_OK Succeeded
 317 /// \~english @retval TSKM_E_PAR %Parameter error
 318 /// \~english @retval TSKM_E_NG Error
 319 /// \~english @par Preconditions:
 320 ///       - TSKM_Init must be used and initialized
 321 /// \~english @par Changes of the internal state:
 322 ///       - The internal state is not changed
 323 /// \~english @par Causes of failures:
 324 ///       - Parameters hAPP is NULL [TSKM_E_PAR]
 325 ///       - Parameters p_info is NULL [TSKM_E_PAR]
 326 ///       - Member type of parameters p_info is except for TSKM_DATAINIT_TYPE_USER [TSKM_E_PAR]
 327 ///       - Member onCompInit of parameters p_info is NULL [TSKM_E_PAR]
 328 ///       - The process of FrameworkunifiedAttachCallbackToDispatcher failed [TSKM_E_NG]
 329 ///       - The process of FrameworkunifiedOpenService failed [TSKM_E_STATE]
 330 ///       - The process of FrameworkunifiedSendMsg failed [TSKM_E_NG]
 331 /// \~english @par Classification:
 332 ///       Public
 333 /// \~english @par Type
 334 ///       Method only
 335 /// \~english @par Detail:
 336 ///       - How to report \n
 337 ///       Reports by Callback of onCompInit. \n
 338 ///       This can get message data by calling GetMsgData inside onCompInit. \n
 339 ///       - Structure of message data \n
 340 ///       TSKM_ERR_t:Processing result \n
 341 ///       TSKM_E_OK :Normal end \n
 342 ///       TSKM_E_STATE  :State error \n
 343 ///       TSKM_E_NG :Error
 344 ///       - Summary of action \n
 345 ///       Calls initialization functions which each service implemented. \n
 346 ///       When this API was called before Availability of Task_Manager becomes TRUE, this
 347 ///       does not call initialization functions and returns TSKM_E_STATE by onCompInit. \n
 348 ///       It is permitted for same application to call this API several times, at this case,
 349 ///       it is necessary to designate the pointer to same functions to onCompInit. \n
 350 ///       When this API was called by designating TSKM_DATAINIT_TYPE_USER to type, this calls
 351 ///       the initialization functions of each service by designating the following parameters. \n
 352 ///       <table>
 353 ///       <tr><th>Member</th><th>Values</th></tr>
 354 ///       <tr><td>startupReason</td><td>epswfIGN_ACC</td></tr>
 355 ///       <tr><td>isUserModeOn</td><td>TRUE</td></tr>
 356 ///       <tr><td>dataResetMode</td><td>e_SS_SM_DATA_RESET_MODE_USER</td></tr>
 357 ///       <tr><td>wakeupType</td><td>epsstWARMSTART</td></tr>
 358 ///       <tr><td>dramBackupStatus</td><td>e_SS_SM_DRAM_BACKUP_OK</td></tr>
 359 ///       <tr><td>resetStatus</td><td>e_SS_SM_RESET_STATUS_NONE</td></tr>
 360 ///       <tr><td>resetCount</td><td>0</td></tr>
 361 ///       </table>
 362 ///       Because Task_Manager calls the initialization functions of each service and implements
 363 ///       the recovery processing according to running factors at the timing of fixing running factor,
 364 ///       this designates the above parameters not to do duplicate recover processing.
 365 /// \~english @see  TSKM_DATA_INIT_FUNC
 366 ////////////////////////////////////////////////////////////////////////////////////
 367 TSKM_ERR_t TSKM_DataInit(HANDLE hApp, const TSKM_DATAINIT_t *p_info);
 368 /////////////////////////////////////////////////////////////////////////////////////
 369 /// \ingroup TSKM_SetWakeupOrder
 370 /// \~english @par Summary:
 371 ///        Holds running order.
 372 /// \~english @param [in] p_order
 373 ///        TSKM_WAKEUP_ORDER_t *   - Running order information
 374 /// \~english @code
 375 ///               typedef struct {
 376 ///                 char orderName[TSKM_ORDER_NAME_MAX];
 377 ///               } TSKM_WAKEUP_ORDER_t;
 378 ///                 orderName: Order name (MAX:31 characters)
 379 ///            @endcode
 380 /// \~english @retval TSKM_E_OK Succeeded
 381 /// \~english @retval TSKM_E_PAR %Parameter error
 382 /// \~english @retval TSKM_E_NG Error
 383 /// \~english @par Preconditions:
 384 ///       - TSKM_Init must be used and initialized
 385 /// \~english @par Changes of the internal state:
 386 ///       - The internal state is not changed
 387 /// \~english @par Causes of failures:
 388 ///       - Parameters p_order is NULL [TSKM_E_PAR]
 389 ///       - The string length of the member orderName of Parameters p_order exceeds 32 [TSKM_E_PAR]
 390 ///       - The process of SetWakeupOrderToSystemManager failed [TSKM_E_NG]
 391 /// \~english @par Classification:
 392 ///       Public
 393 /// \~english @par Type
 394 ///       Sync x Sync
 395 /// \~english @par Detail:
 396 ///       This function is Wrapper function to provide SetWakeupOrderToSystemManager
 397 ///       by sessionless which SystemManger provides.
 398 ///       This designates NULL to p_order and returns TSKM_E_PAR.
 399 ///       For the detail of action, refer to SystemManager (SetWakeupOrderToSystemManager).
 400 /// \~english @see  None
 401 ////////////////////////////////////////////////////////////////////////////////////
 402 TSKM_ERR_t TSKM_SetWakeupOrder(const TSKM_WAKEUP_ORDER_t* p_order);
 403 #ifdef __cplusplus
 404 }
 405 #endif
 406
 407 #endif  // TASK_MANAGER_SERVER_INCLUDE_SYSTEM_SERVICE_TSKM_H_
 408
 409 /** @}*/  // end of Task_Manager
 410 /** @}*/  // end of SystemService
 411 /** @}*/  // end of BaseSystem
 412
 413