1 /*
2 * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 * or visit www.oracle.com if you need additional information or have any
21 * questions.
22 *
23 */
24
25 #ifndef SHARE_VM_CLASSFILE_IMAGEFILE_HPP
26 #define SHARE_VM_CLASSFILE_IMAGEFILE_HPP
27
28 #include "classfile/classLoader.hpp"
29 #include "memory/allocation.hpp"
30 #include "memory/allocation.inline.hpp"
31 #include "utilities/globalDefinitions.hpp"
32
33 // Image files are an alternate file format for storing classes and resources. The
34 // goal is to supply file access which is faster and smaller that the jar format.
35 // It should be noted that unlike jars information stored in an image is in native
36 // endian format. This allows the image to be memory mapped into memory without
37 // endian translation. This also means that images are platform dependent.
38 //
39 // Image files are structured as three sections;
40 //
41 // +-----------+
42 // | Header |
43 // +-----------+
44 // | |
45 // | Directory |
46 // | |
47 // +-----------+
48 // | |
49 // | |
50 // | Resources |
51 // | |
52 // | |
53 // +-----------+
54 //
55 // The header contains information related to identification and description of
56 // contents.
57 //
58 // +-------------------------+
59 // | Magic (0xCAFEDADA) |
60 // +------------+------------+
61 // | Major Vers | Minor Vers |
62 // +------------+------------+
63 // | Location Count |
64 // +-------------------------+
65 // | Attributes Size |
66 // +-------------------------+
67 // | Strings Size |
68 // +-------------------------+
69 //
70 // Magic - means of identifying validity of the file. This avoids requiring a
71 // special file extension.
72 // Major vers, minor vers - differences in version numbers indicate structural
73 // changes in the image.
74 // Location count - number of locations/resources in the file. This count is also
75 // the length of lookup tables used in the directory.
76 // Attributes size - number of bytes in the region used to store location attribute
77 // streams.
78 // Strings size - the size of the region used to store strings used by the
79 // directory and meta data.
80 //
81 // The directory contains information related to resource lookup. The algorithm
82 // used for lookup is "A Practical Minimal Perfect Hashing Method"
83 // (http://homepages.dcc.ufmg.br/~nivio/papers/wea05.pdf). Given a path string
84 // in the form <package>/<base>.<extension> return the resource location
85 // information;
86 //
87 // redirectIndex = hash(path, DEFAULT_SEED) % count;
88 // redirect = redirectTable[redirectIndex];
89 // if (redirect == 0) return not found;
90 // locationIndex = redirect < 0 ? -1 - redirect : hash(path, redirect) % count;
91 // location = locationTable[locationIndex];
92 // if (!verify(location, path)) return not found;
93 // return location;
94 //
95 // Note: The hash function takes an initial seed value. A different seed value
96 // usually returns a different result for strings that would otherwise collide with
97 // other seeds. The verify function guarantees the found resource location is
98 // indeed the resource we are looking for.
99 //
100 // The following is the format of the directory;
101 //
102 // +-------------------+
103 // | Redirect Table |
104 // +-------------------+
105 // | Attribute Offsets |
106 // +-------------------+
107 // | Attribute Data |
108 // +-------------------+
109 // | Strings |
110 // +-------------------+
111 //
112 // Redirect Table - Array of 32-bit signed values representing actions that
113 // should take place for hashed strings that map to that
114 // value. Negative values indicate no hash collision and can be
115 // quickly converted to indices into attribute offsets. Positive
116 // values represent a new seed for hashing an index into attribute
117 // offsets. Zero indicates not found.
118 // Attribute Offsets - Array of 32-bit unsigned values representing offsets into
119 // attribute data. Attribute offsets can be iterated to do a
120 // full survey of resources in the image.
121 // Attribute Data - Bytes representing compact attribute data for locations. (See
122 // comments in ImageLocation.)
123 // Strings - Collection of zero terminated UTF-8 strings used by the directory and
124 // image meta data. Each string is accessed by offset. Each string is
125 // unique. Offset zero is reserved for the empty string.
126 //
127 // Note that the memory mapped directory assumes 32 bit alignment of the image
128 // header, the redirect table and the attribute offsets.
129 //
130
131
132 // Manage image file string table.
133 class ImageStrings {
134 private:
135 // Data bytes for strings.
136 u1* _data;
137 // Number of bytes in the string table.
138 u4 _size;
139
140 public:
141 // Prime used to generate hash for Perfect Hashing.
142 static const u4 HASH_MULTIPLIER = 0x01000193;
143
144 ImageStrings(u1* data, u4 size) : _data(data), _size(size) {}
145
146 // Return the UTF-8 string beginning at offset.
147 inline const char* get(u4 offset) const {
148 assert(offset < _size, "offset exceeds string table size");
149 return (const char*)(_data + offset);
150 }
151
152 // Compute the Perfect Hashing hash code for the supplied string.
153 inline static u4 hash_code(const char* string) {
154 return hash_code(string, HASH_MULTIPLIER);
155 }
156
157 // Compute the Perfect Hashing hash code for the supplied string, starting at seed.
158 static u4 hash_code(const char* string, u4 seed);
159
160 // Test to see if string begins with start. If so returns remaining portion
161 // of string. Otherwise, NULL. Used to test sections of a path without
162 // copying.
163 static const char* starts_with(const char* string, const char* start);
164
165 };
166
167 // Manage image file location attribute streams. Within an image, a location's
168 // attributes are compressed into a stream of bytes. An attribute stream is
169 // composed of individual attribute sequences. Each attribute sequence begins with
170 // a header byte containing the attribute 'kind' (upper 5 bits of header) and the
171 // 'length' less 1 (lower 3 bits of header) of bytes that follow containing the
172 // attribute value. Attribute values present as most significant byte first.
173 //
174 // Ex. Container offset (ATTRIBUTE_OFFSET) 0x33562 would be represented as 0x22
175 // (kind = 4, length = 3), 0x03, 0x35, 0x62.
176 //
177 // An attribute stream is terminated with a header kind of ATTRIBUTE_END (header
178 // byte of zero.)
179 //
180 // ImageLocation inflates the stream into individual values stored in the long
181 // array _attributes. This allows an attribute value can be quickly accessed by
182 // direct indexing. Unspecified values default to zero.
183 //
184 // Notes:
185 // - Even though ATTRIBUTE_END is used to mark the end of the attribute stream,
186 // streams will contain zero byte values to represent lesser significant bits.
187 // Thus, detecting a zero byte is not sufficient to detect the end of an attribute
188 // stream.
189 // - ATTRIBUTE_OFFSET represents the number of bytes from the beginning of the region
190 // storing the resources. Thus, in an image this represents the number of bytes
191 // after the directory.
192 // - Currently, compressed resources are represented by having a non-zero
193 // ATTRIBUTE_COMPRESSED value. This represents the number of bytes stored in the
194 // image, and the value of ATTRIBUTE_UNCOMPRESSED represents number of bytes of the
195 // inflated resource in memory. If the ATTRIBUTE_COMPRESSED is zero then the value
196 // of ATTRIBUTE_UNCOMPRESSED represents both the number of bytes in the image and
197 // in memory. In the future, additional compression techniques will be used and
198 // represented differently.
199 // - Package strings include trailing slash and extensions include prefix period.
200 //
201 class ImageLocation {
202 public:
203 // Attribute kind enumeration.
204 static const u1 ATTRIBUTE_END = 0; // End of attribute stream marker
205 static const u1 ATTRIBUTE_BASE = 1; // String table offset of resource path base
206 static const u1 ATTRIBUTE_PARENT = 2; // String table offset of resource path parent
207 static const u1 ATTRIBUTE_EXTENSION = 3; // String table offset of resource path extension
208 static const u1 ATTRIBUTE_OFFSET = 4; // Container byte offset of resource
209 static const u1 ATTRIBUTE_COMPRESSED = 5; // In image byte size of the compressed resource
210 static const u1 ATTRIBUTE_UNCOMPRESSED = 6; // In memory byte size of the uncompressed resource
211 static const u1 ATTRIBUTE_COUNT = 7; // Number of attribute kinds
212
213 private:
214 // Values of inflated attributes.
215 u8 _attributes[ATTRIBUTE_COUNT];
216
217 // Return the attribute value number of bytes.
218 inline static u1 attribute_length(u1 data) {
219 return (data & 0x7) + 1;
220 }
221
222 // Return the attribute kind.
223 inline static u1 attribute_kind(u1 data) {
224 u1 kind = data >> 3;
225 assert(kind < ATTRIBUTE_COUNT, "invalid attribute kind");
226 return kind;
227 }
228
229 // Return the attribute length.
230 inline static u8 attribute_value(u1* data, u1 n) {
231 assert(0 < n && n <= 8, "invalid attribute value length");
232 u8 value = 0;
233
234 // Most significant bytes first.
235 for (u1 i = 0; i < n; i++) {
236 value <<= 8;
237 value |= data[i];
238 }
239
240 return value;
241 }
242
243 public:
244 ImageLocation(u1* data);
245
246 // Retrieve an attribute value from the inflated array.
247 inline u8 get_attribute(u1 kind) const {
248 assert(ATTRIBUTE_END < kind && kind < ATTRIBUTE_COUNT, "invalid attribute kind");
249 return _attributes[kind];
250 }
251
252 // Retrieve an attribute string value from the inflated array.
253 inline const char* get_attribute(u4 kind, const ImageStrings& strings) const {
254 return strings.get((u4)get_attribute(kind));
255 }
256 };
257
258 // Manage the image file.
259 class ImageFile: public CHeapObj<mtClass> {
260 private:
261 // Image file marker.
262 static const u4 IMAGE_MAGIC = 0xCAFEDADA;
263 // Image file major version number.
264 static const u2 MAJOR_VERSION = 0;
265 // Image file minor version number.
266 static const u2 MINOR_VERSION = 1;
267
268 struct ImageHeader {
269 u4 _magic; // Image file marker
270 u2 _major_version; // Image file major version number
271 u2 _minor_version; // Image file minor version number
272 u4 _location_count; // Number of locations managed in index.
273 u4 _locations_size; // Number of bytes in attribute table.
274 u4 _strings_size; // Number of bytes in string table.
275 };
276
277 char* _name; // Name of image
278 int _fd; // File descriptor
279 bool _memory_mapped; // Is file memory mapped
280 ImageHeader _header; // Image header
281 u8 _index_size; // Total size of index
282 u1* _index_data; // Raw index data
283 s4* _redirect_table; // Perfect hash redirect table
284 u4* _offsets_table; // Location offset table
285 u1* _location_bytes; // Location attributes
286 u1* _string_bytes; // String table
287
288 // Compute number of bytes in image file index.
289 inline u8 index_size() {
290 return sizeof(ImageHeader) +
291 _header._location_count * sizeof(u4) * 2 +
292 _header._locations_size +
293 _header._strings_size;
294 }
295
296 public:
297 ImageFile(const char* name);
298 ~ImageFile();
299
300 // Open image file for access.
301 bool open();
302 // Close image file.
303 void close();
304
305 // Retrieve name of image file.
306 inline const char* name() const {
307 return _name;
308 }
309
310 // Return a string table accessor.
311 inline const ImageStrings get_strings() const {
312 return ImageStrings(_string_bytes, _header._strings_size);
313 }
314
315 // Return number of locations in image file index.
316 inline u4 get_location_count() const {
317 return _header._location_count;
318 }
319
320 // Return location attribute stream for location i.
321 inline u1* get_location_data(u4 i) const {
322 u4 offset = _offsets_table[i];
323
324 return offset != 0 ? _location_bytes + offset : NULL;
325 }
326
327 // Return the attribute stream for a named resourced.
328 u1* find_location_data(const char* path) const;
329
330 // Verify that a found location matches the supplied path.
331 bool verify_location(ImageLocation& location, const char* path) const;
332
333 // Return the resource for the supplied location info.
334 u1* get_resource(ImageLocation& location) const;
335
336 // Return the resource associated with the path else NULL if not found.
337 void get_resource(const char* path, u1*& buffer, u8& size) const;
338
339 // Return an array of packages for a given module
340 GrowableArray<const char*>* packages(const char* name);
341 };
342
343 #endif // SHARE_VM_CLASSFILE_IMAGEFILE_HPP