RISC-V Meta

Date : January 15, 2020

Version : (under version control)

About

RISC-V Meta is a suite of tools that operate on RISC-V ISA (Instruction Set Architecture) Metadata. The RISC-V Meta tools can generate RISC-V instruction opcode maps, C headers and source containing instruction set metadata, instruction decoders, disassemblers, JIT encoders, instruction interpreters and LaTeX documentation.

The suite contains simple decoupled libraries including an ELF parser, a functional metadata based RISC-V disassembler (riscv-parse-elf), an extensible source generator (riscv-parse-meta), an RVC compressor / decompressor (riscv-compress-elf) plus library routines and tools for generating statistics on RISC-V ELF executables (riscv-histogram-elf).

RISC-V Meta is the starting point for a RISC-V binary translation and security sandboxing investigation.

The future goals of the RISC-V Meta project are:

• Concise metadata representing the RISC-V ISA
• Tools for metadata-based generation of source and documentation
• Full color disassembler
• ELF Binary compressor, decompressor
• High performance emulation, sandboxing and binary translation
• RISC-V-(n) → RISC-V-(n+1)
• RISC-V-(n) → Intel i786 + AVX-512
• RISC-V Linux ABI emulation on MacOS, Windows, Linux and *BSD
• RISC-V Linux ABI randomisation and entropy coding
• RISC-V Specification undefined behaviour investigation
• RISC-V Virtualization and memory protection investigation

See RISC-V Instruction Set Listing for sample LaTeX output.

Screenshots

Example ASCII map output from make map

Example Instructions Histogram from riscv-histogram-elf

Example Registers Histogram from riscv-histogram-elf

Example Disassembly output from riscv-parse-elf

References

• lowRISC project
• Native Client x86-64 Sandbox
• Native Client ARM 32-bit Sandbox
• Design of the RISC-V Instruction Set Architecture
• RISC-V ISA Specification
• RISC-V Compressed ISA Specification
• RISC-V Privileged ISA Specification
• RISC-V ISA Simulator
• RISC-V Opcodes
• RISC-V LLVM
• RISC-V Clang
• Clang SafeStack
• musl libc
• Yocto Project
• Bit Twiddling Hacks
• The Netwide Assembler
• Complete x86/x64 JIT and Remote Assembler for C++
• Abstractions for Practical Virtual Machine Replay
• A Secure Processor Architecture for Encrypted Computation on Untrusted Programs
• SoK: Eternal War in Memory
• SoK: Introspections on Trust and the Semantic Gap
• Hacking Blind
• Code Pointer Integrity
• Geometric Memory Management
• Two-Level Segregated Fit memory allocator implementation
• TLSF: a New Dynamic Memory Allocator for Real-Time Systems
• A Precise Memory Model for Low-Level Bounded Model Checking
• IEEE Std 1003.1™, 2013 Edition
• Standard C++
• Exception Handling in LLVM
• ELF Handling for Thread-Local Storage
• DWARF Debugging Information Format Version 4
• The Error Model and other essays
• No sane compiler would optimize atomics
• A Guide to Undefined Behavior in C and C++ (part 1 part 2 part 3)

Project Structure

Directory	Description
meta	Instruction set metadata
src/abi	Application binary interface
src/app	Test programs and utilities
src/asm	Assembler metadata library
src/elf	ELF parser library
src/emu	ISA emulator headers
src/model	ISA metamodel library
src/util	Miscellaneous utilities library
doc/pdf	Generated documentation

Libraries

The following table shows the RISC-V Meta libraries:

Name	Description	Scale
libriscv_asm.a	disassembly formatting	micro
libriscv_elf.a	ELF parser	micro
libriscv_meta.a	instruction set metadata	nano
libriscv_model.a	instruction set metamodel	macro
libriscv_util.a	utility functions for tools	mini

The project code idiom is a subset of C++14 with STL, C struct with member functions, single inheritance, operator overloading, variadiac templates and template based static polymorphism. RTTI and exceptions are disallowed. C++ virtual functions are disallowed in nano, micro and mini. C++ virtual functions are currently present in src/gen but will be removed when static polymorphism is implemented for generators (virtual functions are discouraged). The use of stringstream is temporarily permitted in src/gen, src/model and src/util (mini and macro) until a variadic template based string formatter has been implemented.

Tools

The following table shows the RISC-V Meta tools:

Name	Description
riscv-parse-meta	generates source, headers and documentation
riscv-parse-elf	ELF parser and disassmbler tool
riscv-compress-elf	ELF compressor tool (work in progress)
riscv-histogram-elf	ELF histogram tool
riscv-test-emulate	Emulator Proof of Concept

Dependencies

• gmake
• gcc-5.4 or clang-3.4
• ragel (required to regenerate config grammar)
• riscv-gnu-toolchain (required for make test-emulate)
• Note: Set RISCV environment variable to point to toolchain

Supported Platforms

• Linux
• macOS
• FreeBSD
• Windows Services for Linux

Build Instructions

The meta compiler has been tested on Linux, Darwin and FreeBSD.

To print a colour opcode map: make map

To output a LaTeX opcode tex: make latex

To output a LaTeX opcode pdf: make pdf

To run the proof of concept emulator: make test-emulate

Parse ELF Utility

Parse ELF usage command line options:

usage: riscv-parse-elf [<options>] <elf_file>
                       --color, -c            Enable Color
            --print-elf-header, -e            Print ELF header
       --print-section-headers, -s            Print Section headers
       --print-program-headers, -p            Print Program headers
          --print-symbol-table, -t            Print Symbol Table
           --print-disassembly, -d            Print Disassembly
                   --no-pseudo, -x            Disable Pseudoinstructions
                   --print-all, -a            Print All
                        --help, -h            Show help

To run the ELF parser and disassembler:

# Requires RISC-V GNU Compiler Toolchain to build tests
make test-build-rv64
./build/darwin_x86_64/bin/riscv-parse-elf -c -a build/riscv64-unknown-elf/bin/hello-world-pcrel

Parse Meta Utility

Parse Meta usage command line options:

usage: riscv-parse-meta [<options>]
                        --help, -h            Show help
                  --isa-subset, -I <string>   ISA subset (e.g. RV32IMA, RV32G, RV32GSC, RV64IMA, RV64G, RV64GSC)
                    --read-isa, -r <string>   Read instruction set metadata from directory
                  --no-comment, -N            Don't emit comments in generated source
           --numeric-constants, -0            Use numeric constants in generated source
         --print-constraints-h, -XC           Print constraints header
            --print-fpu-test-h, -FH           Print FPU test header
            --print-fpu-test-c, -FC           Print FPU test source
              --print-interp-h, -V            Print interpreter header
                 --print-jit-h, -J            Print jit header
                --print-jit-cc, -K            Print jit source
   --substitute-question-marks, -?            Substitute question marks for zeros in LaTeX output
                 --print-latex, -l            Print LaTeX instruction listing
                       --color, -c            Enable ANSI color map
                   --print-map, -m            Print instruction map
      --print-map-pseudocode-c, -mc           Print instruction map with C pseudocode
    --print-map-pseudocode-alt, -ma           Print instruction map with alternate pseudocode
                --print-meta-h, -H            Print metadata header
               --print-meta-cc, -C            Print metadata source
            --print-operands-h, -A            Print operands header
             --print-strings-h, -SH           Print strings header
            --print-strings-cc, -SC           Print strings source
              --print-switch-h, -S            Print switch header

To print a colour opcode map for the RV32IMA ISA subset:

./build/darwin_x86_64/bin/riscv-parse-meta -I RV32IMA -m -c -r meta

To print a colour opcode map for the RV64IMAFDS ISA subset:

./build/darwin_x86_64/bin/riscv-parse-meta -I RV64IMAFDS -m -c -r meta

To output LaTeX for the RV32C ISA subset:

./build/darwin_x86_64/bin/riscv-parse-meta -I RV32C -l -r meta

To output LaTeX for the RV64G ISA subset:

./build/darwin_x86_64/bin/riscv-parse-meta -I RV64G -l -r meta

RISC-V Test Emulator

Emulator command line options:

usage: riscv-test-emulate [<options>] <elf_file>
                --memory-debug, -m            Memory debug
              --emulator-debug, -d            Emulator debug
                         --isa, -i <string>   ISA Extensions (IMA, IMAC, IMAFD, IMAFDC)
                  --privileged, -p            Privileged ISA Emulation
           --log-int-registers, -r            Log Integer Registers
         --log-float-registers, -F            Log SP Float Registers
        --log-double-registers, -D            Log DP Float Registers
            --log-instructions, -l            Log Instructions
                   --no-pseudo, -x            Disable Pseudoinstructions
                --log-operands, -o            Log Instructions and operands
                        --seed, -s <string>   Random seed
                        --help, -h            Show help

To run the simple Hello World program:

build/darwin_x86_64/bin/riscv-test-emulate build/riscv64-unknown-elf/bin/hello-world-libc

RISC-V ELF Histogram Utility

ELF Histogram usage command line options:

usage: riscv-histogram-elf [<options>] <elf_file>
                        --help, -h            Show help
                        --char, -c <string>   Character to use in bars
                        --bars, -b            Print bars next to counts
                --instructions, -I            Instruction Usage Histogram
                   --registers, -R            Register Usage Histogram
          --registers-operands, -P            Register Usage Histogram (with operand positions)
                   --max-chars, -m <string>   Maximum number of characters for bars
                --reverse-sort, -r            Sort in Reverse

To print the top 20 instructions in a RISC-V ELF binary:

./build/darwin_x86_64/bin/riscv-histogram-elf -b -c █ linux/vmlinux | head -20