Debian Codegraph @

visa/iga/IGALibrary/api/kv.hpp

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 #ifndef IGA_KV_HPP
10 #define IGA_KV_HPP
11
12 #include "iga_types_ext.hpp"
13 #include "kv.h"
14
15 // This convenience class wraps the pure C interface.
16 // Typical use involves something such as following.
17 // const void *myBits = ... your kernel
18 // size_t myBitsLen = ... the length in bytes
19 // KernelView kv(IGA_GEN_SKL, &myBits, myBitsLen);
20 // if (!kv.decodeSucceeded()) {
21 // ReportDecodeError();
22 // // all operations on kv should fail if !kv.decodeSucceeded()
23 // } else {
24 // ProcessKernelView(&kv);
25 // }
26 // Further, a log may be passed in to the constructor that may be populated
27 // with error and warning diagnostics.
28 // char log[256];
29 // KernelView kv(IGA_GEN_SKL, &myBits, myBitsLen, &log, sizeof(log));
30 // if (!kv.decodeSucceeded()) {
31 // ReportDecodeError(log);
32 // // all operations on kv should fail if !kv.decodeSucceeded()
33 // }
34 //
35 class KernelView {
36 // handle to the IGA-internal KV object; may be nullptr upon error
37 kv_t *m_kv = nullptr;
38
39 // The status from kv_create
40 iga_status_t m_disasm_status = IGA_SUCCESS;
41
42 // The platform this kernel view platform corresponds to
43 iga_gen_t m_gen = IGA_GEN_INVALID;
44
45 public:
46 // Constructs a kernel view.
47 //
48 // This disassembles the kernel and copies out the disassembly log,
49 // which may indicate errors or warnings.
50 KernelView(
51 iga_gen_t platf, const void *bytes, size_t bytesLength,
52 iga::SWSB_ENCODE_MODE swsb_mode = iga::SWSB_ENCODE_MODE::SWSBInvalidMode,
53 char *decodeLog = nullptr, size_t decodeLogLen = 0
54 )
55 : m_kv(nullptr), m_disasm_status(IGA_SUCCESS), m_gen(platf) {
56 m_kv = kv_create(platf, bytes, bytesLength, &m_disasm_status, decodeLog,
57 decodeLogLen, static_cast<uint32_t>(swsb_mode)
58 );
59 }
60
61 // The destructor automatically deallocates the underlying kernel view
62 // and all IGA resources.
63 ~KernelView() {
64 if (m_kv) {
65 kv_delete(m_kv);
66 m_kv = nullptr;
67 }
68 }
69
70 // Returns a raw handle to the underlying interface object.
71 const kv_t *getHandle() const { return m_kv; }
72 // Returns a raw handle to the underlying interface object.
73 kv_t *getHandle() { return m_kv; }
74
75 // If the kernel bits are malformed, m_kv is a valid instance of kernel View
76 // If user proceeds to use it to retrieve information per instructiong we do
77 // not gurantee that information is correct operations should be called.
78 //
79 // Upon decode failure, the 'decodeLog' arguments can be consulted for
80 // a specific error message.
81 bool decodeSucceeded() const { return decodeStatus() == IGA_SUCCESS; }
82
83 // The decode status will be IGA_SUCCESS, IGA_OUT_OF_MEM or IGA_DECODE_ERROR
84 iga_status_t decodeStatus() const { return m_disasm_status; }
85
86 // Returns the size of the instruction at 'pc'
87 // returns 0 if pc is out of bounds (invalid).
88 //
89 // This allows one to iterate a kernel
90 // KernelView k...;
91 // int32_t pc = 0, pcSz;
92 // while ((pcSz = k.getInstSize(pc)) != 0) {
93 // ... process instruction
94 // pc += pcSz;
95 // }
96 int32_t getInstSize(int32_t pc) const { return kv_get_inst_size(m_kv, pc); }
97
98 // Returns the targets of the instruction at PC in the given input
99 // buffer. The count of valid entries is returned.
100 // The input buffer should be at least KV_MAX_TARGETS_PER_INSTRUCTION
101 // elements long. The nullptr can be passed instead if only the count
102 // of targets is desired.
103 //
104 // int32_t js[KV_MAX_TARGETS_PER_INSTRUCTION];
105 // size_t n = k.getInstTargets(pc, js);
106 // printf(" the instruction at PC%d:", (int)pc);
107 // for (size_t i = 0; i < n; i++) {
108 // printf(" targets PC %d", (int)js[i]);
109 // }
110 //
111 size_t getInstTargets(int32_t pc, int32_t *targetPcs) const {
112 return (size_t)kv_get_inst_targets(m_kv, pc, targetPcs);
113 }
114
115 // size_t count = k.getInstTargetsCount(pc);
116 // if (count > 1) {
117 // int32_t jip = k.getInstJIP(pc);
118 // int32_t uip = 0;
119 // if(count == 2)
120 // uip = kv.getInstUIP(pc);
121 // }
122 // OR
123 // int32_t jumps[KV_MAX_TARGETS_PER_INSTRUCTION];
124 // getInstTargets(pc, jumps);
125 // returns the number of targets of the instruction at 'pc'
126 // size_t getInstTargetsCount(uint32_t pc) const {
127 // return kv_get_inst_targets(m_kv, pc);
128 // }
129 //
130 // returns JIP or 0 if JIP is not valid.
131
132 // If JIP is invalid or a register KV_INVALID_PC_VALUE is returned
133 int32_t getInstJIP(int32_t pc) const {
134 int32_t tpcs[KV_MAX_TARGETS_PER_INSTRUCTION];
135 if (getInstTargets(pc, &tpcs[0]) < 1) {
136 return KV_INVALID_PC_VALUE;
137 } else {
138 return tpcs[0];
139 }
140 }
141
142 // If UIP is invalid KV_INVALID_PC_VALUE is returned
143 int32_t getInstUIP(int32_t pc) const {
144 int32_t tpcs[KV_MAX_TARGETS_PER_INSTRUCTION];
145 if (getInstTargets(pc, &tpcs[0]) < 2) {
146 return KV_INVALID_PC_VALUE;
147 } else {
148 return tpcs[1];
149 }
150 }
151
152 // returns true if the instruction at 'pc' is the target of some branch
153 // instruction (and needs a label). i.e. this is the beginning of a block
154 bool isInstTarget(int32_t pc) const {
155 return kv_is_inst_target(m_kv, pc) != 0;
156 }
157
158 // Generates syntax for the instruction at 'pc' to a user-provided buffer.
159 // The required number of bytes is returned. If sBuf is nullptr, then
160 // it is ignored and the function just computes the number of characters
161 // needed to format the instruction.
162 //
163 // An example use of this API is as follows:
164 // size_t n = kv.getInstSyntax(pc, nullptr, 0);
165 // char *str = (char *)alloca(n);
166 // auto fmtOpts = IGA_FORMATTING_OPTS_DEFAULT; // see iga.h
167 // (void)kv.getInstSyntax(pc, str, n, fmtOpts);
168 //
169 // The formatter options 'fmtOpts' are the same as those in
170 // iga_disassemble_options_t::formatting_opts. See iga.h for a
171 // valid values.
172 //
173 // The final two arguments are for an optional labeler callback.
174 // The function pointer points to a function which converts a PC
175 // to a string.
176 // * The 'env' is threaded to that callback it as well.
177 // * The callback function should return a NUL terminated string
178 // for the given PC or nullptr if you don't care about a given pc.
179 // * The pointer returned is *not* freed or written by IGA. For
180 // instructions that have multiple labels (e.g. an 'if' instruction)
181 // IGA will copy the string out before calling the the callback on
182 // the next label. Hence, a single buffer can be reused by the
183 // callback for both labels.
184 //
185 // E.g.
186 // static const char *labelerFunction(int32_t pc, void *buf) {
187 // snprintf((char*)buf, 63, "LABEL%u", pc);
188 // }
189 //
190 // Then in your code you'd have:
191 //
192 // char lblbuf[64];
193 // char instbuf[256]; // labeler environment (state)
194 // kv.getInstSyntax(
195 // pc,
196 // instbuf, sizeof(instbuf),
197 // IGA_FORMATTING_OPTS_DEFAULT,
198 // &labelerFunction, lblbuf);
199 //
200 // The above is safe for any instruction with multiple labels as 'lblbuf'
201 // can be used multiple times safely.
202 size_t getInstSyntax(int32_t pc, char *sBuf, size_t sBufCapacity,
203 uint32_t fmtOpts,
204 const char *(*labeler)(int32_t, void *) = nullptr,
205 void *env = nullptr) const {
206 return kv_get_inst_syntax(m_kv, pc, sBuf, sBufCapacity, fmtOpts, labeler,
207 env);
208 }
209 size_t getInstSyntax(int32_t pc, char *sBuf, size_t sBufCapacity,
210 const char *(*labeler)(int32_t, void *) = nullptr,
211 void *env = nullptr) const {
212 return getInstSyntax(pc, sBuf, sBufCapacity, IGA_FORMATTING_OPTS_DEFAULT,
213 labeler, env);
214 }
215
216 // This function returns the default label name if custom labeler is not used.
217 size_t getDefaultLabelName(int32_t pc, char *sBuf,
218 size_t sBufCapacity) const {
219 return kv_get_default_label_name(pc, sBuf, sBufCapacity);
220 }
221
222 // This method returns the opcode group.
223 // (See kv_get_opcode_group.)
224 kv_opgroup_t getOpcodeGroup(int32_t pc) const {
225 return (kv_opgroup_t)kv_get_opgroup(m_kv, pc);
226 }
227
228 // Returns the send descriptors for send messages
229 // (See kv_get_send_descs)
230 uint32_t getSendDescs(int32_t pc, uint32_t *ex_desc, uint32_t *desc) const {
231 return kv_get_send_descs(m_kv, pc, ex_desc, desc);
232 }
233
234 // Returns the ExDescImmOff field. This field exists only on
235 // LSC UGM BSS/SS AddressTypes on XE2+.
236 //
237 // Return 0xFFFFFFFF on failure (e.g. invalid PC) and the value on success.
238 //
239 // *NOTE WELL*: this field is encoded as described in BXML. See the
240 // kv.h docs on kv_get_send_exdesc_immoff to see how to decode this value
241 // to a signed offset.
242 uint32_t getSendExDescImmOff(int32_t pc) const {
243 uint32_t immoff = (uint32_t)-1;
244 if (kv_get_send_exdesc_immoff(m_kv, pc, &immoff) != kv_status_t::KV_SUCCESS)
245 return (uint32_t)-1;
246 return immoff;
247 }
248
249 // Maps to kv_get_sendg_desc; confer with that API in kv.h for semantics
250 kv_status_t getSendgDesc(int32_t pc, uint64_t *desc) const {
251 return kv_get_sendg_desc(m_kv, pc, desc);
252 }
253 // Maps to kv_get_sendg_ind_desc0; confer with that API in kv.h
254 kv_status_t getSendgIndDesc0(int32_t pc, uint32_t *subregPresent,
255 uint32_t *subreg) const {
256 return kv_get_sendg_ind_desc0(m_kv, pc, subregPresent, subreg);
257 }
258 // Maps to kv_get_sendg_ind_desc1; confer with that API in kv.h
259 kv_status_t getSendgIndDesc1(int32_t pc, uint32_t *subregPresent,
260 uint32_t *subreg) const {
261 return kv_get_sendg_ind_desc1(m_kv, pc, subregPresent, subreg);
262 }
263
264 /*************************Analysis APIs **********************************/
265
266 // Returns the number of expicit sources this instruction has.
267 int32_t getNumberOfSources(int32_t pc) const {
268 return kv_get_number_sources(m_kv, pc);
269 }
270
271 // Determines if the given send instruction is on ExBSO mode.
272 // Return 1 if true, 0 if false
273 // Return -1 if not success
274 int32_t getSendExBso(int32_t pc) const {
275 int32_t exbso = -1;
276 if (kv_get_send_exbso(m_kv, pc, &exbso) != kv_status_t::KV_SUCCESS)
277 return -1;
278 return exbso;
279 }
280
281 // Fetches the message type for send/sends instructions.
282 //
283 // Returns:
284 // KV_SUCCESS on success (and assigned sfmt)
285 // KV_DESCRIPTOR_INDIRECT if called on a send with a register desriptor
286 // KV_DESCRIPTOR_INVALID if called on a send unrecognized descriptor
287 // KV_INVALID_PC if called on a non-instruction address
288 // KV_NON_SEND_INSTRUCTION if called on a non-send instruction
289 kv_status_t getMessageType(int32_t pc, iga::SFMessageType &sfmt) const;
290
291 // Fetches the message SFID for send/sends instructions.
292 //
293 // Returns:
294 // KV_SUCCESS on success (and assigned sfmt)
295 // KV_DESCRIPTOR_INDIRECT if called on a send with a register desriptor
296 // KV_DESCRIPTOR_INVALID if called on a send unrecognized descriptor
297 // KV_INVALID_PC if called on a non-instruction address
298 // KV_NON_SEND_INSTRUCTION if called on a non-send instruction
299 kv_status_t getMessageSFID(int32_t pc, iga::SFID &sfid) const;
300
301 // Fetches the cache control option for load/store instructions.
302 //
303 // Returns:
304 // KV_SUCCESS on success and cacheOpt is assigned
305 // KV_DECODE_ERROR on decoding error
306 // KV_NON_SEND_INSTRUCTION if called on a non-send instruction
307 // KV_INVALID_ARGUMENT if cacheLevel is invalid
308 // KV_INVALID_PC if called on a non-instruction address
309 kv_status_t getCacheOpt(int32_t pc, iga::CacheLevel cahceLevel,
310 iga::CacheOpt &cacheOpt) const;
311
312 // Returns message, extended message, and response lengths in units of
313 // registers. The count of length variables successfully set is returned.
314 //
315 // - mLen (message length) is usually addresses to load or store to
316 // - emLen (extended message length) is usually data being stored
317 // - rLen (response length) is usually data being loaded
318 //
319 // If any of the parameters is NULL, it returns 0.
320 // Invalid lengths are set to KV_INVALID_LEN.
321 // Reasons for failures:
322 // - the instruction is not a send instruction
323 // - a register descriptor is used by the send instruction.
324 // - the given PC does not refer to an instruction.
325 uint32_t getMessageLen(int32_t pc, uint32_t *mLen, uint32_t *emLen,
326 uint32_t *rLen) const {
327 return kv_get_message_len(m_kv, pc, mLen, emLen, rLen);
328 }
329
330 // Returns execution size of the instruction
331 iga::ExecSize getExecutionSize(int32_t pc) const {
332 return static_cast<iga::ExecSize>(kv_get_execution_size(m_kv, pc));
333 }
334
335 iga::SWSB getSWSBInfo(int32_t pc, iga::SWSB_ENCODE_MODE encode_mode) const {
336 iga::SWSB swsb;
337 kv_get_swsb_info(m_kv, pc, encode_mode, swsb);
338 return swsb;
339 }
340
341 // Returns opcode of the instruction
342 //
343 // N.B.: the opcode is not the same as the 7-bit value encoded in the
344 // actual encoding, but maps to the enumeration value of the underlyings
345 // iga::Op.
346 iga::Op getOpcode(int32_t pc) const {
347 return static_cast<iga::Op>(kv_get_opcode(m_kv, pc));
348 }
349
350 // Returns the subfunction (iga::Subfunction) of the given operation.
351 // E.g. for "math.exp" (iga::Op::MATH) this returns
352 // static_cast<uint32_t>(iga::MathFC::EXP);
353 //
354 // For operations that do not support a subfunction this returns
355 // (uint32_t)-1. For invalid PC's this also returns that value.
356 //
357 // Example usage:
358 // if (getOpcode(pc) == iga::Op::MATH) {
359 // iga::MathFC mfc = static_cast<iga::MathFC>(getSubfunction(pc));
360 // ...
361 // }
362 iga::Subfunction getSubfunction(int32_t pc) const {
363 iga::Subfunction sf;
364 kv_get_subfunction(m_kv, pc, &sf.bits);
365 return sf;
366 }
367
368 // Returns the Execution Mask Offset for the given PC
369 iga::ChannelOffset getChannelOffset(int32_t pc) const {
370 return static_cast<iga::ChannelOffset>(kv_get_channel_offset(m_kv, pc));
371 }
372
373 // Returns Mask Control
374 iga::MaskCtrl getMaskCtrl(int32_t pc) const {
375 return static_cast<iga::MaskCtrl>(kv_get_mask_control(m_kv, pc));
376 }
377
378 int32_t getHasDestination(int32_t pc) const {
379 return kv_get_has_destination(m_kv, pc);
380 }
381 // Returns Register Number Row of destination register.
382 // i.e for r23.5 returns 23
383 int32_t getDstRegNumber(int32_t pc) const {
384 return kv_get_destination_register(m_kv, pc);
385 }
386
387 // Returns sub-register number in a register row.
388 // The subregister is scaled by the type just like in syntactic form.
389 // So r32.5:f is 5*sizeof(:f) = 20 bytes into the 32-byte register.
390 //
391 // i.e. for r32.5 returns 5
392 int32_t getDstSubRegNumber(int32_t pc) const {
393 return kv_get_destination_sub_register(m_kv, pc);
394 }
395
396 // Returns destination data Type
397 // i.e. F, HF, INT, UINT, etc
398 iga::Type getDstDataType(int32_t pc) const {
399 return static_cast<iga::Type>(kv_get_destination_data_type(m_kv, pc));
400 }
401
402 // Returns destination register Type
403 // i.e. GRF, NULL, ACC, etc
404 iga::RegName getDstRegType(int32_t pc) const {
405 return static_cast<iga::RegName>(
406 kv_get_destination_register_type(m_kv, pc));
407 }
408
409 // Returns destination Kind
410 // i.e. DIRECT, INDIRECT, IMM
411 iga::Kind getDstRegKind(int32_t pc) const {
412 return static_cast<iga::Kind>(kv_get_destination_register_kind(m_kv, pc));
413 }
414
415 // Returns Register Number Row of source register.
416 // valid range [0,127]
417 // i.e for r23.5 returns 23
418 int32_t getSrcRegNumber(int32_t pc, uint32_t sourceNumber) const {
419 return kv_get_source_register(m_kv, pc, sourceNumber);
420 }
421
422 // Returns sub register number in a register row.
423 // valid range [0, 31]
424 // i.e. for r32.5 returns 5
425 int32_t getSrcSubRegNumber(int32_t pc, uint32_t sourceNumber) const {
426 return kv_get_source_sub_register(m_kv, pc, sourceNumber);
427 }
428
429 // Returns source data Type
430 // i.e. F, HF, INT, UINT, etc
431 iga::Type getSrcDataType(int32_t pc, uint32_t sourceNumber) const {
432 return static_cast<iga::Type>(
433 kv_get_source_data_type(m_kv, pc, sourceNumber));
434 }
435
436 // Returns source register Type
437 // i.e. GRF, NULL, ACC, etc
438 iga::RegName getSrcRegType(int32_t pc, uint32_t sourceNumber) const {
439 return static_cast<iga::RegName>(
440 kv_get_source_register_type(m_kv, pc, sourceNumber));
441 }
442
443 // Returns source Kind
444 // i.e. DIRECT, INDIRECT, IMM
445 iga::Kind getSrcRegKind(int32_t pc, uint32_t sourceNumber) const {
446 return static_cast<iga::Kind>(
447 kv_get_source_register_kind(m_kv, pc, sourceNumber));
448 }
449
450 // Returns source Indirect Immediate Offset
451 int16_t getSrcRegIndirectImmOff(int32_t pc, uint32_t sourceNumber) const {
452 int16_t result = 0;
453 kv_get_source_indirect_imm_off(m_kv, pc, sourceNumber, &result);
454 return result;
455 }
456
457 // Returns destination Indirect Immediate Offset
458 int16_t getDstRegIndirectImmOff(int32_t pc) const {
459 int16_t result = 0;
460 kv_get_destination_indirect_imm_off(m_kv, pc, &result);
461 return result;
462 }
463
464 // Returns source mme number
465 int16_t getSrcMMENumber(int32_t pc, uint32_t sourceNumber) const {
466 int16_t result = 0;
467 kv_get_source_mme_number(m_kv, pc, sourceNumber, &result);
468 return result;
469 }
470
471 // Returns destination mme number
472 int16_t getDstMMENumber(int32_t pc) const {
473 int16_t result = 0;
474 kv_get_destination_mme_number(m_kv, pc, &result);
475 return result;
476 }
477
478 // Returns if source is a vector
479 // -1 - ERROR
480 // 0 - FALSE
481 // 1 - TRUE
482 int32_t getIsSrcVector(int32_t pc, uint32_t sourceNumber) const {
483 return kv_is_source_vector(m_kv, pc, sourceNumber);
484 }
485
486 // Returns 0 if instruction's destination operand horizontal stride
487 // (DstRgnHz) is succesfully returned.
488 // Otherwise returns -1.
489 // DstRgnHz is returned by *hz parameter, as numeric numeric value
490 // (e.g. 1,2,4).
491 int32_t getDstRegion(int32_t pc, uint32_t *hz) const {
492 return kv_get_destination_region(m_kv, pc, hz);
493 }
494
495 // Returns 0 if any of instruction's src operand region components
496 // (Src RgnVt, RgnWi, RgnHz) are succesfully determined.
497 // Otherwise returns -1.
498 //
499 // Vt, Wi and Hz are returned by *vt, *wi and *hz parameter,
500 // as numeric numeric values (e.g. 1,2,4).
501 int32_t getSrcRegion(int32_t pc, uint32_t src_op, uint32_t *vt, uint32_t *wi,
502 uint32_t *hz) const {
503 return kv_get_source_region(m_kv, pc, src_op, vt, wi, hz);
504 }
505
506 // Returns 0 if the source is an immediate and sets the 64b immediate value
507 // in imm; otherwise it returns -1.
508 //
509 // 16b and 32b immediate will stored in the lower bits of imm.
510 int32_t getSrcImmediate(int32_t pc, uint32_t src_op, uint64_t *imm) const {
511 return kv_get_source_immediate(m_kv, pc, src_op, imm);
512 }
513
514 // Return the flag predicate mode
515 iga::PredCtrl getPredicate(int32_t pc) const {
516 return static_cast<iga::PredCtrl>(kv_get_predicate(m_kv, pc));
517 }
518
519 // Return if inverse predicate is on or not
520 bool isInversePredicate(int32_t pc) const {
521 return static_cast<bool>(kv_get_is_inverse_predicate(m_kv, pc));
522 }
523
524 // Return the flag register
525 int32_t getFlagReg(int32_t pc) const {
526 return kv_get_flag_register(m_kv, pc);
527 }
528
529 // Return the flag sub register
530 int32_t getFlagSubReg(int32_t pc) const {
531 return kv_get_flag_sub_register(m_kv, pc);
532 }
533
534 private:
535 // disable value assignment
536 KernelView(const KernelView &) {}
537 KernelView &operator=(const KernelView &) { return *this; }
538 };
539
540 inline kv_status_t KernelView::getMessageType(int32_t pc,
541 iga::SFMessageType &sfmt) const {
542 if (m_disasm_status != IGA_SUCCESS)
543 return kv_status_t::KV_DECODE_ERROR;
544 int32_t val = 0;
545 kv_status_t s = kv_get_message_type(m_kv, pc, &val);
546 sfmt = static_cast<iga::SFMessageType>(val);
547 return s;
548 }
549
550 inline kv_status_t KernelView::getMessageSFID(int32_t pc,
551 iga::SFID &sfid) const {
552 if (m_disasm_status != IGA_SUCCESS)
553 return kv_status_t::KV_DECODE_ERROR;
554 int32_t val = 0;
555 kv_status_t s = kv_get_message_sfid(m_kv, pc, &val);
556 sfid = static_cast<iga::SFID>(val);
557 return s;
558 }
559
560 inline kv_status_t KernelView::getCacheOpt(int32_t pc,
561 iga::CacheLevel cahceLevel,
562 iga::CacheOpt &cacheOpt) const {
563 if (m_disasm_status != IGA_SUCCESS)
564 return kv_status_t::KV_DECODE_ERROR;
565 int32_t val = 0;
566 kv_status_t s =
567 kv_get_cache_opt(m_kv, pc, static_cast<int32_t>(cahceLevel), &val);
568 cacheOpt = static_cast<iga::CacheOpt>(val);
569 return s;
570 }
571
572 #endif