-
Notifications
You must be signed in to change notification settings - Fork 97
/
p9_xip_image.h
1996 lines (1695 loc) · 74.4 KB
/
p9_xip_image.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/* IBM_PROLOG_BEGIN_TAG */
/* This is an automatically generated prolog. */
/* */
/* $Source: src/import/chips/p9/xip/p9_xip_image.h $ */
/* */
/* OpenPOWER HostBoot Project */
/* */
/* Contributors Listed Below - COPYRIGHT 2015,2017 */
/* [+] International Business Machines Corp. */
/* */
/* */
/* Licensed under the Apache License, Version 2.0 (the "License"); */
/* you may not use this file except in compliance with the License. */
/* You may obtain a copy of the License at */
/* */
/* http://www.apache.org/licenses/LICENSE-2.0 */
/* */
/* Unless required by applicable law or agreed to in writing, software */
/* distributed under the License is distributed on an "AS IS" BASIS, */
/* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or */
/* implied. See the License for the specific language governing */
/* permissions and limitations under the License. */
/* */
/* IBM_PROLOG_END_TAG */
/// \file p9_xip_image.h
/// \brief definition of structs in sections
///
/// Contains struct ProcSbeFixed which contains functions, rings and
/// attributes whose pointers are stored in the fixed and fixed_toc section
/// Everything related to creating and manipulating P9-XIP binary images
// *INDENT-OFF*
#ifndef __P9_XIP_IMAGE_H
#define __P9_XIP_IMAGE_H
/// Current version (fields, layout, sections) of the P9_XIP header
///
/// If any changes are made to this file or to p9_xip_header.H, please update
/// the header version and follow-up on all of the error messages.
#define P9_XIP_HEADER_VERSION 9
/// \defgroup p9_xip_magic_numbers P9-XIP magic numbers
///
/// An P9-XIP magic number is a 64-bit constant. The 4 high-order bytes
/// contain the ASCII characters "XIP " and identify the image as a P9-XIP
/// image, while the 4 low-order bytes identify the type of the image.
///
/// @{
#ifdef __ASSEMBLER__
#define ULL(x) x
#else
#define ULL(x) x##ull
#endif
#define P9_XIP_MAGIC 0x58495020 // "XIP "
#define P9_XIP_MAGIC_BASE ULL(0x5849502042415345) // "XIP BASE"
#define P9_XIP_MAGIC_SEEPROM ULL(0x584950205345504d) // "XIP SEPM"
#define P9_XIP_MAGIC_CENTAUR ULL(0x58495020434e5452) // "XIP CNTR"
#define P9_XIP_MAGIC_HW ULL(0x5849502020204857) // "XIP HW"
#define P9_XIP_MAGIC_SGPE ULL(0x5849502053475045) // "XIP SGPE"
#define P9_XIP_MAGIC_RESTORE ULL(0x5849502052455354) // "XIP REST"
#define P9_XIP_MAGIC_CME ULL(0x5849502020434d45) // "XIP CME"
#define P9_XIP_MAGIC_PGPE ULL(0x5849502050475045) // "XIP PGPE"
#define P9_XIP_MAGIC_IOPPE ULL(0x5849502049505045) // "XIP IPPE"
#define P9_XIP_MAGIC_FPPE ULL(0x5849502046505045) // "XIP FPPE"
/// @}
/// \defgroup p9_xip_sections P9-XIP Image Section Indexes
///
/// These constants define the order that the P9XipSection structures appear
/// in the header, which is not necessarily the order the sections appear in
/// the binary image. Given that P9-XIP image contents are tightly
/// controlled, we use this simple indexing scheme for the allowed sections
/// rather than a more general approach, e.g., allowing arbitrary sections
/// identified by their names.
///
/// @{
// fixed number of entries in section table including common and
// image-specific sections
#define P9_XIP_SECTIONS 15
// this ensures that common sections go first followed by image-specific
// sections, to be used to define image-specific sections
#define P9_XIP_SECTIONS_PLUS(num) (P9_XIP_SECTIONS_COMMON + num)
#ifndef __ASSEMBLER__
// these are common P9-XIP sections defined for a images
typedef enum {
P9_XIP_SECTION_HEADER = 0,
P9_XIP_SECTION_FIXED = 1,
P9_XIP_SECTION_FIXED_TOC = 2,
P9_XIP_SECTION_TOC = 3,
P9_XIP_SECTION_STRINGS = 4,
P9_XIP_SECTIONS_COMMON = 5 // total number of common sections
} p9_xip_section_common_t;
/// Applications can expand this macro to create an array of section names.
#define P9_XIP_SECTION_NAMES_COMMON \
".header", \
".fixed", \
".fixedtoc", \
".toc", \
".strings"
#define P9_XIP_SECTION_NAMES(var, ...) \
const char* var[] = { \
P9_XIP_SECTION_NAMES_COMMON, \
__VA_ARGS__ \
}
/// Applications can use this macro to safely index the array of section
/// names.
#define P9_XIP_SECTION_NAME(var, n) \
((((n) < 0) || ((n) >= (int)(sizeof(var) / sizeof(char*)))) ? \
"" : var[n])
#endif /* __ASSEMBLER__ */
/// @}
/// \defgroup p9_xip_validate() ignore masks.
///
/// These defines, when matched in p9_xip_validate(), cause the validation
/// to skip the check of the corresponding property. The purpose is to more
/// effectively debug images that may be damaged and which have excess info
/// before or after the image. The latter will be the case when dumping the
/// image as a memory block without knowing where the image starts and ends.
///
/// @{
#define P9_XIP_IGNORE_FILE_SIZE (uint32_t)0x00000001
#define P9_XIP_IGNORE_ALL (uint32_t)0x80000000
/// @}
/// Maximum section alignment for P9-XIP sections
#define P9_XIP_MAX_SECTION_ALIGNMENT 128
/// \defgroup p9_xip_toc_types P9-XIP Table of Contents data types
///
/// These are the data types stored in the \a iv_type field of the P9XipToc
/// objects. These must be defined as manifest constants because they are
/// required to be recognized as manifest constants in C (as opposed to C++)
/// code.
///
/// NB: The 0x0 code is purposefully left undefined to catch bugs.
///
/// @{
/// Data is a single unsigned byte
#define P9_XIP_UINT8 0x01
/// Data is a 16-bit unsigned integer
#define P9_XIP_UINT16 0x02
/// Data is a 32-bit unsigned integer
#define P9_XIP_UINT32 0x03
/// Data is a 64-bit unsigned integer
#define P9_XIP_UINT64 0x04
/// Data is a single signed byte
#define P9_XIP_INT8 0x05
/// Data is a 16-bit signed integer
#define P9_XIP_INT16 0x06
/// Data is a 32-bit signed integer
#define P9_XIP_INT32 0x07
/// Data is a 64-bit signed integer
#define P9_XIP_INT64 0x08
/// Data is a 0-byte terminated ASCII string
#define P9_XIP_STRING 0x09
/// Data is an address
#define P9_XIP_ADDRESS 0x0A
/// The maximum type number
#define P9_XIP_MAX_TYPE_INDEX 0x0A
/// Applications can expand this macro to get access to string forms of the
/// P9-XIP data types if desired.
#define P9_XIP_TYPE_STRINGS(var) \
const char* var[] = { \
"Illegal 0 Code", \
"P9_XIP_UINT8", \
"P9_XIP_UINT16", \
"P9_XIP_UINT32", \
"P9_XIP_UINT64", \
"P9_XIP_INT8", \
"P9_XIP_INT16", \
"P9_XIP_INT32", \
"P9_XIP_INT64", \
"P9_XIP_STRING", \
"P9_XIP_ADDRESS", \
}
/// Applications can expand this macro to get access to abbreviated string
/// forms of the P9-XIP data types if desired.
#define P9_XIP_TYPE_ABBREVS(var) \
const char* var[] = { \
"Illegal 0 Code", \
"u8 ", \
"u16", \
"u32", \
"u64", \
"i8 ", \
"i16", \
"i32", \
"i64", \
"str", \
"adr", \
}
/// Applications can use this macro to safely index either array of P9-XIP
/// type strings.
#define P9_XIP_TYPE_STRING(var, n) \
(((n) > (sizeof(var) / sizeof(char*))) ? \
"Invalid P9-XIP type specification" : var[n])
/// @}
/// Final alignment constraint for P9-XIP images.
///
/// images are required to be multiples of 8 bytes in length, to
/// gaurantee that the something will be able to complete any 8-byte load/store.
#define P9_XIP_FINAL_ALIGNMENT 8
/// Local undefined DD level value.
#define P9_XIP_UNDEFINED_DDLEVEL (uint8_t)0xff
////////////////////////////////////////////////////////////////////////////
// C Definitions
////////////////////////////////////////////////////////////////////////////
#ifndef __ASSEMBLER__
#ifdef _WIN32
#include "win32_stdint.h"
#else
#include <stdint.h>
#endif
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
#if 0
} /* So __cplusplus doesn't mess w/auto-indent */
#endif
/// P9-XIP Section information
///
/// This structure defines the data layout of section table entries in the
/// P9-XIP image header.
// -*- DO NOT REORDER OR EDIT THIS STRUCTURE DEFINITION WITHOUT ALSO -*-
// -*- EDITING THE ASSEMBLER LAYOUT IN p9_xip_header.H -*-
typedef struct
{
/// The offset (in bytes) of the section from the beginning of the image
///
/// In normalized images the section offset will always be 0 if the
/// section size is also 0.
uint32_t iv_offset;
/// The size of the section in bytes, exclusive of alignment padding
///
/// This is the size of the program-significant data in the section,
/// exclusive of any alignment padding or reserved or extra space. The
/// alignment padding (reserved space) is not represented explicitly, but
/// is only implied by the offset of any subsequent non-empty section, or
/// in the case of the final section in the image, the image size.
///
/// Regardless of the \a iv_offset, if the \a iv_size of a section is 0 it
/// should be considered "not present" in the image. In normalized images
/// the section offset will always be 0 if the section size is also 0.
uint32_t iv_size;
/// The required initial alignment for the section offset
///
/// The image and the applications using P9-XIP images have strict
/// alignment/padding requirements. The image does not handle any type of
/// unaligned instruction or data fetches. Some sections and subsections
/// must also be POWER cache-line aligned. The \a iv_alignment applies to
/// the first byte of the section. image images are also required to be
/// multiples of 8 bytes in length, to gaurantee that the something will be
/// able to complete any 8-byte load/store. These constraints are checked
/// by p9_xip_validate() and enforced by p9_xip_append(). The alignment
/// constraints may force a section to be padded, which may create "holes"
/// in the image as explained in the comments for the \a iv_size field.
///
/// Note that alignment constraints are always checked relative to the
/// first byte of the image for in-memory images, not relative to the host
/// address. Alignment specifications are required to be a power-of-2.
uint8_t iv_alignment;
/// Indicate if section has DD-level support. This value must be set
/// to either 1 for true or 0 for false (default).
uint8_t iv_ddSupport;
/// Reserved structure alignment padding; Pad to 12 bytes
uint8_t iv_reserved8[2];
} P9XipSection;
/// The P9XipSection structure is created by assembler code and is expected
/// to have the same size in C code. This constraint is checked in
/// p9_xip_validate().
#define SIZE_OF_P9_XIP_SECTION 12
/// P9-XIP binary image header
///
/// This header occupies the initial bytes of a P9-XIP binary image.
/// The header contents are documented here, however the structure is actually
/// defined in the file p9_xip_header.S, and these two definitions must be
/// kept consistent.
///
/// The header is a fixed-format representation of the most critical
/// information about the image. The large majority of information about the
/// image and its contents are available through the searchable table of
/// contents. image code itself normally accesses the data directly through
/// global symbols.
///
/// The header only contains information 1) required by OTPROM code (e.g., the
/// entry point); 2) required by search and updating APIs (e.g., the
/// locations and sizes of all of the sections.); a few pieces of critical
/// meta-data (e.g., information about the image build process).
///
/// Any entries that are accessed by image code are required to be 64 bits, and
/// will appear at the beginning of the header.
///
/// The header also contains bytewise offsets and sizes of all of the sections
/// that are assembled to complete the image. The offsets are relative to the
/// start of the image (where the header is loaded). The sizes include any
/// padding inserted by the link editor to guarantee section alignment.
///
/// Every field of the header is also accesssible through the searchable table
/// of contents as documented in p9_xip_header.S.
// -*- DO NOT REORDER OR EDIT THIS STRUCTURE DEFINITION WITHOUT ALSO -*-
// -*- EDITING THE ASSEMBLER LAYOUT IN p9_xip_header.S, AND WITHOUT -*-
// -*- UPDATING THE p9_xip_translate_header() API IN p9_xip_image.c. -*-
typedef struct
{
//////////////////////////////////////////////////////////////////////
// Identification - 8-byte aligned; 8 entries
//////////////////////////////////////////////////////////////////////
/// Contains P9_XIP_MAGIC to identify a P9-XIP image
uint64_t iv_magic;
/// The entry address of the L1 loader entry point in SEEPROM
uint64_t iv_L1LoaderAddr;
/// The entry address of the L2 loader entry point in SRAM
uint64_t iv_L2LoaderAddr;
/// The entry address of Kernel in SRAM
uint64_t iv_kernelAddr;
/// The base address used to link the image, as a full relocatable image
/// address
uint64_t iv_linkAddress;
/// Reserved for future expansion
uint64_t iv_reserved64[3];
//////////////////////////////////////////////////////////////////////
// Section Table - 4-byte aligned; 15 entries
//////////////////////////////////////////////////////////////////////
P9XipSection iv_section[P9_XIP_SECTIONS];
//////////////////////////////////////////////////////////////////////
// Other information - 4-byte aligned; 8 entries
//////////////////////////////////////////////////////////////////////
/// The size of the image (including padding) in bytes
uint32_t iv_imageSize;
/// Build date generated by `date +%Y%m%d`, e.g., 20110630
uint32_t iv_buildDate;
/// Build time generated by `date +%H%M`, e.g., 0756
uint32_t iv_buildTime;
/// Build tag, generated when releasing this image to fw
char iv_buildTag[20];
//////////////////////////////////////////////////////////////////////
// Other Information - 1-byte aligned; 8 entries
//////////////////////////////////////////////////////////////////////
/// Header format version number
uint8_t iv_headerVersion;
/// Indicates whether the image has been normalized (0/1)
uint8_t iv_normalized;
/// Indicates whether the TOC has been sorted to speed searching (0/1)
uint8_t iv_tocSorted;
/// Reserved for future expansion
uint8_t iv_reserved8[5];
//////////////////////////////////////////////////////////////////////
// Strings; 64 characters allocated
//////////////////////////////////////////////////////////////////////
/// Build user, generated by `id -un`
char iv_buildUser[16];
/// Build host, generated by `hostname`
char iv_buildHost[40];
/// Reserved for future expansion
char iv_reservedChar[8];
} P9XipHeader;
/// A C-structure form of the P9-XIP Table of Contents (TOC) entries
///
/// The .toc section consists entirely of an array of these structures.
/// TOC entries are never accessed by image code.
///
/// These structures store indexing information for global data required to be
/// manipulated by external tools. The actual data is usually allocated in a
/// data section and manipulated by the SBE code using global or local symbol
/// names. Each TOC entry contains a pointer to a keyword string naming the
/// data, the address of the data (or the data itself), the data type,
/// meta-information about the data, and for vectors the vector size.
// -*- DO NOT REORDER OR EDIT THIS STRUCTURE DEFINITION WITHOUT ALSO -*-
// -*- EDITING THE ASSEMBLER MACROS (BELOW) THAT CREATE THE TABLE OF -*-
// -*- CONTENTS ENTRIES. -*-
typedef struct
{
/// A pointer to a 0-byte terminated ASCII string identifying the data.
///
/// When allocated by the .xip_toc macro this is a pointer to the string
/// form of the symbol name for the global or local symbol associated with
/// the data which is allocated in the .strings section. This pointer is
/// not aligned.
///
/// When the image is normalized this pointer is replaced by the offset of
/// the string in the .strings section.
uint32_t iv_id;
/// A 32-bit pointer locating the data
///
/// This field is initially populated by the link editor. For scalar,
/// vector and string types this is the final relocated address of the
/// first byte of the data. For address types, this is the relocated
/// address. When the image is normalized, these addresses are converted
/// into the equivalent offsets from the beginning of the section holding
/// the data.
uint32_t iv_data;
/// The type of the data; See \ref p9_xip_toc_types.
uint8_t iv_type;
/// The section containing the data; See \ref p9_xip_sections.
uint8_t iv_section;
/// The number of elements for vector types, otherwise 1 for scalar types
/// and addresses.
///
/// Vectors are naturally limited in size, e.g. to the number of cores,
/// chips in a node, DD-levels etc. If \a iv_elements is 0 then no bounds
/// checking is done on get/set accesses of the data.
uint8_t iv_elements;
/// Structure alignment padding; Pad to 12 bytes
uint8_t iv_pad;
} P9XipToc;
/// The P9XipToc structure is created by assembler code and is expected
/// to have the same size in C code. This constraint is checked in
/// p9_xip_validate().
#define SIZE_OF_P9_XIP_TOC 12
/// A C-structure form of hashed P9-XIP Table of Contents (TOC) entries
///
/// This structure was introduced in order to allow a small TOC for the .fixed
/// section to support minimum-sized SEEPROM images in which the global TOC
/// and all strings have been stripped out. In this structure the index
/// string has been replaced by a 32-bit hash, and there is no longer a record
/// of the original data name other then the hash. The section of the data is
/// assumed to be .fixed, with a maximum 16-bit offset.
///
/// These structures are created when entries are made in the .fixed section.
/// They are created empty, then filled in during image normalization.
///
/// This structure allows the p9_xip_get*() and p9_xip_set*() APIs to work
/// even on highly-stripped SEEPROM images.
typedef struct
{
/// A 32-bit hash (FNV-1a) of the Id string.
uint32_t iv_hash;
/// The offset in bytes from the start of the (implied) section of the data
uint16_t iv_offset;
/// The type of the data; See \ref p9_xip_toc_types.
uint8_t iv_type;
/// The number of elements for vector types, otherwise 1 for scalar types
/// and addresses.
///
/// Vectors are naturally limited in size, e.g. to the number of cores,
/// chips in a node, DD-levels etc. If \a iv_elements is 0 then no bounds
/// checking is done on get/set accesses of the data.
uint8_t iv_elements;
} P9XipHashedToc;
/// The P9XipHashedToc structure is created by assembler code and is expected
/// to have the same size in C code. This constraint is checked in
/// p9_xip_validate().
#define SIZE_OF_P9_XIP_HASHED_TOC 8
/// A decoded TOC entry for use by applications
///
/// This structure is a decoded form of a normalized TOC entry, filled in by
/// the p9_xip_decode_toc() and p9_xip_find() APIs. This structure is
/// always returned with data elements in host-endian format.
///
/// In the event that the TOC has been removed from the image, this structure
/// will also be returned by p9_xip_find() with information populated from
/// the .fixed_toc section if possible. In this case the field \a iv_partial
/// will be set and only the fields \a iv_address, \a iv_imageData, \a iv_type
/// and \a iv_elements will be populated (all other fields will be set to 0).
///
/// \note Only special-purpose applications will ever need to use this
/// structure given that the higher-level APIs p9_xip_get_*() and
/// p9_xip_set_*() are provided and should be used if possible, especially
/// given that the information may be truncated as described above.
typedef struct
{
/// A pointer to the associated TOC entry as it exists in the image
///
/// If \a iv_partial is set this field is returned as 0.
P9XipToc* iv_toc;
/// The full relocatable image address
///
/// All relocatable addresses are computed from the \a iv_linkAddress
/// stored in the header. For scalar and string data, this is the
/// relocatable address of the data. For address-only entries, this is
/// the indexed address itself.
uint64_t iv_address;
/// A host pointer to the first byte of text or data within the image
///
/// For scalar or string types this is a host pointer to the first byte of
/// the data. For code pointers (addresses) this is host pointer to the
/// first byte of code. Note that any use of this field requires the
/// caller to handle conversion of the data to host endian-ness if
/// required. Only 8-bit and string data can be used directly on all
/// hosts.
void* iv_imageData;
/// The item name
///
/// This is a pointer in host memory to a string that names the TOC entry
/// requested. This field is set to a pointer to the ID string of the TOC
/// entry inside the image. If \a iv_partial is set this field is returned
/// as 0.
char* iv_id;
/// The data type, one of the P9_XIP_* constants
uint8_t iv_type;
/// The number of elements in a vector
///
/// This field is set from the TOC entry when the TOC entry is
/// decoded. This value is stored as 1 for scalar declarations, and may be
/// set to 0 for vectors with large or undeclared sizes. Otherwise it is
/// used to bounds check indexed accesses.
uint8_t iv_elements;
/// Is this record only partially populated?
///
/// This field is set to 0 normally, and only set to 1 if a lookup is made
/// in an image that only has the fixed TOC and the requested Id hashes to
/// the fixed TOC.
uint8_t iv_partial;
} P9XipItem;
/// Validate a P9-XIP image
///
/// \param[in] i_image A pointer to a P9-XIP image in host memory.
///
/// \param[in] i_size The putative size of the image
///
/// \param[in] i_maskIgnores Array of ignore bits representing which properties
/// should not be checked for in p9_xip_validate2().
///
/// This API should be called first by all applications that manipulate
/// P9-XIP images in host memory. The magic number is validated, and
/// the image is checked for consistency of the section table and table of
/// contents. The \a iv_imageSize field of the header must also match the
/// provided \a i_size parameter. Validation does not modify the image.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_validate(void* i_image, const uint32_t i_size);
int
p9_xip_validate2(void* i_image, const uint32_t i_size,
const uint32_t i_maskIgnores);
/// Normalize the P9-XIP image
///
/// \param[in] io_image A pointer to a P9-XIP image in host memory. The
/// image is assumed to be consistent with the information contained in the
/// header regarding the presence of and sizes of all sections.
///
/// P9-XIP images must be normalized before any other APIs are allowed to
/// operate on the image. Since normalization modifies the image, an explicit
/// call to normalize the image is required. Briefly, normalization modifies
/// the TOC entries created by the final link to simplify search, updates,
/// modification and relocation of the image. Normalization is explained in
/// the written documentation of the P9-XIP binary format. Normalization does
/// not modify the size of the image.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_normalize(void* io_image);
/// Return the size of a P9-XIP image from the image header
///
/// \param[in] i_image A pointer to a P9-XIP image in host memory. The
/// image is assumed to be consistent with the information contained in the
/// header regarding the presence of and sizes of all sections.
///
/// \param[out] o_size A pointer to a variable returned as the size of the
/// image in bytes, as recorded in the image header.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_image_size(void* i_image, uint32_t* o_size);
/// Locate a section table entry and translate into host format
///
/// \param[in] i_image A pointer to a P9-XIP image in host memory.
///
/// \param[in] i_sectionId Identifies the section to be queried. See \ref
/// p9_xip_sections.
///
/// \param[out] o_hostSection Updated to contain the section table entry
/// translated to host byte order.
///
/// \param[in] i_ddLevel Specified the DD level of the sub-section within
/// the XIP section to be extracted.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_get_section(const void* i_image,
const int i_sectionId,
#if defined(__PPE__) || defined(WIN32)
P9XipSection* o_hostSection);
#else
P9XipSection* o_hostSection,
uint8_t i_ddLevel=P9_XIP_UNDEFINED_DDLEVEL);
#endif
/// Endian translation of a P9XipHeader object
///
/// \param[out] o_hostHeader The destination object.
///
/// \param[in] i_imageHeader The source object.
///
/// Translation of a P9XipHeader includes translation of all data members
/// including traslation of the embedded section table. This translation
/// works even if \a o_src == \a o_dest, i.e., in the destructive case.
void
p9_xip_translate_header(P9XipHeader* o_hostHeader,
const P9XipHeader* i_imageHeader);
/// Get scalar data from a P9-XIP image
///
/// \param[in] i_image A pointer to a P9-XIP image in host memory. The
/// image is assumed to be consistent with the information contained in the
/// header regarding the presence of and sizes of all sections. The image is
/// also required to have been normalized.
///
/// \param[in] i_id A pointer to a 0-terminated ASCII string naming the item
/// requested.
///
/// \param[out] o_data A pointer to an 8-byte integer to receive the scalar
/// data. Assuming the item is located this variable is assigned by the call.
/// In the event of an error the final state of \a o_data is not specified.
///
/// This API searches the P9-XIP Table of Contents (TOC) for the item named
/// \a i_id, assigning \a o_data from the image if the item is found and is a
/// scalar value. Scalar values include 8- 32- and 64-bit integers and image
/// addresses. Image data smaller than 64 bits are extracted as unsigned
/// types, and it is the caller's responsibility to cast or convert the
/// returned data as appropriate.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_get_scalar(void* i_image, const char* i_id, uint64_t* o_data);
/// Get endianness converted value from the P9-XIP image toc data
///
/// \param[in] i_item - decoded toc entry
/// \param[out] o_data A pointer to an 8-byte integer to receive the scalar
/// data. Assuming the item is located this variable is assigned by the call.
/// In the event of an error the final state of \a o_data is not specified.
///
/// \param[in] i_index The index of the vector element to return.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_get_item(const P9XipItem *i_item, uint64_t* o_data, uint32_t i_index);
/// Get an integral element from a vector held in a P9-XIP image
///
/// \param[in] i_image A pointer to a P9-XIP image in host memory. The
/// image is assumed to be consistent with the information contained in the
/// header regarding the presence of and sizes of all sections. The image is
/// also required to have been normalized.
///
/// \param[in] i_id A pointer to a 0-terminated ASCII string naming the item
/// requested.
///
/// \param[in] i_index The index of the vector element to return.
///
/// \param[out] o_data A pointer to an 8-byte integer to receive the
/// data. Assuming the item is located this variable is assigned by the call.
/// In the event of an error the final state of \a o_data is not specified.
///
/// This API searches the P9-XIP Table of Contents (TOC) for the \a i_index
/// element of the item named \a i_id, assigning \a o_data from the image if
/// the item is found, is a vector of an integral type, and the \a i_index is
/// in bounds. Vector elements smaller than 64 bits are extracted as unsigned
/// types, and it is the caller's responsibility to cast or convert the
/// returned data as appropriate.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_get_element(void* i_image,
const char* i_id,
const uint32_t i_index,
uint64_t* o_data);
/// Get string data from a P9-XIP image
///
/// \param[in] i_image A pointer to a P9-XIP image in host memory. The
/// image is assumed to be consistent with the information contained in the
/// header regarding the presence of and sizes of all sections. The image is
/// also required to have been normalized.
///
/// \param[in] i_id A pointer to a 0-terminated ASCII string naming the item
/// requested.
///
/// \param[out] o_data A pointer to a character pointer. Assuming the
/// item is located this variable is assigned by the call to point to the
/// string as it exists in the \a i_image. In the event of an error the final
/// state of \a o_data is not specified.
///
/// This API searches the P9-XIP Table of Contents (TOC) for the item named
/// \a i_id, assigning \a o_data if the item is found and is a string. It is
/// the caller's responsibility to copy the string from the \a i_image memory
/// space if necessary.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_get_string(void* i_image, const char* i_id, char** o_data);
/// Directly read 64-bit data from the image based on a image address
///
/// \param[in] i_image A pointer to a P9-XIP image in host memory. The
/// image is assumed to be consistent with the information contained in the
/// header regarding the presence of and sizes of all sections.
///
/// \param[in] i_imageAddress A relocatable IMAGE address contained in the
/// image, presumably of an 8-byte data area. The \a i_imageAddress is
/// required to be 8-byte aligned, otherwise the P9_XIP_ALIGNMENT_ERROR code
/// is returned.
///
/// \param[out] o_data The 64 bit data in host format that was found at \a
/// i_imageAddress.
///
/// This API is provided for applications that need to manipulate P9-XIP
/// images in terms of their relocatable IMAGE addresses. The API checks that
/// the \a i_imageAddress is properly aligned and contained in the image, then
/// reads the contents of \a i_imageAddress into \a o_data, performing
/// image-to-host endianess conversion if required.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_read_uint64(const void* i_image,
const uint64_t i_imageAddress,
uint64_t* o_data);
/// Set scalar data in a P9-XIP image
///
/// \param[in,out] io_image A pointer to a P9-XIP image in host memory.
/// The image is assumed to be consistent with the information contained in
/// the header regarding the presence of and sizes of all sections. The image
/// is also required to have been normalized.
///
/// \param[in] i_id A pointer to a 0-terminated ASCII string naming the item
/// to be modified.
///
/// \param[in] i_data The new scalar data.
///
/// This API searches the P9-XIP Table of Contents (TOC) for the item named
/// by \a i_id, updating the image from \a i_data if the item is found, has
/// a scalar type and can be modified. For this API the scalar types include
/// 8- 32- and 64-bit integers. Although IMAGE addresses are considered a
/// scalar type for p9_xip_get_scalar(), IMAGE addresses can not be modified
/// by this API. The caller is responsible for ensuring that the \a i_data is
/// of the correct size for the underlying data element in the image.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_set_scalar(void* io_image, const char* i_id, const uint64_t i_data);
/// Set an integral element in a vector held in a P9-XIP image
///
/// \param[in] i_image A pointer to a P9-XIP image in host memory. The
/// image is assumed to be consistent with the information contained in the
/// header regarding the presence of and sizes of all sections. The image is
/// also required to have been normalized.
///
/// \param[in] i_id A pointer to a 0-terminated ASCII string naming the item
/// to be updated.
///
/// \param[in] i_index The index of the vector element to update.
///
/// \param[out] i_data The new vector element.
///
/// This API searches the P9-XIP Table of Contents (TOC) for the \a i_index
/// element of the item named \a i_id, update the image from \a i_data if the
/// item is found, is a vector of an integral type, and the \a i_index is in
/// bounds. The caller is responsible for ensuring that the \a i_data is of
/// the correct size for the underlying data element in the image.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_set_element(void* i_image,
const char* i_id,
const uint32_t i_index,
const uint64_t i_data);
/// Set string data in a P9-XIP image
///
/// \param[in,out] io_image A pointer to a P9-XIP image in host memory. The
/// image is assumed to be consistent with the information contained in the
/// header regarding the presence of and sizes of all sections. The image is
/// also required to have been normalized.
///
/// \param[in] i_id A pointer to a 0-terminated ASCII string naming the item
/// to be modified.
///
/// \param[in] i_data A pointer to the new string data.
///
/// This API searches the P9-XIP Table of Contents (TOC) for the item named
/// \a i_id, which must be a string variable. If found, then the string data
/// in the image is overwritten with \a i_data. Strings are held 0-terminated
/// in the image, and the P9-XIP format does not maintain a record of the
/// amount of memory allocated for an individual string. If a string is
/// overwritten by a shorter string then the 'excess' storage is effectively
/// lost. If the length of \a i_data is longer that the current strlen() of
/// the string data then \a i_data is silently truncated to the first
/// strlen(old_string) characters.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_set_string(void* io_image, const char* i_id, const char* i_data);
/// Directly write 64-bit data into the image based on a IMAGE address
///
/// \param[in, out] io_image A pointer to a P9-XIP image in host memory. The
/// image is assumed to be consistent with the information contained in the
/// header regarding the presence of and sizes of all sections.
///
/// \param[in] i_imageAddress A relocatable IMAGE address contained in the
/// image, presumably of an 8-byte data area. The \a i_imageAddress is
/// required to be 8-byte aligned, otherwise the P9_XIP_ALIGNMENT_ERROR code
/// is returned.
///
/// \param[in] i_data The 64 bit data in host format to be written to \a
/// i_imageAddress.
///
/// This API is provided for applications that need to manipulate P9-XIP
/// images in terms of their relocatable IMAGE addresses. The API checks that
/// the \a i_imageAddress is properly aligned and contained in the image, then
/// updates the contents of \a i_imageAddress with \a i_data, performing
/// host-to-image endianess conversion if required.
///
/// \retval 0 Success
///
/// \retval non-0 See \ref p9_xip_image_errors
int
p9_xip_write_uint64(void* io_image,
const uint64_t i_imageAddress,
const uint64_t i_data);
/// Map over a P9-XIP image Table of Contents
///
/// \param[in,out] io_image A pointer to a P9-XIP image in host memory. The
/// image is assumed to be consistent with the information contained in the
/// header regarding the presence of and sizes of all sections. The image is
/// also required to have been normalized.
///
/// \param[in] i_fn A pointer to a function to call on each TOC entry. The
/// function has the prototype:
///
/// \code
/// int (*i_fn)(void* io_image,
/// const P9XipItem* i_item,
/// void* io_arg)
/// \endcode
///
/// \param[in,out] io_arg The private argument of \a i_fn.
///
/// This API iterates over each entry of the TOC, calling \a i_fn with
/// pointers to the image, a P9XipItem* pointer, and a private argument. The
/// iteration terminates either when all TOC entries have been mapped, or \a
/// i_fn returns a non-zero code.
///
/// \retval 0 Success; All TOC entries were mapped, including the case that
/// the .toc section is empty.
///
/// \retval non-0 May be either one of the P9-XIP image error codes (see \ref
/// p9_xip_image_errors), or a non-zero code from \a i_fn. Since the standard