YAML Specifications¶
This section provides details of the ISA and Platform spec YAML files that need to be provided by the user.
ISA YAML Spec¶
NOTE:
All integer fields accept values as integers or hexadecimals(can be used interchangeably) unless specified otherwise.
Different examples of the input yamls and the generated checked YAMLs can be found here : Examples
Vendor¶
Description: Vendor name.
Examples:
Vendor: Shakti Vendor: Incoresemi
Device¶
Description: Device Name.
Examples:
Device: E-Class Device: C-ClassConstraints:
None
ISA¶
Description: Takes input a string representing the ISA supported by the implementation. All extension names (other than Zext) should be mentioned in upper-case. Z extensions should begin with an upper-case ‘Z’ followed by lower-case extension name (without Camel casing)
Examples:
ISA: RV32IMA ISA: RV64IMAFDCZifenceiConstraints:
Certain extensions are only valid in certain user-spec version. For, eg. Zifencei is available only in user-spec 2.3 and above.
The ISA string must be specified as per the convention mentioned in the specifications(like subsequent Z extensions must be separated with an ‘_’)
User_Spec_Version¶
Description: Version number of User/Non-priveleged ISA specification as string. Please enclose the version in “” to avoid type mismatches.
Examples:
User_Spec_Version: "2.2" User_Spec_Version: "2.3"Constraints:
should be a valid version later than 2.2
Privilege_Spec_Version¶
Description: Version number of Priveleged ISA specification as string. Please enclose the version in “” to avoid type mismatches.
Examples:
Privilege_Spec_Version: "1.10" Privilege_Spec_Version: "1.11"Constraints:
should be a valid version later than 1.10
hw_data_misaligned_support¶
Description: A boolean value indicating whether hardware support for misaligned load/store requests exists.
Examples:
hw_data_misaligned_support: True hw_data_misaligned_support: FalseConstraints:
None
supported_xlen¶
Description: list of supported xlen on the target
Examples:
supported_xlen : [32] supported_xlen : [64, 32] supported_xlen : [64]Constraints:
None
pmp_granularity¶
Description: Granularity of pmps
Examples:
pmp_granularity : 2 pmp_granularity : 4Constraints:
None
physical_addr_sz¶
Description: size of the physical address
Examples:
physical_addr_sz : 32Constraints:
None
custom_exceptions¶
Description: list of custom exceptions implemented
Examples:
custom_exceptions: - cause_val: 25 cause_name: mycustom - cause_val: 26 cause_name: mycustom2Constraints:
None
custom_interrupts¶
Description: list of custom interrupts implemented
Examples:
custom_interrupts: - cause_val: 25 cause_name: mycustom - cause_val: 26 cause_name: mycustom2Constraints:
None
CSR Template¶
All csrs are defined using a common template. Two variants are available: csrs with subfields and those without
CSRs with sub-fields¶
<name>: # name of the csr
description: <text> # textual description of the csr
address: <hex> # address of the csr
priv_mode: <D/M/H/S/U> # privilege mode that owns the register
reset-val: <hex> # Reset value of the register. This an accumulation
# of the all reset values of the sub-fields
rv32: # this node and its subsequent fields can exist
# if [M/S/U]XL value can be 1
accessible: <boolean> # indicates if the csr is accessible in rv32 mode or not.
# When False, all fields below will be trimmed off
# in the checked yaml. False also indicates that
# access-exception should be generated.
fields: # a quick summary of the list of all fields of the
# csr including a list of WPRI fields of the csr.
- <field_name1>
- <field_name2>
- - [23,30] # A list which contains a squashed pair
- 6 # (of form [lsb,msb]) of all WPRI bits within the
# csr. Does not exist if there are no WPRI bits
<field_name1>: # name of the field
description: <text> # textual description of the csr
shadow: <csr-name>::<field> # which this field shadows,'none' indicates that
# this field does not shadow anything.
msb: <integer> # msb index of the field. max: 31, min:0
lsb: <integer> # lsb index of the field. max: 31, min:0
implemented: <boolean> # indicates if the user has implemented this field
# or not. When False, all
# fields below this will be trimmed.
type: # type of field. Can be only one of the following
wlrl: [list of value-descriptors] # field is wlrl and the set of legal values.
ro_constant: <hex> # field is readonly and will return the same value.
ro_variable: True # field is readonly but the value returned depends
# on other arch-states
warl: # field is warl type. Refer to WARL section
dependency_fields: [list]
legal: [list of warl-string]
wr_illegal: [list of warl-string]
rv64: # this node and its subsequent fields can exist
# if [M/S/U]XL value can be 2
accessible: <boolean> # indicates if this register exists in rv64 mode
# or not. Same definition as for rv32 node.
rv128: # this node and its subsequent fields can exist if
# [M/S/U]XL value can be 3
accessible: <boolean> # indicates if this register exists in rv128 mode
# or not. Same definition as for rv32 node.
CSRs without sub-fields¶
<name>: # name of the csr
description: <text> # textual description of the csr
address: <hex> # address of the csr
priv_mode: <D/M/H/S/U> # privilege mode that owns the register
reset-val: <hex> # Reset value of the register. This an accumulation
# of the all reset values of the sub-fields
rv32: # this node and its subsequent fields can exist
# if [M/S/U]XL value can be 1
accessible: <boolean> # indicates if the csr is accessible in rv32 mode or not.
# When False, all fields below will be trimmed off
# in the checked yaml. False also indicates that
# access-exception should be generated
fields: [] # This should be empty always.
shadow: <csr-name>::<register> # which this register shadows,'none' indicates that
# this register does not shadow anything.
msb: <int> # msb index of the csr. max: 31, min:0
lsb: <int> # lsb index of the csr. max: 31, min:0
type: # type of field. Can be only one of the following
wlrl: [list of value-descriptors] # field is wlrl and the set of legal values.
ro_constant: <hex> # field is readonly and will return the same value.
ro_variable: True # field is readonly but the value returned depends
# on other arch-states
warl: # field is warl type. Refer to WARL section
dependency_fields: [list]
legal: [list of warl-string]
wr_illegal: [list of warl-string]
rv64: # this node and its subsequent fields can exist
# if [M/S/U]XL value can be 2
accessible: <boolean> # indicates if this register exists in rv64 mode
# or not. Same definition as for rv32 node.
rv128: # this node and its subsequent fields can exist if
# [M/S/U]XL value can be 3
accessible: <boolean> # indicates if this register exists in rv128 mode
Constraints¶
Each csr undergoes the following checks:
All implemented fields at the csr-level, if set to True, are checked if they comply with the supported_xlen field of the ISA yaml.
The reset-val is checked against compliance with the type field specified by the user. All unimplemented fields are considered to be hardwired to 0.
For each of the above templates the following fields for all standard csrs defined by the spec are frozen and CANNOT be modified by the user.
description
address
priv_mode
fields
shadow
msb
lsb
The type field for certain csrs (like readonly) is also constrained.
fields names also cannot be modified for standard csrs
Only the following fields can be modified by the user:
reset-value
type
implemented
Example¶
Following is an example of how a user can define the mtvec csr in the input ISA YAML for a 32-bit core:
mtvec:
reset-val: 0x80010000
rv32:
accessible: true
base:
implemented: true
type:
warl:
dependency_fields: [mtvec::mode]
legal:
- "mode[1:0] in [0] -> base[29:0] in [0x20000000, 0x20004000]" # can take only 2 fixed values in direct mode.
- "mode[1:0] in [1] -> base[29:6] in [0x000000:0xF00000] base[5:0] in [0x00]" # 256 byte aligned values only in vectored mode.
wr_illegal:
- "mode[1:0] in [0] -> Unchanged"
- "mode[1:0] in [1] && writeval in [0x2000000:0x4000000] -> 0x2000000"
- "mode[1:0] in [1] && writeval in [0x4000001:0x3FFFFFFF] -> Unchanged"
mode:
implemented: true
type:
warl:
dependency_fields: []
legal:
- "mode[1:0] in [0x0:0x1] # Range of 0 to 1 (inclusive)"
wr_illegal:
- "Unchanged"
The following is what the riscv-config will output after performing relevant checks on the above user-input:
mtvec:
description: MXLEN-bit read/write register that holds trap vector configuration.
address: 773
priv_mode: M
reset-val: 0x80010000
rv32:
accessible: true
base:
implemented: true
type:
warl:
dependency_fields: [mtvec::mode, writeval]
legal:
- 'mode[1:0] in [0] -> base[29:0] in [0x20000000, 0x20004000]' # can take only 2 fixed values in direct mode.
- 'mode[1:0] in [1] -> base[29:6] in [0x000000:0xF00000] base[5:0] in [0x00]' # 256 byte aligned values only in vectored mode.
wr_illegal:
- 'mode[1:0] in [0] -> Unchanged'
- 'mode[1:0] in [1] && writeval in [0x2000000:0x4000000] -> 0x2000000'
- 'mode[1:0] in [1] && writeval in [0x4000001:0x3FFFFFFF] -> Unchanged'
description: Vector base address.
shadow: none
msb: 31
lsb: 2
mode:
implemented: true
type:
warl:
dependency_fields: []
legal:
- 'mode[1:0] in [0x0:0x1] # Range of 0 to 1 (inclusive)'
wr_illegal:
- Unchanged
description: Vector mode.
shadow: none
msb: 1
lsb: 0
fields:
- mode
- base
rv64:
accessible: false
WARL field Definition¶
Since the RISC-V privilege spec indicates several csrs and sub-fields of csrs to be WARL (Write-Any-Read-Legal), it is necessary to provide a common scheme of representation which can precisely define the functionality of any such WARL field/register.
Value Descriptors¶
Value descriptors are standard syntaxes that are used to define values in any part of the WARL string. The 2 basic descriptors are : distinct-values and range-values as described below:
distinct-values - This specifies that only the particular value should be added to the set.
val
range - This specifies that all the values greater than or equal to lower and less than or equal to upper is to be included in the set.
lower:upper
For any variable in the WARL string, the values can an amalgamation of distinct-values and/or range-values. They are typically captured in a list as shown in the below examples:
Example:
# To represent the set {0, 1, 2, 3, 4, 5}
[0:5]
# To represent the set {5, 10, 31}
[5, 10, 31]
# To represent the set {2, 3, 4, 5, 10, 11, 12, 13, 50}
[2:5, 10:13, 50]
WARL Node definition¶
A typical WARL node (used for a WARL csr or subfield) has the following skeleton in the riscv-config:
warl:
dependency_fields: [list of csrs/subfields that legal values depend on]
legal: [list of strings adhering to the warl-syntax for legal assignments]
wr_illegal: [list of strings ahdering to the warl-syntax for illegal assignments]
dependency_fields : This is a list of csrs/subfields whose values affect the legal values of the csr under question.
::
is used as a hierarchy separator to indicate subfields. This list can be empty to indicate that the csr under question is not affected by any other architectural state. The ordering of the csr/subfields has no consequence. Examples of the list are provided below:- dependency_fields: [mtvec::mode] - dependency_fields: [misa::mxl, mepc]
The following keywords are reserved and can be used accordingly in the dependency_fields list:
writeval
: to represent dependency on the current value being written to the csr/subfieldcurrval
: to represent dependency on the value of the csr/subfield before performing the write operation
Restrictions imposed: The following restrictions are imposed on the elements of the list:
The csrs/subfields mentioned in the list must have their accessible/implemented fields set to True in the isa yaml.
legal : This field is a list of strings which define the warl functions of the csr/subfield. Each string needs to adhere to the following warl-syntax:
dependency_string -> legal_value_string
The
dependency_string
substring is basically a string defining a boolean condition based on the dependent csrs (those listed in thedependency_fields
). Only when the boolean condition is satisfied, the corresponding warl function defined inlegal_value_string
substring is evaluated. A write only occurs when the evaluation of thelegal_value_string
also is True. The symbol->
is used to denote implies and is primarily used to split the string in to the above two substrings. If none of the entries in the list evaluate to True, then the current write value is considered illegal and the actions defined by the wr_illegal field is carried out.The substrings
dependency_string ->
is optional. If thedependency_fields
list is empty, then the substringdependency_string ->
must be omitted from the warl string.The
dependency_string
and thelegal_value_string
both follow the same legal syntax:<variable-name>[<hi-index>:<lo-index>] <op> <value-descriptors>
The
variable-name
field can be the name a csr or a subfield (without the hierarchical delimiter::
). Within thedependency_string
substring the variable names can only be those listed in thedependency_fields
list. In thelegal_value_string
substring however, thevariable-name
should be either writeval or the name the csr or the subfield (without the hierarchical delimiter::
) that the warl node belongs to.The indices fields
hi-index
andlo-index
are used to indicate the bit range of the variable that being looked-up or modified. The basic constraints are thathi-index
must be greater than thelo-index
. If only a single-bit is being looked-up/assigned, then:lo-index
can be skipped. This definition applies to both thedependency_string
and thelegal_value_string
.The
op
field in thedependency_string
substring can be one ofin
ornot in
to indicate that the variable takes the values defined in thevalue-descriptors
field or does not take those values respectively. In addition to the above operators, thelegal_value_string
can include one more operator :bitmask
. When using thebitmask
operator the value-descriptors have to be a list of two distinct-values as follows:csr_name[hi:lo] bitmask [mask, fixedval]
Both the
mask
andfixedval
fields are integers. All bits set in the mask indicates writable bits of the variable. All bits bits cleared in the mask indicate bits with a constant value which is derived from the corresponding bit in the fixedval field.Since the
dependency_string
is supposed to represent a boolean condition, it also has the flexibility to use basic boolean operators like&&
and||
around the above legal syntax. Examples are provided below:(csrA[2:0] in [0, 1]) && (csrB[5:0] in [0:25] || csrB[5:0] in [31,30]) ->
Restrictions imposed: The following restrictions are imposed on the above substrings:
No element of the value-descriptors must exceed the maximum value which can be supported by the indices of the csr/subfield.
The csrs/subfields used in the
dependency_string
must be in those listed in thedependency_fields
list.Valid operators in the
dependency_string
substring arein
andnot in
.Valid operators in the
legal_value_string
substring arein
,not in
andbitmask
Within the
legal_value_string
substrings the legal values of all bits of the csr/subfield must be specified. No bits must be left undefined.If the
dependency_fields
is empty, then only one legal string must be defined in this list.The first combination of the
dependency_string
andlegal_value_string
to evaluate to True, starting from the top of the list is given highest priority to define the next legal value of the csr/subfield.The reset-value of the csr/subfield must cause atleast one of the legal strings in the list to evaluate to True.
Assumptions
Since the list of all
dependency_string
substrings is not required to be exhaustively defined by the user, if none of thedependency_strings
in the list evaluate to true, then the current write operation should be treated as an illegal write operation, and the action defined by thewr_illegal
node must be carried out.If one of the dependent csrs/subfield defined in the
dependency_fields
is not used in thedependency_strings
, then it implictly assumed that, the variable does not affect the legal value for that string
wr_illegal : This field takes in a list of strings which define the next legal value of the field when an illegal value is being written to the csr/subfield. Each string needs to adhere to the following syntax:
dependency_string -> update_mode
The
dependency_string
follows the same rules, assumptions and restrictions described above. When thedependency_string
evaluates to True theupdate_mode
substring defines the next legal value of the csr/subfield. The supported values of theupdate_mode
string are :Unchanged: The value remains unchanged to the current legal value held in the csr/subfield.
<val>: A single value can also be specified
Nextup: ceiling(writeval) i.e. the next larger or the largest element of the legal list
Nextdown: floor(writeval) i.e. the next smallest or the smallest element of the legal list
Nearup: celing(writeval) i.e. the closest element in the list, with the larger element being chosen in case of a tie.
Neardown: floor(writeval) i.e. the closes element in the list, with the smaller element being chosen in case of a tie
Max: maximum of all legal values
Min: minimum of all legal values
Addr:
if ( val < base || val > bound) return Flip-MSB of field
Examples¶
# When base of mtvec depends on the mode field.
WARL:
dependency_fields: [mtvec::mode]
legal:
- "mode[1:0] in [0] -> base[29:0] in [0x20000000, 0x20004000]" # can take only 2 fixed values when mode==0.
- "mode[1:0] in [1] -> base[29:6] in [0x000000:0xF00000] base[5:0] in [0x00]" # 256 byte aligned when mode==1
wr_illegal:
- "mode[1:0] in [0] -> unchanged"
- "mode[1:0] in [1] && writeval in [0x2000000:0x4000000] -> 0x2000000" # predefined value if write value is
- "mode[1:0] in [1] && writeval in [0x4000001:0x3FFFFFFF] -> unchanged"
# When base of mtvec depends on the mode field. Using bitmask instead of range
WARL:
dependency_fields: [mtvec::mode]
legal:
- "mode[1:0] in [0] -> base[29:0] in [0x20000000, 0x20004000]" # can take only 2 fixed values when mode==0.
- "mode[1:0] in [1] -> base[29:0] bitmask [0x3FFFFFC0, 0x00000000]" # 256 byte aligned when mode==1
wr_illegal:
- "mode[1:0] in [0] -> unchanged" # no illegal for bitmask defined legal strings.
- Unchanged
# no dependencies. Mode field of mtvec can take only 2 legal values using range-descriptor
WARL:
dependency_fields:
legal:
- "mode[1:0] in [0x0:0x1] # Range of 0 to 1 (inclusive)"
wr_illegal:
- "0x00"
# no dependencies. using single-value-descriptors
WARL:
dependency_fields:
legal:
- "mode[1:0] in [0x0,0x1] # Range of 0 to 1 (inclusive)"
wr_illegal:
- "0x00"
Platform YAML Spec¶
This section describes each node of the PLATFORM-YAML. For each node, we have identified the fields required from the user and also the various constraints involved.
reset¶
Description: Stores the value for the reset vector. It can either be a label or an address.
label: A string field equal to the label in the assembly code
address: A value equal to the absolute address where the vector is present
Examples:
reset: label: reset_vector reset: label: 0x80000000
nmi¶
Description: Stores the value for the nmi vector. It can either be a label or an address.
label: A string field equal to the label in the assembly code.
address: A value equal to the absolute address where the vector is present.
Examples:
nmi: label: nmi_vector nmi: address: 0x8000000
mtime¶
Description: Stores the fields for memory mapped mtime register.
implemented: A boolean field indicating that the register has been implemented.
address: A value equal to the physical address at which the register is present.
Examples:
mtime: implemented: True address: 0x458Constraints:
None
mtimecmp¶
Description: Stores the fields for memory mapped mtimecmp register.
implemented: A boolean field indicating that the register has been implemented.
address: A value equal to the physical address at which the register is present.
Examples:
mtimecmp: implemented: True address: 0x458Constraints:
None
mtval_condition_writes¶
Description: Stores the fields for mtval_condition_writes register.
implemented: A Boolean value indicating whether the register is implemented.
behaviour: A dictionary type to specify which of the exceptions modify the mtval_condition_writes reg
e0: A string type describing the behaviour of exception 0.
e1: A string type describing the behaviour of exception 1.
e2: A string type describing the behaviour of exception 2.
e3: A string type describing the behaviour of exception 3.
e4: A string type describing the behaviour of exception 4.
e5: A string type describing the behaviour of exception 5.
e6: A string type describing the behaviour of exception 6.
e7: A string type describing the behaviour of exception 7.
e8: A string type describing the behaviour of exception 8.
e9: A string type describing the behaviour of exception 9.
e10: A string type describing the behaviour of exception 10.
e11: A string type describing the behaviour of exception 11.
e12: A string type describing the behaviour of exception 12.
e13: A string type describing the behaviour of exception 13.
e15: A string type describing the behaviour of exception 15.
Examples:
TBD: Provide a concrete use-case for the above.Constraints:
None
scause_non_standard¶
Description: Stores the fields for the scause register.
implemented: A boolean field indicating that the register has been implemented.
values: The list of exception values greater than 16 as assumed by the platform as integers.
Examples:
scause_non_standard: implemented: True value: [16,17,20]Constraints:
None
stval_condition_writes¶
Description: Stores the fields for stval_condition_writes register.
implemented: A Boolean value indicating whether the field is implemented.
behaviour: A dictionary type to specify which of the exceptions modify the stval_condition_writes reg
e0: A string type describing the behaviour of exception 0.
e1: A string type describing the behaviour of exception 1.
e2: A string type describing the behaviour of exception 2.
e3: A string type describing the behaviour of exception 3.
e4: A string type describing the behaviour of exception 4.
e5: A string type describing the behaviour of exception 5.
e6: A string type describing the behaviour of exception 6.
e7: A string type describing the behaviour of exception 7.
e8: A string type describing the behaviour of exception 8.
e9: A string type describing the behaviour of exception 9.
e10: A string type describing the behaviour of exception 10.
e11: A string type describing the behaviour of exception 11.
e12: A string type describing the behaviour of exception 12.
e13: A string type describing the behaviour of exception 13.
e15: A string type describing the behaviour of exception 15.
Examples:
TBD: Provide a concrete use-case for the above.Constraints:
None
zicbo_cache_block_sz¶
Description: byte size of the cache block
Examples:
zicbo_cache_block_sz : implemented: true zicbom_sz: 64 zicboz_sz: 64Constraints:
None
Debug YAML Spec¶
supported_xlen¶
Description: list of supported xlen on the target
Examples:
supported_xlen : [32] supported_xlen : [64, 32] supported_xlen : [64]Constraints:
None
Debug_Spec_Version¶
Description: Version number of Debug specification as string. Please enclose the version in “” to avoid type mismatches.
Examples:
Debug_Spec_Version: "1.0.0" Debug_Spec_Version: "0.13.2"Constraints:
should be a valid version later than 1.0.0
debug_mode¶
Description: Boolean value indicating if the debug instructions are accessible.
Examples:
debug_mode: False
parking_loop¶
Description: Integer value indicating the address of the debug parking loop
Examples:
parking_loop: 0x800