Common APIs
comm Module
The comm module provides some commonly used APIs, which can be called in the following ways:
# import all
from comm import *
# or direct import functions you need
from comm import function_you_need
# or access from module
import comm
comm.function_you_need()
cfg Submodule
get_config(cfg=None)
Get the current Config configuration
- Input: If cfg is not empty, return cfg. Otherwise, automatically get the global Config via toffee.
- Return: Config object
import comm
cfg = comm.get_config()
print(cfg.rtl.version)
cfg_as_str(cfg: CfgObject)
Convert the config object to a string type
- Input: Config object
- Return: Encoded Config object
import comm
cfg_str = comm.cfg_as_str(comm.get_config())
cfg_from_str(cfg_str)
Restore the Config object from a string
- Input: Encoded Config object
- Return: Config object
import comm
cfg = comm.cfg_from_str(cfg_str)
dump_cfg(cfg: CfgObject = None, cfg_file=None)
Save the config object to a file
- Input:
- cfg: the config to save
- cfg_file: target file
import comm
cfg = comm.get_config()
comm.dump_cfg(cfg, "config.yaml")
functions Submodule
get_log_dir(subdir="", cfg=None)
Get the log directory
- Input:
- subdir: subdirectory
- cfg: config file
- Output: log directory
import comm
my_log = comm.get_log_dir("my_log")
print(my_log) # /workspace/UnityChipForXiangShan/out/log/my_log
get_out_dir(subdir="", cfg=None)
Get the output directory
- Input:
- subdir: subdirectory
- cfg: config file
- Output: output directory
get_rtl_dir(subdir="", cfg=None)
Get the RTL directory
- Input:
- subdir: subdirectory
- cfg: config file
- Output: RTL directory
get_root_dir(subdir="")
Get the root directory:
- Input: subdirectory under the root directory
- Output: root directory of the current repository
is_all_file_exist(files_to_check, dir)
Check whether all files exist in the specified directory
- Input:
- files_to_check: list of files to check
- dir: target directory
- Output: whether all exist; returns False if any file does not exist
time_format(seconds=None, fmt="%Y%m%d-%H%M%S")
Format time
- Input:
- seconds: time to format, None means current time
- fmt: time format
- Return: formatted time string
import comm
import time
print(time_format(time.time())) # 20241202-083726
base64_encode(input_str)
Base64 encode:
- Input: string to encode
- Output: encoded string
import comm
print(comm.base64_encode("test")) # dGVzdA==
base64_decode(base64_str)
Base64 decode:
- Input: base64 encoded string
- Output: decoded original string
import comm
print(comm.base64_decode("dGVzdA==")) # test
exe_cmd(cmd, no_log=False)
Execute an OS command:
- Input:
- cmd: OS command to execute
- no_log: whether to return command line output
- Output: success, stdout, stderr
- success: whether the command executed successfully
- command standard output string (forced to empty if no_log=True)
- command standard error string (forced to empty if no_log=True)
import comm
su, st, er = exe_cmd("pwd")
print(st)
get_git_commit()
Get the current repository git commit hash
get_git_branch()
Get the current repository git branch name
UT_FCOV(group, ignore_prefix=“ut_”)
Get function coverage group
- Input:
- group: group name
- ignore_prefix: prefix to remove
- Output: coverage group name with module prefix
For example, called in ut_backend/ctrl_block/decode/env/decode_wrapper.py
:
print(UT_FCOV("../../INT"))
# out
backend.ctrl_block.decode.INT
get_version_checker(target_version)
Get version check function
- Input: target version string
- Output: check function
The returned check function is usually used for version checking in fixtures.
import comm
import pytest
checker = comm.get_version_checker("openxiangshan-kmh-24092701+")
@pytest.fixture
def fixture():
checker()
...
module_name_with(names, prefix=None)
Add a module prefix to names
- Input:
- names: list of strings to add prefix to
- prefix: module prefix
- Return: list of strings with prefix added
For example, called in a/b/c/d/e.py:
import comm
print(comm.module_name_with(["X", "Y"], "../../x"))
# out
["a.b.c.x.X", "a.b.c.x.Y"]
get_all_rtl_files(top_module, cfg)
Get a list of all RTL files (.v
or .sv
) that the module named top_module
depends on, and ensure that the first element of the list is the absolute path of the file where top_module
is located. All RTL files are located in the UnityChipForXiangShan/rtl/rtl
directory.
-
Input:
top_module
: module name, typestr
cfg
: config info, typeCfgObject
-
Output:
- Returns a list of strings, each string is the absolute path of an RTL file that the module depends on. The first element of the list is the path of the file where
top_module
is located.
- Returns a list of strings, each string is the absolute path of an RTL file that the module depends on. The first element of the list is the path of the file where
Suppose top_module
is "ALU"
, and its dependent RTL files include ALU.sv
, adder.v
, and multiplier.v
:
paths = get_all_rtl_files("ALU", cfg)
"""
Possible contents of paths:
[
"/path/to/UnityChipForXiangShan/rtl/rtl/ALU.sv",
"/path/to/UnityChipForXiangShan/rtl/rtl/adder.v",
"/path/to/UnityChipForXiangShan/rtl/rtl/multiplier.v"
]
"""