ISF  2.2 rev 5
Intelligent Sensing Framework for Kinetis with Processor Expert
isf.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright (c) 2015, Freescale Semiconductor, Inc.
4  *
5 */
6 
7 /*!
8  * @file isf.h
9  * @brief Main ISF header file. Contains code common to all ISF components.
10  *
11  */
12 
13 
14 
15 #ifndef ISF_H_
16 #define ISF_H_
17 
18 
19 #include "isf_types.h"
20 #include "isf_target.h"
21 
22 /*!
23  * @enum isf_status_enum
24  *
25  * @brief ISF library return status type.
26 */
27 typedef enum
28 {
29  /*! General ISF success status
30  */
32 
33  //! General library initialization failure status.
35 
37 
38 
39 /*!
40  * @enum isf_app_type_enum
41  *
42  * @brief ISF Embedded Application types.
43 */
44 typedef enum
45 {
46  //! ISF Application Type for Invalid Application.
48  //! ISF Application Type for MailBox Application.
50  //! ISF Application Type for RLI Application.
52  //! ISF Application Type for Basic Application.
54  //! ISF Application Type for Embedded Application.
56  //! ISF Application Type for the DataLogger Application.
58  //! ISF Application Type for the Sensor Fusion Application.
60  //! ISF Application Type for User Application1.
62  //! MAX ISF APP Type.
65 
66 /*!
67  * @typedef isf_status_t
68  *
69  * @brief ISF return status type.
70  * @details ISF general success status for API functions.<br>
71  * Any value not equal to ISF_SUCCESS is considered a<br>
72  * failure and the error is application specific. See<br>
73  * application API documentation for specific error<br>
74  * definitions.
75 */
77 
78 
79 /*!
80  * @typedef isf_duration_t
81  *
82  * @brief ISF time duration in microseconds.
83 */
85 
86 
87 /*!
88  * @def MAX_ISF_APPLICATIONS
89  * @brief Maximum number of applications
90  * @details The maximum number of applications that can exists. Note <br>
91  * that the application id can be anywhere between APP_ID_NULL and <br>
92  * NO_APP_FBID_INDX, but the maximum number of those applications<br>
93  * is limited to the value set here.
94 */
95 #define MAX_ISF_APPLICATIONS (32)
96 
97 
98 /*!
99  * @def APP_ID_NULL
100  * @brief Null application ID
101  * @details Value for null application ID.
102 */
103 #define APP_ID_NULL (0)
104 
105 
106 /*!
107  * @def MAX_ISF_COMMIT_ID_SIZE
108  * @brief The maximum size of the ISF commit_id
109  * @details The maximum size of the ISF commit_id from which build is made.
110 */
111 #define MAX_ISF_COMMIT_ID_SIZE (8)
112 
113 /*!
114  * @def ISF_EMB_APPS_PRESENT
115  * @brief The number of separate addressable apps in the build
116  * @details The number of addressable apps includes, when applicable,
117  * the Mailbox App, instances of BasicApp, EmbApp, and RLI Apps.
118  * This number is reported in the DeviceInfo Command response.
119  * Apps are numbered from 1. I.e., if three apps are present they will
120  * be numbered 1, 2, and 3. App 1 is almost always the mailbox app.
121 */
122 #define ISF_EMB_APPS_PRESENT 5
123 
124 /*!
125  * @struct version_info_t
126  * @brief This structure holds the version information of device/lib/component
127  * /user application etc.
128  *
129 */
130 typedef struct
131 {
132  //! Major version number information
134  //! Minor version number information
136 
138 
139 /*!
140  * @struct build_info_t
141  * @brief This structure holds the build information of device/lib/component
142  * /user application etc.
143  *
144 */
145 typedef struct
146 {
147  //! The Year of the build (valid values: 2000 + buildYear, max value = 2255)
149  //! The Month of the build (valid values: 1(JAN) to 12(DEC))
151  //! The Day of the build (valid values: 1 to 31)
153  //! The time of build in hours (in 24-hour notation) (valid values: 0 to 23)
155  //! The time of build in minutes (valid values: 0 to 59)
157  //! The time of build in seconds (valid values: 0 to 59)
159  //! The last commit_id from which the build is made
161 
162 } build_info_t;
163 
164 
165 /*!
166  * @struct isf_lib_info_t
167  * @brief This structure holds the ISF library information such <br>
168  * as version and part number.
169  *
170 */
171 typedef struct
172 {
173  //! ISF version information
175  //! ISF build information
177 
178 } isf_info_t;
179 
180 /*!
181  * @struct device_info_t
182  * @brief This structure holds the ROM device information such as device id
183  * and number of EmbApps present. This information is returned by the
184  * _fw_device_info_get() API.
185  *
186 */
187 typedef struct {
188  /**< System Device Identification information of the device (SIM_SDID Register)*/
190  /**< Number of Embedded Applications present in the image */
192  /**< The ISF library version and build information */
194 
195 } device_info_t;
196 
197 /*!
198  * @brief API to get ISF information
199  *
200  * The isf_get_info() function is called by an application that needs <br>
201  * retrieve ISF version and part number that the library is targeted for.
202  *
203  *
204  * @return Pointer to isf_lib_info_t structure containing the<br>
205  * library information.
206  *
207  * @errors
208  *
209  * @constraints
210  *
211  * @reentrant No<br>
212  *
213  * @libs isf_core.lib
214  *
215  * @see
216  *
217  */
218 extern isf_info_t isf_get_info(void);
219 
220 
221 /*!
222  * @brief API to get ISF information
223  *
224  * The isf_get_info() function is called by an application that needs <br>
225  * retrieve library version and part number that the library is targeted for.
226  *
227  * @return ISF_SUCCESS if initialization was successful.<br>
228  * ISF_ERR_LIB_INIT if tasks were not created properly.
229  *
230  * @errors <br>
231  *
232  * @constraints <br>
233  *
234  * @reentrant No<br>
235  *
236  * @libs <br>
237  *
238  * @see <br>
239  *
240  */
241 extern isf_status_t isf_lib_init(void *pNull);
242 
243 
244 
245 /*!
246  * @enum isf_app_id_enum
247  * @brief ISF application number.
248  *
249 */
251 {
255 };
256 #define USER_APP_ID_START (ISF_APP_ID_LAST)
257 
258 
259 
260 
261 /*!
262  * @def ISF_TASK_INDEX_START
263  * @brief ISF starting task index
264  *
265  * @details This define specifies the starting task index of ISF<br>
266  * tasks. The user should use task index that are LOWER than<br>
267  * the value stated here.
268  */
269 #define ISF_TASK_INDEX_START (50)
270 
271 
272 
273 /*************************************************************************************************
274  * @brief Copies a device info structure to the supplied memory location and returns the
275  * number of bytes that were copied to the location.
276  *
277  * @details The device info structure contains:
278  * uint32 device_id; - ROM: Pseudo random part identification value
279  * uint16 rom_version; - ROM: ROM version code: major.minor
280  * uint16 fw_version; - FW: Firmware version code: major.minor
281  * uint16 hw_version; - ROM: Hardware version code: major.minor
282  * uint16 build_code; - FW: Firmware build number and date code. The value is
283  * encoded in the following bit fields:
284  * - [15:13] daily build number, 0 to 7
285  * - [12: 9] build month, 1 to 12
286  * - [ 8: 4] build day, 1 to 31
287  * - [ 3: 0] build year, 2012 to 2027
288  * uint16 part_number; - FW: BCD encoded part number, e.g. 0x9559
289  * uint8 reset_cause; - FW: Lower 5 bits from the RCSR reports reset source.
290  * uint8 secure_mode; - FW: Lower 2 bits of FOPT report the security mode of
291  * the device: 2 = secure, otherwise not secure.
292  *
293  * The values marked ROM are retrieved from the ROM using the ROM device info command, while the
294  * vales marked with FW are written by the firmware.
295  *
296  * The number of bytes copied to the destination is limited to the lesser of the number of bytes
297  * requested in the device structure, and the length of the device info structure.
298  *
299  * @return The number of bytes copied to the supplied destination.
300  ************************************************************************************************/
301 void _fw_device_info_get(device_info_t *info_ptr);
302 
303 
304 
305 
306 /*! @brief This API returns the time in microseconds.
307  *
308  *
309  * @details This API call uses the RTOS services to calculate and
310  * return the elapsed time since the system started running. Note that
311  * if the elapsed time has exceeded a 32bit value, that is 2^32-1 or
312  * 4294.96 seconds, then the time elapsed will rollover and start at
313  * zero.
314  *
315  * @return ::isf_time_util_get_usec() returns a value of type
316  * uint32 providing the number of microseconds since
317  * the system started running.
318  *
319  * @Constraints None
320  *
321  * @Reentrant No
322  *
323  * @Libs libisf_core.a
324  *
325  */
327 
328 
329 #endif /* ISF_H_ */
330 
331 
isf_app_id_enum
ISF application number.
Definition: isf.h:250
ISF board support header files.
unsigned char uint8
Definition: isf_types.h:76
void _fw_device_info_get(device_info_t *info_ptr)
Definition: isf.c:77
ISF Application Type for the Sensor Fusion Application.
Definition: isf.h:59
This structure holds the ROM device information such as device id and number of EmbApps present...
Definition: isf.h:187
ISF Application Type for Invalid Application.
Definition: isf.h:47
ISF Application Type for Embedded Application.
Definition: isf.h:55
uint32 isf_time_util_get_usec(void)
This API returns the time in microseconds.
Definition: isf_util.c:55
ISF Application Type for RLI Application.
Definition: isf.h:51
MAX ISF APP Type.
Definition: isf.h:63
uint8 emb_apps_present
Definition: isf.h:191
ISF Application Type for User Application1.
Definition: isf.h:61
This structure holds the version information of device/lib/component /user application etc...
Definition: isf.h:130
uint8 buildMinutes
The time of build in minutes (valid values: 0 to 59)
Definition: isf.h:156
uint8 buildDay
The Day of the build (valid values: 1 to 31)
Definition: isf.h:152
The isf_types.h file contains the ISF data type definitions and some of the globally used macros...
uint8 majorVersion
Major version number information.
Definition: isf.h:133
uint8 buildSeconds
The time of build in seconds (valid values: 0 to 59)
Definition: isf.h:158
uint8 buildYear
The Year of the build (valid values: 2000 + buildYear, max value = 2255)
Definition: isf.h:148
build_info_t build_info
ISF build information.
Definition: isf.h:176
isf_status_t isf_lib_init(void *pNull)
API to get ISF information.
Definition: isf_init.c:18
isf_info_t isf_get_info(void)
API to get ISF information.
Definition: isf.c:29
ISF Application Type for MailBox Application.
Definition: isf.h:49
isf_status_enum
ISF library return status type.
Definition: isf.h:27
uint32 isf_duration_t
ISF time duration in microseconds.
Definition: isf.h:84
ISF Application Type for the DataLogger Application.
Definition: isf.h:57
version_info_t version_info
ISF version information.
Definition: isf.h:174
uint8 buildHours
The time of build in hours (in 24-hour notation) (valid values: 0 to 23)
Definition: isf.h:154
isf_info_t isf_info
Definition: isf.h:193
signed long int int32
Definition: isf_types.h:74
This structure holds the build information of device/lib/component /user application etc...
Definition: isf.h:145
uint32 system_device_id
Definition: isf.h:189
General library initialization failure status.
Definition: isf.h:34
int32 isf_status_t
ISF return status type.
Definition: isf.h:76
uint8 minorVersion
Minor version number information.
Definition: isf.h:135
unsigned long int uint32
Definition: isf_types.h:78
#define MAX_ISF_COMMIT_ID_SIZE
The maximum size of the ISF commit_id.
Definition: isf.h:111
isf_app_type_enum
ISF Embedded Application types.
Definition: isf.h:44
ISF Application Type for Basic Application.
Definition: isf.h:53
uint8 buildMonth
The Month of the build (valid values: 1(JAN) to 12(DEC))
Definition: isf.h:150