2 * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
19 * @brief \~english This file provide api to operating INI
22 /** @addtogroup BaseSystem
25 /** @addtogroup system_service
29 /** @addtogroup task_manager
30 * @ingroup system_service
37 #include <native_service/frameworkunified_types.h>
38 #include <system_service/ss_system_manager_if.h>
39 #include "system_service/Primary_common.h"
41 #define INI_SUCCESS 0 /* Normal */
42 #define INI_FALSE -1 /* Failed */
46 // Only the information required for event completion notification is left
48 #define INI_INITCOMP_NONE 0x0000000000000000LLU
49 #define INI_INITCOMP_ON_START 0x0000000000000001LLU /* ON_START */
50 #define INI_INITCOMP_NVM_ACCESS 0x0000000000000002LLU /* NVM ACCESS */
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 */
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 */
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 */
70 typedef struct _T_PRIM_PRM{
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);
84 wakeupExFuncTbl = NULL;
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.)
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
123 /// char shmName[32]; /* Shared memory name */
124 /// uint32_t size; /* Shared memory size (BYTE) */
125 /// }PRIM_SHAREDATA_TBL;
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
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;
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
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 */
159 /// \~english @retval INI_SUCCESS Normal end
160 /// \~english @retval INI_FALSE Abnormal end
161 /// \~english @par Preconditions:
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:
176 /// \~english @par Type
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[]);
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:
195 /// \~english @par Changes of the internal state:
196 /// - The internal state is not changed
197 /// \~english @par Causes of failures:
199 /// \~english @par Classification:
201 /// \~english @par Type
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
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:
226 /// \~english @par Changes of the internal state:
227 /// - The internal state is not changed
228 /// \~english @par Causes of failures:
230 /// \~english @par Classification:
232 /// \~english @par Type
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
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:
253 /// \~english @par Classification:
255 /// \~english @par Type
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();
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:
275 /// \~english @par Classification:
277 /// \~english @par Type
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();
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:
299 /// \~english @par Classification:
301 /// \~english @par Type
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);
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)
319 /// The ID descripted at INI_API.hpp
321 /// - INI_INITCOMP_NONE: None
322 /// - INI_INITCOMP_ON_START: For ON Start
323 /// - INI_INITCOMP_NVM_ACCESS: For NVM access
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:
335 /// \~english @par Type
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);
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)
361 /// The ID described at INI_API.hpp
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
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:
378 /// \~english @par Type
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);
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
403 /// T_SS_SM_START_DataStructType structure
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;
416 /// Startup reason type:
417 /// - epswfIGN_ACC : Ignition ACC (Currently, Fixed)
418 /// User mode ON/OFF:
419 /// - TRUE : User mode ON (Currently, Fixed)
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
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
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
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:
450 /// \~english @par Type
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);
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
467 /// T_SS_SM_START_ExtDataStructType structure
469 /// #define SS_SM_START_EXT_INFO_SIZE 64
470 /// #define SS_SM_START_EXT_BODY_SIZE ( sizeof(BOOL)
471 /// + sizeof(EMRelaunchStatus)
475 /// define SS_SM_START_EXT_RSV_SIZE SS_SM_START_EXT_INFO_SIZE
476 /// - SS_SM_START_EXT_BODY_SIZE
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;
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
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:
510 /// \~english @par Type
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);
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
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
545 /// char shmName[32]; /* Shared memory name */
546 /// uint32_t size; /* Shared memory size (BYTE) */
547 /// }PRIM_SHAREDATA_TBL;
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
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;
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
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 */
581 /// \~english @retval INI_SUCCESS Succeeded
582 /// \~english @retval INI_FALSE Failed
583 /// \~english @par Preconditions:
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:
598 /// \~english @par Type
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]);
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:
625 /// \~english @par Type
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);
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:
649 /// \~english @par Classification:
651 /// \~english @par Type
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 ////////////////////////////////////////////////////////////////////////////////////
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
668 /// T_PRIM_MONITOR_PRM structure
671 /// BOOL bIsRun; /* Monitoring state (TRUE:RUN FALSE:SLEEP) */
672 /// uint32_t timeout; /* Monitoring timeout time (sec) */
673 /// }PRIM_SHAREDATA_TBL;
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:
685 /// \~english @par Type
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);
698 void _INI_DEBUGDUMP(BOOL bIsNeedSvcName, PCSTR f_cFormat, ...);
700 #define INI_DEBUGDUMP(args...) _INI_DEBUGDUMP(TRUE, ## args)
701 #define INI_DEBUGDUMP_RAW(args...) _INI_DEBUGDUMP(FALSE, ## args)
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:
725 /// \~english @see None
726 ////////////////////////////////////////////////////////////////////////////////////
727 EFrameworkunifiedStatus TaskmanagerOnTouch(HANDLE hApp);
734 #endif //_INI_API_HPP_
736 /** @}*/ // end of TaskManager
737 /** @}*/ // end of SystemService
738 /** @}*/ // end of BaseSystem