service/system/task_manager/server/include/system_service/INI_API.hpp

   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 INI_API.hpp
  19  * @brief \~english This file provide api to operating INI
  20  */
  21
  22 /** @addtogroup BaseSystem
  23  *  @{
  24  */
  25 /** @addtogroup system_service
  26  *  @ingroup BaseSystem
  27  *  @{
  28  */
  29 /** @addtogroup task_manager
  30  *  @ingroup system_service
  31  *  @{
  32  */
  33
  34 #ifndef _INI_API_HPP_
  35 #define _INI_API_HPP_
  36
  37 #include <native_service/frameworkunified_types.h>
  38 #include <system_service/ss_system_manager_if.h>
  39 #include "system_service/Primary_common.h"
  40
  41 #define INI_SUCCESS                 0              /* Normal */
  42 #define INI_FALSE                  -1              /* Failed */
  43
  44 #define INI_FD_MAX                  3
  45
  46 // Only the information required for event completion notification is left
  47 // Gradual startup
  48 #define INI_INITCOMP_NONE                   0x0000000000000000LLU
  49 #define INI_INITCOMP_ON_START               0x0000000000000001LLU   /* ON_START    */
  50 #define INI_INITCOMP_NVM_ACCESS             0x0000000000000002LLU   /* NVM ACCESS  */
  51
  52 #define INI_INITCOMP_TEST0                  0x1000000000000000LLU   /* for test    */
  53 #define INI_INITCOMP_TEST1                  0x2000000000000000LLU   /* for test    */
  54 #define INI_INITCOMP_TEST2                  0x4000000000000000LLU   /* for test    */
  55 #define INI_INITCOMP_TEST3                  0x8000000000000000LLU   /* for test    */
  56
  57 // Gradual termination
  58 #define INI_TERMCOMP_NONE                   0x0000000000000000LLU
  59 #define INI_TERMCOMP_ACTIVITYMGR            0x0000000000000001LLU   /* Terminate ActivityManager  */
  60 #define INI_TERMCOMP_RESIDENT               0x0000000000000002LLU   /* Terminate regident SVC     */
  61 #define INI_TERMCOMP_TRANSIENT              0x0000000000000004LLU   /* Terminate non-regident SVC */
  62
  63 #define INI_TERMCOMP_TEST0                  0x1000000000000000LLU   /* for test    */
  64 #define INI_TERMCOMP_TEST1                  0x2000000000000000LLU   /* for test    */
  65 #define INI_TERMCOMP_TEST2                  0x4000000000000000LLU   /* for test    */
  66 #define INI_TERMCOMP_TEST3                  0x8000000000000000LLU   /* for test    */
  67
  68
  69
  70 typedef struct _T_PRIM_PRM{
  71   PCSTR                      name;
  72   const PRIM_SHAREDATA_TBL*  shmTbl;
  73   const PRIM_EXFUNC_TBL*     wakeupExFuncTbl;
  74   const PRIM_EXFUNC_TBL*     downExFuncTbl;
  75   EFrameworkunifiedStatus (*onInit)(HANDLE hApp);
  76   EFrameworkunifiedStatus (*onDestory)(HANDLE hApp);
  77   EFrameworkunifiedStatus (*onDebugDump)(HANDLE hApp);
  78   EFrameworkunifiedStatus (*onTouch)(HANDLE hApp);
  79   EFrameworkunifiedStatus (*onLowMem)(HANDLE hApp);
  80   void* priv;
  81   _T_PRIM_PRM(){
  82     name            = NULL;
  83     shmTbl          = NULL;
  84     wakeupExFuncTbl = NULL;
  85     downExFuncTbl   = NULL;
  86     onInit          = NULL;
  87     onDestory       = NULL;
  88     onDebugDump     = NULL;
  89     onTouch         = NULL;
  90     onLowMem        = NULL;
  91     priv            = NULL;
  92   }
  93 }T_PRIM_PRM;
  94
  95
  96 typedef struct {
  97   BOOL      bIsRun;
  98   uint32_t  timeout;
  99 }T_PRIM_MONITOR_PRM;
 100
 101 #ifdef __cplusplus
 102 extern "C" {
 103 #endif
 104
 105 /////////////////////////////////////////////////////////////////////////////////////
 106 /// \ingroup INI_Main
 107 /// \~english @par Summary:
 108 ///        Runs the main thread of primary library.
 109 /// \~english @param  [in] p_prm
 110 ///        T_PRIM_PRM   - The pointer to the parameter table of primary library
 111 /// \~english @param  [in] argc
 112 ///        int   -  The number of command parameters (The parameters passed to main functions must be set without processing.)
 113 /// \~english @param  [in] argv
 114 ///        char* -  Command parameters (The parameters passed to main functions must be set without processing.)
 115 /// \~english @par
 116 ///    - Shared memory creation table \n
 117 ///      In process running, register the shared memory to create.\n
 118 ///      This creates the shared memory to be registered in process running and releases it in process end.\n
 119 ///      This must terminate by adding {"\0"} into member shmName of table termination.\n
 120 ///      It is able to access to the shared memory to have been created by shm_open.\n
 121 /// \~english @code
 122 ///         typedef struct {
 123 ///             char       shmName[32];                   /* Shared memory name           */
 124 ///             uint32_t   size;                          /* Shared memory size (BYTE) */
 125 ///         }PRIM_SHAREDATA_TBL;
 126 ///            @endcode
 127 /// \~english @par
 128 ///    - Running extended function table / End extended function table \n
 129 ///      Registers callback functions to be called in process start and exit.\n
 130 ///      This must terminate by adding NULL into member func of table termination.\n
 131 ///      Parameters prm of callback functions are User private information and the pointer designated by prm is passed as input parameters [in].\n
 132 ///      Local phase numbers callback func by the designated phase numbers.\n
 133 /// \~english @code
 134 ///         typedef struct {
 135 ///             void     (* func)( void* prm);             /* Callback functions for function extension           */
 136 ///             void*    prm;                              /* The pointer to the parameters of Callback function func  */
 137 ///             uint8_t  localStep;                        /* Local phase numbers                       */
 138 ///             uint8_t  rsv[3];                           /* Reserve for alignment               */
 139 ///         }PRIM_EXFUNC_TBL;
 140 ///            @endcode
 141 /// \~english @par
 142 ///    - %Parameter table of primary library\n
 143 ///      For FrameworkunifiedOnInitialization/FrameworkunifiedOnDestroy/FrameworkunifiedOnDebugDump/TaskmanagerOnTouch/FrameworkunifiedOnLowMemory, check the corresponding API specification.\n
 144 ///      It is able to get User private data by INI_GetPrivate().\n
 145 /// \~english @code
 146 ///         typedef struct _T_PRIM_PRM{
 147 ///             PCSTR                      name;            /* Application name                       */
 148 ///             const PRIM_SHAREDATA_TBL*  shmTbl;          /* The pointer to shared memory creation table        */
 149 ///             const PRIM_EXFUNC_TBL*     wakeupExFuncTbl; /* The pointer to running extended function table          */
 150 ///             const PRIM_EXFUNC_TBL*     downExFuncTbl;   /* The pointer to end extended function table          */
 151 ///             EFrameworkunifiedStatus (*onInit)(HANDLE hApp);          /* FrameworkunifiedOnInitialization callback function setting */
 152 ///             EFrameworkunifiedStatus (*onDestory)(HANDLE hApp);       /* FrameworkunifiedOnDestroy callback function setting        */
 153 ///             EFrameworkunifiedStatus (*onDebugDump)(HANDLE hApp);     /* FrameworkunifiedOnDebugDump Callback function setting     */
 154 ///             EFrameworkunifiedStatus (*onTouch)(HANDLE hApp);         /* TaskmanagerOnTouch callback function setting          */
 155 ///             EFrameworkunifiedStatus (*onLowMem)(HANDLE hApp);        /* FrameworkunifiedOnLowMemory callback function setting      */
 156 ///             void* priv;                                 /* User private data */
 157 ///         }T_PRIM_PRM;
 158 ///            @endcode
 159 /// \~english @retval INI_SUCCESS Normal end
 160 /// \~english @retval INI_FALSE  Abnormal end
 161 /// \~english @par Preconditions:
 162 ///       - None
 163 /// \~english @par Changes of the internal state:
 164 ///       - The internal state is not changed
 165 /// \~english @par Causes of failures:
 166 ///       - The pointer to the parameter table of primary library is NULL [INI_FALSE]
 167 ///       - The pointer to the shared memory creation table inside the parameter table of primary library is NULL [INI_FALSE]
 168 ///       - The pointer to the running extended function table inside the parameter table of primary library is NULL [INI_FALSE]
 169 ///       - The pointer to the end extended function table inside the parameter table of primary library is NULL [INI_FALSE]
 170 ///       - The setting of FrameworkunifiedOnInitialization callback function inside the parameter table of primary library is NULL [INI_FALSE]
 171 ///       - The setting of FrameworkunifiedOnDestroy callback function inside the parameter table of primary library is NULL [INI_FALSE]
 172 ///       - The setting of FrameworkunifiedOnDebugDump callback function inside the parameter table of primary library is NULL [INI_FALSE]
 173 ///       - The setting of TaskmanagerOnTouch callback function inside the parameter table of primary library is NULL [INI_FALSE]
 174 /// \~english @par Classification:
 175 ///       Public
 176 /// \~english @par Type
 177 ///       Method only
 178 /// \~english @par Detail:
 179 ///       This executes the main processing of primary library. Functions do not return until all of end processing of process is completed. \n
 180 ///       Normal end returns INI_SUCCESS and abnormal end does INI_FALSE. \n
 181 ///       User process must return this function's returned values as the returned values of main function and end main function. \n
 182 /// \~english @see  INI_Init
 183 ////////////////////////////////////////////////////////////////////////////////////
 184 int     INI_Main(T_PRIM_PRM* p_prm,int argc,char* argv[]);
 185
 186 /////////////////////////////////////////////////////////////////////////////////////
 187 /// \ingroup INI_ExitStart
 188 /// \~english @par Summary:
 189 ///        Starts the end processing of process.
 190 /// \~english @param  [in] rsv
 191 ///        void*   - The pointer to reservation parameters (NULL must be appointed)
 192 /// \~english @retval None
 193 /// \~english @par Preconditions:
 194 ///       - None
 195 /// \~english @par Changes of the internal state:
 196 ///       - The internal state is not changed
 197 /// \~english @par Causes of failures:
 198 ///       - None
 199 /// \~english @par Classification:
 200 ///       Public
 201 /// \~english @par Type
 202 ///       Sync only
 203 /// \~english @par Detail:
 204 ///       Collects the resource which primary library got, does the end processing equal to local_step=all and end process. \n
 205 ///       (At the end processing in abnormality, process must be ended by not this function but exit(),_exit() function immediately) \n
 206 ///       When this API is called after this API is already called, do nothing to process.
 207 /// \~english @par Supplemtent:
 208 ///       local_step is the information defined in default_wakeup.xml/default_shutdown.xml as the definition of running order / end order. \n
 209 ///       local_step defined in default_shutdown.xml has the following types.
 210 ///       - 1-9  : Designates local phase numbers (the phase numbers of end processing)
 211 ///       - last : This designates local phase numbers to be last. When there is the local phase processing not to be executed, this executes all.
 212 ///       - all  : The same as last.
 213 /// \~english @see  INI_Main, INI_Init, INI_ExitDone
 214 ////////////////////////////////////////////////////////////////////////////////////
 215 void    INI_ExitStart(void* rsv); // Termination process start
 216
 217 /////////////////////////////////////////////////////////////////////////////////////
 218 /// \ingroup INI_ExitDone
 219 /// \~english @par Summary:
 220 ///        Notifies the completion of process end processing.
 221 /// \~english @param  [in] status
 222 ///        int   -   Unused (This is for future extension. 0 must be designated.)
 223 /// \~english @retval None
 224 /// \~english @par Preconditions:
 225 ///       - None
 226 /// \~english @par Changes of the internal state:
 227 ///       - The internal state is not changed
 228 /// \~english @par Causes of failures:
 229 ///       - None
 230 /// \~english @par Classification:
 231 ///       Public
 232 /// \~english @par Type
 233 ///       Sync only
 234 /// \~english @par Detail:
 235 ///       Notifies the completion of service end processing to TaskManager. \n
 236 ///       TaskManager ends the corresponding service by this notification. At the time, this callbacks FrameworkunifiedOnDestroy(). \n
 237 /// \~english @see  INI_Main, INI_Init, INI_ExitStart
 238 ////////////////////////////////////////////////////////////////////////////////////
 239 void    INI_ExitDone(int status);  // Termination process completed
 240
 241 /////////////////////////////////////////////////////////////////////////////////////
 242 /// \ingroup INI_GetPrivate
 243 /// \~english @par Summary:
 244 ///        Gets private data.
 245 /// \~english @param  None
 246 /// \~english @retval void*  The pointer to user private data
 247 /// \~english @par Preconditions:
 248 ///       - INI_Main or INI_Init must be called and user private data must be set.
 249 /// \~english @par Changes of the internal state:
 250 ///       - The internal state is not changed
 251 /// \~english @par Causes of failures:
 252 ///       - None
 253 /// \~english @par Classification:
 254 ///       Public
 255 /// \~english @par Type
 256 ///       Sync only
 257 /// \~english @par Detail:
 258 ///       Gets the private data designated at INI_Main/INI_Init from the inside of the context management information of the process inside primary library and returns it.
 259 /// \~english @see  INI_Main, INI_Init
 260 ////////////////////////////////////////////////////////////////////////////////////
 261 void*   INI_GetPrivate();
 262
 263 /////////////////////////////////////////////////////////////////////////////////////
 264 /// \ingroup INI_GetHandle
 265 /// \~english @par Summary:
 266 ///        Gets the application handle of NSFW.
 267 /// \~english @param  None
 268 /// \~english @retval void*(HANDLE)  The application handle of NSFW
 269 /// \~english @par Preconditions:
 270 ///       - INI_Main or INI_Init must be called and the application handle of NSFW must be generated.
 271 /// \~english @par Changes of the internal state:
 272 ///       - The internal state is not changed
 273 /// \~english @par Causes of failures:
 274 ///       - None
 275 /// \~english @par Classification:
 276 ///       Public
 277 /// \~english @par Type
 278 ///       Sync only
 279 /// \~english @par Detail:
 280 ///       Gets the application handle of NSFW from the inside of the context management information of the process inside primary library and returns it.
 281 /// \~english @see  INI_Main, INI_Init
 282 ////////////////////////////////////////////////////////////////////////////////////
 283 void*   INI_GetHandle();
 284
 285 /////////////////////////////////////////////////////////////////////////////////////
 286 /// \ingroup INI_SetMonitorTimeout
 287 /// \~english @par Summary:
 288 ///        Requests the change for abnormality monitoring timeout time to Task Manager. \n
 289 ///        (This is used when main thread is not implemented at service side)
 290 /// \~english @param  [in] timeout
 291 ///        uint32_t -  Abnormality monitoring timeout time (sec)(When 0 is designated, the service must be out of abnormality monitoring object.)
 292 /// \~english @retval INI_SUCCESS Succeeded
 293 /// \~english @par Preconditions:
 294 ///       - Main thread must be run at INI_Main()
 295 /// \~english @par Changes of the internal state:
 296 ///       - The internal state is not changed
 297 /// \~english @par Causes of failures:
 298 ///       - None
 299 /// \~english @par Classification:
 300 ///       Public
 301 /// \~english @par Type
 302 ///       Sync only
 303 /// \~english @par Detail:
 304 ///       Sets the abnormality monitoring timeout time designated by parameters inside the context management information of the process inside primary library and returns returned values and INI_SUCCESS. \n
 305 ///       Set timeout time becomes valid after the event waiting at the loop of main thread and this requests the change for service abnormality monitoring timeout time to TaskManager. In other words, this API can be used after running extended function Callback. \n
 306 ///       When process does not return to main thread past the timeout time designated by this function, TaskManager ends the service forcibly. When this function is not called, TaskManager treats the timeout of monitoring time as 50 seconds.
 307 /// \~english @see  INI_Main
 308 ////////////////////////////////////////////////////////////////////////////////////
 309 int32_t INI_SetMonitorTimeout(uint32_t timeout);
 310
 311 // Event completion notification
 312 /////////////////////////////////////////////////////////////////////////////////////
 313 /// \ingroup INI_StepForkComp
 314 /// \~english @par Summary:
 315 ///        Notifies the completion of running event to TaskManager.
 316 /// \~english @param  [in] compId
 317 ///        uint64_t   - The comparison ID for phase running (Designates INI_INITCOMP_[a-zA-Z_]+ to define at INI_API.hpp)
 318 /// \~english @par
 319 ///        The ID descripted at INI_API.hpp
 320 /// \~english @code
 321 ///        - INI_INITCOMP_NONE:         None
 322 ///        - INI_INITCOMP_ON_START:    For ON Start
 323 ///        - INI_INITCOMP_NVM_ACCESS:  For NVM access
 324 ///            @endcode
 325 /// \~english @retval INI_SUCCESS Succeeded
 326 /// \~english @retval INI_FALSE  Failed
 327 /// \~english @par Preconditions:
 328 ///       - INI_Main or INI_Init must be called.
 329 /// \~english @par Changes of the internal state:
 330 ///       - The internal state is not changed
 331 /// \~english @par Causes of failures:
 332 ///       - The sending of the completion notification of running event to TaskManager failed [INI_FALSE]
 333 /// \~english @par Classification:
 334 ///       Public
 335 /// \~english @par Type
 336 ///       Sync only
 337 /// \~english @par Detail:
 338 ///       Sends the comparison ID for phase running as the completion notification of running event to TaskManager. If it succeeded, returns INI_SUCCESS and if it failed, does INI_FALSE. \n
 339 ///       TaskManager holds which completion notification of running event is notified and can add it to the transition conditions to next phase at phase running. \n
 340 ///       The way to add at TaskManager side depends on the definition of next_trans_condition element described in default_wakeup.xml as the definition of running order.
 341 /// \~english @par Supplement:
 342 ///       next_trans_condition is the element to designate transition conditions to next phase. The transition to next phase is done when the following two conditions are met. \n
 343 ///       When the description of next_trans_condition element is omitted, transition is done only by condition 1. \n
 344 ///       1. All of the phase running request processing set by request element is completed. (The phase running request processing is executed by primary library asynchronously) \n
 345 ///       2. The completion notification of the event designated by next_trans_condition element is completed. \n
 346 ///       Waiting conditions for event completion notification INI_INITCOMP_[A-Z]+ stipulated at INI_API.hpp is set in cond property designated at next_trans_condition element. \n
 347 ///       AND condition can be set by being INI_INITCOMP_AAAA| INI_INITCOMP_BBBB when conditions are some. \n
 348 ///       Event completion notification can be issued by using INI_StepForkComp.
 349 /// \~english @see  INI_Main, INI_Init
 350 ////////////////////////////////////////////////////////////////////////////////////
 351 int32_t INI_StepForkComp(uint64_t compId);
 352
 353 // Event completion notification
 354 /////////////////////////////////////////////////////////////////////////////////////
 355 /// \ingroup INI_AccOffComp
 356 /// \~english @par Summary:
 357 ///        Notifies end event completion notification to TaskManager.
 358 /// \~english @param  [in] compId
 359 ///        uint64_t   - The comparison ID for phase running (Designates INI_TERMCOMP_[a-zA-Z_]+ defined at INI_API.hpp)
 360 /// \~english @par
 361 ///        The ID described at INI_API.hpp
 362 /// \~english @code
 363 ///        - INI_TERMCOMP_NONE         :  None
 364 ///        - INI_TERMCOMP_ACTIVITYMGR  : For ActivityManager end
 365 ///        - INI_TERMCOMP_RESIDENT     : For resident service end
 366 ///        - INI_TERMCOMP_TRANSIENT    : For non-resident service end
 367 ///            @endcode
 368 /// \~english @retval INI_SUCCESS Succeeded
 369 /// \~english @retval INI_FALSE  Failed
 370 /// \~english @par Preconditions:
 371 ///       - INI_Main or INI_Init must be called
 372 /// \~english @par Changes of the internal state:
 373 ///       - The internal state is not changed
 374 /// \~english @par Causes of failures:
 375 ///       - The sending of the completion notification of end event to TaskManager failed [INI_FALSE]
 376 /// \~english @par Classification:
 377 ///       Public
 378 /// \~english @par Type
 379 ///       Sync only
 380 /// \~english @par Detail:
 381 ///       Sends the comparison ID for phase running as the completion notification of end event to TaskManager. If it succeeded, returns INI_SUCCESS and if it failed, return INI_FALSE. \n
 382 ///       TaskManager holds which completion notification of end event is notified and can add it to the transition conditions to next phase at phase end. \n
 383 ///       The way to add at TaskManager side depends on the definition of next_trans_condition element described in default_shutdown.xml as the definition of end order.
 384 /// \~english @par Supplement:
 385 ///       next_trans_condition is the element to designate transition conditions to next phase. The transition to next phase is done when the following two conditions are met. \n
 386 ///       When the description of next_trans_condition element is omitted, transition is done only by condition 1. \n
 387 ///       1. All of the phase end request processing set by request element is completed. (The phase end request processing is executed by primary library asynchronously) \n
 388 ///       2. The completion notification of the event designated by next_trans_condition element is completed. Waiting conditions for event completion notification INI_INITCOMP_[A-Z]+ stipulated at INI_API.hpp is set in cond property designated at next_trans_condition element. \n
 389 ///       AND condition can be set by being INI_INITCOMP_AAAA| INI_INITCOMP_BBBB when conditions are some. \n
 390 ///       Event completion notification can be issued by using INI_ AccOffComp.
 391 /// \~english @see  INI_Main, INI_Init
 392 ////////////////////////////////////////////////////////////////////////////////////
 393 int32_t INI_AccOffComp(uint64_t compId);
 394
 395 // Get boot info
 396 /////////////////////////////////////////////////////////////////////////////////////
 397 /// \ingroup INI_GetBootInfo
 398 // \~english @par Summary:
 399 ///        Gets boot information.
 400 /// \~english @param  [in] info
 401 ///        T_SS_SM_START_DataStructType *   - The pointer to boot information structure
 402 /// \~english @par
 403 ///         T_SS_SM_START_DataStructType structure
 404 /// \~english @code
 405 ///            typedef struct T_SS_SM_START_DataStruct{
 406 ///                EPWR_WAKEUP_FACTOR_TYPE   startupReason;    /* Startup reason                   */
 407 ///                BOOL                      isUserModeOn;     /* User mode ON/OFF         */
 408 ///                ESMDataResetModeInfo      dataResetMode;    /* Data reset mode       */
 409 ///                EPWR_SC_SECURITY_STATUS   securityStatus;   /* Security state           */
 410 ///                EPWR_SC_WAKEUP_TYPE       wakeupType;       /* Battery disconnection state         */
 411 ///                ESMDramBackupStatus       dramBackupStatus; /* Backup memory area state */
 412 ///                ESMResetStatus            resetStatus;      /* Reset state               */
 413 ///              UI_32                     resetCount;       /* Abnormal reboot number           */
 414 ///            } T_SS_SM_START_DataStructType;
 415 ///
 416 ///            Startup reason type:
 417 ///                - epswfIGN_ACC     : Ignition ACC (Currently, Fixed)
 418 ///            User mode ON/OFF:
 419 ///                - TRUE             : User mode ON     (Currently, Fixed)
 420 ///            Data reset mode:
 421 ///                - e_SS_SM_DATA_RESET_NONE: Not-initialized
 422 ///                - e_SS_SM_DATA_RESET_USER: User data initialization
 423 ///                - e_SS_SM_DATA_RESET_FACTORY: Factory initialization
 424 ///            Security state:
 425 ///                - epsssUNLOCK      : Unlock state
 426 ///                - epsssLOCK        : Lock state
 427 ///            Battery disconnection state:
 428 ///                - epsstWARMSTART   : Battery disconnection does not occur
 429 ///                - epsstCOLDSTART   : Battery disconnection occurs
 430 ///            Backup memory area state:
 431 ///                - e_SS_SM_DRAM_BACKUP_OK: Backup OK of Backup memory area
 432 ///                - e_SS_SM_DRAM_BACKUP_NG: Backup NG of Backup memory area
 433 ///            Reset state:
 434 ///                - e_SS_SM_RESET_STATUS_UNSET: Information unsetting(Not decided yet)
 435 ///                - e_SS_SM_RESET_STATUS_NONE : Normal
 436 ///                - e_SS_SM_RESET_STATUS_NG   : Abnormality occurred (Abnormal RESET or booting after service abnormal end)
 437 ///                - e_SS_SM_RESET_STATUS_IMMEDIATE : Immediate RESET occurred
 438 ///            @endcode
 439 /// \~english @retval INI_SUCCESS Succeeded
 440 /// \~english @retval INI_FALSE  Failed
 441 /// \~english @par Preconditions:
 442 ///       - INI_Main or INI_Init must be called. (%Process running must be completed)
 443 /// \~english @par Changes of the internal state:
 444 ///       - The internal state is not changed
 445 /// \~english @par Causes of failures:
 446 ///       - The pointer to boot information structure designated at parameters is NULL [INI_FALSE]
 447 ///       - Startup reason type inside the context management information of the process inside primary library is wrong (%Process running is not completed) [INI_FALSE]
 448 /// \~english @par Classification:
 449 ///       Public
 450 /// \~english @par Type
 451 ///       Sync only
 452 /// \~english @par Detail:
 453 ///       Gets boot information which is managed inside the context management information of the process inside primary library.
 454 ///       If it succeeded, returns INI_SUCCESS and if it failed, does INI_FALSE. \n
 455 ///       This sets valid values as info values in FrameworkunifiedOnStart of TaskManager. In other words, this sets valid values after running ActivityManager.
 456 /// \~english @see  INI_Main, INI_Init
 457 ////////////////////////////////////////////////////////////////////////////////////
 458 int32_t INI_GetBootInfo(T_SS_SM_START_DataStructType *info);
 459
 460 /////////////////////////////////////////////////////////////////////////////////////
 461 /// \ingroup INI_GetExtBootInfo
 462 /// \~english @par Summary:
 463 ///        Gets boot extended information.
 464 /// \~english @param  [in] info
 465 ///        T_SS_SM_START_ExtDataStructType *   - The pointer to boot extended information structure
 466 /// \~english @par
 467 ///         T_SS_SM_START_ExtDataStructType structure
 468 /// \~english @code
 469 ///            #define SS_SM_START_EXT_INFO_SIZE 64
 470 ///            #define SS_SM_START_EXT_BODY_SIZE ( sizeof(BOOL)
 471 ///                                                + sizeof(EMRelaunchStatus)
 472 ///                                                + sizeof(BOOL)
 473 ///                                                + sizeof(BOOL)
 474 ///                                              )
 475 ///            define SS_SM_START_EXT_RSV_SIZE  SS_SM_START_EXT_INFO_SIZE
 476 ///                                            - SS_SM_START_EXT_BODY_SIZE
 477 ///            typedef struct {
 478 ///                BOOL                      isProgUpdated;     /* Program update information       */
 479 ///                EMRelaunchStatus relaunchStatus;             /* Own-service Relaunch state */
 480 ///                BOOL             isMapUpdated;               /* Map update information               */
 481 ///                BOOL             isMapDiffUpdated;           /* Map difference update information         */
 482 ///                uint8_t          reserved[SS_SM_START_EXT_RSV_SIZE]; /* Reserve area     */
 483 ///            } T_SS_SM_START_ExtDataStructType;
 484 ///
 485 ///            Program update information
 486 ///                - TRUE  : Program update
 487 ///                - FALSE : No Program update
 488 ///            Own-service Relaunch state:
 489 ///                - e_SS_SM_RELAUNCH_STATUS_NONE : Relaunch does not occur (Initial boot)
 490 ///                - e_SS_SM_RELAUNCH_STATUS_SAFE : Normal Relaunch
 491 ///                - e_SS_SM_RELAUNCH_STATUS_ERR  : Abnormal Relaunch
 492 ///            Map update information:
 493 ///                - TRUE  : Map update
 494 ///                - FALSE : No Map update
 495 ///            Map difference update information
 496 ///                - TRUE  : Map difference update
 497 ///                - FALSE : No Map difference update
 498 ///            @endcode
 499 /// \~english @retval INI_SUCCESS Succeeded
 500 /// \~english @retval INI_FALSE  Failed
 501 /// \~english @par Preconditions:
 502 ///       - INI_Main or INI_Init must be called. (%Process running must be completed.)
 503 /// \~english @par Changes of the internal state:
 504 ///       - The internal state is not changed
 505 /// \~english @par Causes of failures:
 506 ///       - The pointer to boot information structure designated at parameters is NULL [INI_FALSE]
 507 ///       - Startup reason type inside the context management information of the process inside primary library is wrong (%Process running is not completed) [INI_FALSE]
 508 /// \~english @par Classification:
 509 ///       Public
 510 /// \~english @par Type
 511 ///       Sync only
 512 /// \~english @par Detail:
 513 ///       Gets boot extended information which is managed inside the context management information of the process inside primary library.
 514 ///       If it succeeded, returns INI_SUCCESS and if it failed, does INI_FALSE \n
 515 ///       This sets valid values as info values in FrameworkunifiedOnStart of TaskManager. In other words, this sets valid values after running ActivityManager.
 516 ///       Because TaskManager does not have Relaunch function, always sets e_SS_SM_RELAUNCH_STATUS_NONE in relaunchStatus.
 517 /// \~english @see  INI_Main, INI_Init
 518 ////////////////////////////////////////////////////////////////////////////////////
 519 int32_t INI_GetExtBootInfo(T_SS_SM_START_ExtDataStructType *info);
 520
 521 //withoutMainLoop
 522 /////////////////////////////////////////////////////////////////////////////////////
 523 /// \ingroup INI_Init
 524 /// \~english @par Summary:
 525 ///        Initializes primary library. \n
 526 ///        (This is used when implementing main thread at service side)
 527 /// \~english @param  [in] p_prm
 528 ///        T_PRIM_PRM   - The pointer to parameter table of primary library
 529 /// \~english @param  [in] argc
 530 ///        int   -  The number of command parameters (The parameters passed to main functions must be set without processing)
 531 /// \~english @param  [in] argv
 532 ///        char* -  Command parameters (The parameters passed to main functions must be set without processing)
 533 /// \~english @param  [out] fdNum
 534 ///        int * -  The number of element stored in fdlist (INI_FD_MAX:3)
 535 /// \~english @param  [out] fdlist[INI_FD_MAX]
 536 ///        int -  The array of FD (File Descriptor) for event reception which primary library waits
 537 /// \~english @par
 538 ///    - Shared memory creation table \n
 539 ///      In process running, register the shared memory to create. \n
 540 ///      This creates the shared memory to be registered in process running and releases it in process end. \n
 541 ///      This must terminate by adding {"\0"} into member shmName of table termination. \n
 542 ///      It is able to access to the shared memory to have been created by shm_open. \n
 543 /// \~english @code
 544 ///         typedef struct {
 545 ///             char       shmName[32];                   /* Shared memory name           */
 546 ///             uint32_t   size;                          /* Shared memory size (BYTE) */
 547 ///         }PRIM_SHAREDATA_TBL;
 548 ///            @endcode
 549 /// \~english @par
 550 ///    - Running extended function table / End extended function table \n
 551 ///      Registers callback functions to be called in process start and exit. \n
 552 ///      This must terminate by adding NULL into member func of table termination. \n
 553 ///      Parameters prm of callback functions are User private information and the pointer designated by prm is passed as input parameters [in]. \n
 554 ///      Local phase numbers callback func by the designated phase numbers. \n
 555 /// \~english @code
 556 ///         typedef struct {
 557 ///             void     (* func)( void* prm);             /* Callback functions for function extension           */
 558 ///             void*    prm;                              /* The pointer to the parameters of Callback function func  */
 559 ///             uint8_t  localStep;                        /* Local phase numbers                       */
 560 ///             uint8_t  rsv[3];                           /* Reserve for alignment               */
 561 ///         }PRIM_EXFUNC_TBL;
 562 ///            @endcode
 563 /// \~english @par
 564 ///    - %Parameter table of primary library \n
 565 ///      For FrameworkunifiedOnInitialization/FrameworkunifiedOnDestroy/FrameworkunifiedOnDebugDump/TaskmanagerOnTouch/FrameworkunifiedOnLowMemory, check the corresponding API specification. \n
 566 ///      It is able to get User private data by INI_GetPrivate(). \n
 567 /// \~english @code
 568 ///         typedef struct _T_PRIM_PRM{
 569 ///             PCSTR                      name;            /* Application name                        */
 570 ///             const PRIM_SHAREDATA_TBL*  shmTbl;          /* The pointer to shared memory creation table        */
 571 ///             const PRIM_EXFUNC_TBL*     wakeupExFuncTbl; /* The pointer to running extended function table          */
 572 ///             const PRIM_EXFUNC_TBL*     downExFuncTbl;   /* The pointer to end extended function table          */
 573 ///             EFrameworkunifiedStatus (*onInit)(HANDLE hApp);          /* FrameworkunifiedOnInitialization callback function setting */
 574 ///             EFrameworkunifiedStatus (*onDestory)(HANDLE hApp);       /* FrameworkunifiedOnDestroy callback function setting        */
 575 ///             EFrameworkunifiedStatus (*onDebugDump)(HANDLE hApp);     /* FrameworkunifiedOnDebugDump Callback function setting      */
 576 ///             EFrameworkunifiedStatus (*onTouch)(HANDLE hApp);         /* TaskmanagerOnTouch callback function setting          */
 577 ///             EFrameworkunifiedStatus (*onLowMem)(HANDLE hApp);        /* FrameworkunifiedOnLowMemory callback function setting      */
 578 ///             void* priv;                                 /* User private data */
 579 ///         }T_PRIM_PRM;
 580 ///            @endcode
 581 /// \~english @retval INI_SUCCESS Succeeded
 582 /// \~english @retval INI_FALSE  Failed
 583 /// \~english @par Preconditions:
 584 ///       - None
 585 /// \~english @par Changes of the internal state:
 586 ///       - The internal state is not changed
 587 /// \~english @par Causes of failures:
 588 ///       - The pointer to the parameter table of primary library is NULL [INI_FALSE]
 589 ///       - The pointer to the shared memory creation table inside the parameter table of primary library is NULL [INI_FALSE]
 590 ///       - The pointer to the running extended function table inside the parameter table of primary library is NULL [INI_FALSE]
 591 ///       - The pointer to the end extended function table inside the parameter table of primary library is NULL [INI_FALSE]
 592 ///       - The setting of FrameworkunifiedOnInitialization callback function inside the parameter table of primary library is NULL [INI_FALSE]
 593 ///       - The setting of FrameworkunifiedOnDestroy callback function inside the parameter table of primary library is NULL [INI_FALSE]
 594 ///       - The setting of FrameworkunifiedOnDebugDump callback function inside the parameter table of primary library is NULL [INI_FALSE]
 595 ///       - The setting of TaskmanagerOnTouch callback function inside the parameter table of primary library is NULL [INI_FALSE]
 596 /// \~english @par Classification:
 597 ///       Public
 598 /// \~english @par Type
 599 ///       Sync only
 600 /// \~english @par Detail:
 601 ///       Initializes primary thread. If it succeeded, returns INI_SUCCESS and if it failed, does INI_FALSE. \n
 602 ///       When implementing main thread at service, this function must be called in running main thread. \n
 603 ///       Waits fd of fdlist gotten by functions by select and when there is change in fd, service must execute event handler of primary by calling INI_Handler().
 604 /// \~english @see  INI_Main
 605 ////////////////////////////////////////////////////////////////////////////////////
 606 int32_t INI_Init(T_PRIM_PRM* p_prm,int argc ,char* argv[],int *fdNum,int fdlist[INI_FD_MAX]);
 607
 608 /////////////////////////////////////////////////////////////////////////////////////
 609 /// \ingroup INI_Handler
 610 /// \~english @par Summary:
 611 ///        Processes the reception event of primary library. \n
 612 ///        (This is used when implementing main thread at service side)
 613 /// \~english @param  [in] p_fds
 614 ///        fd_set* -  fd set varied and detected by select()
 615 /// \~english @retval TRUE Service running (Continuing)
 616 /// \~english @retval FALSE  The process end processing of primary library is completed
 617 /// \~english @par Preconditions:
 618 ///       - Main thread must be run at INI_Init()
 619 /// \~english @par Changes of the internal state:
 620 ///       - The internal state is not changed
 621 /// \~english @par Causes of failures:
 622 ///       - Access is not from main thread context  [FALSE]
 623 /// \~english @par Classification:
 624 ///       Public
 625 /// \~english @par Type
 626 ///       Sync only
 627 /// \~english @par Detail:
 628 ///       When FD which primary library should process in fd set designated by p_fds is included, processes event processing of primary library. \n
 629 ///       When implementing main thread by service, it is necessary to execute the event reception processing of primary library by this function. \n
 630 ///       Returns TRUE during service running and does FALSE when the process end processing of primary library was completed. When FALSE is returned, service must call
 631 ///       INI_Term() and end itself.
 632 /// \~english @see  INI_Init
 633 ////////////////////////////////////////////////////////////////////////////////////
 634 BOOL INI_Handler(fd_set* p_fds);
 635
 636 /////////////////////////////////////////////////////////////////////////////////////
 637 /// \ingroup INI_Term
 638 /// \~english @par Summary:
 639 ///        Releases the resource of primary library. \n
 640 ///        (This is used when implementing main thread at service side)
 641 /// \~english @param  None
 642 /// \~english @retval None
 643 /// \~english @par Preconditions:
 644 ///       - Main thread must be run at INI_Init()
 645 /// \~english @par Changes of the internal state:
 646 ///       - The internal state is not changed
 647 /// \~english @par Causes of failures:
 648 ///       - None
 649 /// \~english @par Classification:
 650 ///       Public
 651 /// \~english @par Type
 652 ///       Sync only
 653 /// \~english @par Detail:
 654 ///       Releases the resource of primary library. \n
 655 ///       When implementing main thread at service, this function must release the resource of primary library in service end.
 656 /// \~english @see  INI_Init, INI_Handler
 657 ////////////////////////////////////////////////////////////////////////////////////
 658 void INI_Term(void);
 659
 660 /////////////////////////////////////////////////////////////////////////////////////
 661 /// \ingroup INI_SetMonitorState
 662 /// \~english @par Summary:
 663 ///        Sets abnormality monitoring state. \n
 664 ///        (This is used when implementing main thread at service side)
 665 /// \~english @param  [in] p_prm
 666 ///        T_PRIM_MONITOR_PRM   - The pointer to the parameters structure for monitoring
 667 /// \~english @par
 668 ///         T_PRIM_MONITOR_PRM structure
 669 /// \~english @code
 670 ///         typedef struct {
 671 ///             BOOL        bIsRun;     /* Monitoring state (TRUE:RUN  FALSE:SLEEP) */
 672 ///             uint32_t    timeout;    /* Monitoring timeout time (sec)        */
 673 ///         }PRIM_SHAREDATA_TBL;
 674 ///            @endcode
 675 /// \~english @retval INI_SUCCESS Succeeded
 676 /// \~english @retval INI_FALSE  Failed
 677 /// \~english @par Preconditions:
 678 ///       - Main thread must be run at INI_ Init ()
 679 /// \~english @par Changes of the internal state:
 680 ///       - The internal state is not changed
 681 /// \~english @par Causes of failures:
 682 ///       - The pointer(p_prm) to the parameters structure for monitoring designated by parameters is NULL [INI_FALSE]
 683 /// \~english @par Classification:
 684 ///       Public
 685 /// \~english @par Type
 686 ///       Sync only
 687 /// \~english @par Detail:
 688 ///       Sets abnormality monitoring for TaskManager. If it succeeded, returns INI_SUCCESS and if it failed, does INI_FALSE \n
 689 ///       When bIsRun=FALSE is not set until time designated by timeout passes after setting bIsRun=TRUE, TaskManager decides that the service falls into abnormal state and ends forcibly. \n
 690 ///        When 0 is designated at monitoring timeout time(timeout), the service must be out of abnormality monitoring object.
 691 ///       When monitoring state (bIsRun) is FALSE, monitoring state becomes invalid. \n
 692 ///       This API can be used after running extended function CALLBACK.
 693 /// \~english @see  INI_Init
 694 ////////////////////////////////////////////////////////////////////////////////////
 695 int32_t INI_SetMonitorState(T_PRIM_MONITOR_PRM *p_prm);
 696
 697
 698 void _INI_DEBUGDUMP(BOOL bIsNeedSvcName, PCSTR f_cFormat, ...);
 699
 700 #define INI_DEBUGDUMP(args...)     _INI_DEBUGDUMP(TRUE,  ## args)
 701 #define INI_DEBUGDUMP_RAW(args...) _INI_DEBUGDUMP(FALSE, ## args)
 702
 703 // Callback functions
 704 /////////////////////////////////////////////////////////////////////////////////////
 705 /// \ingroup TaskmanagerOnTouch
 706 /// \~english @par Summary:
 707 ///        Callback to notify process use
 708 /// \~english @param  [in] hApp
 709 ///        HANDLE   - Application handle
 710 /// \~english @retval eFrameworkunifiedStatusOK Succeeded
 711 /// \~english @retval Other-than-eFrameworkunifiedStatusOK  Failed (Error type depends on the implementation at user side)
 712 /// \~english @par Preconditions:
 713 ///       - Must set inside running information structure in calling INI_Main or  INI_Init
 714 /// \~english @par Changes of the internal state:
 715 ///       - The internal state is not changed
 716 /// \~english @par Causes of failures:
 717 ///       - Implementation specification of callback depends on the implementation (design) of an application. For this, error type on failure conditions must be considered at an application side.
 718 /// \~english @par Detail:
 719 ///       Service is call backed just before using.  \n
 720 ///       INI_ExitStart must not be issued for 30 seconds after service called this function. \n
 721 ///       Timeout must be implemented such as counting up by using interval timer so that INI_ExitStart is not issued by timeout after this API was called. \n
 722 ///       This function cannot call the API (TSKM_Xxxx) of TaskManager. (If this calls, deadlock occurs)
 723 /// \~english @par Classification:
 724 ///          Public
 725 /// \~english @see  None
 726 ////////////////////////////////////////////////////////////////////////////////////
 727 EFrameworkunifiedStatus TaskmanagerOnTouch(HANDLE hApp);
 728
 729 #ifdef __cplusplus
 730 }
 731 #endif
 732
 733
 734 #endif //_INI_API_HPP_
 735
 736 /** @}*/ // end of TaskManager
 737 /** @}*/ // end of SystemService
 738 /** @}*/ // end of BaseSystem