| 1 |
/*========================== begin_copyright_notice ============================ |
| 2 |
|
| 3 |
Copyright (C) 2018-2022 Intel Corporation |
| 4 |
|
| 5 |
SPDX-License-Identifier: MIT |
| 6 |
|
| 7 |
============================= end_copyright_notice ===========================*/ |
| 8 |
|
| 9 |
#ifndef IGA_KV_H |
| 10 |
#define IGA_KV_H |
| 11 |
|
| 12 |
#include "iga.h" |
| 13 |
#ifdef __cplusplus |
| 14 |
#include "iga_types_swsb.hpp" |
| 15 |
#endif |
| 16 |
|
| 17 |
/************************************************************************* |
| 18 |
* * |
| 19 |
* The KernelView C interface * |
| 20 |
* * |
| 21 |
* Consider the kv.hpp wrapper which provides a slightly friendlier * |
| 22 |
* interface to all these functions with simplified resource management. * |
| 23 |
*************************************************************************/ |
| 24 |
|
| 25 |
#ifdef __cplusplus |
| 26 |
extern "C" { |
| 27 |
#endif |
| 28 |
|
| 29 |
/* |
| 30 |
* This symbols defines the maximum number of PC targets that an instruction |
| 31 |
* may have. It is typically used to statically allocate an array of target |
| 32 |
* PCs with the kv_get_inst_targets function. |
| 33 |
* E.g. |
| 34 |
* uint32_t targetPCs[KV_MAX_TARGETS_PER_INSTRUCTION]; |
| 35 |
* uint32_t num = kv_get_inst_targets(kv, atPc, &targets[0]); |
| 36 |
* for (int i = 0; i < num; i++) { |
| 37 |
* processTarget(targetPCs[i]); |
| 38 |
* } |
| 39 |
*/ |
| 40 |
#define KV_MAX_TARGETS_PER_INSTRUCTION 3 |
| 41 |
/* |
| 42 |
* This symbol represents an invalid PC. 0 is a valid PC (the beginnning |
| 43 |
* of the kernel). |
| 44 |
*/ |
| 45 |
#define KV_INVALID_PC_VALUE ((int32_t)0xFFFFFFFF) |
| 46 |
|
| 47 |
/* |
| 48 |
* Incomplete type for a kernel view handle. |
| 49 |
*/ |
| 50 |
struct kv_t; |
| 51 |
|
| 52 |
/* Kernel Viewer API Statuses */ |
| 53 |
typedef enum { |
| 54 |
KV_SUCCESS = 0, |
| 55 |
KV_ERROR = 1, /* general error (unlisted below) */ |
| 56 |
KV_DECODE_ERROR = 2, /* |
| 57 |
* error during initial decode of the kernel |
| 58 |
* always check KernelView::decodeSucceeded. |
| 59 |
*/ |
| 60 |
KV_INVALID_PC = 3, /* invalid instruction PC */ |
| 61 |
|
| 62 |
KV_INVALID_ARGUMENT = 10, /* an invalid argument passed in (e.g. nullptr) */ |
| 63 |
|
| 64 |
KV_NON_SEND_INSTRUCTION = 20, /* underlying inst isn't a send */ |
| 65 |
KV_DESCRIPTOR_INDIRECT = 21, /* a send message with a reg desc */ |
| 66 |
KV_DESCRIPTOR_INVALID = 22, /* an unrecognized send descriptor */ |
| 67 |
KV_NO_SUBFUNCTION = 23, /* underlying inst has no sub-function */ |
| 68 |
|
| 69 |
KV_INCAPABLE_PLATFORM = 30 /* invalid API for the given platform */ |
| 70 |
} kv_status_t; |
| 71 |
|
| 72 |
/* |
| 73 |
* Creates a kernel view instance. This decodes a kernel binary and allocates |
| 74 |
* internal state to represent with an intermediate representation. |
| 75 |
* Various functions (see below) can be called on this object to inspect the |
| 76 |
* kernel and its instructions. The user is responsible for calling kv_delete |
| 77 |
* to delete the object after they are done with it. |
| 78 |
* 'plat' - the platform |
| 79 |
* 'bytes' - the kernel binary |
| 80 |
* 'bytes_len' - the length of 'bytes' |
| 81 |
* 'status' - the IGA status code |
| 82 |
* 'errbuf' - an optional buffer to emit errors or warnings (can pass nullptr) |
| 83 |
* 'errbuf_cap' - the capacity of errbuf. |
| 84 |
* RETURNS: a kernel view object for use in other kv_* functions. |
| 85 |
* Deallocate it with kv_delete. If there is a decode error (or other errors), |
| 86 |
* this function returns an instance of Kernel Views and error status. |
| 87 |
* If user proceeds to use the returned Kernel View under error the behavior |
| 88 |
* of various APIs may be undefined. |
| 89 |
*/ |
| 90 |
IGA_API struct kv_t *kv_create(iga_gen_t plat, const void *bytes, size_t bytes_len, |
| 91 |
iga_status_t *status, char *errbuf, size_t errbuf_cap, |
| 92 |
uint32_t swsb_enc_mode /* iga::SWSB_ENCODE_MODE */ |
| 93 |
); |
| 94 |
|
| 95 |
/* |
| 96 |
* Destroys a kernel view deallocating all resources sequestered by the kv_t |
| 97 |
* object. |
| 98 |
*/ |
| 99 |
IGA_API void kv_delete(struct kv_t *); |
| 100 |
|
| 101 |
/* |
| 102 |
* Returns the size of the instruction at 'pc'; returns 0 if the program |
| 103 |
* address is out of bounds. This allows one to iterate a kernel using this |
| 104 |
* API. For example: |
| 105 |
* |
| 106 |
* uint32_t iLen; |
| 107 |
* for (uint32_t pc = 0; |
| 108 |
* (iLen = kv_get_inst_size(kv, pc)) != 0; |
| 109 |
* pc += iLen) |
| 110 |
* { |
| 111 |
* ... process instruction |
| 112 |
* } |
| 113 |
*/ |
| 114 |
IGA_API int32_t kv_get_inst_size(const struct kv_t *kv, int32_t pc); |
| 115 |
|
| 116 |
/* |
| 117 |
* Returns some attributes of a message: if it is atomic, slm, scratch |
| 118 |
* operation. |
| 119 |
* Returns: |
| 120 |
* KV_SUCCESS on success; output is stored to isAtomic and isSlm |
| 121 |
* KV_ERROR if kv is invalid |
| 122 |
* KV_INVALID_PC if instruction cannot be found |
| 123 |
* KV_DECODE_ERROR if an instruction cannot be docoded |
| 124 |
*/ |
| 125 |
IGA_API kv_status_t kv_get_inst_msg_info(const kv_t* kv, int32_t pc, |
| 126 |
bool* isAtomic, bool* isSlm, bool* isScratch); |
| 127 |
|
| 128 |
/* |
| 129 |
* Returns true if the instruction has the opt |
| 130 |
*/ |
| 131 |
IGA_API bool kv_has_inst_opt(const struct kv_t *kv, int32_t pc, uint32_t opt); |
| 132 |
|
| 133 |
/* |
| 134 |
* This function returns the absolute PC targets of this instruction. |
| 135 |
* For branching instructions, it populates 'pcs' with the jump targets |
| 136 |
* of this instruction. The number of PC's will always be less than or |
| 137 |
* equal to MAX_KV_TARGETS_COUNT. The function returns the number of |
| 138 |
* target PCs populated in the 'pcs' argument. |
| 139 |
* |
| 140 |
* For non-branching instructions this returns 0 and does not touch 'pcs'. |
| 141 |
* |
| 142 |
* If 'pcs' is NULL, it is ignored. The number of targets is still returned. |
| 143 |
*/ |
| 144 |
IGA_API uint32_t kv_get_inst_targets(const struct kv_t *kv, int32_t pc, int32_t *pcs); |
| 145 |
|
| 146 |
/* |
| 147 |
* This function returns the syntax for a given instruction. |
| 148 |
* The user passes the buffer 'sbuf' (along with its capacity) to hold |
| 149 |
* the output. The output may be truncated if the passed buffer is too |
| 150 |
* small, but it will always be suffixed with a NUL byte. |
| 151 |
* |
| 152 |
* The formatting options 'fmt_opts' are the same as those in |
| 153 |
* iga_disassemble_options_t::formatting_opts. |
| 154 |
* |
| 155 |
* The optional 'get_label_name' callback may be called to converts |
| 156 |
* a PC into a label. The caller can provide NULL and internal label names |
| 157 |
* will be used. The 'env' context parameter is passed to 'get_label_name'. |
| 158 |
* Memory returned by the callback is only read by IGA. |
| 159 |
* |
| 160 |
* This function returns the number of characters written to sbuf |
| 161 |
* (including NUL byte). If the PC is out of bounds or 'kv' NULL or |
| 162 |
* something else is wrong, then 0 is returned. |
| 163 |
*/ |
| 164 |
IGA_API size_t kv_get_inst_syntax( |
| 165 |
const struct kv_t *kv, int32_t pc, char *sbuf, size_t sbuf_cap, uint32_t fmt_opts, |
| 166 |
const char *(*get_label_name)(int32_t, void *), void *env); |
| 167 |
|
| 168 |
/* |
| 169 |
* This function returns the default label name if custom labeler is not used. |
| 170 |
*/ |
| 171 |
IGA_API size_t kv_get_default_label_name(int32_t pc, char *sbuf, |
| 172 |
size_t sbuf_cap); |
| 173 |
|
| 174 |
/* |
| 175 |
* Returns non-zero iff this instruction is a branch target. |
| 176 |
* The caller can use this function to determine if it should emit a label |
| 177 |
* first. |
| 178 |
*/ |
| 179 |
IGA_API uint32_t kv_is_inst_target(const struct kv_t *kv, int32_t pc); |
| 180 |
|
| 181 |
/* |
| 182 |
* This enumeration allows one to determine if a given PC is for structured |
| 183 |
* control flow. This is for tools that want to render an indentation for |
| 184 |
* readability. |
| 185 |
*/ |
| 186 |
typedef enum { |
| 187 |
KV_OPGROUP_INVALID, /* not a valid op (e.g. out of bounds, middle of |
| 188 |
instruction) */ |
| 189 |
KV_OPGROUP_OTHER, /* some other instruction */ |
| 190 |
KV_OPGROUP_IF, /* an 'if' op */ |
| 191 |
KV_OPGROUP_ELSE, /* an 'else' op */ |
| 192 |
KV_OPGROUP_ENDIF, /* an 'endif' op */ |
| 193 |
KV_OPGROUP_WHILE, /* a 'while' op */ |
| 194 |
KV_OPGROUP_SEND_EOT, /* a send message with the EOT bit set */ |
| 195 |
} kv_opgroup_t; |
| 196 |
|
| 197 |
/* |
| 198 |
* This function returns the opcode group. The result may be compared |
| 199 |
* to the integral value of the various kv_opcode_group enumerates. |
| 200 |
* (See enum kv_get_opgroup_t.) |
| 201 |
*/ |
| 202 |
IGA_API int32_t kv_get_opgroup(const struct kv_t *kv, int32_t pc); |
| 203 |
|
| 204 |
/* |
| 205 |
* Returns the send function descriptors. The count of descriptors is |
| 206 |
* returned; hence, if the instruction is invalid or not a send or |
| 207 |
* send using two index registers, 0 is returned. |
| 208 |
* If one of the descriptors is not immediate, then 1 is returned |
| 209 |
* and that descriptor is set to KV_INVALID_SEND_DESC. |
| 210 |
* |
| 211 |
* Also returns 0 if any parameter is NULL (and parameters are untouched). |
| 212 |
*/ |
| 213 |
IGA_API uint32_t kv_get_send_descs(const struct kv_t *kv, int32_t pc, |
| 214 |
uint32_t *ex_desc, uint32_t *desc); |
| 215 |
|
| 216 |
/* |
| 217 |
* Returns the special ExDescImmOff field, which only exists on |
| 218 |
* LSC UGM XE2+ BSS/SS immediate offsets field and with an ExDesc in register |
| 219 |
* form. This field is returned in the packed form. |
| 220 |
* See BXML for how to decode this to a signed 17b value, but the gist is to |
| 221 |
* unpack it from [31:19][15:12] and interpret that as a signed 17b value. |
| 222 |
* The other bits should be 0's as they lack an encoding in the send. |
| 223 |
* Also note that FLAT/BTI addresses will not use this API. The offset bits |
| 224 |
* will be encoded as part of the regular ExDesc value. |
| 225 |
* |
| 226 |
* Returns: |
| 227 |
* KV_SUCCESS on success; output is stored to exdesc_immoff |
| 228 |
* KV_INVALID_ARGUMENT given a nullptr argument or invalid PC |
| 229 |
* KV_NON_SEND_INSTRUCTION if not a send instruction |
| 230 |
* KV_DESCRIPTOR_INVALID if not an LSC UGM XE2 BSS/SS descriptor |
| 231 |
*/ |
| 232 |
IGA_API kv_status_t kv_get_send_exdesc_immoff(const struct kv_t *kv, int32_t pc, |
| 233 |
uint32_t *exdesc_immoff); |
| 234 |
|
| 235 |
/* |
| 236 |
* Returns the indirect descriptor registers for a send message. |
| 237 |
* Given a valid send instruction with some (or both) a0.# registers |
| 238 |
* the register and subregister are returned for each descriptor. |
| 239 |
* If a given register is not indirect (i.e. immediate) then the value returned |
| 240 |
* will be KV_INVALID_REG. It is possible for one descriptor or both |
| 241 |
* to be registers on many platforms. |
| 242 |
* Examples: |
| 243 |
* send... ... 0x0 a0.0 |
| 244 |
* => ex_desc_reg = ex_desc_subreg = KV_INVALID_REG, // imm |
| 245 |
* desc_reg = 0, desc_subreg = 0 // a0.0 |
| 246 |
* send... ... a0.2 0x1234 |
| 247 |
* => ex_desc_reg = 0, ex_desc_subreg = 2, // a0.2 |
| 248 |
* desc_reg = 0 = desc_subreg = KV_INVALID_REG // imm |
| 249 |
* send... ... a0.2 a0.0 |
| 250 |
* => ex_desc_reg = 0, ex_desc_subreg = 2, // a0.2 |
| 251 |
* desc_reg = 0, desc_subreg = 0 // a0.0 |
| 252 |
* |
| 253 |
* RETURNS: |
| 254 |
* KV_SUCCESS if the arguments are valid (non-null and valid kv) |
| 255 |
* and in range (pc) |
| 256 |
* KV_INVALID_ARGUMENT given a nullptr or invalid kv |
| 257 |
* KV_INVALID_PC if the pc is out of range |
| 258 |
* KV_NON_SEND_INSTRUCTION if given a non-send instruction or a send |
| 259 |
* instruction on a platform that does not use a0.# registers. |
| 260 |
*/ |
| 261 |
IGA_API kv_status_t kv_get_send_indirect_descs(const struct kv_t *kv, int32_t pc, |
| 262 |
uint8_t *ex_desc_reg, |
| 263 |
uint8_t *ex_desc_subreg, |
| 264 |
uint8_t *desc_reg, |
| 265 |
uint8_t *desc_subreg); |
| 266 |
|
| 267 |
/* |
| 268 |
* Determines if the given send instruction is on ExBSO mode. |
| 269 |
* exbso = 1 if true, 0 if fales. |
| 270 |
* exbso = -1 if not success. |
| 271 |
* exbso mode is introduces since XeHP. |
| 272 |
* |
| 273 |
* RETURNS: |
| 274 |
* KV_SUCCESS on success |
| 275 |
* KV_NON_SEND_INSTRUCTION if called on a non-send instruction |
| 276 |
* KV_INVALID_PC if passed an invalid PC |
| 277 |
* KV_INVALID_ARGUMENT if given a null parameter |
| 278 |
* KV_INCAPABLE_PLATFORM if it's not XeHP+ platform |
| 279 |
*/ |
| 280 |
IGA_API kv_status_t kv_get_send_exbso(const struct kv_t *kv, int32_t pc, |
| 281 |
int32_t *exbso); |
| 282 |
|
| 283 |
/* |
| 284 |
* Returns the simplified/unified send 42b or 47b descriptor. |
| 285 |
* |
| 286 |
* RETURNS: |
| 287 |
* KV_SUCCESS on success |
| 288 |
* KV_NON_SEND_INSTRUCTION if called on a non-send instruction |
| 289 |
* KV_INVALID_PC if passed an invalid PC |
| 290 |
* KV_INVALID_ARGUMENT if given a null parameter |
| 291 |
* KV_INCAPABLE_PLATFORM if called on unuspported platform |
| 292 |
*/ |
| 293 |
IGA_API kv_status_t kv_get_sendg_desc(const kv_t *kv, int32_t pc, |
| 294 |
uint64_t *desc); |
| 295 |
|
| 296 |
/* |
| 297 |
* Returns the simplified/unified indirect descriptor subregister. |
| 298 |
* subregPresent holds nonzero if this indirect descriptor is valid |
| 299 |
* in the send instruction. The subreg holds the s0.# subregister in bytes. |
| 300 |
* |
| 301 |
* RETURNS: similar to kv_get_sendg_desc |
| 302 |
*/ |
| 303 |
IGA_API kv_status_t kv_get_sendg_ind_desc0(const kv_t *kv, int32_t pc, |
| 304 |
uint32_t *subregPresent, |
| 305 |
uint32_t *subreg); |
| 306 |
|
| 307 |
/* |
| 308 |
* Returns the simplified/unified indirect descriptor subregister. |
| 309 |
* subregPresent holds nonzero if this indirect descriptor is valid |
| 310 |
* in the send instruction. The subreg holds the s0.# subregister in bytes. |
| 311 |
* |
| 312 |
* RETURNS: similar to kv_get_sendg_desc |
| 313 |
*/ |
| 314 |
IGA_API kv_status_t kv_get_sendg_ind_desc1(const kv_t *kv, int32_t pc, |
| 315 |
uint32_t *subregPresent, |
| 316 |
uint32_t *subreg); |
| 317 |
|
| 318 |
/* |
| 319 |
* A symbol to indicate an invalid send descriptor value. |
| 320 |
*/ |
| 321 |
#define KV_INVALID_SEND_DESC ((uint32_t)0xFFFFFFFFF) |
| 322 |
|
| 323 |
/* |
| 324 |
* A symbol to indicate an invalid sendg descriptor value. |
| 325 |
*/ |
| 326 |
#define KV_INVALID_SEND_DESC64B ((uint64_t)0xFFFFFFFFFFFFFFFFL) |
| 327 |
|
| 328 |
/* TODO: review necessity of this macro. |
| 329 |
* A symbol to indicate an invalid message length value. |
| 330 |
*/ |
| 331 |
#define KV_INVALID_LEN ((uint32_t)0xFFFFFFFFF) |
| 332 |
|
| 333 |
/* |
| 334 |
* Indicates invalid register |
| 335 |
*/ |
| 336 |
#define KV_INVALID_REG 0xff |
| 337 |
|
| 338 |
/* |
| 339 |
* Determines the message type for the given send instruction. |
| 340 |
* The result is returned via the pointer 'message_type_enum' - an |
| 341 |
* iga::SFMessageType value. |
| 342 |
* |
| 343 |
* RETURNS: |
| 344 |
* KV_SUCCESS on success |
| 345 |
* KV_NON_SEND_INSTRUCTION if called on a non-send instruction |
| 346 |
* KV_DESCRIPTOR_INDIRECT if called on a send with reg descriptors |
| 347 |
* KV_DESCRIPTOR_INVALID if unable to map the descriptor value |
| 348 |
* (not all messages are mapped via this API) |
| 349 |
* KV_INVALID_PC if passed an invalid PC |
| 350 |
* KV_INVALID_ARGUMENT if given a null parameter |
| 351 |
*/ |
| 352 |
IGA_API kv_status_t kv_get_message_type(const struct kv_t *kv, int32_t pc, |
| 353 |
int32_t *message_type_enum); |
| 354 |
|
| 355 |
/* |
| 356 |
* Determines the message type for the given send instruction. |
| 357 |
* desc and sfid are passed in explicitly when indirect desc prevents |
| 358 |
* use of kv_get_message_type. |
| 359 |
* The result is returned via the pointer 'message_type_enum' - an |
| 360 |
* iga::SFMessageType value. |
| 361 |
* |
| 362 |
* RETURNS: |
| 363 |
* KV_SUCCESS on success |
| 364 |
* KV_NON_SEND_INSTRUCTION if called on a non-send instruction |
| 365 |
* KV_DESCRIPTOR_INDIRECT if called on a send with reg descriptors |
| 366 |
* KV_DESCRIPTOR_INVALID if unable to map the descriptor value |
| 367 |
* (not all messages are mapped via this API) |
| 368 |
* KV_INVALID_PC if passed an invalid PC |
| 369 |
* KV_INVALID_ARGUMENT if given a null parameter |
| 370 |
*/ |
| 371 |
IGA_API kv_status_t kv_get_message_type_ext(const struct kv_t *kv, int32_t pc, |
| 372 |
uint32_t desc, int32_t sfid, |
| 373 |
int32_t *message_type_enum); |
| 374 |
|
| 375 |
/* |
| 376 |
* Determines the message sfid for the given send instruction. |
| 377 |
* The result is returned via the pointer 'sfid_enum' - an iga::SFID |
| 378 |
* |
| 379 |
* RETURNS: |
| 380 |
* KV_SUCCESS on success |
| 381 |
* KV_NON_SEND_INSTRUCTION if called on a non-send instruction |
| 382 |
* KV_DESCRIPTOR_INDIRECT if called on a send with reg descriptors |
| 383 |
* KV_DESCRIPTOR_INVALID if unable to map the descriptor value |
| 384 |
* KV_INVALID_PC if passed an invalid PC |
| 385 |
* KV_INVALID_ARGUMENT if given a null parameter |
| 386 |
*/ |
| 387 |
IGA_API kv_status_t kv_get_message_sfid(const struct kv_t *kv, int32_t pc, |
| 388 |
int32_t *sfid_enum); |
| 389 |
|
| 390 |
/* |
| 391 |
* Gets message length, extended message length, and response length in |
| 392 |
* units of registers. The count of lengths successfully set is returned. |
| 393 |
* If any of the parameters is NULL, it returns 0. Invalid lengths are set |
| 394 |
* to KV_INVALID_LEN. |
| 395 |
*/ |
| 396 |
IGA_API uint32_t kv_get_message_len(const struct kv_t *kv, int32_t pc, uint32_t *mLen, |
| 397 |
uint32_t *emLen, uint32_t *rLen); |
| 398 |
|
| 399 |
/* |
| 400 |
* Alternative version of kv_get_message_len when desc or exDesc are |
| 401 |
* indirect. If any of the parameters is NULL, it returns 0. Invalid lengths |
| 402 |
* are set to KV_INVALID_LEN. |
| 403 |
*/ |
| 404 |
IGA_API uint32_t kv_get_message_len_ext(const struct kv_t *kv, int32_t pc, |
| 405 |
uint32_t desc, uint32_t exDesc, |
| 406 |
uint32_t *mLen, uint32_t *emLen, |
| 407 |
uint32_t *rLen); |
| 408 |
|
| 409 |
/* |
| 410 |
* Returns the ExecSize of the instruction (SIMD width) |
| 411 |
* 0 - INVALID |
| 412 |
* 1 - EXEC_SIZE_1 |
| 413 |
* 2 - EXEC_SIZE_2 |
| 414 |
* 3 - EXEC_SIZE_4 |
| 415 |
* 4 - EXEC_SIZE_8 |
| 416 |
* 5 - EXEC_SIZE_16 |
| 417 |
* 6 - EXEC_SIZE_32 |
| 418 |
*/ |
| 419 |
IGA_API uint32_t kv_get_execution_size(const struct kv_t *kv, int32_t pc); |
| 420 |
|
| 421 |
#ifdef __cplusplus |
| 422 |
/* |
| 423 |
* Returns Software scoreboarding information. |
| 424 |
*/ |
| 425 |
IGA_API bool kv_get_swsb_info(const kv_t *kv, int32_t pc, |
| 426 |
iga::SWSB_ENCODE_MODE encode_mode, |
| 427 |
iga::SWSB &swsb); |
| 428 |
#endif |
| 429 |
|
| 430 |
/* |
| 431 |
* Returns number of sources this instruction has. |
| 432 |
*/ |
| 433 |
IGA_API int32_t kv_get_number_sources(const struct kv_t *kv, int32_t pc); |
| 434 |
|
| 435 |
/* |
| 436 |
* This function returns OPcode integer. The value corresponds to |
| 437 |
* binary encoding value of the opcode. |
| 438 |
*/ |
| 439 |
IGA_API uint32_t kv_get_opcode(const struct kv_t *kv, int32_t pc); |
| 440 |
|
| 441 |
/* |
| 442 |
* This function returns OPcode integer. The value corresponds to |
| 443 |
* binary encoding value of the opcode. |
| 444 |
*/ |
| 445 |
IGA_API kv_status_t kv_get_subfunction(const struct kv_t *kv, int32_t pc, |
| 446 |
uint32_t *subfunc); |
| 447 |
|
| 448 |
/* |
| 449 |
* This function returns if instruction has destination. |
| 450 |
*/ |
| 451 |
IGA_API int32_t kv_get_has_destination(const struct kv_t *kv, int32_t pc); |
| 452 |
|
| 453 |
/* |
| 454 |
* This function returns destination Register row |
| 455 |
*/ |
| 456 |
IGA_API int32_t kv_get_destination_register(const struct kv_t *kv, int32_t pc); |
| 457 |
|
| 458 |
/* |
| 459 |
* This function returns destination subRegister |
| 460 |
*/ |
| 461 |
IGA_API int32_t kv_get_destination_sub_register(const struct kv_t *kv, int32_t pc); |
| 462 |
|
| 463 |
/* |
| 464 |
* This function returns destination data type |
| 465 |
* i.e. F, HF, INT, etc |
| 466 |
*/ |
| 467 |
IGA_API uint32_t kv_get_destination_data_type(const struct kv_t *kv, int32_t pc); |
| 468 |
|
| 469 |
/* |
| 470 |
* This function returns destination register type |
| 471 |
* i.e. GRF, various ARF registers |
| 472 |
*/ |
| 473 |
IGA_API uint32_t kv_get_destination_register_type(const struct kv_t *kv, int32_t pc); |
| 474 |
|
| 475 |
/* |
| 476 |
* This function returns destination register KIND |
| 477 |
* DIRECT, INDIRECT, IMM, INDIR etc |
| 478 |
*/ |
| 479 |
IGA_API uint32_t kv_get_destination_register_kind(const struct kv_t *kv, int32_t pc); |
| 480 |
|
| 481 |
/* |
| 482 |
* This function returns source register line number for a given source. |
| 483 |
*/ |
| 484 |
IGA_API int32_t kv_get_source_register(const struct kv_t *kv, int32_t pc, |
| 485 |
uint32_t sourceNumber); |
| 486 |
|
| 487 |
/* |
| 488 |
* This function returns source subRegister for a given source. |
| 489 |
*/ |
| 490 |
IGA_API int32_t kv_get_source_sub_register(const struct kv_t *kv, int32_t pc, |
| 491 |
uint32_t sourceNumber); |
| 492 |
|
| 493 |
/* |
| 494 |
* This function returns source data type for a given source |
| 495 |
* i.e. F, HF, INT, etc |
| 496 |
*/ |
| 497 |
IGA_API uint32_t kv_get_source_data_type(const struct kv_t *kv, int32_t pc, |
| 498 |
uint32_t sourceNumber); |
| 499 |
|
| 500 |
/* |
| 501 |
* This function returns source register type for a given source. |
| 502 |
* i.e. GRF, various ARF registers |
| 503 |
*/ |
| 504 |
IGA_API uint32_t kv_get_source_register_type(const struct kv_t *kv, int32_t pc, |
| 505 |
uint32_t sourceNumber); |
| 506 |
|
| 507 |
/* |
| 508 |
* This function returns source register KIND for a given source |
| 509 |
* DIRECT, INDIRECT, IMM, INDIR etc |
| 510 |
*/ |
| 511 |
IGA_API uint32_t kv_get_source_register_kind(const struct kv_t *kv, int32_t pc, |
| 512 |
uint32_t sourceNumber); |
| 513 |
|
| 514 |
/* |
| 515 |
* This function returns whether source is a vector. |
| 516 |
*/ |
| 517 |
IGA_API int32_t kv_is_source_vector(const struct kv_t *kv, int32_t pc, |
| 518 |
uint32_t sourceNumber); |
| 519 |
|
| 520 |
/* |
| 521 |
* This function returns mask offset |
| 522 |
*/ |
| 523 |
IGA_API uint32_t kv_get_channel_offset(const struct kv_t *kv, int32_t pc); |
| 524 |
|
| 525 |
/* |
| 526 |
* This function returns mask control |
| 527 |
*/ |
| 528 |
IGA_API uint32_t kv_get_mask_control(const struct kv_t *kv, int32_t pc); |
| 529 |
|
| 530 |
/* |
| 531 |
* This function exposes destination region. |
| 532 |
*/ |
| 533 |
IGA_API int32_t kv_get_destination_region(const struct kv_t *kv, int32_t pc, |
| 534 |
uint32_t *hz); |
| 535 |
|
| 536 |
/* |
| 537 |
* This function exposes source operand region. |
| 538 |
*/ |
| 539 |
IGA_API int32_t kv_get_source_region(const struct kv_t *kv, int32_t pc, |
| 540 |
uint32_t src_op, uint32_t *vt, |
| 541 |
uint32_t *wi, uint32_t *hz); |
| 542 |
|
| 543 |
/* |
| 544 |
* This function exposes source operand immediate value. |
| 545 |
*/ |
| 546 |
IGA_API int32_t kv_get_source_immediate(const struct kv_t *kv, int32_t pc, |
| 547 |
uint32_t src_op, uint64_t *imm); |
| 548 |
|
| 549 |
/* |
| 550 |
* This function exposes indirect source's immediate offset. |
| 551 |
* Return -1 if given source is not indirect srouce |
| 552 |
*/ |
| 553 |
IGA_API int32_t kv_get_source_indirect_imm_off(const struct kv_t *kv, int32_t pc, |
| 554 |
uint32_t src_op, |
| 555 |
int16_t *immoff); |
| 556 |
|
| 557 |
/* |
| 558 |
* This function exposes indirect destination's immediate offset. |
| 559 |
Return -1 if given destination is not indirect srouce |
| 560 |
*/ |
| 561 |
IGA_API int32_t kv_get_destination_indirect_imm_off(const struct kv_t *kv, int32_t pc, |
| 562 |
int16_t *mme); |
| 563 |
|
| 564 |
/* |
| 565 |
* This function exposes source's MathMacroExt number for |
| 566 |
* math macro instructions. |
| 567 |
* mme is the mme numbar, set to 8 if it's nomme. |
| 568 |
* Return 0 if the given instruction is math macro instruction. |
| 569 |
* Return -1 if given instruction is not math macro instruction. |
| 570 |
*/ |
| 571 |
IGA_API int32_t kv_get_source_mme_number(const struct kv_t *kv, int32_t pc, |
| 572 |
uint32_t src_op, int16_t *mme); |
| 573 |
|
| 574 |
/* |
| 575 |
* This function exposes destination's MathMacroExt number for |
| 576 |
* math macro instructions. |
| 577 |
* mme is the mme numbar, set to 8 if it's nomme. |
| 578 |
* Return 0 if the given instruction is math macro instruction. |
| 579 |
* Return -1 if given instruction is not math macro instruction. |
| 580 |
*/ |
| 581 |
IGA_API int32_t kv_get_destination_mme_number(const struct kv_t *kv, int32_t pc, |
| 582 |
int16_t *immoff); |
| 583 |
|
| 584 |
/* |
| 585 |
* This function return flag modifier (FlagModifier) |
| 586 |
*/ |
| 587 |
IGA_API uint32_t kv_get_flag_modifier(const struct kv_t *kv, int32_t pc); |
| 588 |
|
| 589 |
/* |
| 590 |
* This function return source modifier |
| 591 |
* This returns a SrcModifier |
| 592 |
*/ |
| 593 |
IGA_API uint32_t kv_get_source_modifier(const struct kv_t *kv, int32_t pc, |
| 594 |
uint32_t src_op); |
| 595 |
|
| 596 |
/* |
| 597 |
* This function return destination modifier |
| 598 |
* This returns a DstModifier |
| 599 |
*/ |
| 600 |
IGA_API uint32_t kv_get_destination_modifier(const struct kv_t *kv, int32_t pc); |
| 601 |
|
| 602 |
/* |
| 603 |
* This function return the flag register |
| 604 |
*/ |
| 605 |
IGA_API int32_t kv_get_flag_register(const struct kv_t *kv, int32_t pc); |
| 606 |
|
| 607 |
/* |
| 608 |
* This function return the flag sub register |
| 609 |
*/ |
| 610 |
IGA_API int32_t kv_get_flag_sub_register(const struct kv_t *kv, int32_t pc); |
| 611 |
|
| 612 |
/* |
| 613 |
* This function return the flag predicate function (a PredCtrl) |
| 614 |
*/ |
| 615 |
IGA_API uint32_t kv_get_predicate(const struct kv_t *kv, int32_t pc); |
| 616 |
|
| 617 |
/* |
| 618 |
* This function returns the logical sign on the predicate (inverted or not) |
| 619 |
*/ |
| 620 |
IGA_API uint32_t kv_get_is_inverse_predicate(const struct kv_t *kv, int32_t pc); |
| 621 |
|
| 622 |
/* |
| 623 |
* This function returns cache control options for a load/store instruction. |
| 624 |
* Either L1 or L3 cache options can be queried by setting 'cache_level' with |
| 625 |
* corresponding iga::CacheLevel value. The result is returned via the pointer |
| 626 |
* 'cacheopt_enum' - an iga::CacheOpt value. |
| 627 |
* |
| 628 |
* RETURNS: |
| 629 |
* KV_SUCCESS on success |
| 630 |
* KV_DECODE_ERROR on decoding error |
| 631 |
* KV_NON_SEND_INSTRUCTION if called on a non-send instruction |
| 632 |
* KV_INVALID_ARGUMENT if cacheLevel is invalid |
| 633 |
* KV_INVALID_PC if called on a non-instruction address |
| 634 |
* Return value is a CachOpt enum value |
| 635 |
*/ |
| 636 |
IGA_API kv_status_t kv_get_cache_opt(const struct kv_t *kv, int32_t pc, |
| 637 |
int32_t cache_level, |
| 638 |
int32_t *cacheopt_enum); |
| 639 |
|
| 640 |
/* |
| 641 |
* This function returns the sync function of a sync instruction |
| 642 |
*/ |
| 643 |
IGA_API int32_t kv_get_syncfc(const struct kv_t *kv, int32_t pc); |
| 644 |
|
| 645 |
#ifdef __cplusplus |
| 646 |
} |
| 647 |
#endif |
| 648 |
#endif |