target/hexagon/README

   1 Hexagon is Qualcomm's very long instruction word (VLIW) digital signal
   2 processor(DSP).  We also support Hexagon Vector eXtensions (HVX).  HVX
   3 is a wide vector coprocessor designed for high performance computer vision,
   4 image processing, machine learning, and other workloads.
   5
   6 The following versions of the Hexagon core are supported
   7     Scalar core: v67
   8     https://developer.qualcomm.com/downloads/qualcomm-hexagon-v67-programmer-s-reference-manual
   9     HVX extension: v66
  10     https://developer.qualcomm.com/downloads/qualcomm-hexagon-v66-hvx-programmer-s-reference-manual
  11
  12 We presented an overview of the project at the 2019 KVM Forum.
  13     https://kvmforum2019.sched.com/event/Tmwc/qemu-hexagon-automatic-translation-of-the-isa-manual-pseudcode-to-tiny-code-instructions-of-a-vliw-architecture-niccolo-izzo-revng-taylor-simpson-qualcomm-innovation-center
  14
  15 *** Tour of the code ***
  16
  17 The qemu-hexagon implementation is a combination of qemu and the Hexagon
  18 architecture library (aka archlib).  The three primary directories with
  19 Hexagon-specific code are
  20
  21     qemu/target/hexagon
  22         This has all the instruction and packet semantics
  23     qemu/target/hexagon/imported
  24         These files are imported with very little modification from archlib
  25         *.idef                  Instruction semantics definition
  26         macros.def              Mapping of macros to instruction attributes
  27         encode*.def             Encoding patterns for each instruction
  28         iclass.def              Instruction class definitions used to determine
  29                                 legal VLIW slots for each instruction
  30     qemu/linux-user/hexagon
  31         Helpers for loading the ELF file and making Linux system calls,
  32         signals, etc
  33
  34 We start with scripts that generate a bunch of include files.  This
  35 is a two step process.  The first step is to use the C preprocessor to expand
  36 macros inside the architecture definition files.  This is done in
  37 target/hexagon/gen_semantics.c.  This step produces
  38     <BUILD_DIR>/target/hexagon/semantics_generated.pyinc.
  39 That file is consumed by the following python scripts to produce the indicated
  40 header files in <BUILD_DIR>/target/hexagon
  41         gen_opcodes_def.py              -> opcodes_def_generated.h.inc
  42         gen_op_regs.py                  -> op_regs_generated.h.inc
  43         gen_printinsn.py                -> printinsn_generated.h.inc
  44         gen_op_attribs.py               -> op_attribs_generated.h.inc
  45         gen_helper_protos.py            -> helper_protos_generated.h.inc
  46         gen_shortcode.py                -> shortcode_generated.h.inc
  47         gen_tcg_funcs.py                -> tcg_funcs_generated.c.inc
  48         gen_tcg_func_table.py           -> tcg_func_table_generated.c.inc
  49         gen_helper_funcs.py             -> helper_funcs_generated.c.inc
  50
  51 Qemu helper functions have 3 parts
  52     DEF_HELPER declaration indicates the signature of the helper
  53     gen_helper_<NAME> will generate a TCG call to the helper function
  54     The helper implementation
  55
  56 Here's an example of the A2_add instruction.
  57     Instruction tag        A2_add
  58     Assembly syntax        "Rd32=add(Rs32,Rt32)"
  59     Instruction semantics  "{ RdV=RsV+RtV;}"
  60
  61 By convention, the operands are identified by letter
  62     RdV is the destination register
  63     RsV, RtV are source registers
  64
  65 The generator uses the operand naming conventions (see large comment in
  66 hex_common.py) to determine the signature of the helper function.  Here are the
  67 results for A2_add
  68
  69 helper_protos_generated.h.inc
  70     DEF_HELPER_3(A2_add, s32, env, s32, s32)
  71
  72 tcg_funcs_generated.c.inc
  73     static void generate_A2_add(
  74                     CPUHexagonState *env,
  75                     DisasContext *ctx,
  76                     Insn *insn,
  77                     Packet *pkt)
  78     {
  79         TCGv RdV = tcg_temp_local_new();
  80         const int RdN = insn->regno[0];
  81         TCGv RsV = hex_gpr[insn->regno[1]];
  82         TCGv RtV = hex_gpr[insn->regno[2]];
  83         gen_helper_A2_add(RdV, cpu_env, RsV, RtV);
  84         gen_log_reg_write(RdN, RdV);
  85         ctx_log_reg_write(ctx, RdN);
  86         tcg_temp_free(RdV);
  87     }
  88
  89 helper_funcs_generated.c.inc
  90     int32_t HELPER(A2_add)(CPUHexagonState *env, int32_t RsV, int32_t RtV)
  91     {
  92         uint32_t slot __attribute__((unused)) = 4;
  93         int32_t RdV = 0;
  94         { RdV=RsV+RtV;}
  95         return RdV;
  96     }
  97
  98 Note that generate_A2_add updates the disassembly context to be processed
  99 when the packet commits (see "Packet Semantics" below).
 100
 101 The generator checks for fGEN_TCG_<tag> macro.  This allows us to generate
 102 TCG code instead of a call to the helper.  If defined, the macro takes 1
 103 argument.
 104     C semantics (aka short code)
 105
 106 This allows the code generator to override the auto-generated code.  In some
 107 cases this is necessary for correct execution.  We can also override for
 108 faster emulation.  For example, calling a helper for add is more expensive
 109 than generating a TCG add operation.
 110
 111 The gen_tcg.h file has any overrides. For example, we could write
 112     #define fGEN_TCG_A2_add(GENHLPR, SHORTCODE) \
 113         tcg_gen_add_tl(RdV, RsV, RtV)
 114
 115 The instruction semantics C code relies heavily on macros.  In cases where the
 116 C semantics are specified only with macros, we can override the default with
 117 the short semantics option and #define the macros to generate TCG code.  One
 118 example is L2_loadw_locked:
 119     Instruction tag        L2_loadw_locked
 120     Assembly syntax        "Rd32=memw_locked(Rs32)"
 121     Instruction semantics  "{ fEA_REG(RsV); fLOAD_LOCKED(1,4,u,EA,RdV) }"
 122
 123 In gen_tcg.h, we use the shortcode
 124 #define fGEN_TCG_L2_loadw_locked(SHORTCODE) \
 125     SHORTCODE
 126
 127 There are also cases where we brute force the TCG code generation.
 128 Instructions with multiple definitions are examples.  These require special
 129 handling because qemu helpers can only return a single value.
 130
 131 For HVX vectors, the generator behaves slightly differently.  The wide vectors
 132 won't fit in a TCGv or TCGv_i64, so we pass TCGv_ptr variables to pass the
 133 address to helper functions.  Here's an example for an HVX vector-add-word
 134 istruction.
 135     static void generate_V6_vaddw(
 136                     CPUHexagonState *env,
 137                     DisasContext *ctx,
 138                     Insn *insn,
 139                     Packet *pkt)
 140     {
 141         const int VdN = insn->regno[0];
 142         const intptr_t VdV_off =
 143             ctx_future_vreg_off(ctx, VdN, 1, true);
 144         TCGv_ptr VdV = tcg_temp_local_new_ptr();
 145         tcg_gen_addi_ptr(VdV, cpu_env, VdV_off);
 146         const int VuN = insn->regno[1];
 147         const intptr_t VuV_off =
 148             vreg_src_off(ctx, VuN);
 149         TCGv_ptr VuV = tcg_temp_local_new_ptr();
 150         const int VvN = insn->regno[2];
 151         const intptr_t VvV_off =
 152             vreg_src_off(ctx, VvN);
 153         TCGv_ptr VvV = tcg_temp_local_new_ptr();
 154         tcg_gen_addi_ptr(VuV, cpu_env, VuV_off);
 155         tcg_gen_addi_ptr(VvV, cpu_env, VvV_off);
 156         TCGv slot = tcg_constant_tl(insn->slot);
 157         gen_helper_V6_vaddw(cpu_env, VdV, VuV, VvV, slot);
 158         tcg_temp_free(slot);
 159         gen_log_vreg_write(ctx, VdV_off, VdN, EXT_DFL, insn->slot, false);
 160         ctx_log_vreg_write(ctx, VdN, EXT_DFL, false);
 161         tcg_temp_free_ptr(VdV);
 162         tcg_temp_free_ptr(VuV);
 163         tcg_temp_free_ptr(VvV);
 164     }
 165
 166 Notice that we also generate a variable named <operand>_off for each operand of
 167 the instruction.  This makes it easy to override the instruction semantics with
 168 functions from tcg-op-gvec.h.  Here's the override for this instruction.
 169     #define fGEN_TCG_V6_vaddw(SHORTCODE) \
 170         tcg_gen_gvec_add(MO_32, VdV_off, VuV_off, VvV_off, \
 171                          sizeof(MMVector), sizeof(MMVector))
 172
 173 Finally, we notice that the override doesn't use the TCGv_ptr variables, so
 174 we don't generate them when an override is present.  Here is what we generate
 175 when the override is present.
 176     static void generate_V6_vaddw(
 177                     CPUHexagonState *env,
 178                     DisasContext *ctx,
 179                     Insn *insn,
 180                     Packet *pkt)
 181     {
 182         const int VdN = insn->regno[0];
 183         const intptr_t VdV_off =
 184             ctx_future_vreg_off(ctx, VdN, 1, true);
 185         const int VuN = insn->regno[1];
 186         const intptr_t VuV_off =
 187             vreg_src_off(ctx, VuN);
 188         const int VvN = insn->regno[2];
 189         const intptr_t VvV_off =
 190             vreg_src_off(ctx, VvN);
 191         fGEN_TCG_V6_vaddw({ fHIDE(int i;) fVFOREACH(32, i) { VdV.w[i] = VuV.w[i] + VvV.w[i] ; } });
 192         gen_log_vreg_write(ctx, VdV_off, VdN, EXT_DFL, insn->slot, false);
 193         ctx_log_vreg_write(ctx, VdN, EXT_DFL, false);
 194     }
 195
 196 In addition to instruction semantics, we use a generator to create the decode
 197 tree.  This generation is also a two step process.  The first step is to run
 198 target/hexagon/gen_dectree_import.c to produce
 199     <BUILD_DIR>/target/hexagon/iset.py
 200 This file is imported by target/hexagon/dectree.py to produce
 201     <BUILD_DIR>/target/hexagon/dectree_generated.h.inc
 202
 203 *** Key Files ***
 204
 205 cpu.h
 206
 207 This file contains the definition of the CPUHexagonState struct.  It is the
 208 runtime information for each thread and contains stuff like the GPR and
 209 predicate registers.
 210
 211 macros.h
 212 mmvec/macros.h
 213
 214 The Hexagon arch lib relies heavily on macros for the instruction semantics.
 215 This is a great advantage for qemu because we can override them for different
 216 purposes.  You will also notice there are sometimes two definitions of a macro.
 217 The QEMU_GENERATE variable determines whether we want the macro to generate TCG
 218 code.  If QEMU_GENERATE is not defined, we want the macro to generate vanilla
 219 C code that will work in the helper implementation.
 220
 221 translate.c
 222
 223 The functions in this file generate TCG code for a translation block.  Some
 224 important functions in this file are
 225
 226     gen_start_packet - initialize the data structures for packet semantics
 227     gen_commit_packet - commit the register writes, stores, etc for a packet
 228     decode_and_translate_packet - disassemble a packet and generate code
 229
 230 genptr.c
 231 gen_tcg.h
 232
 233 These files create a function for each instruction.  It is mostly composed of
 234 fGEN_TCG_<tag> definitions followed by including tcg_funcs_generated.c.inc.
 235
 236 op_helper.c
 237
 238 This file contains the implementations of all the helpers.  There are a few
 239 general purpose helpers, but most of them are generated by including
 240 helper_funcs_generated.c.inc.  There are also several helpers used for debugging.
 241
 242
 243 *** Packet Semantics ***
 244
 245 VLIW packet semantics differ from serial semantics in that all input operands
 246 are read, then the operations are performed, then all the results are written.
 247 For exmaple, this packet performs a swap of registers r0 and r1
 248     { r0 = r1; r1 = r0 }
 249 Note that the result is different if the instructions are executed serially.
 250
 251 Packet semantics dictate that we defer any changes of state until the entire
 252 packet is committed.  We record the results of each instruction in a side data
 253 structure, and update the visible processor state when we commit the packet.
 254
 255 The data structures are divided between the runtime state and the translation
 256 context.
 257
 258 During the TCG generation (see translate.[ch]), we use the DisasContext to
 259 track what needs to be done during packet commit.  Here are the relevant
 260 fields
 261
 262     reg_log            list of registers written
 263     reg_log_idx        index into ctx_reg_log
 264     pred_log           list of predicates written
 265     pred_log_idx       index into ctx_pred_log
 266     store_width        width of stores (indexed by slot)
 267
 268 During runtime, the following fields in CPUHexagonState (see cpu.h) are used
 269
 270     new_value             new value of a given register
 271     reg_written           boolean indicating if register was written
 272     new_pred_value        new value of a predicate register
 273     pred_written          boolean indicating if predicate was written
 274     mem_log_stores        record of the stores (indexed by slot)
 275
 276 For Hexagon Vector eXtensions (HVX), the following fields are used
 277     VRegs                       Vector registers
 278     future_VRegs                Registers to be stored during packet commit
 279     tmp_VRegs                   Temporary registers *not* stored during commit
 280     VRegs_updated               Mask of predicated vector writes
 281     QRegs                       Q (vector predicate) registers
 282     future_QRegs                Registers to be stored during packet commit
 283     QRegs_updated               Mask of predicated vector writes
 284
 285 *** Debugging ***
 286
 287 You can turn on a lot of debugging by changing the HEX_DEBUG macro to 1 in
 288 internal.h.  This will stream a lot of information as it generates TCG and
 289 executes the code.
 290
 291 To track down nasty issues with Hexagon->TCG generation, we compare the
 292 execution results with actual hardware running on a Hexagon Linux target.
 293 Run qemu with the "-d cpu" option.  Then, we can diff the results and figure
 294 out where qemu and hardware behave differently.
 295
 296 The stacks are located at different locations.  We handle this by changing
 297 env->stack_adjust in translate.c.  First, set this to zero and run qemu.
 298 Then, change env->stack_adjust to the difference between the two stack
 299 locations.  Then rebuild qemu and run again. That will produce a very
 300 clean diff.
 301
 302 Here are some handy places to set breakpoints
 303
 304     At the call to gen_start_packet for a given PC (note that the line number
 305         might change in the future)
 306         br translate.c:602 if ctx->base.pc_next == 0xdeadbeef
 307     The helper function for each instruction is named helper_<TAG>, so here's
 308         an example that will set a breakpoint at the start
 309         br helper_A2_add
 310     If you have the HEX_DEBUG macro set, the following will be useful
 311         At the start of execution of a packet for a given PC
 312             br helper_debug_start_packet if env->gpr[41] == 0xdeadbeef
 313         At the end of execution of a packet for a given PC
 314             br helper_debug_commit_end if env->this_PC == 0xdeadbeef