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 contains primary API of task manager
23 /** @addtogroup BaseSystem
26 /** @addtogroup system_service
30 /** @addtogroup task_manager
31 * @ingroup system_service
35 #ifndef TASK_MANAGER_SERVER_INCLUDE_SYSTEM_SERVICE_TSKM_H_
36 #define TASK_MANAGER_SERVER_INCLUDE_SYSTEM_SERVICE_TSKM_H_
39 #include <other_service/rpc.h>
40 #include "system_service/tskm_type.h"
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:
57 /// \~english @par Changes of the internal state:
58 /// - The internal state is not changed
59 /// \~english @par Causes of failures:
61 /// \~english @par Classification:
63 /// \~english @par Type
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 /////////////////////////////////////////////////////////////////////////////////////
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:
85 /// \~english @par Classification:
87 /// \~english @par Type
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)
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
105 /// TSKM_SVC_CMD_t cmd;
106 /// } TSKM_SVC_CTL_t;
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:
129 /// \~english @par Type
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
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
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:
191 /// \~english @par Type
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
206 /// TSKM_ERROR_REBOOT_TYPE_t type;
207 /// TSKM_LOGGING_ INFO_t log;
208 /// } TSKM_ERROR_REBOOT_t;
210 /// TSKM_ERROR_REBOOT_NORMAL : Abnormal detection
211 /// log : Log saving information
213 /// char messageStr[TSKM_LOGGING_MSG_STR_SIZE];
214 /// } TSKM_LOGGING_INFO_ t;
215 /// messageStr : Abnormal message character string
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:
228 /// \~english @par Type
230 /// \~english @par Detail:
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:
258 /// \~english @par Type
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
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
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:
291 /// \~english @par Type
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
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
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:
333 /// \~english @par Type
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
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
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>
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
376 /// char orderName[TSKM_ORDER_NAME_MAX];
377 /// } TSKM_WAKEUP_ORDER_t;
378 /// orderName: Order name (MAX:31 characters)
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:
393 /// \~english @par Type
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);
407 #endif // TASK_MANAGER_SERVER_INCLUDE_SYSTEM_SERVICE_TSKM_H_
409 /** @}*/ // end of Task_Manager
410 /** @}*/ // end of SystemService
411 /** @}*/ // end of BaseSystem