1 2 3 4 5 6 7 8 9 10 11 12
13 14 15
16
17 package xdc.rov;
18
19 /*!
20 * ======== StructureDecoder ========
21 * Module for retrieving and decoding target structures.
22 *
23 * The StructureDecoder is responsible for decoding target data given the
24 * raw target bytes and the data's type as defined in XDC. It also contains
25 * APIs for retrieving data from the target given the data's address.
26 *
27 * The StructureDecoder relies on the TargetDecoder to decode the raw target
28 * bytes, but is itself responsible for decoding the structure layout. The
29 * decodeStruct API takes as an argument the structure's type representation
30 * in the XDC object model, and refers to this object to determine the size
31 * and offsets of the structure's fields.
32 *
33 * The object returned by decodeStruct is not the typed Java representation of
34 * the structure, but rather a typeless JavaScript object which simply
35 * contains all of the same fields. This allows ROV to control the type of the
36 * fields, and specifically to represent arrays as addresses rather than as
37 * objects.
38 *
39 * All of the 'decode' methods are essentially private methods. The intended
40 * interface to the StructureDecoder is through the 'fetch' APIs.
41 */
42 metaonly module StructureDecoder
43 {
44 /*!
45 * ======== Buffer ========
46 * Target buffer
47 *
48 * This structure encapsulates a buffer of target memory (`buffer`),
49 * the buffer's original target address (`addr`), and a running offset
50 * into that buffer (`off`).
51 *
52 * Decoding a structure is a recursive process, since the structure may
53 * include fields which are also structures. As `StructureDecoder`
54 * decodes each field, it updates the `off` field to move to the next
55 * field.
56 *
57 * The original address of the buffer is stored as well so that each
58 * structure field can be given a `$addr` property with its target
59 * address.
60 */
61 metaonly struct Buffer {
62 Any buffer;
63 Int addr;
64 Int off;
65 }
66
67 /*!
68 * @_nodoc
69 * ======== FieldType ========
70 * Object representing the type of a field.
71 *
72 * An object of this type is returned by the `{@link #parseTypeString}`
73 * method.
74 *
75 * A field can either be a scalar, a structure, or an array.
76 */
77 metaonly struct FieldType {
78
79 Bool isScalarType;
80 Bool signed;
81 Bool isEnum;
82 Bool isEncoded;
83 Int size;
84 Int align;
85 Bool isAddr;
86 String fldType;
87
88
89 Bool isStrType;
90 Any strType;
91
92
93 Bool isArrType;
94 Int len;
95 String elemType;
96 }
97
98 instance:
99 /*!
100 * ======== create ========
101 * Create a StructureDecoder instance
102 *
103 * The StructureDecoder requires a MemoryImage instance and the target
104 * configuration object from the ROV recap file; i.e.,
105 * recap.build.target.
106 */
107 create(Any mem, Any targConfig);
108
109 /*!
110 * ======== fetchStruct ========
111 * Retrieve and decode a structure from the target
112 *
113 * This method retrieves and decodes a structure of the given type at
114 * the given address from the target.
115 * @p(dlist)
116 * - `structType`
117 * Structure type. Not just a string, it is the XDC object
118 * model representation of the type.
119 * - `addr`
120 * Target address of the structure to retrieve.
121 * - `addrCheck`
122 * Whether to check the memory read against the section map.
123 * @p
124 */
125 Any fetchStruct(Any structType, Int addr, Bool addrCheck);
126
127 /*!
128 * ======== fetchArray ========
129 * Retrieve and decode an array of structures from the target
130 *
131 * @p(dlist)
132 * - `structType`
133 * Structure type. Not just a string, it is the XDC object
134 * model representation of the type.
135 * - `addr`
136 * Target address of the structure to retrieve.
137 * - `len`
138 * Number of entries in the array.
139 * - `isScalar`
140 * Whether it is an array of scalars.
141 * - `addrCheck`
142 * Whether to check the memory read against the section map.
143 * @p
144 */
145 Any fetchArray(Any structType, Int addr, Int len, Bool isScalar,
146 Bool addrCheck);
147
148 /*!
149 * ======== decodeStruct ========
150 * Decode an entire structure by decoding each of the structure's fields
151 *
152 * @p(dlist)
153 * - `structType`
154 * Structure type. Not just a string, it is the XDC object
155 * model representation of the type.
156 * - `buffer`
157 * Buffer of target memory containing raw data.
158 * - `inStr`
159 * Optional structure to fill in. Otherwise decodeStruct will
160 * create a new one.
161 * @p
162 */
163 Any decodeStruct(Any structType, Buffer buffer, Any inStr = null);
164
165 /*!
166 * ======== decodeStructArray ========
167 * Decode an array of structures
168 *
169 * This API exists to perform some optimizations when decoding an array
170 * of a single type of object.
171 *
172 * @p(dlist)
173 * - `structType`
174 * Structure type of the elements in the array. Not just a
175 * string, it is the XDC object model representation of the
176 * type.
177 * - `buffer`
178 * Buffer of target memory containing raw data.
179 * - `len`
180 * Number of elements in the array.
181 * @p
182 */
183 Any decodeStructArray(Any structType, Buffer buffer, Int len);
184
185 /*!
186 * @_nodoc
187 * ======== _parseTypeString ========
188 * Convert a type string to a FieldType
189 *
190 * This method interperets a type string from a $$sizes structure, and
191 * returns the interpretation in a FieldType object.
192 */
193 FieldType _parseTypeString(String fieldType);
194
195 /*!
196 * @_nodoc
197 * ======== _decodeField ========
198 * Decodes a single field within a structure and returns its value.
199 * This API is only called by decodeStruct. It does not take an XDC type
200 * object but just a string representing the type of a single field within
201 * a structure.
202 *
203 * @p(dlist)
204 * - `fieldType`
205 * Type info for the field.
206 * - `buffer`
207 * Buffer of target memory containing raw data.
208 * @p
209 *
210 * TODO - This should be spec'd, but currently it can't because it will
211 * not properly return an Enum object.
212 */
213
214 function _decodeField(fieldType, buffer);
215
216 /*!
217 * @_nodoc
218 * ======== _decodeArray ========
219 * This API decodes an array of any type of elements given the elements'
220 * type string.
221 *
222 * decodeStructArray takes an XDC OM type object, while decodeArray takes
223 * a type string. decodeArray calls down to decodeStructArray if the
224 * element type is a structure.
225 *
226 * @p(dlist)
227 * - `elemType`
228 * Type info for the elements of the array.
229 * - `buffer`
230 * Buffer of target memory containing raw data.
231 * - `len`
232 * Number of elements in the array.
233 * @p
234 */
235 Any _decodeArray(String elemType, Buffer buffer, Int len);
236
237 /*!
238 * @_nodoc
239 * ======== _decodeScalar ========
240 * Decodes a scalar value of 'type' at the offset specified in
241 * 'buffer.off'.
242 *
243 * @p(dlist)
244 * - `type`
245 * Type info for the scalar
246 * - `buffer`
247 * Buffer of target memory containing raw data.
248 * @p
249 *
250 * TODO - This should be spec'd, but currently it can't because it will
251 * not properly return an Enum object.
252 */
253
254 function _decodeScalar(type, buffer);
255
256 }
257 258 259
260