gen_trace.py

<<<<<<< HEAD

Script to generate human-readable instruction traces for Snitch.

This script takes a trace generated by a Snitch hart (see snitch_cc.sv) and transforms the additional decode stage info into meaningful annotation.

It also counts and computes various performance metrics for every execution region. An execution region is a sequence of instructions. Every mcycle CSR read instruction in your trace implicitly defines two execution regions, comprising respectively:

• all instructions executed before the read, up to the previous read or the first executed instruction
• all instructions executed after the read, up to the next read or the last executed instruction

Performance metrics are appended at the end of the generated trace and can optionally be dumped to a separate JSON file.

It also computes various performance metrics for every DMA transfer, provided that the Snitch core is equipped with a tightly-coupled DMA engine, and the DMA trace logged during simulation is fed to the tool. DMA performance metrics are dumped to a separate JSON file.

disasm_inst(hex_inst, mc_exec='llvm-mc', mc_flags='-disassemble -mcpu=snitch') cached

Disassemble a single RISC-V instruction using llvm-mc.

Source code in util/trace/gen_trace.py

@lru_cache
def disasm_inst(hex_inst, mc_exec='llvm-mc', mc_flags='-disassemble -mcpu=snitch'):
    """Disassemble a single RISC-V instruction using llvm-mc."""
    # Reverse the endianness of the hex instruction
    inst_fmt = ' '.join(f'0x{byte:02x}' for byte in bytes.fromhex(hex_inst)[::-1])

    # Use llvm-mc to disassemble the binary instruction
    result = subprocess.run(
        [mc_exec] + mc_flags.split(),
        input=inst_fmt,
        capture_output=True,
        text=True,
        check=True,
    )

    # Extract disassembled instruction from llvm-mc output
    return result.stdout.splitlines()[-1].strip().replace('\t', ' ')

flt_decode(val, fmt)

Interprets the binary encoding of an integer as a FP value.

Parameters:

Name	Type	Description	Default
val	int	The integer encoding of the FP variable to decode.	required
fmt	int	The floating point number format, as an index into the FLOAT_FMTS array.	required

Returns: The floating point value represented by the input integer.

Source code in util/trace/gen_trace.py

def flt_decode(val: int, fmt: int) -> float:
    """Interprets the binary encoding of an integer as a FP value.

    Args:
        val: The integer encoding of the FP variable to decode.
        fmt: The floating point number format, as an index into the
            `FLOAT_FMTS` array.
    Returns:
        The floating point value represented by the input integer.
    """
    # get format and bit vector
    w_exp, w_mnt = FLOAT_FMTS[fmt]
    width = 1 + w_exp + w_mnt
    bitstr = '{:064b}'.format(val)[-width:]
    # print(bitstr)
    # Read bit vector slices
    sgn = -1.0 if bitstr[0] == '1' else 1.0
    mnt = int(bitstr[w_exp + 1:], 2)
    exp_unb = int(bitstr[1:w_exp + 1], 2)
    # derive base and exponent
    bse = int('1' + bitstr[w_exp + 1:], 2) / (2**w_mnt)
    exp_bias = -(2**(w_exp - 1) - 1)
    exp = exp_unb + exp_bias
    # case analysis
    if exp_unb == 2**w_exp - 1:
        return sgn * float('inf' if mnt == 0 else 'nan')
    elif exp_unb == 0 and mnt == 0:
        return sgn * 0.0
    elif exp_unb == 0:
        return float(sgn * mnt / (2**w_mnt) * (2**(exp_bias + 1)))
    else:
        return float(sgn * bse * (2**exp))

flt_fmt(flt, width=6)

Formats a floating-point number rounding to a certain decimal precision.

Parameters:

Name	Type	Description	Default
flt	float	The floating-point number to format.	required
width	int	The number of significant decimal digits to round to.	6

Returns: The formatted floating-point number as a string.

Source code in util/trace/gen_trace.py

def flt_fmt(flt: float, width: int = 6) -> str:
    """Formats a floating-point number rounding to a certain decimal precision.

    Args:
        flt: The floating-point number to format.
        width: The number of significant decimal digits to round to.
    Returns:
        The formatted floating-point number as a string.
    """
    fmt = '{:.' + str(width) + '}'
    return fmt.format(flt)

flt_lit(num, fmt, width=6, vlen=1)

Formats an integer encoding into a floating-point literal.

Parameters:

Name	Type	Description	Default
num	int	The integer encoding of the floating-point number(s).	required
fmt	int	The floating point number format, as an index into the FLOAT_FMTS array.	required
width	int	The number of significant decimal digits to round to.	6
vlen	int	The number of floating-point numbers packed in the encoding, 1 for SIMD vectors.	1

Source code in util/trace/gen_trace.py

def flt_lit(num: int, fmt: int, width: int = 6, vlen: int = 1) -> str:
    """Formats an integer encoding into a floating-point literal.

    Args:
        num: The integer encoding of the floating-point number(s).
        fmt: The floating point number format, as an index into the
            `FLOAT_FMTS` array.
        width: The number of significant decimal digits to round to.
        vlen: The number of floating-point numbers packed in the encoding,
            >1 for SIMD vectors.
    """
    # Divide the binary encoding into individual encodings for each number in the SIMD vector.
    bitwidth = 1 + FLOAT_FMTS[fmt][0] + FLOAT_FMTS[fmt][1]
    vec = [num >> (bitwidth * i) & (2**bitwidth - 1) for i in reversed(range(vlen))]
    # Format each individual float encoding to a string.
    floats = [flt_fmt(flt_decode(val, fmt), width) for val in vec]
    # Represent the encodings as a vector if SIMD.
    if len(floats) > 1:
        return '[{}]'.format(', '.join(floats))
    else:
        return floats[0]

flt_op_fmt(extras, port)

Extracts the floating-point format of an instruction operand.

Parameters:

Name	Type	Description	Default
extras	dict	The dictionary containing the instruction's extra information.	required
port	int	The index of the floating-point operand.	required

Source code in util/trace/gen_trace.py

def flt_op_fmt(extras: dict, port: int) -> int:
    """Extracts the floating-point format of an instruction operand.

    Args:
        extras: The dictionary containing the instruction's extra
            information.
        port: The index of the floating-point operand.
    """
    op_sel = extras['op_sel_{}'.format(port)]
    oper_type = FPU_OPER_TYPES[op_sel]
    if extras['is_store']:
        return LS_TO_FLOAT[extras['ls_size']]
    else:
        if oper_type == 'rd':
            return extras['dst_fmt']
        else:
            return extras['src_fmt']

flt_op_vlen(insn, op_type)

Get the vector length of a floating-point instruction operand.

Parameters:

Name	Type	Description	Default
insn	str	Instruction as extracted from the trace line.	required
op_type	str	One of the operand types defined in FPU_OPER_TYPES.	required

Returns: The vector length of the operand, greater than one if SIMD.

Source code in util/trace/gen_trace.py

def flt_op_vlen(insn: str, op_type: str) -> int:
    """Get the vector length of a floating-point instruction operand.

    Args:
        insn: Instruction as extracted from the trace line.
        op_type: One of the operand types defined in `FPU_OPER_TYPES`.
    Returns:
        The vector length of the operand, greater than one if SIMD.
    """
    global _cached_opcodes
    if _cached_opcodes is None:
        load_opcodes()

    # Cut the instruction after the first space to get the instruction name
    insn = insn.split(' ')[0]

    # Check if operand is a source or a destination
    is_rd = (op_type == 'rd')

    # Get operand parameters from the instruction
    op_params = _cached_opcodes.get(insn, None)

    # Get vector length of operand
    if op_params is not None and op_params != ([''] * 4):
        vlen = int(op_params[3]) if is_rd else int(op_params[1])
    else:
        vlen = 1
    return vlen

flt_oper(insn, extras, port)

Extracts details on the floating-point operand of an instruction.

Parameters:

Name	Type	Description	Default
insn	str	The current instruction mnemonic.	required
extras	dict	The dictionary containing the instruction's extra information.	required
port	int	The index of the floating-point operand.	required

Returns: A tuple containing the operand's register name and a string literal representing the floating-point value.

Source code in util/trace/gen_trace.py

def flt_oper(insn: str, extras: dict, port: int) -> (str, str):
    """Extracts details on the floating-point operand of an instruction.

    Args:
        insn: The current instruction mnemonic.
        extras: The dictionary containing the instruction's extra
            information.
        port: The index of the floating-point operand.
    Returns:
        A tuple containing the operand's register name and a string
        literal representing the floating-point value.
    """
    op_sel = extras['op_sel_{}'.format(port)]
    oper_type = FPU_OPER_TYPES[op_sel]

    # Assign default return values
    reg = oper_type
    lit = None

    # If operand comes from accelerator interface, format as integer.
    if oper_type == 'acc':
        reg = 'ac{}'.format(port + 1)
        lit = int_lit(extras['acc_qdata_{}'.format(port)], extras['int_fmt'])
    # If operand is not unspecified, format as floating-point.
    elif oper_type != 'NONE':
        # Get operand vector length, FP format and integer encoding
        vlen = flt_op_vlen(insn, oper_type)
        fmt = flt_op_fmt(extras, port)
        enc = extras['op_{}'.format(port)]
        # Return register name and floating-point literal
        return REG_ABI_NAMES_F[extras[oper_type]], flt_lit(enc, fmt, vlen=vlen)
    return reg, lit

fpu_operand_lit(num, fmt, is_vector, is_int)

Formats an FPU operand's data.

Parameters:

Name	Type	Description	Default
num		The integer encoding of the floating-point number(s).	required
fmt		The floating point number format, as an index into the FLOAT_FMTS array.	required
width		The bitwidth of the floating-point type.	required
vlen		The number of floating-point numbers packed in the encoding, 1 for SIMD vectors.	required

Source code in util/trace/gen_trace.py

def fpu_operand_lit(num, fmt, is_vector, is_int) -> str:
    """Formats an FPU operand's data.

    Args:
        num: The integer encoding of the floating-point number(s).
        fmt: The floating point number format, as an index into the
             `FLOAT_FMTS` array.
        width: The bitwidth of the floating-point type.
        vlen: The number of floating-point numbers packed in the encoding,
            >1 for SIMD vectors.
    """
    if is_int:
        vlen = INT_VLEN[fmt] if is_vector else 1
        return int_lit(num, 3, vlen)
    else:
        vlen = FP_VLEN[fmt] if is_vector else 1
        return flt_lit(num, fmt, 6, vlen)

int_lit(num, size=2, vlen=1, as_hex=None)

Formats integer data.

Parameters:

Name	Type	Description	Default
num	int	The integer data to format.	required
size	int	log2 of the size in bytes of each number (in the vector).	2
vlen	int	The number of numbers packed in the encoding, 1 for SIMD vectors.	1
as_hex	Optional[bool]	If True, always format as hex.	None

Source code in util/trace/gen_trace.py

def int_lit(num: int, size: int = 2, vlen: int = 1, as_hex: Optional[bool] = None) -> str:
    """Formats integer data.

    Args:
        num: The integer data to format.
        size: log2 of the size in bytes of each number (in the vector).
        vlen: The number of numbers packed in the encoding,
              >1 for SIMD vectors.
        as_hex: If True, always format as hex.
    """
    ints = []
    bitwidth = (8 * int(2**size))
    for i in reversed(range(vlen)):
        slice = num >> (bitwidth * i) & (2**bitwidth - 1)
        slice_signed = c_int32(c_uint32(slice).value).value
        if as_hex is True or abs(slice_signed) > MAX_SIGNED_INT_LIT and as_hex is not False:
            ints.append('0x{0:0{1}x}'.format(slice, bitwidth // 4))
        else:
            ints.append(str(slice_signed))
    # Represent the encodings as a vector if SIMD.
    if len(ints) > 1:
        return '[{}]'.format(', '.join(ints))
    else:
        return ints[0]

=======

Script to generate human-readable instruction traces for Snitch.

This script takes a trace generated by a Snitch hart (see snitch_cc.sv) and transforms the additional decode stage info into meaningful annotation.

It also counts and computes various performance metrics for every execution region. An execution region is a sequence of instructions. Every mcycle CSR read instruction in your trace implicitly defines two execution regions, comprising respectively:

• all instructions executed before the read, up to the previous read or the first executed instruction
• all instructions executed after the read, up to the next read or the last executed instruction

Performance metrics are appended at the end of the generated trace and can optionally be dumped to a separate JSON file.

It also computes various performance metrics for every DMA transfer, provided that the Snitch core is equipped with a tightly-coupled DMA engine, and the DMA trace logged during simulation is fed to the tool. DMA performance metrics are dumped to a separate JSON file.

disasm_inst(hex_inst, mc_exec='llvm-mc', mc_flags='-disassemble -mcpu=snitch') cached

Disassemble a single RISC-V instruction using llvm-mc.

Source code in util/trace/gen_trace.py

@lru_cache
def disasm_inst(hex_inst, mc_exec='llvm-mc', mc_flags='-disassemble -mcpu=snitch'):
    """Disassemble a single RISC-V instruction using llvm-mc."""
    # Reverse the endianness of the hex instruction
    inst_fmt = ' '.join(f'0x{byte:02x}' for byte in bytes.fromhex(hex_inst)[::-1])

    # Use llvm-mc to disassemble the binary instruction
    result = subprocess.run(
        [mc_exec] + mc_flags.split(),
        input=inst_fmt,
        capture_output=True,
        text=True,
        check=True,
    )

    # Extract disassembled instruction from llvm-mc output
    return result.stdout.splitlines()[-1].strip().replace('\t', ' ')

flt_decode(val, fmt)

Interprets the binary encoding of an integer as a FP value.

Parameters:

Name	Type	Description	Default
val	int	The integer encoding of the FP variable to decode.	required
fmt	int	The floating point number format, as an index into the FLOAT_FMTS array.	required

Returns: The floating point value represented by the input integer.

Source code in util/trace/gen_trace.py

def flt_decode(val: int, fmt: int) -> float:
    """Interprets the binary encoding of an integer as a FP value.

    Args:
        val: The integer encoding of the FP variable to decode.
        fmt: The floating point number format, as an index into the
            `FLOAT_FMTS` array.
    Returns:
        The floating point value represented by the input integer.
    """
    # get format and bit vector
    w_exp, w_mnt = FLOAT_FMTS[fmt]
    width = 1 + w_exp + w_mnt
    bitstr = '{:064b}'.format(val)[-width:]
    # print(bitstr)
    # Read bit vector slices
    sgn = -1.0 if bitstr[0] == '1' else 1.0
    mnt = int(bitstr[w_exp + 1:], 2)
    exp_unb = int(bitstr[1:w_exp + 1], 2)
    # derive base and exponent
    bse = int('1' + bitstr[w_exp + 1:], 2) / (2**w_mnt)
    exp_bias = -(2**(w_exp - 1) - 1)
    exp = exp_unb + exp_bias
    # case analysis
    if exp_unb == 2**w_exp - 1:
        return sgn * float('inf' if mnt == 0 else 'nan')
    elif exp_unb == 0 and mnt == 0:
        return sgn * 0.0
    elif exp_unb == 0:
        return float(sgn * mnt / (2**w_mnt) * (2**(exp_bias + 1)))
    else:
        return float(sgn * bse * (2**exp))

flt_fmt(flt, width=6)

Formats a floating-point number rounding to a certain decimal precision.

Parameters:

Name	Type	Description	Default
flt	float	The floating-point number to format.	required
width	int	The number of significant decimal digits to round to.	6

Returns: The formatted floating-point number as a string.

Source code in util/trace/gen_trace.py

def flt_fmt(flt: float, width: int = 6) -> str:
    """Formats a floating-point number rounding to a certain decimal precision.

    Args:
        flt: The floating-point number to format.
        width: The number of significant decimal digits to round to.
    Returns:
        The formatted floating-point number as a string.
    """
    fmt = '{:.' + str(width) + '}'
    return fmt.format(flt)

flt_lit(num, fmt, width=6, vlen=1)

Formats an integer encoding into a floating-point literal.

Parameters:

Name	Type	Description	Default
num	int	The integer encoding of the floating-point number(s).	required
fmt	int	The floating point number format, as an index into the FLOAT_FMTS array.	required
width	int	The number of significant decimal digits to round to.	6
vlen	int	The number of floating-point numbers packed in the encoding, 1 for SIMD vectors.	1

Source code in util/trace/gen_trace.py

def flt_lit(num: int, fmt: int, width: int = 6, vlen: int = 1) -> str:
    """Formats an integer encoding into a floating-point literal.

    Args:
        num: The integer encoding of the floating-point number(s).
        fmt: The floating point number format, as an index into the
            `FLOAT_FMTS` array.
        width: The number of significant decimal digits to round to.
        vlen: The number of floating-point numbers packed in the encoding,
            >1 for SIMD vectors.
    """
    # Divide the binary encoding into individual encodings for each number in the SIMD vector.
    bitwidth = 1 + FLOAT_FMTS[fmt][0] + FLOAT_FMTS[fmt][1]
    vec = [num >> (bitwidth * i) & (2**bitwidth - 1) for i in reversed(range(vlen))]
    # Format each individual float encoding to a string.
    floats = [flt_fmt(flt_decode(val, fmt), width) for val in vec]
    # Represent the encodings as a vector if SIMD.
    if len(floats) > 1:
        return '[{}]'.format(', '.join(floats))
    else:
        return floats[0]

flt_op_fmt(extras, port)

Extracts the floating-point format of an instruction operand.

Parameters:

Name	Type	Description	Default
extras	dict	The dictionary containing the instruction's extra information.	required
port	int	The index of the floating-point operand.	required

Source code in util/trace/gen_trace.py

def flt_op_fmt(extras: dict, port: int) -> int:
    """Extracts the floating-point format of an instruction operand.

    Args:
        extras: The dictionary containing the instruction's extra
            information.
        port: The index of the floating-point operand.
    """
    op_sel = extras['op_sel_{}'.format(port)]
    oper_type = FPU_OPER_TYPES[op_sel]
    if extras['is_store']:
        return LS_TO_FLOAT[extras['ls_size']]
    else:
        if oper_type == 'rd':
            return extras['dst_fmt']
        else:
            return extras['src_fmt']

flt_op_vlen(insn, op_type)

Get the vector length of a floating-point instruction operand.

Parameters:

Name	Type	Description	Default
insn	str	Instruction as extracted from the trace line.	required
op_type	str	One of the operand types defined in FPU_OPER_TYPES.	required

Returns: The vector length of the operand, greater than one if SIMD.

Source code in util/trace/gen_trace.py

def flt_op_vlen(insn: str, op_type: str) -> int:
    """Get the vector length of a floating-point instruction operand.

    Args:
        insn: Instruction as extracted from the trace line.
        op_type: One of the operand types defined in `FPU_OPER_TYPES`.
    Returns:
        The vector length of the operand, greater than one if SIMD.
    """
    global _cached_opcodes
    if _cached_opcodes is None:
        load_opcodes()

    # Cut the instruction after the first space to get the instruction name
    insn = insn.split(' ')[0]

    # Check if operand is a source or a destination
    is_rd = (op_type == 'rd')

    # Get operand parameters from the instruction
    op_params = _cached_opcodes.get(insn, None)

    # Get vector length of operand
    if op_params is not None and op_params != ([''] * 4):
        vlen = int(op_params[3]) if is_rd else int(op_params[1])
    else:
        vlen = 1
    return vlen

flt_oper(insn, extras, port)

Extracts details on the floating-point operand of an instruction.

Parameters:

Name	Type	Description	Default
insn	str	The current instruction mnemonic.	required
extras	dict	The dictionary containing the instruction's extra information.	required
port	int	The index of the floating-point operand.	required

Returns: A tuple containing the operand's register name and a string literal representing the floating-point value.

Source code in util/trace/gen_trace.py

def flt_oper(insn: str, extras: dict, port: int) -> (str, str):
    """Extracts details on the floating-point operand of an instruction.

    Args:
        insn: The current instruction mnemonic.
        extras: The dictionary containing the instruction's extra
            information.
        port: The index of the floating-point operand.
    Returns:
        A tuple containing the operand's register name and a string
        literal representing the floating-point value.
    """
    op_sel = extras['op_sel_{}'.format(port)]
    oper_type = FPU_OPER_TYPES[op_sel]

    # Assign default return values
    reg = oper_type
    lit = None

    # If operand comes from accelerator interface, format as integer.
    if oper_type == 'acc':
        reg = 'ac{}'.format(port + 1)
        lit = int_lit(extras['acc_qdata_{}'.format(port)], extras['int_fmt'])
    # If operand is not unspecified, format as floating-point.
    elif oper_type != 'NONE':
        # Get operand vector length, FP format and integer encoding
        vlen = flt_op_vlen(insn, oper_type)
        fmt = flt_op_fmt(extras, port)
        enc = extras['op_{}'.format(port)]
        # Return register name and floating-point literal
        return REG_ABI_NAMES_F[extras[oper_type]], flt_lit(enc, fmt, vlen=vlen)
    return reg, lit

fpu_operand_lit(num, fmt, is_vector, is_int)

Formats an FPU operand's data.

Parameters:

Name	Type	Description	Default
num		The integer encoding of the floating-point number(s).	required
fmt		The floating point number format, as an index into the FLOAT_FMTS array.	required
width		The bitwidth of the floating-point type.	required
vlen		The number of floating-point numbers packed in the encoding, 1 for SIMD vectors.	required

Source code in util/trace/gen_trace.py

def fpu_operand_lit(num, fmt, is_vector, is_int) -> str:
    """Formats an FPU operand's data.

    Args:
        num: The integer encoding of the floating-point number(s).
        fmt: The floating point number format, as an index into the
             `FLOAT_FMTS` array.
        width: The bitwidth of the floating-point type.
        vlen: The number of floating-point numbers packed in the encoding,
            >1 for SIMD vectors.
    """
    if is_int:
        vlen = INT_VLEN[fmt] if is_vector else 1
        return int_lit(num, 3, vlen)
    else:
        vlen = FP_VLEN[fmt] if is_vector else 1
        return flt_lit(num, fmt, 6, vlen)

int_lit(num, size=2, vlen=1, as_hex=None)

Formats integer data.

Parameters:

Name	Type	Description	Default
num	int	The integer data to format.	required
size	int	log2 of the size in bytes of each number (in the vector).	2
vlen	int	The number of numbers packed in the encoding, 1 for SIMD vectors.	1
as_hex	Optional[bool]	If True, always format as hex.	None

Source code in util/trace/gen_trace.py

def int_lit(num: int, size: int = 2, vlen: int = 1, as_hex: Optional[bool] = None) -> str:
    """Formats integer data.

    Args:
        num: The integer data to format.
        size: log2 of the size in bytes of each number (in the vector).
        vlen: The number of numbers packed in the encoding,
              >1 for SIMD vectors.
        as_hex: If True, always format as hex.
    """
    ints = []
    bitwidth = (8 * int(2**size))
    for i in reversed(range(vlen)):
        slice = num >> (bitwidth * i) & (2**bitwidth - 1)
        slice_signed = c_int32(c_uint32(slice).value).value
        if as_hex is True or abs(slice_signed) > MAX_SIGNED_INT_LIT and as_hex is not False:
            ints.append('0x{0:0{1}x}'.format(slice, bitwidth // 4))
        else:
            ints.append(str(slice_signed))
    # Represent the encodings as a vector if SIMD.
    if len(ints) > 1:
        return '[{}]'.format(', '.join(ints))
    else:
        return ints[0]

c744477... trace: Refactor and prepare for DMA trace generation