4 * Copyright (c) Freescale Semiconductor, Inc. All rights reserved.
6 * Freescale Semiconductor, Inc.
7 * Proprietary & Confidential
9 * This source code and the algorithms implemented therein constitute
10 * confidential information and may comprise trade secrets of Freescale Semiconductor, Inc.
11 * or its associates, and any use thereof is subject to the terms and
12 * conditions of the Confidential Disclosure Agreement pursual to which this
13 * source code was originally received.
15 #if !defined(_IVTDataSource_h_)
16 #define _IVTDataSource_h_
18 #include "DataSource.h"
20 /** Header field components
23 typedef struct hab_hdr {
24 uint8_t tag; /**< Tag field */
25 uint8_t len[2]; /**< Length field in bytes (big-endian) */
26 uint8_t par; /**< Parameters field */
29 /** Image entry function prototype
32 * This typedef serves as the return type for hab_rvt.authenticate_image(). It
33 * specifies a void-void function pointer, but can be cast to another function
34 * pointer type if required.
36 typedef void (*hab_image_entry_f)(void);
38 /** @ref ivt structure
43 * An @ref ivt consists of a @ref hdr followed by a list of addresses as
44 * described further below.
46 * @warning The @a entry address may not be NULL.
48 * @warning On an IC not configured as #HAB_CFG_CLOSED, the
49 * @a csf address may be NULL. If it is not NULL, the @ref csf will be
50 * processed, but any failures should be non-fatal.
52 * @warning On an IC configured as #HAB_CFG_CLOSED, the @a
53 * csf address may not be NULL, and @ref csf failures are typically fatal.
55 * @remark The Boot Data located using the @a boot_data field is interpreted
56 * by the HAB caller in a boot-mode specific manner. This may be used by the
57 * boot ROM as to determine the load address and boot device configuration for
58 * images loaded from block devices (see @ref ref_rug for details).
60 * @remark All addresses given in the IVT, including the Boot Data (if
61 * present) are those for the final load location.
65 * @par Initial load addresses
67 * The @a self field is used to calculate addresses in boot modes where an
68 * initial portion of the image is loaded to an initial location. In such
69 * cases, the IVT, Boot Data (if present) and DCD (if present) are used in
70 * configuring the IC and loading the full image to its final location. Only
71 * the IVT, Boot Data (if present) and DCD (if present) are required to be
72 * within the initial image portion.
74 * The method for calculating an initial load address for the DCD is
75 * illustrated in the following C fragment. Similar calculations apply to
79 hab_ivt_t* ivt_initial = <initial IVT load address>;
80 const void* dcd_initial = ivt_initial->dcd;
81 if (ivt_initial->dcd != NULL)
82 dcd_initial = (const uint8_t*)ivt_initial
83 + (ivt_initial->dcd - ivt_initial->self)
86 * \note The void* types in this structure have been changed to uint32_t so
87 * that this code will work correctly when compiled on a 64-bit host.
88 * Otherwise the structure would come out incorrect.
91 /** @ref hdr with tag #HAB_TAG_IVT, length and HAB version fields
95 /** Absolute address of the first instruction to execute from the
98 /*hab_image_entry_f*/ uint32_t entry;
99 /** Reserved in this version of HAB: should be NULL. */
100 /*const void*/ uint32_t reserved1;
101 /** Absolute address of the image DCD: may be NULL. */
102 /*const void*/ uint32_t dcd;
103 /** Absolute address of the Boot Data: may be NULL, but not interpreted
106 /*const void*/ uint32_t boot_data;
107 /** Absolute address of the IVT.*/
108 /*const void*/ uint32_t self;
109 /** Absolute address of the image CSF.*/
110 /*const void*/ uint32_t csf;
111 /** Reserved in this version of HAB: should be zero. */
118 typedef struct hab_ivt hab_ivt_t;
123 #define HAB_CMD_UNS 0xff
125 #define DEFAULT_IMG_KEY_IDX 2
127 #define GEN_MASK(width) \
128 ((1UL << (width)) - 1)
130 #define GEN_FIELD(f, width, shift) \
131 (((f) & GEN_MASK(width)) << (shift))
133 #define PACK_UINT32(a, b, c, d) \
134 ( (((a) & 0xFF) << 24) \
135 |(((b) & 0xFF) << 16) \
136 |(((c) & 0xFF) << 8) \
139 #define EXPAND_UINT32(w) \
140 (uint8_t)((w)>>24), (uint8_t)((w)>>16), (uint8_t)((w)>>8), (uint8_t)(w)
142 #define HDR(tag, bytes, par) \
143 (uint8_t)(tag), (uint8_t)((bytes)>>8), (uint8_t)(bytes), (uint8_t)(par)
145 #define HAB_VER(maj, min) \
146 (GEN_FIELD((maj), HAB_VER_MAJ_WIDTH, HAB_VER_MAJ_SHIFT) \
147 | GEN_FIELD((min), HAB_VER_MIN_WIDTH, HAB_VER_MIN_SHIFT))
153 #define CSF_HDR(bytes, HABVER) \
154 HDR(HAB_TAG_CSF, (bytes), HABVER)
161 #define DCD_HDR(bytes, HABVER) \
162 HDR(HAB_TAG_DCD, (bytes), HABVER)
165 * IVT header (goes in the struct's hab_hdr_t field, not a byte array)
167 #define IVT_HDR(bytes, HABVER) \
168 {HAB_TAG_IVT, {(uint8_t)((bytes)>>8), (uint8_t)(bytes)}, HABVER}
170 /** @name External data structure tags
173 * Tag values 0x00 .. 0xef are reserved for HAB. Values 0xf0 .. 0xff
174 * are available for custom use.
177 #define HAB_TAG_IVT 0xd1 /**< Image Vector Table */
178 #define HAB_TAG_DCD 0xd2 /**< Device Configuration Data */
179 #define HAB_TAG_CSF 0xd4 /**< Command Sequence File */
180 #define HAB_TAG_CRT 0xd7 /**< Certificate */
181 #define HAB_TAG_SIG 0xd8 /**< Signature */
182 #define HAB_TAG_EVT 0xdb /**< Event */
183 #define HAB_TAG_RVT 0xdd /**< ROM Vector Table */
184 /* Values b0 ... cf reserved for CSF commands. Values e0 ... ef reserved for
187 * Available values: 03, 05, 06, 09, 0a, 0c, 0f, 11, 12, 14, 17, 18, 1b, 1d,
188 * 1e, 21, 22, 24, 27, 28, 2b, 2d, 2e, 30, 33, 35, 36, 39, 3a, 3c, 3f, 41, 42,
189 * 44, 47, 48, 4b, 4d, 4e, 50, 53, 55, 56, 59, 5a, 5c, 5f, 60, 63, 65, 66, 69,
190 * 6a, 6c, 6f, 71, 72, 74, 77, 78, 7b, 7d, 7e, 81, 82, 84, 87, 88, 8b, 8d, 8e,
191 * 90, 93, 95, 96, 99, 9a, 9c, 9f, a0, a3, a5, a6, a9, aa, ac, af, b1, b2, b4,
194 * Custom values: f0, f3, f5, f6, f9, fa, fc, ff
198 /** @name HAB version */
200 #define HAB_MAJOR_VERSION 4 /**< Major version of this HAB release */
201 #define HAB_MINOR_VERSION 0 /**< Minor version of this HAB release */
202 #define HAB_VER_MAJ_WIDTH 4 /**< Major version field width */
203 #define HAB_VER_MAJ_SHIFT 4 /**< Major version field offset */
204 #define HAB_VER_MIN_WIDTH 4 /**< Minor version field width */
205 #define HAB_VER_MIN_SHIFT 0 /**< Minor version field offset */
206 /** Full version of this HAB release @hideinitializer */
207 #define HAB_VERSION HAB_VER(HAB_MAJOR_VERSION, HAB_MINOR_VERSION)
208 /** Base version for this HAB release @hideinitializer */
209 #define HAB_BASE_VERSION HAB_VER(HAB_MAJOR_VERSION, 0)
216 * \brief Data source for an IVT structure used by HAB4.
218 * This data source represents an IVT structure used by HAB4. Fields of the IVT can be set
219 * by name, making it easy to interface with a parser. And it has some intelligence regarding
220 * the IVT's self pointer. Before the data is copied out by the getData() method, the self field
221 * will be filled in automatically if it has not already been set and there is an associated
222 * data target object. This lets the IVT pick up its own address from the location where it is
223 * being loaded. Alternatively, if the self pointer is filled in explicitly, then the data
224 * source will have a natural location equal to the self pointer.
226 * This data source acts as its own segment.
228 class IVTDataSource : public DataSource, public DataSource::Segment
231 //! \brief Default constructor.
234 //! \brief There is only one segment.
235 virtual unsigned getSegmentCount() { return 1; }
237 //! \brief Returns this object, as it is its own segment.
238 virtual DataSource::Segment * getSegmentAt(unsigned index) { return this; }
240 //! \name Segment methods
243 //! \brief Copy out some or all of the IVT structure.
245 virtual unsigned getData(unsigned offset, unsigned maxBytes, uint8_t * buffer);
247 //! \brief Gets the length of the segment's data.
248 virtual unsigned getLength();
250 //! \brief Returns whether the segment has an associated address.
251 virtual bool hasNaturalLocation();
253 //! \brief Returns the address associated with the segment.
254 virtual uint32_t getBaseAddress();
261 //! \brief Set one of the IVT's fields by providing its name.
263 //! Acceptable field names are:
270 //! As long as the \a name parameter specifies one of these fields, the return value
271 //! will be true. If \a name contains any other value, then false will be returned and
272 //! the IVT left unmodified.
274 //! Once the \a self field has been set to any value, the data source will have a
275 //! natural location. This works even if the \a self address is 0.
277 //! \param name The name of the field to set. Field names are case sensitive, just like in
279 //! \param value The value to which the field will be set.
280 //! \retval true The field was set successfully.
281 //! \retval false There is no field with the provided name.
282 bool setFieldByName(const std::string & name, uint32_t value);
284 //! \brief Returns a reference to the IVT structure.
285 hab_ivt_t & getIVT() { return m_ivt; }
290 hab_ivt_t m_ivt; //!< The IVT structure.
291 bool m_isSelfSet; //!< True if the IVT self pointer was explicitly set.
296 #endif // _IVTDataSource_h_