From caad8cfaabd6f8489cc9be3792ed51cbb00962e4 Mon Sep 17 00:00:00 2001 From: Neel Gala Date: Wed, 7 Sep 2022 17:04:25 +0530 Subject: [PATCH 1/6] modified functions to use the new warl_class from riscv-config-3.0.0+ --- riscof/framework/test.py | 130 ++++++++++++++++++++------------------- 1 file changed, 66 insertions(+), 64 deletions(-) diff --git a/riscof/framework/test.py b/riscof/framework/test.py index 8ccde63..5ec32a9 100644 --- a/riscof/framework/test.py +++ b/riscof/framework/test.py @@ -13,7 +13,8 @@ from riscof.utils import yaml import riscof.utils as utils import riscof.constants as constants -from riscv_config.warl import warl_interpreter +from riscv_config.warl import warl_class +from riscv_config.isa_validator import get_extension_list logger = logging.getLogger(__name__) @@ -96,38 +97,38 @@ def eval_cond(condition, spec): the given specifications or not. ''' condition = (condition.replace("check", '')).strip() - if 'writable' in condition: + if 'range_writable' in condition: parts = condition.split("=") - func_args = ((parts[0].replace("writable(","")).replace(")","")).split(",") - if writable(spec,int(func_args[0]),func_args[1]) == eval(parts[1]): + func_args = ((parts[0].replace("range_writable(","")).replace(")","")).split(",") + if range_writable(spec,int(func_args[0]),func_args[1], func_args[2]) == eval(parts[1]): return True else: return False elif 'islegal' in condition: func_args = ((condition.replace("islegal(","")).replace(")","")).split(",") try: - spec = get_node(spec,func_args[2]) + node = get_node(spec,func_args[2]) except KeyError: return False - if 'warl' in spec['type']: - warl = warl_interpreter(spec['type']['warl']) - deps = warl.dependencies() - return warl.islegal(func_args[0],eval(func_args[1])) + if 'warl' in node['type']: + warl = warl_class(node['type']['warl'], "".join(func_args[2]),node['msb'], node['lsb'], spec) + err = warl.islegal(func_args[0], eval(func_args[1])) + return not bool(err) return False elif ':=' in condition: temp = condition.split(":=") try: - spec = get_node(spec,temp[0]) + node = get_node(spec,temp[0]) except KeyError: return False if "regex(" in temp[1]: exp = temp[1].replace("regex(", "r\"")[:-1] + ("\"") - x = re.match(eval(exp), spec) + x = re.match(eval(exp), node) if x is None: return False else: return True - elif ast.literal_eval(temp[1]) == spec: + elif ast.literal_eval(temp[1]) == node: return True else: return False @@ -144,69 +145,71 @@ def eval_cond(condition, spec): def getlegal(spec,dep_vals,num,node): end_vals = [] + csrname = node.split('>')[0] try: - spec = get_node(spec,node) + node= get_node(spec,node) except KeyError: return [] - if 'warl' in spec['type']: - warl = (warl_interpreter(spec['type']['warl'])) - deps = warl.dependencies() - vals = warl.legal(eval(dep_vals)) - end_vals = [ hex(int(li[0],base=16)<')[0] try: - spec = get_node(spec,node) + csrnode = get_node(spec,node) except KeyError: return False - - bit_width = spec['msb']-spec['lsb']+1 - if bit>bit_width: + bit_width = csrnode['msb']-csrnode['lsb']+1 + range_msb = bits.split(':')[0] + range_lsb = bits.split(':')[1] if ':' in bits else range_msb + range_mask = int("0b"+"".join(['1']*(range_msb-range_lsb+1)),0)< bit_width or range_lsb > bit_width: + return False + if 'ro_' in csrnode['type']: + return False + elif 'warl' in csrnode['type']: + warl = warl_class(node['type']['warl'], csrname,node['msb'], node['lsb'], spec) + val = warl.getlegal([]) + new_val = val ^ range_mask + err = warl.islegal(new_val, dep_vals) + return not bool(err) + else: return False - if 'warl' in spec['type']: - warl = (warl_interpreter(spec['type']['warl'])) - deps = warl.dependencies() - vals = warl.legal([]) - legal = [ bin(int(li[0],base=16))[2:].zfill(bit_width) if '0x' in li[0] else bin(int(li[0]))[2:].zfill(bit_width) for li in vals ] - if any([x[bit_width-bit-1]=='1' for x in legal]) and any([x[bit_width-bit-1]=='0' for x in legal]): - return True - else: - return False def getillegal(spec,dep_vals,num,node): - end_vals = [] - legal = [] + csrname = node.split('>')[0] try: - spec = get_node(spec,node) + csrnode = get_node(spec,node) except KeyError: return [] - bit_width = spec['msb']-spec['lsb']+1 - if 'warl' in spec['type']: - warl = (warl_interpreter(spec['type']['warl'])) - deps = warl.dependencies() - vals = warl.legal(eval(dep_vals)) - legal = [ bin(int(li[0],base=16))[2:].zfill(bit_width) if '0x' in li[0] else bin(int(li[0]))[2:].zfill(bit_width) for li in vals ] - elif 'ro_constant' in spec['type']: - legal = [bin(spec['type']['ro_constant'][0])[2:].zfill(bit_width)] - num = int(num) - if legal: + bitlen = csrnode['msb'] - csr['lsb'] + 1 + end_vals = [] + if 'warl' in csrnode['type']: + warl = warl_class(csrnode['type']['warl'], csrname, csrnode['msb'], csrnode['lsb'], spec) + tries = 0 + while len(end_vals) < num and tries < 2**num: + random_val = random.randint(0,(2**bitlen)-1) + err = warl.islegal(random_val, dep_vals) + if err: + end_vals.append(random_val) + tries += 1 + elif 'ro_constant' in csrnode['type']: + constant_val = csrnode['type']['ro_constant'] while len(end_vals) < num: - random.seed(datetime.now()) - flip_bits = random.sample(list(range(0,bit_width)),random.randint(0,bit_width-1)) - val = legal[random.randint(0,len(legal)-1)] - flip = lambda x: '1' if x=='0' else '0' - ill_val = ''.join([flip(val[i]) if i in flip_bits else val[i] for i in range(0,bit_width)]) - if ill_val not in legal: - end_vals.append(ill_val) - end_vals = [hex(int(x,base=2)< Date: Wed, 7 Sep 2022 17:05:26 +0530 Subject: [PATCH 2/6] modified prod_isa to use riscv-config isa_validator This function will now pick the first RVTEST_ISA string that is a proper subset of the dut_isa --- riscof/framework/test.py | 57 ++++++++-------------------------------- 1 file changed, 11 insertions(+), 46 deletions(-) diff --git a/riscof/framework/test.py b/riscof/framework/test.py index 5ec32a9..0401c78 100644 --- a/riscof/framework/test.py +++ b/riscof/framework/test.py @@ -249,36 +249,6 @@ def eval_macro(macro, spec): else: return (False,[]) -def isa_set(string): - str_match = re.findall(r'([^\d]*?)(?!_)*(Z.*?)*(_|$)',string,re.M) - extension_list= [] - for match in str_match: - stdisa, z, ignore = match - if stdisa != '': - for e in stdisa: - extension_list.append(e) - if z != '': - extension_list.append(z) - return set(extension_list) - -def canonicalise(isa): - all_ext = ["M","A","F","D","Q","L","C","B","J","K","T","P","V","N","S","H","U","Zicsr", - "Zifencei","Zihintpause","Zmmul","Zam","Zba","Zbc","Zbb","Zbs","Zbp","Zbm","Zbe","Zbf","Zkne", - "Zknd","Zknh","Zkse","Zksh","Zkg","Zkb","Zkr","Zks","Zkn","Ztso","Zbkb","Zbkc","Zbkx"] - canonical_string = "" - switch = False - for ext in all_ext: - if ext in isa: - if switch: - canonical_string += "_" - elif ext.startswith("Z"): - switch=True - canonical_string += ext - if ext.startswith("Z"): - switch=True - return canonical_string - - def prod_isa(dut_isa, test_isa): ''' Function to generate the isa a test has to be compiled with. The various possible ISAs a @@ -297,22 +267,17 @@ def prod_isa(dut_isa, test_isa): :raises: TestSelectError ''' - dut_exts = isa_set(re.sub("RV(64|128|32)(I|E)","",dut_isa)) - isa = set([]) - last_prefix = '' - atleast_1 = False - match = re.findall("(?PRV(64|128|32)(I|E))",dut_isa) - prefix = match[0][0] - for entry in test_isa: - match = re.findall("(?PRV(64|128|32)(I|E))",entry) - exts = isa_set(re.sub("RV(64|128|32)(I|E)","",entry)) - overlap = dut_exts & exts - if overlap == exts and match[0][0] == prefix: - atleast_1 = True - isa = isa | overlap - if not atleast_1: - raise TestSelectError("Test Selected without the relevant extensions being available on DUT.") - return prefix+canonicalise(isa) + (dut_ext_list, err, err_list) = get_extension_list(dut_isa) + dut_ext_set = set(dut_ext_list) + dut_base = 32 if '32' in dut_isa else 64 + for isa in test_isa: + (test_ext_list, err, err_list) = get_extension_list(isa) + test_base = 32 if '32' in isa else 64 + test_ext_set = set(test_ext_list) + if test_ext_set.issubset(dut_ext_set) and dut_base == test_base: + return isa + raise TestSelectError("Test Selected without the relevant extensions being available on DUT.") + return '' def generate_test_pool(ispec, pspec, workdir, dbfile = None): ''' From 0574a771d9cd34fbd2356fcb9e0555c6734a8d1f Mon Sep 17 00:00:00 2001 From: Neel Gala Date: Wed, 7 Sep 2022 17:05:39 +0530 Subject: [PATCH 3/6] bump riscv_config requirements to 3.0+ --- riscof/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/riscof/requirements.txt b/riscof/requirements.txt index 18eed1f..0b8d099 100644 --- a/riscof/requirements.txt +++ b/riscof/requirements.txt @@ -2,5 +2,5 @@ GitPython==3.1.17 click>=7.1.2 Jinja2>=2.10.1 pytz>=2019.1 -riscv-config==2.17.0 +riscv-config>=3.0.0 riscv_isac>=0.7.2 From 1bf9c6d6d1efb55945ab5f1728d674f26db4cbc6 Mon Sep 17 00:00:00 2001 From: Neel Gala Date: Wed, 7 Sep 2022 17:05:56 +0530 Subject: [PATCH 4/6] clean up docs for RVTEST_CASE condition formating --- docs/source/index.rst | 1 + docs/source/testformat.rst | 715 +++++++++++++++++++------------------ 2 files changed, 371 insertions(+), 345 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 0cccef8..d83ce4a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,6 +15,7 @@ Welcome to RISCOF plugins arch-tests testlist + testformat database coverage code-doc diff --git a/docs/source/testformat.rst b/docs/source/testformat.rst index 928e595..6ffafc0 100644 --- a/docs/source/testformat.rst +++ b/docs/source/testformat.rst @@ -4,191 +4,348 @@ Test Format Spec ################ -Vocabulary ----------- +.. Vocabulary +.. ---------- +.. +.. +.. .. _architectural_test: +.. +.. The architectural test +.. ^^^^^^^^^^^^^^^^^^^^^^ +.. The architectural test is a nonfunctional testing technique which is done to validate whether the system +.. developed meets the prescribed standard or not. In this particular case the golden reference is +.. the RISC-V ISA standard. +.. +.. For purpose of this document we understand that the architectural test is a single test which +.. represents the minimum test code that can be compiled and run. It is written in assembler code +.. and its product is a :ref:`test signature `. An architectural test may consist of +.. several :ref:`test cases `. +.. +.. .. _architectural_test_pool: +.. +.. The RISC-V architectural test pool +.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. The RISC-V architectural test pool consists of all approved :ref:`architectural tests ` that can be assembled by the test framework, forming the :ref:`architectural test suite `. The RISC-V architectural test pool must be test target independent (so, should correctly run on any compliant target). Note that this nonfunctional testing is not a substitute for verification or device test. +.. +.. .. _architectural_test_suite: +.. +.. The RISC-V architectural test suite +.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. The RISC-V architectural test suite is a group of tests selected from the :ref:`architectural test pool ` to test architectural for the specific RISC-V configuration. Test results are obtained in the form of a :ref:`test suite signature `. Selection of tests is performed based on the target's asserted configuration, and the spec, Execution Environment or platform requirements. Compliant processor or processor models shall exhibit the same test suite signature as the golden reference test suite signature for the specific configuration being tested. +.. +.. +.. .. _test_case: +.. +.. The test case +.. ^^^^^^^^^^^^^ +.. A *test case* is part of the architectural test that tests just one feature of the specification. +.. +.. +.. .. note:: a single test can contain multiple test cases, each of which can have its own test inclusion condition (as defined by the cond_str parameter of the RVTEST_CASE macro. +.. +.. .. image:: testpool.jpg +.. :align: center +.. :alt: testStruct +.. +.. .. _test_case_signature: +.. +.. The test case signature +.. ^^^^^^^^^^^^^^^^^^^^^^^ +.. The *test case signature* is represented by single or multiple values. Values are written to memory at the address starting at the address specified by the RVMODEL_DATA_BEGIN and ending at RVMODEL_DATA_END. Signatures can be generated most easily using the RVTEST_SIGUPD macro. +.. +.. .. _test_signature: +.. +.. The test signature +.. ^^^^^^^^^^^^^^^^^^ +.. The :ref:`test signature ` is a characteristic value which is generated by the architectural test run. The :ref:`test signature ` may consist of several :ref:`test case signature `, prefixed with a separate line containing the name of the test and a unique value indicating its version (e.g. git checkin hash). The test target is responsible for extracting values from memory and properly formatting them, using metadata provided to it by the framework using the RVMODEL_DATA_BEGIN and RVMODEL_DATA_END macros. Test case signature values are written one per line, starting with the most-significant byte on the left-hand side with the format where the length of value will be 32 bits (so 8 characters), regardless of the actual value length computed by the test. +.. +.. .. _test_suite_signature: +.. +.. The test suite signature +.. ^^^^^^^^^^^^^^^^^^^^^^^^ +.. The *test suite signature* is defined as a set of :ref:`test signature ` valid for given :ref:`computed test suite `. It represents the test signature of the particular RISC-V configuration selected for the architectural test. +.. +.. .. _target_shell: +.. +.. The target shell +.. ^^^^^^^^^^^^^^^^ +.. The :ref:`target shell` is a vendor-supplied software and hardware environment around the :ref:`test target ` that enables it to communicate with the framework, including assembling and linking tests, loading tests into memory, executing tests, and extracting the signature. The input to the :ref:`target shell` is a .S :ref:`architectural test ` file, and the output is a :ref:`test signature `. +.. +.. .. _test_target: +.. +.. The test target +.. ^^^^^^^^^^^^^^^ +.. The :ref:`test target ` can include a RISC-V Instruction Set Simulator (ISS), a RISC-V emulator, a RISC-V RTL model running on an HDL simulator, a RISC-V FPGA implementation or a physical chip or other model type. Each of the target types offers specific features and represents specific interface challenges. It is a role of the :ref:`target shell ` to handle different targets while using the same :ref:`architectural test pool ` as a test source. +.. +.. .. The RISC-V processor (device) configuration +.. .. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. .. The RISC-V ISA specification allows many optional instructions, registers, and other features. Production directed targets typically have a fixed subset of available options. A simulator, on the other hand, may implement all known options which may be constrained to mimic the behavior of the RISC-V processor with the particular configuration. It is a role of the Architectural Test Framework to build and use the :ref:`The RISC-V architectural test suite ` suitable for the selected RISC-V configuration. +.. +.. .. _architectural_test_framework: +.. +.. The architectural test framework +.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. The :ref:`architectural test framework ` selects and configures the :ref:`architectural test suite ` from the :ref:`architectural test pool ` for the selected :ref:`test target ` based on both the specific architectural choices made by an implementation and those required by the Execution Environment. It causes the :ref:`target shell ` to build, execute, and report a signature. The :ref:`architectural test framework ` then compares reported signatures, inserts test part names and version numbers and summarizes differences (or lack of them) into a RISC-V architectural report. The primary role of the well-defined :ref:`architectural test pool ` structure is to provide the tests in a form suitable for the Architectural Test Framework selection engine. +.. +.. +.. Architectural test pool +.. ----------------------- +.. +.. .. _test_pool_structure: +.. +.. Test pool structure +.. ^^^^^^^^^^^^^^^^^^^ +.. +.. The structure of :ref:`architectural test ` in the :ref:`architectural test pool ` shall be based on defined RISC-V extensions and privileged mode selection. This will provide a good overview of which parts of the ISA specification are already covered in the :ref:`architectural test suite `, and which tests are suitable for certain configurations. The architectural test pool has this structure: +.. +.. .. code-block:: bash +.. +.. architectural-tests-suite (root) +.. -- _/, where +.. +.. is [ RV32I | RV64I | RV32E ] +.. +.. is [ M | MU | MS | MSU ], where +.. M Machine mode tests - tests execute in M-mode only +.. MU Machine/User mode tests - tests execute in both M- & U-modes (S-mode may exist) +.. MS Machine/Supv mode tests - tests execute in both M- & S-modes (not U-mode) +.. MSU All mode tests - tests execute in all of M-, S-, & U-Modes +.. +.. are the lettered extension [A | B | C | M ...] or subextension [Zifencei | Zam | ...] +.. when the tests involve extensions, or more general names when tests cut across extension +.. definitions (e.g. Priv, Interrupt, Vm). The feature string consists of an initial capital +.. letter, followed by any further letters in lower case. +.. +.. .. note:: this structure is for organizational purposes, not functional purposes, although full test names will take advantage of it. +.. +.. Tests that will be executed in different modes, even if the results are identical, should be replicated in each mode directory, e.g. RV32I_M/, RV32I_MS/, and RV32I_MU/. These tests are typically those involving trapping behavior, e.g load, store, and privileged ops. +.. +.. Test naming +.. ^^^^^^^^^^^ +.. +.. The naming convention of a single test: +.. +.. *-.S* +.. +.. * **test objective** - an aspect that the test is focused on. A test objective may be an instruction for ISA tests (ADD, SUB, ...), or a characteristic covering multiple instructions, e.g. exception event (misaligned fetch, misalign load/store) and others. +.. +.. * **test number** - number of the test. It is expected that multiple tests may be specified for one test objective. We recommend to break down complex tests into a set of small tests. A simple rule of thumb is one simple test objective = one simple test. The code becomes more readable and the test of the objective can be improved just by adding :ref:`test case `. The typical example are instruction tests for the F extension. +.. +.. * A test name shall not include an ISA category as part of its name (i.e. the directory, subdirectory names). Experience has shown that including ISA category in the test name leads to very long test names. Instead, we have introduced the :ref:`Test pool structure` where the full name is composed of the test path in the :ref:`Test pool structure` and the simple test name. Since full names can be reconstructed easily it is not necessary to include the path in test names. +.. +.. .. _available_macros: +.. +.. Assembly macros and test labels +.. ------------------------------- +.. +.. There are both pre-defined and model-specific macros which shall be used in every test to guarantee +.. their portability. In addition, there are both pre-defined and model specific macros that are not required, +.. but may be used in tests for either convenience or debugging purposes. +.. +.. Required, Pre-defined Macros +.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. +.. These macros are be defined in the file **compilance_test.h** by the author of the test. A +.. significant amount of the framework shall depend on the existence of these macros. +.. +.. +.. ``RVTEST_ISA(isa_str)`` : +.. - defines the Test Virtual Machine (TVM, the ISA being tested) +.. - empty macro to specify the isa required for compilation of the test. +.. - this is mandated to be present at the start of the test. +.. +.. ``RVTEST_CODE_BEGIN`` : +.. - start of code (test) section +.. - macro to indicate test code start add and where test startup routine is inserted. + +.. - no part of the test-code section should precede this macro +.. - this macro includes an initialization routine which pre-loads all the GPRs with unique values +.. (not `0xdeadbeef`). Register t0 and t1 are initialized to point to the labels : +.. `rvtest_code_begin` and `rvtest_code_end` respectively. +.. - the macros contains a label `rvtest_code_begin` after the above initilization routine to mark +.. the begining of the actual test. +.. +.. ``RVTEST_CODE_END`` : +.. - end of code (test) section + +.. - macro to indicate test code end. + +.. - no part of the test-code section should follow after this macro. +.. - the macro enforces a 16-byte boundary alignment +.. - the macro also inlcudes the label `rvtest_code_end` which marks the end of the actual test. +.. - if trap handling is enabled, this macro contains the entire trap handler code required by the +.. test. +.. +.. ``RVTEST_DATA_BEGIN``: +.. - marks the begining of the test data section + +.. - used to provided initialized data regions to be used by the test + +.. - this region starts at a 16-byte boundary + +.. - the start of this is macro can be addressed using the label: `rvtest_data_begin` +.. - when trap handling is enabled, this macro also includes the following labels : +.. . trapreg_sv: This region is used to save the temporary registers used in the trap-handler +.. code +.. . tramptbl_sv: This region is used to save the contents of the test-target's initial +.. code-section which is overwritten with the necessary trampoline table. +.. . mtvec_save: a double-word region to save the test-target specific mtvec register +.. . mscratch_save: a double-word region to save the test-target specific mscratch register +.. +.. ``RVTEST_DATA_END``: +.. - this macros marks the end of the test input data section. +.. - the start of this macro can be addressed using the label: `rvtest_data_end` +.. +.. ``RVTEST_CASE(CaseName, CondStr)``: +.. - execute this case only if condition in cond_str are met + +.. - caseName is arbitrary string + +.. - condStr is evaluated to determine if the test-case is enabled and sets name variable + +.. - condStr can also define compile time macros required for the test-case to be enabled. + +.. - the test-case must be delimited with an #ifdef CaseName/#endif pair + +.. - the format of CondStr can be found in https://riscof.readthedocs.io/en/latest/testformat.html#rvtest-case-condition-formating +.. +.. Required, Model-defined Macros +.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. +.. These macros are be defined by the owner of the test target in the file **model_test.h**. +.. These macros are required to define the signature regions and also the logic required to halt/exit +.. the test. +.. +.. ``RVMODEL_DATA_BEGIN``: +.. - This macro marks the start of test-target data section. This section may include any of the +.. test-target specific data initialization. This macro however, must include labels (if any) to +.. indicate the begining of the signature region. One must ensure to not enforce any alignment +.. constraints on the signature region to avoid mismatches. +.. +.. .. note:: The signature region should always begin at a XLEN-bit boundary. +.. +.. ``RVMODEL_DATA_END``: +.. - This macros marks the signature-region. The entire signature reqgion must be included within +.. the RVMODEL_DATA_BEGIN and the RVMODEL_DATA_END macros. +.. +.. ``RVMODEL_HALT``: +.. - This macros must define the test-target halt mechanism. This macro is called when the test is +.. to be terminated either due to completion or dur to unsupported behavior. This macro could +.. also include routines to dump the signature region to a file on the host system which can be +.. used for comparison. +.. +.. Optional, Pre-defined Macros +.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. +.. ``RVTEST_SIGBASE(BaseReg,Val)``: +.. - defines the base register used to update signature values + +.. - Register BaseReg is loaded with value Val + +.. - hidden_offset is initialized to zero +.. +.. ``RVTEST_SIGUPD(BaseReg, SigReg [, Offset])``: +.. - if Offset is present in the arguments, hidden_offset if set to Offset + +.. - Sigreg is stored at hidden_offset[BaseReg] +.. - hidden_offset is post incremented so repeated uses store signature values sequentially +.. +.. ``RVTEST_BASEUPD(BaseReg[oldBase[,newOff]])``: +.. - [moves &] updates BaseReg past stored signature + +.. - Register BaseReg is loaded with the oldReg+newOff+hidden_offset + +.. - BaseReg is used if oldBase isn't specified; 0 is used if newOff isn't specified + +.. - hidden_offset is re-initialized to 0 afterwards +.. +.. Optional, Model-defined Macros +.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. +.. ``RVMODEL_BOOT``: +.. - contains boot code for the test-target; may include emulation code or trap stub. If the +.. test-target enforces alignment or value restrictions on the mtvec csr, it is required that +.. this macro sets the value of mtvec to a region which is readable and writable by the machine +.. mode. +.. +.. Test structure +.. -------------- +.. +.. All tests shall use a signature approach. Each test shall be written in the same style, with defined mandatory items. +.. The test structure of an architectural test shall have the following sections in the order as follows: +.. +.. . Header + license (including a specification link, a brief test description and RVTEST_ISA macro)). +.. . Includes of header files (see Common Header Files section). +.. . Test Virtual Machine (TVM) specification, +.. . Test code between “RVTEST_CODE_BEGIN” and “RVTEST_CODE_END”. +.. . Input data section, marked with "RVTEST_DATA_BEGIN" and "RVTEST_DATA_END". +.. . Output data section between “RVMODEL_DATA_BEGIN” and “RVMODEL_DATA_END”. +.. +.. +.. Note:: Note that there is no requirement that the code or scratch data sections must be contiguous +.. in memory, or that they be located before or after data or code sections +.. (configured by embedded directives recognized by the linker) +.. +.. Common test format rules +.. ^^^^^^^^^^^^^^^^^^^^^^^^ +.. +.. There are the following common rules that shall be applied to each :ref:`The architectural test `: +.. +.. 1. Always use “//” as commentary. “#” should be used only for includes and defines. +.. 2. As part of the initialization code, all GPRs are preloaded with unique predefined values (which is not `0xdeadbeef`). However, t0 is initialized with `rvtest_code_begin` and t1 is initialized with `rvtest_data_begin`. +.. 3. The signature section of every test is pre-loaded with the word `0xdeadbeef` +.. 4. The signature region should always begin at a 16-byte boundary +.. 5. A test shall be divided into logical blocks (:ref:`The test case `) according to the test goals. Test cases are enclosed in an `#ifdef <__CaseName__>, #endif` pair and begin with the RVTEST_CASE(CaseName,CondStr) macro that specifies the test case name, and a string that defines the conditions under which that :ref:`The test case ` can be selected for assembly and execution. Those conditions will be collected and used to generate the database which in turn is used to select tests for inclusion in the test suite for this target. +.. 6. Tests should use the RVTEST_SIGBASE(BaseReg,Val) macro to define the GPR used as a pointer to the output signature area, and its initial value. It can be used multiple times within a test to reassign the output area or change the base register. This value will be used by the invocations of the RVTEST_SIGUPD macro. +.. 7. Tests should use the RVTEST_SIGUPD(BaseReg, SigReg, ScratchReg, Value) macro to store signature values using (only) the base register defined in the most recently encountered RVTEST_SIGBASE(BaseReg,Val) macro. Repeated uses will automatically have an increasing offset that is managed by the macro. +.. +.. - Uses of RVTEST_SIGUPD shall always be preceded sometime in the test case by RVTEST_SIGBASE. +.. - Tests that use SIGUPD inside a loop or in any section of code that will be repeated (e.g. traps) must use the BASEUPD macro between each loop iteration or repeated code to ensure static values of the base and offset don't overwrite older values. +.. +.. 8. When macros are needed for debug purposes, only macros from _model_test.h_ shall be used. +.. Note that using this feature shall not affect the signature results of the test run. +.. 9. Test shall not include other tests (e.g. #include “../add.S”) to prevent non-complete tests, compilation issues, and problems with code maintenance. +.. 10. Tests and test cases shall be skipped if not required for a specific model test configuration based on test conditions defined in the RVTEST_CASE macro. Tests that are selected may be further configured using variables (e.g. XLEN) which are passed into the tests and used to compile them. In either case, those conditions and variables are derived from the YAML specification of the device and execution environment that are passed into the framework. The flow is to run an architectural test suite built by the :ref:`The architectural test framework,` from the :ref:`The RISC-V architectural test pool ` to determine which tests and test cases to run. +.. 11. Tests shall not depend on tool specific features. For example, tests shall avoid usage of internal GCC macros (e..g. ____risc_xlen__), specific syntax (char 'a' instead of 'a) or simulator features (e.g. tohost) etc. +.. 12. A test will end by either jumping to or implicitly reaching the `RVTEST_CODE_END` macro (i.e. rvtest_code_end label). The `RVTEST_CODE_END` macro is always followed by the `RVMODEL_HALT` macro. +.. 13. Macros defined outside of a test shall only be defined in specific predefined header files (see :ref:`Common Header Files ` below), and once they are in use, they may be modified only if the function of all affected tests remains unchanged. It is acceptable that macros use may lead to operand repetition (register X is used every time). +.. +.. - The aim of this restriction is to have test code more readable and to avoid side effects which may occur when different contributors will include new :ref:`The architectural test ` or updates of existing ones in the :ref:`The RISC-V architectural test pool `. This measure results from the negative experience, where the :ref:`The RISC-V architectural test suite, ` could be used just for one target while the architectural test code changes were necessary to have it also running for other targets. +.. +.. 14. All contents of the signature region must always be initialized to `0xdeadbeef`. +.. 15. The result of no operation should be stored in the signature even though not register has been altered. +.. 16. Pseudo ops other than `li` and `la` which can map to multiple standard instruction sequences should not be used. +.. 17. The actual test-section of the assembly must always start with the `RVTEST_CODE_BEGIN` which contains a routine to initialize the registers to specific values. +.. +.. +.. .. _common_header_files: +.. +.. Common Header Files +.. ^^^^^^^^^^^^^^^^^^^ +.. +.. Each test shall include only the following header files: +.. +.. . _model_test.h_ – defines target-specific macros, both required and optional: (e.g. RVMODEL_xxx) +.. . _arch_test.h_ – defines pre-defined test macros both required and optional: (e.g. RVTEST_xxx) +.. +.. The inclusion of the _arch_test.h_ should always occur after the _model_test.h_ file. +.. +.. Important points to be noted regarding header files : +.. +.. . Adding new header files is forbidden in the test. It may lead to macro redefinition and compilation issues. +.. . Macros maybe defined and used inside a test, as they will not be defined and used outside that specific test. +.. // . Assertions will generate code that reports assertion failures (and optionally successes?) only if enabled by the framework. +.. // . In addition, the framework may collect the assertion values and save them as a signature output file if enabled by the framework. +.. +.. Framework Requirements +.. ---------------------- +.. +.. The framework will import files that describe +.. +.. - the implemented, target-specific configuration parameters in YAML format +.. +.. - the required, platform-specific configuration parameters in YAML format +.. +.. The framework will generate intermediate files, including a Test Database YAML file that selects tests from the test pool to generate a test suite for the target. +.. +.. The framework will also invoke the :ref:`The target shell ` as appropriate to cause tests to be built, loaded, executed, and results reported. +.. +.. The YAML files define both the values of those conditions and values that can be used by the framework to configure tests (e.g. format of WARL CSR fields). +.. Tests should not have #if, #ifdef, etc. for conditional assembly except those that surround RVMODEL_CASE macros +.. Instead, each of those should be a separate :ref:`The test case ` whose conditions are defined in +.. the common reference document entry for that test and test case number. -.. _architectural_test: - -The architectural test -^^^^^^^^^^^^^^^^^^^^^^ -The architectural test is a nonfunctional testing technique which is done to validate whether the system -developed meets the prescribed standard or not. In this particular case the golden reference is -the RISC-V ISA standard. - -For purpose of this document we understand that the architectural test is a single test which -represents the minimum test code that can be compiled and run. It is written in assembler code -and its product is a :ref:`test signature `. An architectural test may consist of -several :ref:`test cases `. - -.. _architectural_test_pool: - -The RISC-V architectural test pool -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The RISC-V architectural test pool consists of all approved :ref:`architectural tests ` that can be assembled by the test framework, forming the :ref:`architectural test suite `. The RISC-V architectural test pool must be test target independent (so, should correctly run on any compliant target). Note that this nonfunctional testing is not a substitute for verification or device test. - -.. _architectural_test_suite: - -The RISC-V architectural test suite -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The RISC-V architectural test suite is a group of tests selected from the :ref:`architectural test pool ` to test architectural for the specific RISC-V configuration. Test results are obtained in the form of a :ref:`test suite signature `. Selection of tests is performed based on the target's asserted configuration, and the spec, Execution Environment or platform requirements. Compliant processor or processor models shall exhibit the same test suite signature as the golden reference test suite signature for the specific configuration being tested. - - -.. _test_case: - -The test case -^^^^^^^^^^^^^ -A *test case* is part of the architectural test that tests just one feature of the specification. - - -.. note:: a single test can contain multiple test cases, each of which can have its own test inclusion condition (as defined by the cond_str parameter of the RVTEST_CASE macro. - -.. image:: testpool.jpg - :align: center - :alt: testStruct - -.. _test_case_signature: - -The test case signature -^^^^^^^^^^^^^^^^^^^^^^^ -The *test case signature* is represented by single or multiple values. Values are written to memory at the address starting at the address specified by the RVMODEL_DATA_BEGIN and ending at RVMODEL_DATA_END. Signatures can be generated most easily using the RVTEST_SIGUPD macro. - -.. _test_signature: - -The test signature -^^^^^^^^^^^^^^^^^^ -The :ref:`test signature ` is a characteristic value which is generated by the architectural test run. The :ref:`test signature ` may consist of several :ref:`test case signature `, prefixed with a separate line containing the name of the test and a unique value indicating its version (e.g. git checkin hash). The test target is responsible for extracting values from memory and properly formatting them, using metadata provided to it by the framework using the RVMODEL_DATA_BEGIN and RVMODEL_DATA_END macros. Test case signature values are written one per line, starting with the most-significant byte on the left-hand side with the format where the length of value will be 32 bits (so 8 characters), regardless of the actual value length computed by the test. - -.. _test_suite_signature: - -The test suite signature -^^^^^^^^^^^^^^^^^^^^^^^^ -The *test suite signature* is defined as a set of :ref:`test signature ` valid for given :ref:`computed test suite `. It represents the test signature of the particular RISC-V configuration selected for the architectural test. - -.. _target_shell: - -The target shell -^^^^^^^^^^^^^^^^ -The :ref:`target shell` is a vendor-supplied software and hardware environment around the :ref:`test target ` that enables it to communicate with the framework, including assembling and linking tests, loading tests into memory, executing tests, and extracting the signature. The input to the :ref:`target shell` is a .S :ref:`architectural test ` file, and the output is a :ref:`test signature `. - -.. _test_target: - -The test target -^^^^^^^^^^^^^^^ -The :ref:`test target ` can include a RISC-V Instruction Set Simulator (ISS), a RISC-V emulator, a RISC-V RTL model running on an HDL simulator, a RISC-V FPGA implementation or a physical chip or other model type. Each of the target types offers specific features and represents specific interface challenges. It is a role of the :ref:`target shell ` to handle different targets while using the same :ref:`architectural test pool ` as a test source. - -.. The RISC-V processor (device) configuration -.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. The RISC-V ISA specification allows many optional instructions, registers, and other features. Production directed targets typically have a fixed subset of available options. A simulator, on the other hand, may implement all known options which may be constrained to mimic the behavior of the RISC-V processor with the particular configuration. It is a role of the Architectural Test Framework to build and use the :ref:`The RISC-V architectural test suite ` suitable for the selected RISC-V configuration. - -.. _architectural_test_framework: - -The architectural test framework -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The :ref:`architectural test framework ` selects and configures the :ref:`architectural test suite ` from the :ref:`architectural test pool ` for the selected :ref:`test target ` based on both the specific architectural choices made by an implementation and those required by the Execution Environment. It causes the :ref:`target shell ` to build, execute, and report a signature. The :ref:`architectural test framework ` then compares reported signatures, inserts test part names and version numbers and summarizes differences (or lack of them) into a RISC-V architectural report. The primary role of the well-defined :ref:`architectural test pool ` structure is to provide the tests in a form suitable for the Architectural Test Framework selection engine. - - -Architectural test pool ------------------------ - -.. _test_pool_structure: - -Test pool structure -^^^^^^^^^^^^^^^^^^^ - -The structure of :ref:`architectural test ` in the :ref:`architectural test pool ` shall be based on defined RISC-V extensions and privileged mode selection. This will provide a good overview of which parts of the ISA specification are already covered in the :ref:`architectural test suite `, and which tests are suitable for certain configurations. The architectural test pool has this structure: - -.. code-block:: bash - - architectural-tests-suite (root) - -- _/, where - - is [ RV32I | RV64I | RV32E ] - - is [ M | MU | MS | MSU ], where - M Machine mode tests - tests execute in M-mode only - MU Machine/User mode tests - tests execute in both M- & U-modes (S-mode may exist) - MS Machine/Supv mode tests - tests execute in both M- & S-modes (not U-mode) - MSU All mode tests - tests execute in all of M-, S-, & U-Modes - - are the lettered extension [A | B | C | M ...] or subextension [Zifencei | Zam | ...] - when the tests involve extensions, or more general names when tests cut across extension - definitions (e.g. Priv, Interrupt, Vm). The feature string consists of an initial capital - letter, followed by any further letters in lower case. - -.. note:: this structure is for organizational purposes, not functional purposes, although full test names will take advantage of it. - -Tests that will be executed in different modes, even if the results are identical, should be replicated in each mode directory, e.g. RV32I_M/, RV32I_MS/, and RV32I_MU/. These tests are typically those involving trapping behavior, e.g load, store, and privileged ops. - -Test naming -^^^^^^^^^^^ - -The naming convention of a single test: - -*-.S* - - * **test objective** - an aspect that the test is focused on. A test objective may be an instruction for ISA tests (ADD, SUB, ...), or a characteristic covering multiple instructions, e.g. exception event (misaligned fetch, misalign load/store) and others. - - * **test number** - number of the test. It is expected that multiple tests may be specified for one test objective. We recommend to break down complex tests into a set of small tests. A simple rule of thumb is one simple test objective = one simple test. The code becomes more readable and the test of the objective can be improved just by adding :ref:`test case `. The typical example are instruction tests for the F extension. - - * A test name shall not include an ISA category as part of its name (i.e. the directory, subdirectory names). Experience has shown that including ISA category in the test name leads to very long test names. Instead, we have introduced the :ref:`Test pool structure` where the full name is composed of the test path in the :ref:`Test pool structure` and the simple test name. Since full names can be reconstructed easily it is not necessary to include the path in test names. - -.. _available_macros: - -Assembly macros and test labels -------------------------------- - -There are both pre-defined and model-specific macros which shall be used in every test to guarantee -their portability. In addition, there are both pre-defined and model specific macros that are not required, -but may be used in tests for either convenience or debugging purposes. - -Required, Pre-defined Macros -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +RVTEST_CASE Condition Formatting +-------------------------------- -These macros are be defined in the file **compilance_test.h** by the author of the test. A -significant amount of the framework shall depend on the existence of these macros. +This section describes the format for the conditions `CondStr` to be followed while writing the ``RVTEST_CASE`` macro. +Each of the statements within this macro ends with a ';' . - -``RVTEST_ISA(isa_str)`` : - - defines the Test Virtual Machine (TVM, the ISA being tested) - - empty macro to specify the isa required for compilation of the test. - - this is mandated to be present at the start of the test. - -``RVTEST_CODE_BEGIN`` : - - start of code (test) section - - macro to indicate test code start add and where test startup routine is inserted. + - - no part of the test-code section should precede this macro - - this macro includes an initialization routine which pre-loads all the GPRs with unique values - (not `0xdeadbeef`). Register t0 and t1 are initialized to point to the labels : - `rvtest_code_begin` and `rvtest_code_end` respectively. - - the macros contains a label `rvtest_code_begin` after the above initilization routine to mark - the begining of the actual test. - -``RVTEST_CODE_END`` : - - end of code (test) section + - - macro to indicate test code end. + - - no part of the test-code section should follow after this macro. - - the macro enforces a 16-byte boundary alignment - - the macro also inlcudes the label `rvtest_code_end` which marks the end of the actual test. - - if trap handling is enabled, this macro contains the entire trap handler code required by the - test. - -``RVTEST_DATA_BEGIN``: - - marks the begining of the test data section + - - used to provided initialized data regions to be used by the test + - - this region starts at a 16-byte boundary + - - the start of this is macro can be addressed using the label: `rvtest_data_begin` - - when trap handling is enabled, this macro also includes the following labels : - . trapreg_sv: This region is used to save the temporary registers used in the trap-handler - code - . tramptbl_sv: This region is used to save the contents of the test-target's initial - code-section which is overwritten with the necessary trampoline table. - . mtvec_save: a double-word region to save the test-target specific mtvec register - . mscratch_save: a double-word region to save the test-target specific mscratch register - -``RVTEST_DATA_END``: - - this macros marks the end of the test input data section. - - the start of this macro can be addressed using the label: `rvtest_data_end` +The macro follows the convention mentioned here: ``RVTEST_CASE(CaseName, CondStr)``: - execute this case only if condition in cond_str are met + @@ -197,157 +354,8 @@ significant amount of the framework shall depend on the existence of these macro - condStr can also define compile time macros required for the test-case to be enabled. + - the test-case must be delimited with an #ifdef CaseName/#endif pair + - the format of CondStr can be found in https://riscof.readthedocs.io/en/latest/testformat.html#rvtest-case-condition-formating - -Required, Model-defined Macros -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -These macros are be defined by the owner of the test target in the file **model_test.h**. -These macros are required to define the signature regions and also the logic required to halt/exit -the test. - -``RVMODEL_DATA_BEGIN``: - - This macro marks the start of test-target data section. This section may include any of the - test-target specific data initialization. This macro however, must include labels (if any) to - indicate the begining of the signature region. One must ensure to not enforce any alignment - constraints on the signature region to avoid mismatches. - - .. note:: The signature region should always begin at a XLEN-bit boundary. - -``RVMODEL_DATA_END``: - - This macros marks the signature-region. The entire signature reqgion must be included within - the RVMODEL_DATA_BEGIN and the RVMODEL_DATA_END macros. - -``RVMODEL_HALT``: - - This macros must define the test-target halt mechanism. This macro is called when the test is - to be terminated either due to completion or dur to unsupported behavior. This macro could - also include routines to dump the signature region to a file on the host system which can be - used for comparison. - -Optional, Pre-defined Macros -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``RVTEST_SIGBASE(BaseReg,Val)``: - - defines the base register used to update signature values + - - Register BaseReg is loaded with value Val + - - hidden_offset is initialized to zero - -``RVTEST_SIGUPD(BaseReg, SigReg [, Offset])``: - - if Offset is present in the arguments, hidden_offset if set to Offset + - - Sigreg is stored at hidden_offset[BaseReg] - - hidden_offset is post incremented so repeated uses store signature values sequentially - -``RVTEST_BASEUPD(BaseReg[oldBase[,newOff]])``: - - [moves &] updates BaseReg past stored signature + - - Register BaseReg is loaded with the oldReg+newOff+hidden_offset + - - BaseReg is used if oldBase isn't specified; 0 is used if newOff isn't specified + - - hidden_offset is re-initialized to 0 afterwards - -Optional, Model-defined Macros -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``RVMODEL_BOOT``: - - contains boot code for the test-target; may include emulation code or trap stub. If the - test-target enforces alignment or value restrictions on the mtvec csr, it is required that - this macro sets the value of mtvec to a region which is readable and writable by the machine - mode. - -Test structure --------------- - -All tests shall use a signature approach. Each test shall be written in the same style, with defined mandatory items. -The test structure of an architectural test shall have the following sections in the order as follows: - -. Header + license (including a specification link, a brief test description and RVTEST_ISA macro)). -. Includes of header files (see Common Header Files section). -. Test Virtual Machine (TVM) specification, -. Test code between “RVTEST_CODE_BEGIN” and “RVTEST_CODE_END”. -. Input data section, marked with "RVTEST_DATA_BEGIN" and "RVTEST_DATA_END". -. Output data section between “RVMODEL_DATA_BEGIN” and “RVMODEL_DATA_END”. - - -Note:: Note that there is no requirement that the code or scratch data sections must be contiguous -in memory, or that they be located before or after data or code sections -(configured by embedded directives recognized by the linker) - -Common test format rules -^^^^^^^^^^^^^^^^^^^^^^^^ - -There are the following common rules that shall be applied to each :ref:`The architectural test `: - -1. Always use “//” as commentary. “#” should be used only for includes and defines. -2. As part of the initialization code, all GPRs are preloaded with unique predefined values (which is not `0xdeadbeef`). However, t0 is initialized with `rvtest_code_begin` and t1 is initialized with `rvtest_data_begin`. -3. The signature section of every test is pre-loaded with the word `0xdeadbeef` -4. The signature region should always begin at a 16-byte boundary -5. A test shall be divided into logical blocks (:ref:`The test case `) according to the test goals. Test cases are enclosed in an `#ifdef <__CaseName__>, #endif` pair and begin with the RVTEST_CASE(CaseName,CondStr) macro that specifies the test case name, and a string that defines the conditions under which that :ref:`The test case ` can be selected for assembly and execution. Those conditions will be collected and used to generate the database which in turn is used to select tests for inclusion in the test suite for this target. -6. Tests should use the RVTEST_SIGBASE(BaseReg,Val) macro to define the GPR used as a pointer to the output signature area, and its initial value. It can be used multiple times within a test to reassign the output area or change the base register. This value will be used by the invocations of the RVTEST_SIGUPD macro. -7. Tests should use the RVTEST_SIGUPD(BaseReg, SigReg, ScratchReg, Value) macro to store signature values using (only) the base register defined in the most recently encountered RVTEST_SIGBASE(BaseReg,Val) macro. Repeated uses will automatically have an increasing offset that is managed by the macro. - - - Uses of RVTEST_SIGUPD shall always be preceded sometime in the test case by RVTEST_SIGBASE. - - Tests that use SIGUPD inside a loop or in any section of code that will be repeated (e.g. traps) must use the BASEUPD macro between each loop iteration or repeated code to ensure static values of the base and offset don't overwrite older values. - -8. When macros are needed for debug purposes, only macros from _model_test.h_ shall be used. - Note that using this feature shall not affect the signature results of the test run. -9. Test shall not include other tests (e.g. #include “../add.S”) to prevent non-complete tests, compilation issues, and problems with code maintenance. -10. Tests and test cases shall be skipped if not required for a specific model test configuration based on test conditions defined in the RVTEST_CASE macro. Tests that are selected may be further configured using variables (e.g. XLEN) which are passed into the tests and used to compile them. In either case, those conditions and variables are derived from the YAML specification of the device and execution environment that are passed into the framework. The flow is to run an architectural test suite built by the :ref:`The architectural test framework,` from the :ref:`The RISC-V architectural test pool ` to determine which tests and test cases to run. -11. Tests shall not depend on tool specific features. For example, tests shall avoid usage of internal GCC macros (e..g. ____risc_xlen__), specific syntax (char 'a' instead of 'a) or simulator features (e.g. tohost) etc. -12. A test will end by either jumping to or implicitly reaching the `RVTEST_CODE_END` macro (i.e. rvtest_code_end label). The `RVTEST_CODE_END` macro is always followed by the `RVMODEL_HALT` macro. -13. Macros defined outside of a test shall only be defined in specific predefined header files (see :ref:`Common Header Files ` below), and once they are in use, they may be modified only if the function of all affected tests remains unchanged. It is acceptable that macros use may lead to operand repetition (register X is used every time). - - - The aim of this restriction is to have test code more readable and to avoid side effects which may occur when different contributors will include new :ref:`The architectural test ` or updates of existing ones in the :ref:`The RISC-V architectural test pool `. This measure results from the negative experience, where the :ref:`The RISC-V architectural test suite, ` could be used just for one target while the architectural test code changes were necessary to have it also running for other targets. - -14. All contents of the signature region must always be initialized to `0xdeadbeef`. -15. The result of no operation should be stored in the signature even though not register has been altered. -16. Pseudo ops other than `li` and `la` which can map to multiple standard instruction sequences should not be used. -17. The actual test-section of the assembly must always start with the `RVTEST_CODE_BEGIN` which contains a routine to initialize the registers to specific values. - - -.. _common_header_files: - -Common Header Files -^^^^^^^^^^^^^^^^^^^ - -Each test shall include only the following header files: - -. _model_test.h_ – defines target-specific macros, both required and optional: (e.g. RVMODEL_xxx) -. _arch_test.h_ – defines pre-defined test macros both required and optional: (e.g. RVTEST_xxx) - -The inclusion of the _arch_test.h_ should always occur after the _model_test.h_ file. - -Important points to be noted regarding header files : - -. Adding new header files is forbidden in the test. It may lead to macro redefinition and compilation issues. -. Macros maybe defined and used inside a test, as they will not be defined and used outside that specific test. -// . Assertions will generate code that reports assertion failures (and optionally successes?) only if enabled by the framework. -// . In addition, the framework may collect the assertion values and save them as a signature output file if enabled by the framework. - -Framework Requirements ----------------------- - -The framework will import files that describe - -- the implemented, target-specific configuration parameters in YAML format - -- the required, platform-specific configuration parameters in YAML format - -The framework will generate intermediate files, including a Test Database YAML file that selects tests from the test pool to generate a test suite for the target. - -The framework will also invoke the :ref:`The target shell ` as appropriate to cause tests to be built, loaded, executed, and results reported. - -The YAML files define both the values of those conditions and values that can be used by the framework to configure tests (e.g. format of WARL CSR fields). -Tests should not have #if, #ifdef, etc. for conditional assembly except those that surround RVMODEL_CASE macros -Instead, each of those should be a separate :ref:`The test case ` whose conditions are defined in -the common reference document entry for that test and test case number. - - -RVTEST_CASE Condition Formatting --------------------------------- - -This section describes the format for the conditions `CondStr` to be followed while writing the ``RVTEST_CASE`` macro. -Each of the statements within this macro ends with a ';' . - -The macro follows the convention mentioned :ref:`here `. This section describes -the syntax to be followed by the CondStr of the ``RVTEST_CASE`` macro. +This section describes the syntax to be followed by the CondStr of the ``RVTEST_CASE`` macro. .. note:: A keylist is a string of '>' separated words(keys) which is used to navigate the supplied specs. The schema may be used to specify them. Only valid keys and their combinations are allowed(as present in the scema). @@ -391,18 +399,26 @@ There are two types of valid statements allowed. **Function Signatures** - * writable(bit_position,keylist_for_field) -> bool - - Checks whether the bit at *bit_position* for a particular *csr_field_name* is writable. This function is typically used for *WARL* nodes. - * islegal(value,dependency_values_list,keylist_for_field) -> bool - - This function is valid only for *WARL* fields in the csrs. Checks whether the *value* is a legal value when the values of the fields listed as dependency for the field in question on is equal to the *dependency_values_list*. + * `range_writable(bit_range, dep_vals, keylist_for_field)` -> bool + Checks whether the bits defined in *bit_range* for a particular *csr_field_name* is writable or not. + The *bit_range* must be specified as `:` for range + specification or just `` for a single bit specification. + This function is typically used for *WARL* nodes. For csrs with `ro_constant` or `ro_variable` types, + this function will return False. For WARL fields, this function + simply checks if for a legal value, flipping the bits in + *bit_range* still generates a legal value. + + * `islegal(value, dependency_values_list, keylist_for_field)` -> bool + This function is valid only for *WARL* fields in the csrs. + Checks whether the *value* is a legal value when the values of + the fields listed as dependency for the field in question on + is equal to the *dependency_values_list*. Example: .. code-block:: none - check writable(12,misa>rv32>extensions)=True; # checks if 12th bit in MISA is writable. + check range_writable(12,[],misa>rv32>extensions)=True; # checks if 12th bit in MISA.extensions is writable. 2. ``def`` statements @@ -418,13 +434,22 @@ There are two types of valid statements allowed. **Function Signatures** - * getlegal(dependency_values_list,num_vals,key_list_for_field) -> list(int) - - This function is valid only for *WARL* fields in the csrs. It returns a list of legal values for the specified field when the values of the fields listed as dependency for the field in question on is equal to the *dependency_values_list*. The length of the list returned is equal to *num_vals*. Each entry in the list is assigned to the corresponding macro listed on the left hand side of the *=* sign. - - * getillegal(dependency_values_list,num_vals,key_list_for_field) -> list(int) - - This function is valid only for *WARL* fields in the csrs. It returns a list of illegal values for the specified field when the values of the fields listed as dependency for the field in question on is equal to the *dependency_values_list*. The length of the list returned is equal to *num_vals*. Each entry in the list is assigned to the corresponding macro listed on the left hand side of the *=* sign. + * getlegal(dependency_values_list, num_vals, key_list_for_field) -> list(int) + This function is valid only for *WARL* fields in the csrs. It + returns a list of legal values for the specified field when the values + of the fields listed as dependency for the field in question on is equal + to the *dependency_values_list*. The length of the list returned is equal + to *num_vals*. Each entry in the list is assigned to the corresponding + macro listed on the left hand side of the *=* sign. + + * getillegal(dependency_values_list, num_vals, key_list_for_field) -> list(int) + This function is valid only for *WARL* fields in the csrs. + It returns a list of illegal values for the specified field when the + values of the fields listed as dependency for the field in + question on is equal to the *dependency_values_list*. The length of + the list returned is equal to *num_vals*. Each entry in the + list is assigned to the corresponding macro listed on the left + hand side of the *=* sign. Example: From f8c93680e8a5e12416610b7ef040e15a372aa8aa Mon Sep 17 00:00:00 2001 From: Neel Gala Date: Wed, 7 Sep 2022 17:08:20 +0530 Subject: [PATCH 5/6] =?UTF-8?q?Bump=20version:=201.24.3=20=E2=86=92=201.25?= =?UTF-8?q?.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 5 +++++ riscof/__init__.py | 2 +- setup.cfg | 2 +- setup.py | 2 +- 4 files changed, 8 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 353a686..2e4b042 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [1.25.0] - 2022-09-07 +- migrated to using riscv-config versino 3.0.0+ +- modified functions to use the new warl_class from riscv-config-3.0.0+ +- modified prod_isa to use riscv-config isa_validator + ## [1.24.3] - 2022-08-29 - fix typeo in doc for command related to cloning arch-suites - bump riscv-config version to be 2.17.0 diff --git a/riscof/__init__.py b/riscof/__init__.py index 1f7f6f2..b6dddd7 100644 --- a/riscof/__init__.py +++ b/riscof/__init__.py @@ -4,4 +4,4 @@ __author__ = """InCore Semiconductors Pvt Ltd""" __email__ = 'info@incoresemi.com' -__version__ = '1.24.3' +__version__ = '1.25.0' diff --git a/setup.cfg b/setup.cfg index 85bb5a9..a7e8112 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,5 +1,5 @@ [bumpversion] -current_version = 1.24.3 +current_version = 1.25.0 commit = True tag = True diff --git a/setup.py b/setup.py index b70f656..545cb16 100644 --- a/setup.py +++ b/setup.py @@ -23,7 +23,7 @@ def read_requires(): test_requirements = [ ] setup(name="riscof", - version='1.24.3', + version='1.25.0', description="RISC-V Architectural Test Framework", long_description=readme + '\n\n', classifiers=[ From 0cde1a443412b79665eba9d1a7686d91e1a3e39a Mon Sep 17 00:00:00 2001 From: Neel Gala Date: Thu, 8 Sep 2022 11:10:29 +0530 Subject: [PATCH 6/6] bump rconfig requirements to 3.2.0 --- CHANGELOG.md | 4 ++-- riscof/requirements.txt | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e4b042..0f261f8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,8 +3,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [1.25.0] - 2022-09-07 -- migrated to using riscv-config versino 3.0.0+ -- modified functions to use the new warl_class from riscv-config-3.0.0+ +- migrated to using riscv-config version 3.2.0+ +- modified functions to use the new warl_class from riscv-config-3.2.0+ - modified prod_isa to use riscv-config isa_validator ## [1.24.3] - 2022-08-29 diff --git a/riscof/requirements.txt b/riscof/requirements.txt index 0b8d099..6fc0519 100644 --- a/riscof/requirements.txt +++ b/riscof/requirements.txt @@ -2,5 +2,5 @@ GitPython==3.1.17 click>=7.1.2 Jinja2>=2.10.1 pytz>=2019.1 -riscv-config>=3.0.0 +riscv-config>=3.2.0 riscv_isac>=0.7.2