byteman

Open-source high-performance bitstream manipulation framework.

Binaries

Windows
Linux

Description

byteman uses command line arguments and currently recognizes the following commands: -a/assembly -b/blank -c/change -d/device -e/exit -h/help -i/input -m/merge -o/output -r/region -s/stdin -v/verbose -w/warn. The description of what these commands do and how to use them is provided in the help messages of the program. You can find an up-to-date extraction of these messages below.

Publications

byteman: A Bitstream Manipulation Framework:

@inproceedings{manev2022byteman,
  author={Manev, Kristiyan and Powell, Joseph and M{\"a}tas, Kaspar and Koch, Dirk},
  title = {{byteman: A Bitstream Manipulation Framework}},
  booktitle={2022 International Conference on Field-Programmable Technology (FPT)},
  year={2022}
}

Get in Touch

If you would like to ask questions, report bugs or collaborate on research projects, please email any of the following:

Kristiyan Manev (knmanev@gmail.com)

Usage

$> byteman.exe -help

byteman 1.3 (Build #225, compiled on Nov 29 2022 12:58:10)
Usage:
  byteman.exe ARCH [-command...]* [-stdin]

  ARCH = {"Xilinx Series 7"/"XS7", "Xilinx UltraScale"/"XUS", "Xilinx UltraScale+ "/"XUSP"}

Commands:        : [Description]                                    
  -a (Assembly)  : (de)assemble bitstreams.       see "-help assembly"
  -b (Blank)     : erases bitstream buffers.      see "-help blank"
  -c (Change)    : modify bitstream.              see "-help change"
  -d (Device)    : manually select target device. see "-help device"
  -e (Exit)      : exit byteman. used with stdin. see "-help exit"
  -h (Help)      : get help.                      see "-help help"
  -i (Input)     : input bitstream.               see "-help input"
  -m (Merge)     : merge bitstreams.              see "-help merge"
  -o (Output)    : output bitstream.              see "-help output"
  -r (Region)    : modify region selection.       see "-help region"
  -s (Stdin)     : continue using standard input. see "-help stdin"
  -v (Verbose)   : enable/disable spam.           see "-help verbose"
  -w (Warn)      : enable/disable warnings.       see "-help warn"

Examples: 
  byteman.exe Xilinx US+ -w -i main static.bit -i temp filter.bit -merge logic 180:67 120:30 240:37 -o logic 240:37 120:30 relocatedFilter.bit
  byteman.exe XUSP -w -d ZCU 102 -b main, logic, blockram -i temp filter.bit -merge logic 180:67 120:30 180:67 -o logic 180:67 120:30 mergedFilter.bit

Need more help? Try one of these:
  byteman.exe -help <command>
  byteman.exe -help all
  byteman.exe Xilinx Series 7 -help all
  byteman.exe Xilinx UltraScale -help all
  byteman.exe Xilinx UltraScale+ -help all

$> byteman.exe -help assembly

byteman 1.3 (Build #225, compiled on Nov 29 2022 12:58:10)
  assembles and disassembles between bitstream files (.bit|.bin) and bitstream assembly (.bitasm) format.

  Usage:
    byteman.exe -assembly <InputBitstreamFileName> <OutputAssemblyFileName>
    byteman.exe -assembly <InputAssemblyFileName> <OutputBitstreamFileName>
  Args:
    <InputBitstreamFileName>: name of the input bitstream file. supports ".bit" and ".bin" file formats.
    <OutputBitstreamFileName>: name of the output bitstream file. supports ".bit" and ".bin" file formats.
    <InputAssemblyFileName>: name of the input assembly file. supports ".bitasm" file format.
    <OutputAssemblyFileName>: name of the output assembly file. supports ".bitasm" file format.

  the bitstream assembly files can be edited and converted back to valid bitstreams.
  in bitstream assembly file format:
    every line that doesn't start with '#' is editable.
    bitstream commands are written one per line and have the format "<COMMAND NAME>;"
    bitstream register writesare one per line and have the format "@<REGNAME> = <NEW REG VALUE>"

  Examples:
    byteman.exe XUSP -assembly bitstream.bit bitstream.bitasm

    byteman.exe Xilinx Series 7 -a bitstream.bitasm bitstream.bit

    # Generate a bitstream file and then convert it to bit assembly:
    byteman.exe Xilinx US -... -o bitstreamOut.bit -a bitstreamOut.bit bitstreamOut.bitasm

$> byteman.exe -help blank

byteman 1.3 (Build #225, compiled on Nov 29 2022 12:58:10)
  erases/sets the bitstream in the buffers. uses the list of selected regions (see "-help Region"). if the list is empty, works on the whole chip.

  Usage:
    byteman.exe -blank [First] [Second] [Logic] [Clock] [BlockRAM] [<BlankValue>]

  Args:
    [First]: selects the first of the two bitstream buffers. Enabled by default if no buffer is explicitly specified.
    [Second]: selects the second of the two bitstream buffers.
    [Logic]: selects the data excluding global clock from logic plane of the bitstream. Enabled by default if no plane is explicitly specified.
    [Clock]: selects the global clock data from logic plane of the bitstream. Enabled by default if no plane is explicitly specified.
    [BlockRAM]: selects the blockram contents plane of the bitstream. Enabled by default if no plane is explicitly specified.
    [<BlankValue>]: byte value (0-255) to be written in the selected bitstream location. Default is 0.

  Examples:
    # Blanks the bitstream's logic plane to zeroes:
    byteman.exe XUSP -blank main clb

    # All values in the rectangle describing Y from 100 to 149 and X from 7 to 21 are set to 0xA5A5A5A5:
    byteman.exe Xilinx Series 7 -r add 100:7 50:15 -b 0xA5

    # Blanks the bitstream to zeroes:
    byteman.exe Xilinx US -b

$> byteman.exe -help change

byteman 1.3 (Build #225, compiled on Nov 29 2022 12:58:10)
  modifies bitstream data.

  Usage:
    byteman.exe -change [First] [Second] [BigEndian, LittleEndian, BigEndianWithBitSwap, LittleEndianWithBitSwap, NativeEndian] [word <Y>:<X> <blockType> <frameOffset> <wordOffset> <mask> <value>]

  Args:
    [First]: selects the first of the two bitstream buffers. Enabled by default if no buffer is explicitly specified.
    [Second]: selects the second of the two bitstream buffers.
    [BigEndian]: forces the stored bitstream data is in Big Endian format. any future operations will inherit the endianness (such as -Output)
    [LittleEndian]: forces the stored bitstream data is in Little Endian format. any future operations will inherit the endianness (such as -Output)
    [BigEndianWithBitSwap]: forces the stored bitstream data is in Big Endian with Bit Swap format. any future operations will inherit the endianness (such as -Output)
    [LittleEndianWithBitSwap]: forces the stored bitstream data is in Little Endian with Bit Swap format. any future operations will inherit the endianness (such as -Output)
    [NativeEndian]: forces the stored bitstream data is in the native endianness of the system. any future operations will inherit the endianness (such as -Output)
    [word <Y>:<X> <blockType> <frameOffset> <wordOffset> <mask> <value>]: forces bitstream value <value> (masked by <mask>) to a word located at coordinates <Y>:<X> in block <blockType>
                                                                        : with internal offsets for the frame <frameOffset> and word <wordOffset>

  Examples:
    # reads a bitstream, forces big endianness, writes back the bitstream in the new endianness:
    byteman.exe XUS -input bitstream.bit -change bigEndian -output full bitstream.bit
    # reads a bitstream, forces little endianness, writes back the bitstream in the new endianness:
    byteman.exe xilinx series 7 -input boot.bin -change LITTLEendian -output full boot.bin
    # load a partial bitstream located at 180:0. targetting the third blockram left to right, located at 180:37.
    # modify its routing at the 3rd frame (frame offset 2) at the 41-st word (word offset 40)

Byteman

Install / Use

README