Debian Codegraph @

visa/iga/IGALibrary/api/iga.h

raw
1 /*========================== begin_copyright_notice ============================
2
3 Copyright (C) 2017-2021 Intel Corporation
4
5 SPDX-License-Identifier: MIT
6
7 ============================= end_copyright_notice ===========================*/
8
9 /*
10 * The IGA - Intel Gen Assembler external C API
11 */
12 #ifndef IGA_H
13 #define IGA_H
14
15 #include <stddef.h>
16 #include <stdint.h>
17 #ifdef _WIN32
18 #include <crtdefs.h>
19 #endif
20
21 #ifdef _WIN32
22 #ifdef IGA_BUILDING_DLL
23 #define IGA_API __declspec(dllexport)
24 /* define this symbol if you wish to statically link against iga32.dll */
25 #elif IGA_DLL_IMPORT
26 #define IGA_API __declspec(dllimport)
27 #else
28 #define IGA_API
29 #endif
30 #else
31 #if __GNUC__ >= 4
32 #define IGA_API __attribute__((visibility("default")))
33 #else
34 #define IGA_API
35 #endif
36 #endif
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 /* opaque pointer to context type */
43 typedef void *iga_context_t;
44
45 typedef enum {
46 IGA_SUCCESS = 0, /* the operation completed successfully
47 * (iga_disassemble and iga_assemble may
48 * still have logged warnings) */
49 IGA_ERROR = 1, /* general error */
50 IGA_INVALID_ARG = 2, /* something wrong with an arugment */
51 IGA_OUT_OF_MEM = 3, /* failed to allocate */
52 IGA_DECODE_ERROR = 4, /* error during decode phase */
53 IGA_ENCODE_ERROR = 5, /* error during the encode phase */
54 IGA_PARSE_ERROR = 6, /* error duing the parse phase (syntax) */
55 IGA_VERSION_ERROR = 7, /* this header file is newer than the binary
56 * called */
57 IGA_INVALID_OBJECT = 8, /* attempt to use an destroyed object
58 * (e.g. iga_context_t) */
59 IGA_INVALID_STATE = 9, /* e.g. call to iga_get_errors before disassembly*/
60 IGA_UNSUPPORTED_PLATFORM = 10, /* platform not supported with this binary */
61 IGA_DIFF_FAILURE = 11 /* used by -Xifs for diffing instructions */
62 } iga_status_t;
63
64 /*
65 * Converts an IGA status string code to a human-readable string.
66 *
67 * RETURNS: IGA_SUCCESS
68 */
69 IGA_API const char *iga_status_to_string(iga_status_t st);
70
71 /*
72 * Returns a NUL-terminated version string corresponding to the version of IGA.
73 */
74 IGA_API const char *iga_version_string();
75
76 /* The encoding for GEN version enumerates follows this pattern */
77 #define GEN_VER(MAJ, MIN) (((MAJ) << 16) | (MIN))
78
79 /* The encoding for XE version enumerates follows this pattern
80 * All XE_VER() must be larger than GEN_VER(). XE_VER(0,*) is illegal. TGL is
81 * XE_VER(1,0)
82 */
83 #define XE_VER(MAJ, MIN) (((MAJ) << 24) | (MIN))
84
85 /* Represents the specific version of Gen being assembled or disassembled */
86 typedef enum {
87 IGA_GEN_INVALID = 0,
88 IGA_GEN7 = GEN_VER(7, 0),
89 IGA_GEN7p5 = GEN_VER(7, 5),
90 IGA_GEN8 = GEN_VER(8, 0),
91 IGA_GEN8lp = GEN_VER(8, 1),
92 IGA_GEN9 = GEN_VER(9, 0),
93 IGA_GEN9lp = GEN_VER(9, 1),
94 IGA_GEN9p5 = GEN_VER(9, 5),
95 IGA_GEN10 = GEN_VER(10, 0),
96 IGA_GEN11 = GEN_VER(11, 0),
97 //
98 // XE versions
99 IGA_XE = XE_VER(1, 0), // TGL
100 IGA_XE_HP = XE_VER(1, 1),
101 IGA_XE_HPG = XE_VER(1, 2),
102 IGA_XE_HPC = XE_VER(1, 4)
103 ,
104 IGA_XE2 = XE_VER(2, 0)
105 ,
106 IGA_XE3 = XE_VER(3, 0)
107 , IGA_XE3P_XPC = XE_VER(3, 3)
108
109 // DEPRECATED
110 // Preserve the old values to maintain the binary compatibility
111 // The value should not be used anymore
112 ,
113 IGA_GEN12p1 = GEN_VER(12, 1) // IGA_XE
114 } iga_gen_t;
115
116 /*****************************************************************************/
117 /* Platform Query Functions */
118 /*****************************************************************************/
119
120 /*
121 * Returns a list of the platforms enumeration values supported by this
122 * implementation of IGA into a user-provided buffer. The buffer parameter
123 * maybe omitted.
124 *
125 * PARAMETERS:
126 * gens_length_bytes the length of the gens buffer in bytes;
127 * can be 0 if gens is NULL
128 * gens the user-provided buffer (can be NULL);
129 * if non-NULL, the output will contain the list
130 * of iga_gen_t platforms that this IGA supports
131 * gens_length_bytes_required the required length
132 *
133 * RETURNS:
134 * IGA_INVALID_ARGUMENT if gens_length_bytes != 0 && gens == nullptr
135 * IGA_SUCCESS otherwise
136 */
137 IGA_API iga_status_t iga_platforms_list(size_t gens_length_bytes,
138 iga_gen_t *gens,
139 size_t *gens_length_bytes_required);
140
141 /*
142 * Returns the platform suffix name of a given platform.
143 *
144 * PARAMETERS:
145 * gen the platform to query
146 * suffix an output parameter assigned the result;
147 * NULL is assigned if the 'gen' passed in is invalid
148 * or unsupported
149 *
150 * RETURNS:
151 * IGA_INVALID_ARGUMENT if symbol is NULL or 'gen' is invalid or not
152 * supported by this platform
153 * IGA_SUCCESS otherwise
154 */
155 IGA_API iga_status_t iga_platform_symbol_suffix(iga_gen_t gen,
156 const char **suffix);
157
158 /*
159 * Returns the names for a given platform. E.g. IGA_GEN9 returns "skl".
160 *
161 * PARAMETERS:
162 * gen the platform to query
163 * names_bytes the length in bytes of the names array passed in
164 * 0 iff 'names' is nullptr
165 * names the array to return the platform names in
166 * names_bytes_needed the required length of 'names' in bytes
167 *
168 * RETURNS:
169 * IGA_INVALID_ARGUMENT if gen is an invalid platform
170 * supported by this platform
171 * IGA_INVALID_ARGUMENT if names_bytes != 0 && names == nullptr
172 * IGA_SUCCESS otherwise
173 */
174 IGA_API iga_status_t iga_platform_names(iga_gen_t gen, size_t names_bytes,
175 const char **names,
176 size_t *names_bytes_needed);
177
178 /*****************************************************************************/
179 /* Context Creation Functions */
180 /*****************************************************************************/
181
182 /*
183 * Context creation options
184 */
185 typedef struct {
186 size_t cb; /* set to sizeof(iga_context_options_t) */
187 iga_gen_t gen;
188 } iga_context_options_t;
189
190 /*
191 * This macro initializes options to the context.
192 * iga_gen_t P the gen platform to use
193 */
194 #define IGA_CONTEXT_OPTIONS_INIT(P) \
195 { sizeof(iga_context_options_t), (P) }
196
197 /*
198 * Creates a context, which is needed to assemble and disassemble kernels.
199 * A context manages internal dynamically allocated memory containing
200 * the diagnostics.
201 *
202 * PARAMETERS:
203 * opts the options to this iga context
204 * ctx points to the newly created context
205 *
206 * RETURNS:
207 * IGA_SUCCESS upon successful context creation
208 * IGA_INVALID_ARG if an argument is NULL
209 * IGA_INVALID_OBJECT if ctx has already been destroyed
210 * IGA_OUT_OF_MEM upon internal allocation failure
211 * IGA_INVALID_PLATFORM if the platform passed is unsupported
212 */
213 IGA_API iga_status_t iga_context_create(const iga_context_options_t *opts,
214 iga_context_t *ctx);
215 /* deprecated: covers to iga_context_create */
216 IGA_API iga_status_t iga_create_context(const iga_context_options_t *opts,
217 iga_context_t *ctx);
218
219 /*
220 * Releases a context previously created via 'iga_context_create'.
221 *
222 * RETURNS:
223 * IGA_SUCCESS upon successful context release
224 * IGA_INVALID_ARG if an argument is NULL
225 * IGA_INVALID_OBJECT if ctx has already been destroyed
226 */
227 IGA_API iga_status_t iga_context_release(iga_context_t ctx);
228 /* deprecated: covers to iga_context_release */
229 IGA_API iga_status_t iga_release_context(iga_context_t ctx);
230
231 /*****************************************************************************/
232 /* Assembly Functions */
233 /*****************************************************************************/
234
235 /*
236 * This structure contains options to the 'iga_assemble' call.
237 */
238 typedef struct {
239 uint32_t cb; /* sizeof(iga_context_options_t) */
240 uint32_t enabled_warnings; /* bitset of IGA_WARNINGS* */
241 uint32_t encoder_opts; /* bitset of IGA_ENCODER_OPT* */
242 uint32_t syntax_opts; /* bitset of IGA_SYNTAX_OPT* */
243 /* the following must be 0 or a warning is raised */
244 uint32_t _reserved0; /* use IGA_ENCODER_OPT_ERRONCOMPACT */
245 uint32_t _reserved1; /* use IGA_ENCODER_OPT_AUTODEP */
246 /*
247 * ... future fields (ensure total size is a multiple of 8;
248 * add "reserved" if needed) ...
249 * do not reuse _reserved0 and _reserved1 since those were
250 * historically something else
251 */
252
253 /* number of sbid used for auto dependency setting. This value is effective
254 * only when IGA_ENCODER_OPT_AUTO_DEPENDENCIES is given */
255 uint32_t sbid_count;
256
257 /*
258 * Force the swsb_encode_mode. If not given (SWSBInvalidMode),
259 * then encode mode will be derived from platform.
260 */
261 uint32_t swsb_encode_mode; /* use iga::SWSB_ENCODE_MODE */
262 } iga_assemble_options_t;
263
264 /* detects screwups where someone adds a field and the compiler pads
265 * the structure out implicitly */
266 static_assert(sizeof(iga_assemble_options_t) == 8 * 4,
267 "wrong size for iga_assemble_options");
268
269 /*
270 * encoding options
271 */
272 /*
273 * Automatically compact instructions without explicit compaction annotations.
274 * E.g. with this enabled:
275 * op (...) ... {Compacted} // will compact
276 * op (...) ... { } // try and compact iff IGA_ENCOPTS_AUTOCOMPACT
277 * op (...) ... {Uncompacted} // will not attempt to compact
278 */
279 #define IGA_ENCODER_OPT_AUTO_COMPACT 0x00000001u
280 /* auto set instruction dependencies */
281 #define IGA_ENCODER_OPT_AUTO_DEPENDENCIES 0x00000002u
282 /* treat failure to compact an instruction with a {Compacted} annotation
283 * as a hard error rather than just raising a warning */
284 #define IGA_ENCODER_OPT_ERROR_ON_COMPACT_FAIL 0x00000004u
285 /* enable experimental native encoder */
286 #define IGA_ENCODER_OPT_USE_NATIVE 0x00000008u
287 /* forcely NoCompact to all instructions even if {Compacted} is set on the
288 instruction This option will overried IGA_ENCODER_OPT_AUTO_COMPACT */
289 #define IGA_ENCODER_OPT_FORCE_NO_COMPACT 0x00000010u
290 /* auto set instruction dependencies with sbid counter. This option takes
291 effect only when IGA_ENCODER_OPT_AUTO_DEPENDENCIES is set */
292 #define IGA_ENCODER_OPT_AUTO_SBID_COUNTER 0x00000020u
293 /*
294 * options for the parsing phase
295 */
296 /* nominal support for certain IsaAsm directives and syntax */
297 #define IGA_SYNTAX_OPT_LEGACY_SYNTAX 0x00000001u
298 /* enables syntax extensions */
299 #define IGA_SYNTAX_OPT_EXTENSIONS 0x00000002u
300
301 /*
302 * extra assemble warnings (things to check)
303 * (for iga_assemble_options_t::enabled_warnings)
304 */
305 /* individual warnings */
306 #define IGA_WARNINGS_REGIONS 0x00000001u /* -Wregions */
307 #define IGA_WARNINGS_TYPES 0x00000002u /* -Wtypes */
308 #define IGA_WARNINGS_SCHED 0x00000004u /* -Wscheduling */
309 #define IGA_WARNINGS_NORMFORM 0x00000008u /* -Wnormal-form */
310 /* useful predefined sets */
311 #define IGA_WARNINGS_NONE 0x00000000u /* -Wnone */
312 #define IGA_WARNINGS_ALL \
313 (IGA_WARNINGS_REGIONS | IGA_WARNINGS_TYPES | IGA_WARNINGS_SCHED | \
314 IGA_WARNINGS_NORMFORM) /* -Wall */
315 #define IGA_WARNINGS_DEFAULT \
316 (IGA_WARNINGS_REGIONS | IGA_WARNINGS_SCHED) /* -Wdefault */
317
318 /* helpful initializers for assembly options with good defaults */
319 #define IGA_ASSEMBLE_OPTIONS_INIT() \
320 { \
321 sizeof(iga_assemble_options_t), IGA_WARNINGS_DEFAULT, \
322 (IGA_ENCODER_OPT_ERROR_ON_COMPACT_FAIL), 0, /* syntax_opts = NONE */ \
323 0, /* reserved */ \
324 0, /* reserved */ \
325 16, /* sbid_count */ \
326 0, /* SWSBInvalidMode */ \
327 }
328
329 /*
330 * Assembles some text into bits.
331 *
332 * PARAMETERS:
333 * ctx the iga context
334 * opts the assemble options
335 * kernel_text a NUL-terminated string containing the kernel text
336 * to assemble
337 * output the output assembly binary; upon failure, this is
338 * assigned NULL; this memory should not be modified
339 * or deallocated externally
340 * output_size the length of 'output' (in bytes); assigned 0 upon failure
341 *
342 * RETURNS:
343 * IGA_SUCCESS upon successful assembly; 'iga_get_warnings' may
344 * contain warning diagnostics even upon success
345 * IGA_INVALID_ARG if an argument is NULL
346 * IGA_INVALID_OBJECT if ctx has already been destroyed
347 * IGA_PARSE_ERROR if the text is somehow malformed and IGA is unable
348 * to parse it; use iga_get_errors for more info
349 * IGA_ENCODE_ERROR if the encoder encounters some error
350 * (use iga_get_errors for more info)
351 * IGA_ERROR upon some other error
352 */
353 IGA_API iga_status_t iga_context_assemble(iga_context_t ctx,
354 const iga_assemble_options_t *opts,
355 const char *kernel_text,
356 void **output, uint32_t *output_size);
357 /* deprecated API covers to iga_contex* */
358 IGA_API iga_status_t iga_assemble(iga_context_t ctx,
359 const iga_assemble_options_t *opts,
360 const char *kernel_text, void **output,
361 uint32_t *output_size);
362
363 /*****************************************************************************/
364 /* Disassembly Functions */
365 /*****************************************************************************/
366
367 /*
368 * This structure contains options to the 'iga_disassemble' call.
369 */
370 typedef struct {
371 uint32_t cb; /* set to sizeof(iga_context_options_t) */
372 uint32_t formatting_opts; /* options in formatting the syntax */
373 uint32_t _reserved0; /* use formatting_opts; set this to 0! */
374 uint32_t _reserved1; /* use formatting_opts; set this to 0! */
375 uint32_t decoder_opts; /* opts for the decoding phase */
376 uint32_t base_pc_offset; /* base pc offset to add to pc in disassembly string
377 output*/
378 /* ... future fields (ensure total size is a multiple of 8;
379 * add "reserved" if needed) ... */
380 } iga_disassemble_options_t;
381
382 static_assert(sizeof(iga_disassemble_options_t) == 6 * 4,
383 "wrong size for iga_disassemble_options_t");
384
385 /* A default value for iga_disassemble_options_t */
386 #define IGA_DISASSEMBLE_OPTIONS_INIT() \
387 { \
388 sizeof(iga_disassemble_options_t), IGA_FORMATTING_OPTS_DEFAULT, \
389 0, /* _reserved0 */ \
390 0, /* _reserved1 */ \
391 IGA_DECODING_OPTS_DEFAULT, /* decoder_opts */ \
392 }
393
394 /* A default value for iga_disassemble_options_t that enables numeric labels */
395 #define IGA_DISASSEMBLE_OPTIONS_INIT_NUMERIC_LABELS() \
396 { \
397 sizeof(iga_disassemble_options_t), \
398 IGA_FORMATTING_OPTS_DEFAULT | IGA_FORMATTING_OPT_NUMERIC_LABELS, \
399 0, /* _reserved0 */ \
400 0, /* _reserved1 */ \
401 IGA_DECODING_OPTS_DEFAULT, /* decoder_opts */ \
402 }
403
404 /*
405 * options for the formatting phase (the syntax emitted / printed)
406 */
407 /* does not use numeric labels */
408 #define IGA_FORMATTING_OPT_NUMERIC_LABELS 0x00000001u
409 /* enables certain syntax extensions */
410 #define IGA_FORMATTING_OPT_SYNTAX_EXTS 0x00000002u
411 /* force floats to be emitted in hexadecimal */
412 #define IGA_FORMATTING_OPT_PRINT_HEX_FLOATS 0x00000004u
413 /* print the instruction PC's */
414 #define IGA_FORMATTING_OPT_PRINT_PC 0x00000008u
415 /* print the instruction bits */
416 #define IGA_FORMATTING_OPT_PRINT_BITS 0x00000010u
417 /* print immediate instruction dependencies (mostly for IGA debugging) */
418 #define IGA_FORMATTING_OPT_PRINT_DEPS 0x00000020u
419 /* print load/store pseduo instructions where possible */
420 #define IGA_FORMATTING_OPT_PRINT_LDST 0x00000040u
421 /* print bfn symbolic instructions */
422 #define IGA_FORMATTING_OPT_PRINT_BFNEXPRS 0x00000080u
423 /* use ansi_span escapes when possible */
424 #define IGA_FORMATTING_OPT_PRINT_ANSI 0x00000100u
425 /* emit JSON instead of asm */
426 #define IGA_FORMATTING_OPT_PRINT_JSON 0x00000200u
427 /* emit instruction definitions from a simple dataflow analysis */
428 #define IGA_FORMATTING_OPT_PRINT_DEFS 0x00000400u
429 /* emit JSON old V1 version */
430 #define IGA_FORMATTING_OPT_PRINT_JSON_V1 0x00000800u
431
432 /* just the default formatting opts */
433 #define IGA_FORMATTING_OPTS_DEFAULT (0u)
434 /* a union of all formatter opts */
435 #define IGA_FORMATTING_OPTS_ALL \
436 = (IGA_FORMATTING_OPT_NUMERIC_LABELS | IGA_FORMATTING_OPT_SYNTAX_EXTS | \
437 IGA_FORMATTING_OPT_PRINT_HEX_FLOATS | IGA_FORMATTING_OPT_PRINT_PC | \
438 IGA_FORMATTING_OPT_PRINT_BITS | IGA_FORMATTING_OPT_PRINT_DEPS | \
439 IGA_FORMATTING_OPT_PRINT_DEFS)
440
441 /* uses the native decoder for decoding the kernel */
442 #define IGA_DECODING_OPT_NATIVE 0x00000001u
443 /* just the default decoding opts */
444 #define IGA_DECODING_OPTS_DEFAULT (0u)
445
446
447 /*
448 * Disassembles kernel bits into a string.
449 *
450 * PARAMETERS:
451 * ctx an iga context
452 * dopts the disassemble options
453 * input the instructions to disassemble
454 * input_size the size of the 'input' in bytes
455 * fmt_label_name optional callback to resolve a PC to specific label
456 * - if the callback is NULL or the callback returns NULL,
457 * then IGA generates the label names
458 * - for instructions with multiple labels the caller
459 * may reuse any buffers for each label
460 * *** PCs are relative to the start of the disassembly ***
461 * *** for this API ***
462 * fmt_label_ctx A callback context (environment) forwarded to 'fmt_label'
463 * E.g. a buffer to construct the label with
464 * kernel_text a pointer containing the NUL-terminate disassembly text;
465 * this memory is internally allocated and should not be freed
466 * by the user; moreover, it may be invalidated upon the next
467 * call using this context (freed or even reused); upon a
468 * decoding error this may contain the partially decoded
469 * kernel or the empty string if something catestrophic
470 * happened, but the pointer returned will always be valid
471 * (until the subsequent call)
472 *
473 * RETURNS:
474 * IGA_SUCCESS upon successful disassembly; 'iga_get_warnings' may
475 * contain warning diagnostics even upon success
476 * IGA_INVALID_ARG if an argument is NULL; 'input' may be NULL only
477 * if 'input_size' is also 0
478 * IGA_INVALID_OBJECT if ctx has already been destroyed
479 * IGA_DECODE_ERROR upon failure to decode error; specific error messages
480 * may be retrieved via 'iga_context_get_errors'
481 */
482 IGA_API iga_status_t iga_context_disassemble(
483 iga_context_t ctx, const iga_disassemble_options_t *opts, const void *input,
484 uint32_t input_size, const char *(*fmt_label_name)(int32_t, void *),
485 void *fmt_label_ctx, char **kernel_text);
486 /* deprecated API covers to iga_context_* */
487 IGA_API iga_status_t iga_disassemble(
488 iga_context_t ctx, const iga_disassemble_options_t *opts, const void *input,
489 uint32_t input_size, const char *(*fmt_label_name)(int32_t, void *),
490 void *fmt_label_ctx, char **kernel_text);
491
492 /*
493 * Disassembles a single instruction.
494 *
495 * ctx an iga context
496 * dopts the disassemble options
497 * input the instructions to disassemble; the first 8-16 bytes
498 * must be readable (16 if compaction control is set)
499 * fmt_label_name optional callback to resolve a PC to specific label
500 * - if the callback is NULL or the callback returns NULL,
501 * then IGA generates the label names
502 * - for instructions with multiple labels the caller
503 * may reuse any buffers for each label
504 * *** PCs are relative to the start of this instruction ***
505 * *** for this API ***
506 * fmt_label_ctx A callback context (environment) forwarded to 'fmt_label'
507 * E.g. a buffer to construct the label with
508 * kernel_text a pointer containing the NUL-terminate disassembly text;
509 * this memory is internally allocated and should not be freed
510 * by the user; moreover, it may be invalidated upon the next
511 * call using this context (freed or even reused); upon a
512 * decoding error this may contain the partially decoded
513 * kernel or the empty string if something catestrophic
514 * happened, but the pointer returned will always be valid
515 * (until the subsequent call)
516 *
517 * RETURNS:
518 * IGA_SUCCESS upon successful disassembly; 'iga_get_warnings' may
519 * contain warning diagnostics even upon success
520 * IGA_INVALID_ARG if an argument is NULL
521 * IGA_INVALID_OBJECT if ctx has already been destroyed
522 * IGA_DECODE_ERROR upon failure to decode error; specific error messages
523 * may be retrieved via 'iga_context_get_errors'
524 */
525 IGA_API iga_status_t iga_context_disassemble_instruction(
526 iga_context_t ctx, const iga_disassemble_options_t *dopts,
527 const void *input, const char *(*fmt_label_name)(int32_t, void *),
528 void *fmt_label_ctx, char **kernel_text);
529 /* deprecated API covers to iga_contex* */
530 IGA_API iga_status_t iga_disassemble_instruction(
531 iga_context_t ctx, const iga_disassemble_options_t *dopts,
532 const void *input, const char *(*fmt_label_name)(int32_t, void *),
533 void *fmt_label_ctx, char **kernel_text);
534
535 /*****************************************************************************/
536 /* Diagnostic Processing Functions */
537 /*****************************************************************************/
538
539 /*
540 * A diagnostic message (e.g. error or warning)
541 *
542 * WARNING: This structure may be made opaque in future releases.
543 * Treat it as an opaque type and use the accessors to minimize
544 * any conversion time down the road.
545 */
546 typedef struct {
547 /* lines start at 1; 0 means no location information */
548 uint32_t line;
549 /* columns start at 1; 0 means no location information */
550 uint32_t column;
551 /* the input offset */
552 uint32_t offset;
553 /* the length of the diagnostic (in characters) */
554 uint32_t extent;
555 /* the diagnostic message (NUL terminated) */
556 const char *message;
557 } iga_diagnostic_t;
558
559 /*
560 * Gets the errors from previous 'iga_context_assemble' or
561 * 'iga_context_disassmble'. It is an error to call this before one of these
562 * functions have been called. Further invocations of this function return
563 * the same values until one of the above functions is called again. Memory
564 * returned by this function should not be modified externally. Moreover, it
565 * should not be accessed after the next call to 'iga_context_assemble' or
566 * 'iga_context_disassmble' or the call to 'iga_context_release'.
567 *
568 * PARAMETERS:
569 * ctx the iga context used in the call to 'iga_context_assemble'
570 * or 'iga_context_disassmble'
571 * ds assigned to an internally allocated array of diagnostic
572 * messages (the caller should *not* mutate or free this memory)
573 * ds_len assigned the length of 'ds' upon success
574 *
575 * RETURNS:
576 * IGA_SUCCESS upon getting the list of errors; note if the last call
577 * contained no errors, this still returns IGA_SUCCESS;
578 * 'ds' is assigned a NULL pointer and 'ds_len' is assigned 0.
579 * IGA_INVALID_ARG if an argument is NULL
580 * IGA_INVALID_OBJECT if ctx has already been destroyed
581 * IGA_ERROR if 'iga_assemble' or 'iga_disassmble' never called,
582 * internal allocation fails, or the context is invalid
583 * (after call to 'iga_context_release').
584 */
585 IGA_API iga_status_t iga_context_get_errors(iga_context_t ctx,
586 const iga_diagnostic_t **ds,
587 uint32_t *ds_len);
588 IGA_API iga_status_t iga_get_errors(iga_context_t ctx,
589 const iga_diagnostic_t **ds,
590 uint32_t *ds_len);
591
592 /*
593 * Symmetric to 'iga_context_get_errors'. Various API calls can still succeed
594 * even if there are warnings; hence, robust tools should always check this
595 * as well.
596 */
597 IGA_API iga_status_t iga_context_get_warnings(iga_context_t ctx,
598 const iga_diagnostic_t **ds,
599 uint32_t *ds_len);
600 IGA_API iga_status_t iga_get_warnings(iga_context_t ctx,
601 const iga_diagnostic_t **ds,
602 uint32_t *ds_len);
603
604 /*
605 * Fetches a diagnostic's message. The internal memory containing the message
606 * should be copied out before further disassemble or assembly or context
607 * destruction. This diagnostic field is valid for both binary and text.
608 *
609 * RETURNS:
610 * IGA_SUCCESS upon success
611 * IGA_INVALID_ARG if an argument is NULL
612 */
613 IGA_API iga_status_t iga_diagnostic_get_message(const iga_diagnostic_t *d,
614 const char **message);
615
616 /*
617 * Returns the starting file offset for the diagnostic in bytes (zero based).
618 * This diagnostic field is valid for both binary and text.
619 *
620 * RETURNS:
621 * IGA_SUCCESS upon success
622 * IGA_INVALID_ARG if an argument is NULL or the diagnostic is a binary
623 * location
624 */
625 IGA_API iga_status_t iga_diagnostic_get_offset(const iga_diagnostic_t *d,
626 uint32_t *offset);
627
628 /*
629 * Diagnostics can refer to locations in binary files or text files.
630 * The following enumeration indicates which.
631 */
632 typedef enum {
633 /* the location refers to a text location */
634 IGA_DIAGNOSTIC_TEXT,
635 /* the location refers to a binary location */
636 IGA_DIAGNOSTIC_BINARY,
637 } iga_diagnostic_type_t;
638
639 /*
640 * Fetches the type of diagnostic (binary or text).
641 * For IGA_DIAGNOSTIC_TEXT iga_diagnostic_text_get_* should be used to access
642 * further information.
643 * For IGA_DIAGNOSTIC_BINARY 'iga_diagnostic_get_offset* should be used
644 * access more the binary offset
645 *
646 * RETURNS:
647 * IGA_SUCCESS upon success
648 * IGA_INVALID_ARG if an argument is NULL or the diagnostic is a binary
649 * location
650 */
651 IGA_API iga_status_t iga_diagnostic_get_type(const iga_diagnostic_t *d,
652 iga_diagnostic_type_t *dt);
653
654 /*
655 * Fetches a diagnostic's line number (must be IGA_DIAGNOSTIC_TEXT).
656 * Lines numbers are counted from 1.
657 *
658 * RETURNS:
659 * IGA_SUCCESS upon success
660 * IGA_INVALID_ARG if an argument is NULL or the diagnostic is a binary
661 * location
662 */
663 IGA_API iga_status_t iga_diagnostic_get_text_line(const iga_diagnostic_t *d,
664 uint32_t *line);
665
666 /*
667 * Similar to 'iga_diagnostic_text_get_line', but returns the column.
668 * Columns are counted from 1.
669 */
670 IGA_API iga_status_t iga_diagnostic_get_text_column(const iga_diagnostic_t *d,
671 uint32_t *col);
672
673 /*
674 * Fetches a binary diagnostic's byte offset (must be IGA_DIAGNOSTIC_TEXT).
675 * The extent is the length of the region of source code.
676 *
677 * RETURNS:
678 * IGA_SUCCESS upon success
679 * IGA_INVALID_ARG if an argument is NULL or the diagnostic is a binary
680 * location
681 */
682 IGA_API iga_status_t iga_diagnostic_get_text_extent(const iga_diagnostic_t *d,
683 uint32_t *extent);
684
685 /*****************************************************************************/
686 /* Operation Enumeration Functions */
687 /*****************************************************************************/
688 /*
689 * An opaque type representing an operation (instruction) type.
690 * Can be efficiently copied and passed by value.
691 */
692 typedef const struct opspec *iga_opspec_t;
693
694 /*
695 * Enumerates the opcodes for a given platform.
696 * 'gen' : gen plaform to enumerate operations on
697 * 'ops_arr' : a pointer (can be nul) to an array to hold
698 * all opcode spec.
699 * 'ops_arr_len' : the required length for 'ops_arr'
700 * This API is the usual two-shot pattern, in which the caller invokes it
701 * first time to get the length, the caller allocates enough space to hold
702 * info based on the returned length, then the caller invokes it again.
703 *
704 * This function always returns the required length of the array
705 * from argument 'ops_arr_len'.
706 *
707 * For example,
708 * size_t len;
709 * iga_opspec_enumerate(gen, nullptr, &len);
710 * iga_opspec_t *ops_arr =
711 * (iga_opspec_t*)malloc(sizeof(iga_opspec_t) * len);
712 * iga_opspec_enumerate(gen, ops_arr, &len);
713 *
714 * RETURNS:
715 * IGA_SUCCESS upon success
716 * IGA_INVALID_ARG if a gen argument invalid or ops_arr_len is null
717 */
718 IGA_API iga_status_t iga_opspec_enumerate(iga_gen_t gen, iga_opspec_t *ops_arr,
719 size_t *ops_arr_len);
720
721 /*
722 * Looks up an opspec based on an iga::Op value.
723 * 'gen' gen plaform
724 * 'op' the operation value to lookup; this is an iga::Op;
725 * an invalid op will succeed but return Op::INVALID
726 * 'os' the output value
727 *
728 * RETURNS:
729 * IGA_SUCCESS upon success
730 * IGA_INVALID_ARG if an argument is invalid
731 * (invalid GEN or op or null os)
732 */
733 IGA_API iga_status_t iga_opspec_from_op(iga_gen_t gen,
734 /* iga::Op */ uint32_t op_enum,
735 iga_opspec_t *os);
736
737 /*
738 * Lists the mnemonic name for a given op (e.g. "sends")
739 * (has similar semantics regarding the parameters as 'iga_opspec_enum')
740 *
741 * RETURNS:
742 * IGA_SUCCESS upon success
743 * IGA_INVALID_ARG if given an invalid argument
744 */
745 IGA_API iga_status_t iga_opspec_mnemonic(const iga_opspec_t op, char *mnemonic,
746 size_t *mnemonic_len);
747
748 /*
749 * Lists the op name for a given op (e.g. "Split Send Message")
750 * (has similar semantics regarding the parameters as 'iga_opspec_enum')
751 *
752 * RETURNS:
753 * IGA_SUCCESS upon success
754 * IGA_INVALID_ARG if a gen argument invalid
755 */
756 IGA_API iga_status_t iga_opspec_name(const iga_opspec_t op, char *name,
757 size_t *name_len);
758
759 /*
760 * Lists the op desription for a given op
761 * (has similar semantics regarding the parameters as 'iga_opspec_enum')
762 *
763 * RETURNS:
764 * IGA_SUCCESS upon success
765 * IGA_INVALID_ARG if a gen argument invalid
766 */
767 IGA_API iga_status_t iga_opspec_description(iga_opspec_t op, char *desc,
768 size_t *desc_len);
769
770 /*
771 * Returns iga::Op for this operation as a uint32_t
772 *
773 * RETURNS:
774 * IGA_SUCCESS upon success
775 * IGA_INVALID_ARG if an argument is NULL
776 */
777 IGA_API iga_status_t iga_opspec_op(iga_opspec_t os, uint32_t *op);
778
779 /*
780 * Returns iga::Op value opcode encoding. This can vary for the same op
781 * on platform to platform.
782 *
783 * RETURNS:
784 * IGA_SUCCESS upon success
785 * IGA_INVALID_ARG if an argument is NULL
786 */
787 IGA_API iga_status_t iga_opspec_op_encoding(iga_opspec_t op, uint32_t *opcode);
788
789 #ifdef __cplusplus
790 }
791 #endif
792
793 #endif