ISF  1.1
Intelligent Sensing Framework
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Include/isf.h
Go to the documentation of this file.
00001 /*
00002  * 
00003  * Copyright (c) 2012, Freescale Semiconductor, Inc.
00004  * 
00005 */
00006 
00007 /*!
00008  * @file isf.h
00009  * @brief Main ISF header file.  Contains code common to all ISF components.
00010  *
00011  */
00012 
00013 
00014 
00015 #ifndef ISF_H_
00016 #define ISF_H_
00017 
00018 
00019 #include "mqx.h"
00020 #include "bsp.h"        // for device_info_t declaration
00021 #include "psptypes.h"   // boolean typedef
00022 
00023 #include "isf_types.h"
00024 
00025 
00026 
00027 
00028 #ifdef __cplusplus
00029 extern "C" {
00030 #endif
00031 
00032 
00033 // Use byte alignment for structures
00034 #pragma pack(push)
00035 #pragma pack(1)
00036 
00037 /*! 
00038  *  @enum isf_status_enum
00039  *  
00040  *  @brief ISF library return status type.
00041 */
00042 typedef enum
00043 {
00044  /*! General ISF success status
00045  */
00046   ISF_SUCCESS                          = 0,
00047   
00048   //! General library initialization failure status.  
00049   ISF_ERR_LIB_INIT                     = 1
00050     
00051 } isf_status_enum;
00052 
00053 
00054 /*! 
00055  *  @typedef isf_status_t
00056  *  
00057  *  @brief ISF return status type.
00058  *  @details ISF general success status for API functions.<br>  
00059  *  Any value not equal to ISF_SUCCESS is considered a<br>
00060  *  failure and the error is application specific.  See<br>
00061  *  application API documentation for specific error<br>
00062  *  definitions.
00063 */
00064 typedef int32 isf_status_t;
00065 
00066   
00067 /*! 
00068  *  @typedef isf_duration_t
00069  *  
00070  *  @brief ISF time duration in microseconds.
00071 */
00072 typedef uint32 isf_duration_t; 
00073 
00074 
00075 /*!
00076  *  @def MAX_ISF_APPLICATIONS
00077  *  @brief Maximum number of applications
00078  *  @details The maximum number of applications that can exists.  Note <br>
00079  *    that the application id can be anywhere between APP_ID_NULL and <br>
00080  *    NO_APP_FBID_INDX, but the maximum number of those applications<br>
00081  *    is limited to the value set here. 
00082 */
00083 #define  MAX_ISF_APPLICATIONS  (32)
00084 
00085 
00086 /*!
00087  *  @def APP_ID_NULL
00088  *  @brief Null application ID
00089  *  @details Value for null application ID.
00090 */
00091 #define APP_ID_NULL  (0)
00092 
00093 
00094 
00095 
00096 
00097 /*! 
00098  *  @struct isf_lib_info_t
00099  *  @brief This structure holds the ISF library information such <br> 
00100  *    as version and part number.
00101  *
00102 */
00103 typedef struct
00104 {
00105   //! IPSF library major version number.- dev info cmd encodes this in 8 bits
00106   uint8   majorVersion;
00107   //! ISF library minor version number.- dev info cmd encodes this in 8 bits
00108   uint8   minorVersion;
00109   //! Build code is the 16 bit code returned by the device info command
00110   //   Bit field encoding:
00111   //      - [15:13] daily build number, 3 bits range 0 to 7, mask 0xE000
00112   //      - [12: 9] build month, 4 bits range 1 to 12, mask 0x1E00
00113   //      - [ 8: 4] build day, 5 bits range 1 to 31, mask 0x01F0
00114   //      - [ 3: 0] build year - 2012, 4 bits range 0 to 15 = 2012 to 2027, mask 0x000F
00115   uint16  buildCode;
00116   //! Part number this library is targeted for.- dev info cmd encodes this in 8 bits
00117   uint16  partNumber;
00118   //! The time of the ISF build "hh:mm:ss"
00119   uint8   buildTime[9];
00120 } isf_lib_info_t;
00121 
00122   /* Leave this commented out for ISF 0.44 EA release.  It will be reincluded for    */
00123   /* ISF 0.44 Beta when we will also make a new MQX patch with it removed from bsp.h */
00124 /*! 
00125  *  @struct device_info_t
00126  *  @brief This structure holds the ROM device information such as version and part number
00127  *     and is returned by the _fw_device_info_get() command.
00128  *
00129 */
00130 typedef struct {
00131     uint_32              device_id;   /**< ROM: Pseudo random part identification value           */
00132     uint_16              rom_version; /**< ROM: ROM version code: major.minor                     */
00133     uint_16              fw_version;  /**< FW:  Firmware version code: major.minor                */
00134     uint_16              hw_version;  /**< ROM: Hardware version code: major.minor                */
00135     uint_16              build_code;  /**< FW:  Firmware build number and date code. The value is
00136                                       *        encoded in the following bit fields:
00137                                       *        - [15:12] daily build number, 0 to 15
00138                                       *        - [11: 8] build month, 1 to 12
00139                                       *        - [ 7: 3] build day, 1 to 31
00140                                       *        - [ 2: 0] build year, 2010 to 2017                 */
00141     uint_16              part_number; /**< FW:  BCD encoded part number, e.g. 0x500x              */
00142     uint_8               reset_cause; /**< FW:  Lower 5 bits from the RCSR reports reset source   */
00143     uint_8               secure_mode; /**< FW:  Lower 2 bits of FOPT report the security mode of
00144                                       *         the device: 2 = secure, otherwise not secure      */
00145 } device_info_t;
00146 
00147 /*! 
00148  * @brief API ISF library get information
00149  *
00150  *   The isf_lib_get_info() function is called by an application that needs <br>
00151  *   retrieve library version and part number that the library is targeted for.
00152  *
00153  *  
00154  *  @return             Pointer to isf_lib_info_t structure containing the<br>
00155  *                      library information.
00156  *
00157  *  @errors
00158  *
00159  *  @constraints
00160  *
00161  *  @reentrant          No<br>
00162  *
00163  *  @libs               isf_core.lib               
00164  *
00165  *  @see
00166  *
00167  */
00168 extern isf_lib_info_t * isf_lib_get_info(void);
00169 
00170 
00171 /*! 
00172  * @brief API ISF library get information
00173  *
00174  *   The isf_lib_get_info() function is called by an application that needs <br>
00175  *   retrieve library version and part number that the library is targeted for.
00176  *
00177  *  @return             ISF_SUCCESS if initialization was successful.<br>
00178  *                      ISF_ERR_LIB_INIT if tasks were not created properly.
00179  *
00180  *  @errors             <br>
00181  *
00182  *  @constraints        <br>
00183  *
00184  *  @reentrant          No<br>
00185  *
00186  *  @libs               <br>               
00187  *
00188  *  @see                <br>
00189  *
00190  */
00191 extern isf_status_t isf_lib_init(void *pNull);
00192 
00193 
00194 
00195 /*! 
00196  *  @enum isf_app_id_enum
00197  *  @brief ISF application number. 
00198  *     
00199 */
00200 enum isf_app_id_enum
00201 {
00202   ISF_APP_ID_DEV_INFO  = 0,
00203   ISF_APP_ID_MBOX      = 1,
00204   ISF_APP_ID_LAST
00205 };
00206 #define USER_APP_ID_START         (ISF_APP_ID_LAST)
00207 
00208 
00209 
00210 
00211 /*!
00212  * @def ISF_TASK_INDEX_START
00213  * @brief ISF starting task index
00214  * 
00215  * @details This define specifies the starting task index of ISF<br>
00216  *  tasks.  The user should use task index that are LOWER than<br>
00217  *  the value stated here.
00218  */
00219 #define ISF_TASK_INDEX_START           (50)
00220 
00221 
00222 
00223 /*************************************************************************************************
00224  *  @brief         Copies a device info structure to the supplied memory location and returns the
00225  *                 number of bytes that were copied to the location.
00226  *
00227  *  @details       The device info structure contains:
00228  *  uint32              device_id;   - ROM: Pseudo random part identification value
00229  *  uint16              rom_version; - ROM: ROM version code: major.minor
00230  *  uint16              fw_version;  - FW:  Firmware version code: major.minor
00231  *  uint16              hw_version;  - ROM: Hardware version code: major.minor
00232  *  uint16              build_code;  - FW:  Firmware build number and date code. The value is
00233  *                                          encoded in the following bit fields:
00234  *                                          - [15:13] daily build number, 0 to 7
00235  *                                          - [12: 9] build month, 1 to 12
00236  *                                          - [ 8: 4] build day, 1 to 31
00237  *                                          - [ 3: 0] build year, 2012 to 2027
00238  *  uint16              part_number; - FW:  BCD encoded part number, e.g. 0x9559
00239  *  uint8               reset_cause; - FW:  Lower 5 bits from the RCSR reports reset source.
00240  *  uint8               secure_mode; - FW:  Lower 2 bits of FOPT report the security mode of
00241  *                                          the device: 2 = secure, otherwise not secure.
00242  *
00243  *  The values marked ROM are retrieved from the ROM using the ROM device info command, while the
00244  *  vales marked with FW are written by the firmware.
00245  *
00246  *  The number of bytes copied to the destination is limited to the lesser of the number of bytes
00247  *  requested in the device structure, and the length of the device info structure.
00248  *
00249  *  @return The number of bytes copied to the supplied destination.
00250  ************************************************************************************************/
00251 void _fw_device_info_get(device_info_t *info_ptr);
00252 
00253 
00254 #pragma pack(pop)
00255 
00256 
00257 #ifdef __cplusplus
00258 } /* extern "C" */
00259 #endif
00260 
00261 #endif /* ISF_H_ */