1/**
2 * @defgroup MCLF   MobiCore Load Format
3 *
4 * @defgroup MCLF_VER    MCLF Versions
5 * @ingroup MCLF
6 *
7 * @addtogroup MCLF
8 * @{
9 *
10 * MobiCore Load Format declarations.
11 *
12 * Holds the definitions for the layout of MobiCore Trustlet Blob.
13 * <!-- Copyright Giesecke & Devrient GmbH 2009-2012 -->
14 *
15 * Redistribution and use in source and binary forms, with or without
16 * modification, are permitted provided that the following conditions
17 * are met:
18 * 1. Redistributions of source code must retain the above copyright
19 *    notice, this list of conditions and the following disclaimer.
20 * 2. Redistributions in binary form must reproduce the above copyright
21 *    notice, this list of conditions and the following disclaimer in the
22 *    documentation and/or other materials provided with the distribution.
23 * 3. The name of the author may not be used to endorse or promote
24 *    products derived from this software without specific prior
25 *    written permission.
26 *
27 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
28 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
29 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
30 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
31 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
32 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
33 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
34 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
35 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
36 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
37 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 */
39#ifndef MCLOADFORMAT_H_
40#define MCLOADFORMAT_H_
41
42#include "mcUuid.h"
43#include "mcDriverId.h"
44
45#define MCLF_VERSION_MAJOR   2
46#define MCLF_VERSION_MINOR   1
47
48#define MC_SERVICE_HEADER_MAGIC_BE         ((uint32_t)('M'|('C'<<8)|('L'<<16)|('F'<<24))) /**< "MCLF" in big endian integer representation */
49#define MC_SERVICE_HEADER_MAGIC_LE         ((uint32_t)(('M'<<24)|('C'<<16)|('L'<<8)|'F')) /**< "MCLF" in little endian integer representation */
50#define MC_SERVICE_HEADER_MAGIC_STR         "MCLF"                                        /**< "MCLF" as string */
51
52/** @name MCLF flags */
53/*@{*/
54#define MC_SERVICE_HEADER_FLAGS_PERMANENT               (1U << 0) /**< Loaded service cannot be unloaded from MobiCore. */
55#define MC_SERVICE_HEADER_FLAGS_NO_CONTROL_INTERFACE    (1U << 1) /**< Service has no WSM control interface. */
56#define MC_SERVICE_HEADER_FLAGS_DEBUGGABLE              (1U << 2) /**< Service can be debugged. */
57/*@}*/
58
59#if !defined(ADDR_T_DEFINED)
60#define ADDR_T_DEFINED
61typedef void*    addr_t;                /**< an address, can be physical or virtual */
62#endif // !defined(ADDR_T_DEFINED)
63
64/** Service type.
65 * The service type defines the type of executable.
66 */
67typedef enum {
68    SERVICE_TYPE_ILLEGAL    = 0,        /**< Service type is invalid. */
69    SERVICE_TYPE_DRIVER     = 1,        /**< Service is a driver. */
70    SERVICE_TYPE_SP_TRUSTLET   = 2,     /**< Service is a Trustlet. */
71    SERVICE_TYPE_SYSTEM_TRUSTLET = 3    /**< Service is a system Trustlet. */
72} serviceType_t;
73
74/**
75 * Memory types.
76 */
77typedef enum {
78    MCLF_MEM_TYPE_INTERNAL_PREFERRED = 0, /**< If available use internal memory; otherwise external memory. */
79    MCLF_MEM_TYPE_INTERNAL = 1, /**< Internal memory must be used for executing the service. */
80    MCLF_MEM_TYPE_EXTERNAL = 2, /**< External memory must be used for executing the service. */
81} memType_t;
82
83/**
84 * Descriptor for a memory segment.
85 */
86typedef struct {
87    addr_t      start;  /**< Virtual start address. */
88    uint32_t    len;    /**< Length of the segment in bytes. */
89} segmentDescriptor_t, *segmentDescriptor_ptr;
90
91/**
92 * MCLF intro for data structure identification.
93 * Must be the first element of a valid MCLF file.
94 */
95typedef struct {
96    uint32_t        magic;      /**< Header magic value ASCII "MCLF". */
97    uint32_t        version;    /**< Version of the MCLF header structure. */
98} mclfIntro_t, *mclfIntro_ptr;
99
100/** @} */
101
102
103// Version 2 /////////////////////////////////////////////////////////////////////////////////////////////////////////
104/**
105 * @defgroup MCLF_VER_V2   MCLF Version 2
106 * @ingroup MCLF_VER
107 *
108 * @addtogroup MCLF_VER_V2
109 * @{
110 */
111
112/**
113 * Version 2 MCLF header.
114 */
115typedef struct {
116    mclfIntro_t             intro;           /**< MCLF header start with the mandatory intro. */
117    uint32_t                flags;           /**< Service flags. */
118    memType_t               memType;         /**< Type of memory the service must be executed from. */
119    serviceType_t           serviceType;     /**< Type of service. */
120
121    uint32_t                numInstances;    /**< Number of instances which can be run simultaneously. */
122    mcUuid_t                uuid;            /**< Loadable service unique identifier (UUID). */
123    mcDriverId_t            driverId;        /**< If the serviceType is SERVICE_TYPE_DRIVER the Driver ID is used. */
124    uint32_t                numThreads;      /**<
125                                              * <pre>
126                                              * <br>Number of threads (N) in a service depending on service type.<br>
127                                              *
128                                              *   SERVICE_TYPE_SP_TRUSTLET: N = 1
129                                              *   SERVICE_TYPE_SYSTEM_TRUSTLET: N = 1
130                                              *   SERVICE_TYPE_DRIVER: N >= 1
131                                              * </pre>
132                                              */
133    segmentDescriptor_t     text;           /**< Virtual text segment. */
134    segmentDescriptor_t     data;           /**< Virtual data segment. */
135    uint32_t                bssLen;         /**< Length of the BSS segment in bytes. MUST be at least 8 byte. */
136    addr_t                  entry;          /**< Virtual start address of service code. */
137    uint32_t                serviceVersion; /**< Version of the interface the driver exports. */
138} mclfHeaderV2_t, *mclfHeaderV2_ptr;
139/** @} */
140
141
142/**
143 * Version 2 MCLF text segment header.
144 * Required to be present in MobiCore 1.2 components at address (0x1080).
145 * This extension is initialized already at trustlet compile time,
146 * but may be modified later by configuration tools and by MobiCore at load time.
147 */
148typedef struct {
149    uint32_t                version;        /**< Version of the TextHeader structure. */
150    uint32_t                textHeaderLen;  /**< Size of this structure (fixed at compile time) */
151    uint32_t                requiredFeat;   /**< Flags to indicate features that Mobicore must understand/interprete when loading.
152                                                 Initial value set at compile time.
153                                                 Required always. */
154    addr_t                  mcLibEntry;     /**< Address for McLib entry.
155                                                 Mobicore sets at load time for trustlets / drivers.
156                                                 Required always. */
157    segmentDescriptor_t     mcLibData;      /**< Segment for McLib data.
158                                                 Set at compile time.
159                                                 Required always. */
160    addr_t                  mcLibBase;      /**< McLib base address.
161                                                 Mobicore sets at load time for trustlets / drivers.
162                                                 Required always. */
163} mclfTextHeader_t, *mclfTextHeader_ptr;
164
165// Version 2 ///////////////////////////////////////////////////////////////////////////////////////////////////
166/**
167 * @addtogroup MCLF
168 * @{
169 */
170
171/** MCLF header */
172typedef union {
173    mclfIntro_t    intro;           /**< Intro for data structure identification. */
174    mclfHeaderV2_t mclfHeaderV2;    /**< Version 2 header */
175} mclfHeader_t, *mclfHeader_ptr;
176
177#endif /* MCLOADFORMAT_H_ */
178
179/** @} */
180