Command Line Usage

The Bronzebeard RISC-V assembler is a command line tool meant to be used from a terminal. As such, it has various parameters and flags that can be used to customize its inputs, outputs, and behavior.

usage: bronzebeard [-h] [-v] [-c] [-i DIR] [-o FILE] [-l FILE] [--hex-offset OFFSET]
                   [--include-definitions] [--version]
                   input_asm

Assemble RISC-V source code

positional arguments:
  input_asm             input source file

options:
  -h, --help            show this help message and exit
  -v, --verbose         verbose assembler output
  -c, --compress        identify and compress eligible instructions
  -i DIR, --include DIR
                        add a directory to the assembler search path
  -o FILE, --output FILE
                        output binary file (default "bb.out")
  -l FILE, --labels FILE
                        output resolved labels and their addresses
  --hex-offset OFFSET   output an additional Intel HEX file with the given offset
  --include-definitions
                        update the assembler search path to include common chip and
                        peripheral definitions
  --version             print assembler version and exit

Required Arguments

Input

An assembly source file to be assembled. This file may include other files but the assembly process originates from a single file.

bronzebeard my_asm_file.asm

Optional Arguments

Help

Print the assembler help message (shown above) and exit.

bronzebeard -h
bronzebeard --help

Verbose

Output various diagnostic and debugging messages while assembling the source code.

bronzebeard -v my_asm_file.asm
bronzebeard --verbose my_asm_file.asm

Compress

Identify and compress eligible RISC-V instructions. Note that while this option often reduces output binary size, compressed intructions may not be supported on all RV32 chips. Be sure to check for a C in the CPU description such as in RV32IMAC.

bronzebeard -c my_asm_file.asm
bronzebeard --compress my_asm_file.asm

Include

Add a directory to the assembler’s search path. This argument can be supplied multiple times and each invocation will add an additional directory to the search path. The search path is used by the assembler to find files specified by include directives within the source code.

bronzebeard -i foo/ -i bar/ my_asm_file.asm
bronzebeard --include foo/ --include bar/ my_asm_file.asm

Output

Specify the name and location of the output binary.

bronzebeard -o foo.out my_asm_file.asm
bronzebeard --output foo.out my_asm_file.asm

Labels

Output resolved labels and their addresses to a specified file.

bronzebeard -l labels.txt my_asm_file.asm
bronzebeard --labels labels.txt my_asm_file.asm

Hex Offset

Output an additional binary in the Intel HEX format with the provided offset. The output file will be named the same as the original binary but with a .hex suffix attached.

bronzebeard --hex-offset 0x08000000 my_asm_file.asm

Include Definitions

Update the assembler’s search path to include common chip and peripheral definitions. This feature exists to absolve every project from having to redefine the large set of unchanging contants present in each RISC-V chip’s documentation. You can browse which devices and constants are supported in the repo.

Once this argument is provided, you’ll still need to include the specific definitions file into your source code (include "GD32VF103.asm" for example).

bronzebeard --include-definitions my_asm_file.asm

Version

Print the assembler’s current version and exit.

bronzebeard --version