asciidoc_utils.py

import logging
import os
import pprint

from constants import causes, csrs, csrs32
from shared_utils import InstrDict, arg_lut

pp = pprint.PrettyPrinter(indent=2)
logging.basicConfig(level=logging.INFO, format="%(levelname)s:: %(message)s")


def make_asciidoc(instr_dict: InstrDict):
    """
    Generates an AsciiDoc representation of the encoding details.

    Args:
        instr_dict (InstrDict): Dictionary containing instruction encoding details.
    """
    # Generate commit information
    commit = os.popen('git log -1 --format="format:%h"').read()

    # Generate the preamble
    preamble = f"""// SPDX-License-Identifier: BSD-3-Clause
//
// Copyright (c) 2023 RISC-V International
//
// This document is auto-generated by running 'make' in
// https://github.com/riscv/riscv-opcodes ({commit})
//

= RISC-V Encoding Details

This document describes the RISC-V instruction encodings, CSR names, causes, and instruction field arguments.

"""

    # Generate encoding match and mask section
    encoding_section = '== Instruction Encodings\n\n[cols="2,3"]\n|===\n| Instruction | Encoding Details\n'
    for i in instr_dict:
        match = instr_dict[i]["match"]
        mask = instr_dict[i]["mask"]
        encoding_section += (
            f"| {i.upper().replace('.', '_')}\n| MATCH = `{match}`, MASK = `{mask}`\n"
        )
    encoding_section += "|===\n\n"

    # Generate CSR names section
    csr_section = '== Control and Status Registers (CSRs)\n\n[cols="2,3"]\n|===\n| CSR Name | Hex Value\n'
    for num, name in csrs + csrs32:
        csr_section += f"| {name.upper()} \n| `{hex(num)}`\n"
    csr_section += "|===\n\n"

    # Generate causes section
    causes_section = '== Causes\n\n[cols="2,3"]\n|===\n| Cause Name | Hex Value\n'
    for num, name in causes:
        causes_section += f"| {name.upper().replace(' ', '_')}\n| `{hex(num)}`\n"
    causes_section += "|===\n\n"

    # Generate instruction field arguments section
    arg_section = (
        '== Instruction Field Arguments\n\n[cols="2,3"]\n|===\n| Field Name | Mask\n'
    )
    for name, rng in arg_lut.items():
        sanitized_name = name.replace(" ", "_").replace("=", "_eq_")
        begin = rng[1]
        end = rng[0]
        mask = ((1 << (end - begin + 1)) - 1) << begin
        arg_section += f"| {sanitized_name.upper()}\n| `{hex(mask)}`\n"
    arg_section += "|===\n\n"

    # Combine all sections
    output_str = (
        f"{preamble}{encoding_section}{csr_section}{causes_section}{arg_section}"
    )

    # Write the AsciiDoc output to a file
    output_path = "encoding.adoc"
    with open(output_path, "w", encoding="utf-8") as adoc_file:
        adoc_file.write(output_str)