From: Taylor Simpson <tsimpson@quicinc.com>
To: qemu-devel@nongnu.org
Cc: riku.voipio@iki.fi, richard.henderson@linaro.org,
laurent@vivier.eu, Taylor Simpson <tsimpson@quicinc.com>,
philmd@redhat.com, aleksandar.m.mail@gmail.com
Subject: [RFC PATCH v2 02/67] Hexagon README
Date: Fri, 28 Feb 2020 10:42:58 -0600 [thread overview]
Message-ID: <1582908244-304-3-git-send-email-tsimpson@quicinc.com> (raw)
In-Reply-To: <1582908244-304-1-git-send-email-tsimpson@quicinc.com>
Gives an introduction and overview to the Hexagon target
Signed-off-by: Taylor Simpson <tsimpson@quicinc.com>
---
target/hexagon/README | 296 ++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 296 insertions(+)
create mode 100644 target/hexagon/README
diff --git a/target/hexagon/README b/target/hexagon/README
new file mode 100644
index 0000000..6de71e2
--- /dev/null
+++ b/target/hexagon/README
@@ -0,0 +1,296 @@
+Hexagon is Qualcomm's very long instruction word (VLIW) digital signal
+processor(DSP). We also support Hexagon Vector eXtensions (HVX). HVX
+is a wide vector coprocessor designed for high performance computer vision,
+image processing, machine learning, and other workloads.
+
+The following versions of the Hexagon core are supported
+ Scalar core: v67
+ https://developer.qualcomm.com/downloads/qualcomm-hexagon-v67-programmer-s-reference-manual
+ HVX extension: v66
+ https://developer.qualcomm.com/downloads/qualcomm-hexagon-v66-hvx-programmer-s-reference-manual
+
+We presented an overview of the project at the 2019 KVM Forum.
+ 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
+
+*** Tour of the code ***
+
+The qemu-hexagon implementation is a combination of qemu and the Hexagon
+architecture library (aka archlib). The three primary directories with
+Hexagon-specific code are
+
+ qemu/target/hexagon
+ This has all the instruction and packet semantics
+ qemu/target/hexagon/imported
+ These files are imported with very little modification from archlib
+ *.idef Instruction semantics definition
+ macros.def Mapping of macros to instruction attributes
+ encode*.def Encoding patterns for each instruction
+ iclass.def Instruction class definitions used to determine
+ legal VLIW slots for each instruction
+ qemu/linux-user/hexagon
+ Helpers for loading the ELF file and making Linux system calls,
+ signals, etc
+
+We start with a script that generates qemu helper for each instruction. This
+is a two step process. The first step is to use the C preprocessor to expand
+macros inside the architecture definition files. This is done in
+target/hexagon/semantics.c. This step produces
+ <BUILD_DIR>/hexagon-linux-user/semantics_generated.pyinc.
+That file is consumed by the do_qemu.py script. This script generates
+several files. All of the generated files end in "_generated.*". The
+primary file produced is
+ <BUILD_DIR>/hexagon-linux-user/qemu_def_generated.h
+
+Qemu helper functions have 3 parts
+ DEF_HELPER declaration indicates the signature of the helper
+ gen_helper_<NAME> will generate a TCG call to the helper function
+ The helper implementation
+
+In the qemu_def_generated.h file, there is a DEF_QEMU macro for each user-space
+instruction. The file is included several times with DEF_QEMU defined
+differently, depending on the context. The macro has four arguments
+ The instruction tag
+ The semantics_short code
+ DEF_HELPER declaration
+ Call to the helper
+ Helper implementation
+
+Here's an example of the A2_add instruction.
+ Instruction tag A2_add
+ Assembly syntax "Rd32=add(Rs32,Rt32)"
+ Instruction semantics "{ RdV=RsV+RtV;}"
+
+By convention, the operands are identified by letter
+ RdV is the destination register
+ RsV, RtV are source registers
+
+The generator uses the operand naming conventions (see large comment in
+do_qemu.py) to determine the signature of the helper function. Here is the
+result for A2_add from qemu_def_generated.h
+
+DEF_QEMU(A2_add,{ RdV=RsV+RtV;},
+#ifndef fWRAP_A2_add
+DEF_HELPER_3(A2_add, s32, env, s32, s32)
+#endif
+,
+{
+/* A2_add */
+DECL_RREG_d(RdV, RdN, 0, 0);
+DECL_RREG_s(RsV, RsN, 1, 0);
+DECL_RREG_t(RtV, RtN, 2, 0);
+READ_RREG_s(RsV, RsN);
+READ_RREG_t(RtV, RtN);
+fWRAP_A2_add(
+do {
+gen_helper_A2_add(RdV, cpu_env, RsV, RtV);
+} while (0),
+{ RdV=RsV+RtV;});
+WRITE_RREG_d(RdN, RdV);
+FREE_RREG_d(RdV);
+FREE_RREG_s(RsV);
+FREE_RREG_t(RtV);
+/* A2_add */
+},
+#ifndef fWRAP_A2_add
+int32_t HELPER(A2_add)(CPUHexagonState *env, int32_t RsV, int32_t RtV)
+{
+uint32_t slot = 4; slot = slot;
+int32_t RdV = 0;
+{ RdV=RsV+RtV;}
+COUNT_HELPER(A2_add);
+return RdV;
+}
+#endif
+)
+
+For each operand, there are macros for DECL, FREE, READ, WRITE. These are
+defined in macros.h. Note that we append the operand type to the macro name,
+which allows us to specialize the TCG code tenerated. For read-only operands,
+DECL simply declares the TCGv variable (no need for tcg_temp_local_new()),
+and READ will assign from the TCGv corresponding to the GPR, and FREE doesn't
+have to do anything. Also, note that the WRITE macros update the disassembly
+context to be processed when the packet commits (see "Packet Semantics" below).
+
+Note the fWRAP_A2_add macro around the gen_helper call. Each instruction has a fWRAP_<tag> macro that takes 2 arguments
+ gen_helper call
+ C semantics (aka short code)
+
+This allows the code generator to override the auto-generated code. In some
+cases this is necessary for correct execution. We can also override for
+faster emulation. For example, calling a helper for add is more expensive
+than generating a TCG add operation.
+
+The qemu_wrap_generated.h file contains a default fWRAP_<tag> for each
+instruction. The default is to invoke the gen_helper code.
+ #ifndef fWRAP_A2_add
+ #define fWRAP_A2_add(GENHLPR, SHORTCODE) GENHLPR
+ #endif
+
+The helper_overrides.h file has any overrides. For example,
+ #define fWRAP_A2_add(GENHLPR, SHORTCODE) \
+ tcg_gen_add_tl(RdV, RsV, RtV)
+
+This file is included twice
+1) In genptr.c, it overrides the semantics of the desired instructions
+2) In helper.h, it prevents the generation of helpers for overridden
+ instructions. Notice the #ifndef fWRAP_A2_add above.
+
+The instruction semantics C code heavily on macros. In cases where the C
+semantics are specified only with macros, we can override the default with
+the short semantics option and #define the macros to generate TCG code. One
+example is Y2_dczeroa (dc == data cache, zero == zero out the cache line,
+a == address: zero out the data cache line at the given address):
+ Instruction tag Y2_dczeroa
+ Assembly syntax "dczeroa(Rs32)"
+ Instruction semantics "{fEA_REG(RsV); fDCZEROA(EA);}"
+
+In helper_overrides.h, we use the shortcode
+#define fWRAP_Y2_dczeroa(GENHLPR, SHORTCODE) SHORTCODE
+
+In other cases, just a little bit of wrapper code needs to be written.
+ #define fWRAP_tmp(SHORTCODE) \
+ { \
+ TCGv tmp = tcg_temp_new(); \
+ SHORTCODE; \
+ tcg_temp_free(tmp); \
+ }
+
+For example, some load instructions use a temporary for address computation.
+The SL2_loadrd_sp instruction needs a temporary to hold the value of the stack
+pointer (r29)
+ Instruction tag SL2_loadrd_sp
+ Assembly syntax "Rdd8=memd(r29+#u5:3)"
+ Instruction semantics "{fEA_RI(fREAD_SP(),uiV); fLOAD(1,8,u,EA,RddV);}"
+
+In helper_overrides.h you'll see
+ #define fWRAP_SL2_loadrd_sp(GENHLPR, SHORTCODE) fWRAP_tmp(SHORTCODE)
+
+There are also cases where we brute force the TCG code generation. The
+allocframe and deallocframe instructions are examples. Other examples are
+instructions with multiple definitions. These require special handling
+because qemu helpers can only return a single value.
+
+In addition to instruction semantics, we use a generator to create the decode
+tree. This generation is also a two step process. The first step is to run
+target/hexagon/gen_dectree_import.c to produce
+ <BUILD_DIR>/hexagon-linux-user/iset.py
+This file is imported by target/hexagon/dectree.py to produce
+ <BUILD_DIR>/hexagon-linux-user/dectree_generated.h
+
+*** Key Files ***
+
+cpu.h
+
+This file contains the definition of the CPUHexagonState struct. It is the
+runtime information for each thread and contains stuff like the GPR and
+predicate registers.
+
+macros.h
+mmvec/macros.h
+
+The Hexagon arch lib relies heavily on macros for the instruction semantics.
+This is a great advantage for qemu because we can override them for different
+purposes. You will also notice there are sometimes two definitions of a macro.
+The QEMU_GENERATE variable determines whether we want the macro to generate TCG
+code. If QEMU_GENERATE is not defined, we want the macro to generate vanilla
+C code that will work in the helper implementation.
+
+translate.c
+
+The functions in this file generate TCG code for a translation block. Some
+important functions in this file are
+
+ gen_start_packet - initialize the data structures for packet semantics
+ gen_commit_packet - commit the register writes, stores, etc for a packet
+ decode_packet - disassemble a packet and generate code
+
+genptr.c
+genptr_helpers.h
+helper_overrides.h
+
+These file create a function for each instruction. It is mostly composed of
+fWRAP_<tag> definitions followed by including qemu_def_generated.h. The
+genptr_helpers.h file contains helper functions that are invoked by the macros
+in helper_overrides.h and macros.h
+
+op_helper.c
+
+This file contains the implementations of all the helpers. There are a few
+general purpose helpers, but most of them are generated by including
+qemu_def_generated.h. There are also several helpers used for debugging.
+
+
+*** Packet Semantics ***
+
+VLIW packet semantics differ from serial semantics in that all input operands
+are read, then the operations are performed, then all the results are written.
+For exmaple, this packet performs a swap of registers r0 and r1
+ { r0 = r1; r1 = r0 }
+Note that the result is different if the instructions are executed serially.
+
+Packet semantics dictate that we defer any changes of state until the entire
+packet is committed. We record the results of each instruction in a side data
+structure, and update the visible processor state when we commit the packet.
+
+The data structures are divided between the runtime state and the translation
+context.
+
+During the TCG generation (see translate.[ch]), we use the DisasContext to
+track what needs to be done during packet commit. Here are the relevant
+fields
+
+ ctx_reg_log list of registers written
+ ctx_reg_log_idx index into ctx_reg_log
+ ctx_pred_log list of predicates written
+ ctx_pred_log_idx index into ctx_pred_log
+ ctx_store_width width of stores (indexed by slot)
+
+During runtime, the following fields in CPUHexagonState (see cpu.h) are used
+
+ new_value new value of a given register
+ reg_written boolean indicating if register was written
+ new_pred_value new value of a predicate register
+ pred_written boolean indicating if predicate was written
+ mem_log_stores record of the stores (indexed by slot)
+
+For Hexagon Vector eXtensions (HVX), the following fields are used
+
+ future_VRegs
+ tmp_VRegs
+ future_ZRegs
+ ZRegs_updated
+ VRegs_updated_tmp
+ VRegs_updated
+ VRegs_select
+
+*** Debugging ***
+
+You can turn on a lot of debugging by changing the HEX_DEBUG macro to 1 in
+internal.h. This will stream a lot of information as it generates TCG and
+executes the code.
+
+To track down nasty issues with Hexagon->TCG generation, we compare the
+execution results with actual hardware running on a Hexagon Linux target.
+Run qemu with the "-d cpu" option. Then, we can diff the results and figure
+out where qemu and hardware behave differently.
+
+The stacks are located at different locations. We handle this by changing
+env->stack_adjust in translate.c. First, set this to zero and run qemu.
+Then, change env->stack_adjust to the difference between the two stack
+locations. Then rebuild qemu and run again. That will produce a very
+clean diff.
+
+Here are some handy places to set breakpoints
+
+ At the call to gen_start_packet for a given PC (note that the line number
+ might change in the future)
+ br translate.c:602 if ctx->base.pc_next == 0xdeadbeef
+ The helper function for each instruction is named helper_<TAG>, so here's
+ an example that will set a breakpoint at the start
+ br helper_V6_vgathermh
+ If you have the HEX_DEBUG macro set, the following will be useful
+ At the start of execution of a packet for a given PC
+ br helper_debug_start_packet if env->gpr[41] == 0xdeadbeef
+ At the end of execution of a packet for a given PC
+ br helper_debug_commit_end if env->this_PC == 0xdeadbeef
+
--
2.7.4
next prev parent reply other threads:[~2020-02-28 16:56 UTC|newest]
Thread overview: 72+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-28 16:42 [RFC PATCH v2 00/67] Hexagon patch series Taylor Simpson
2020-02-28 16:42 ` [RFC PATCH v2 01/67] Hexagon Maintainers Taylor Simpson
2020-02-28 16:42 ` Taylor Simpson [this message]
2020-02-28 16:42 ` [RFC PATCH v2 03/67] Hexagon ELF Machine Definition Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 04/67] Hexagon CPU Scalar Core Definition Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 05/67] Hexagon register names Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 06/67] Hexagon Disassembler Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 07/67] Hexagon CPU Scalar Core Helpers Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 08/67] Hexagon GDB Stub Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 09/67] Hexagon architecture types Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 10/67] Hexagon instruction and packet types Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 11/67] Hexagon register fields Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 12/67] Hexagon instruction attributes Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 13/67] Hexagon register map Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 14/67] Hexagon instruction/packet decode Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 15/67] Hexagon instruction printing Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 16/67] Hexagon arch import - instruction semantics definitions Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 17/67] Hexagon arch import - macro definitions Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 18/67] Hexagon arch import - instruction encoding Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 19/67] Hexagon instruction class definitions Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 20/67] Hexagon instruction utility functions Taylor Simpson
2020-04-09 18:53 ` Brian Cain
2020-04-09 20:22 ` Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 21/67] Hexagon generator phase 1 - C preprocessor for semantics Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 22/67] Hexagon generator phase 2 - qemu_def_generated.h Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 23/67] Hexagon generator phase 2 - qemu_wrap_generated.h Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 24/67] Hexagon generator phase 2 - opcodes_def_generated.h Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 25/67] Hexagon generator phase 2 - op_attribs_generated.h Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 26/67] Hexagon generator phase 2 - op_regs_generated.h Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 27/67] Hexagon generator phase 2 - printinsn-generated.h Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 28/67] Hexagon generator phase 3 - C preprocessor for decode tree Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 29/67] Hexagon generater phase 4 - Decode tree Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 30/67] Hexagon opcode data structures Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 31/67] Hexagon macros to interface with the generator Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 32/67] Hexagon macros referenced in instruction semantics Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 33/67] Hexagon instruction classes Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 34/67] Hexagon TCG generation helpers - step 1 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 35/67] Hexagon TCG generation helpers - step 2 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 36/67] Hexagon TCG generation helpers - step 3 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 37/67] Hexagon TCG generation helpers - step 4 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 38/67] Hexagon TCG generation helpers - step 5 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 39/67] Hexagon TCG generation - step 01 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 40/67] Hexagon TCG generation - step 02 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 41/67] Hexagon TCG generation - step 03 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 42/67] Hexagon TCG generation - step 04 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 43/67] Hexagon TCG generation - step 05 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 44/67] Hexagon TCG generation - step 06 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 45/67] Hexagon TCG generation - step 07 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 46/67] Hexagon TCG generation - step 08 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 47/67] Hexagon TCG generation - step 09 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 48/67] Hexagon TCG generation - step 10 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 49/67] Hexagon TCG generation - step 11 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 50/67] Hexagon TCG generation - step 12 Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 51/67] Hexagon translation Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 52/67] Hexagon Linux user emulation Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 53/67] Hexagon build infrastructure Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 54/67] Hexagon - Add Hexagon Vector eXtensions (HVX) to core definition Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 55/67] Hexagon HVX support in gdbstub Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 56/67] Hexagon HVX import instruction encodings Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 57/67] Hexagon HVX import semantics Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 58/67] Hexagon HVX import macro definitions Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 59/67] Hexagon HVX semantics generator Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 60/67] Hexagon HVX instruction decoding Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 61/67] Hexagon HVX instruction utility functions Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 62/67] Hexagon HVX macros to interface with the generator Taylor Simpson
2020-02-28 16:43 ` [RFC PATCH v2 63/67] Hexagon HVX macros referenced in instruction semantics Taylor Simpson
2020-02-28 16:44 ` [RFC PATCH v2 64/67] Hexagon HVX helper to commit vector stores (masked and scatter/gather) Taylor Simpson
2020-02-28 16:44 ` [RFC PATCH v2 65/67] Hexagon HVX TCG generation Taylor Simpson
2020-02-28 16:44 ` [RFC PATCH v2 66/67] Hexagon HVX translation Taylor Simpson
2020-02-28 16:44 ` [RFC PATCH v2 67/67] Hexagon HVX build infrastructure Taylor Simpson
2020-03-25 21:13 ` [RFC PATCH v2 00/67] Hexagon patch series Taylor Simpson
2020-04-30 20:53 ` Taylor Simpson
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1582908244-304-3-git-send-email-tsimpson@quicinc.com \
--to=tsimpson@quicinc.com \
--cc=aleksandar.m.mail@gmail.com \
--cc=laurent@vivier.eu \
--cc=philmd@redhat.com \
--cc=qemu-devel@nongnu.org \
--cc=richard.henderson@linaro.org \
--cc=riku.voipio@iki.fi \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).