diff --git a/.yardopts b/.yardopts deleted file mode 100644 index cbca73fd6..000000000 --- a/.yardopts +++ /dev/null @@ -1 +0,0 @@ --o _site/ruby --embed-mixins 'lib/**/*.rb' diff --git a/README.adoc b/README.adoc index 787782c66..7e6aa73c3 100644 --- a/README.adoc +++ b/README.adoc @@ -107,5 +107,5 @@ Quick start: == More info * xref:arch/README.adoc[Architecture specification format] - * xref:arch/README.adoc[Documentation for the generator tool and IDL] - ** https://riscv-software-src.github.io/riscv-unified-db/ruby/index.html[YARD docs for the generator tool and IDL] + * xref:_site/ruby/arch_def/index.html[Ruby database object model documentation] + * xref:_site/ruby/idl/index.html[IDL Compiler documentation] diff --git a/Rakefile b/Rakefile index 5b5efce73..6e3640302 100644 --- a/Rakefile +++ b/Rakefile @@ -31,7 +31,8 @@ namespace :gen do desc "Generate documentation for the ruby tooling" task tool_doc: "#{$root}/.stamps/dev_gems" do Dir.chdir($root) do - sh "bundle exec yard doc" + sh "bundle exec yard doc --yardopts arch_def.yardopts" + sh "bundle exec yard doc --yardopts idl.yardopts" end end end diff --git a/arch_def.yardopts b/arch_def.yardopts new file mode 100644 index 000000000..0b0393ea3 --- /dev/null +++ b/arch_def.yardopts @@ -0,0 +1 @@ +-o _site/ruby/arch_def --no-private --embed-mixins --readme 'lib/DB_MODEL.README.adoc' 'lib/arch_obj_models/*.rb' lib/arch_def.rb diff --git a/idl.yardopts b/idl.yardopts new file mode 100644 index 000000000..bed1930f5 --- /dev/null +++ b/idl.yardopts @@ -0,0 +1 @@ +-o _site/ruby/idl --title 'IDL Compiler' --no-private --embed-mixins 'lib/idl/*.rb' lib/idl.rb diff --git a/lib/DB_MODEL.README.adoc b/lib/DB_MODEL.README.adoc new file mode 100644 index 000000000..b448d3d2b --- /dev/null +++ b/lib/DB_MODEL.README.adoc @@ -0,0 +1,99 @@ += Ruby interface to database + +A Ruby interface for https://github.com/riscv-software-src/riscv-unified-db[`riscv-unified-db`] is located in the `lib` directory. It can be used to query the database in the context of a configuration through a set of object models. + +The main class is `ArchDef`, which represents all of the database information plus any known configuration parameters. An `ArchDef` must be initialized from a configuration in the `cfg` directory. Two configurations are provided -- _32 and _64 -- that represent generic RV32/RV64 machines (_i.e._, the only known configuration parameter is `MXLEN`). + +== Configuration files + +A configuration consists of a folder under `cfgs`. Inside that folder, there are three required files and one optional directory. + +=== Required configuration files + +`cfg.yaml`:: +A YAML object (hash) that currently contains only one field `type`. `type` can be one of: + +* "partially configured": The configuration has some parameters and/or implemented extensions known, but others are not known. Examples of a _partially configured_ configuration are the generic _32/_64 configs and a profile (which has some known/mandatory extensions, but also many unknown/optional extensions). +* "fully configured": The configuration exhaustively lists a set of implmented extensions and parameters. An example of a _fully configured_ configuration is the `generic_rv64` example, which represents a theoritical implementation of RV64. In a _fully configured_ configuration, any extension that isn't known to be implemented is treated as unimplmented, and will be pruned out of the database for certain operations. + +`implemented_exts.yaml`:: + +A YAML file with an array of known implemented extensions along with their versions. + +.Example `implemented_exts.yaml` +[source,yaml] +---- +implemented_extensions: + - [A, "2.1.0"] + - [B, "1.0.0"] + - [C, "2.2.0"] + - [D, "2.2.0"] + - [F, "2.2.0"] + # ... +---- + +`params.yaml`:: + +A YAML file with values for parameters defined by the implemented extensions. Params must be exhuastive for a _fully configured_ configuration. Params will be schema checked using information stored in the database. + +.Example `params.yaml` +[source,yaml] +---- +params: + MISALIGNED_LDST: true + MISALIGNED_LDST_EXCEPTION_PRIORITY: high + MAX_MISALIGNED_ATOMICITY_GRANULE_SIZE: 0 + MISALIGNED_SPLIT_STRATEGY: by_byte + # ... +---- + +=== Optional overlay + +A configuration can customize the standard RISC-V specification by providing an `arch_overlay` directory. This can be used to, for example, describe a custom extension or to create custom behavior of a standard instructions. + +The `arch_overlay` directory is treated as an overlay on the standard `arch` directory. The contents of any file found in `arch_overlay` is either merged on top of the corresponding file in `arch`, if such a file exists, or added to the overall specification (_e.g._, when defining a new extension). An example of an overlay can be found in `cfgs/generic_rv64/arch_overlay`. + +== ArchDef interface + +An `ArchDef` is most easily obtained by using the convience function `arch_def_for(String)`, which takes the name of a folder under `cfgs`. Once you have an `ArchDef`, you can begin to query the database. + +.Architecture queries +[source,ruby] +---- +# get a configuration +arch_def = arch_def_for("_64") + +# all extensions, implemented or not +arch_def.extensions #=> Array + +# all implemented extensions +arch_def.implemented_extensions #=> Array + +# All Parameters for the 'C' extension +arch_def.extension("C").params #=> Array + +# all ratified extensions +arch_def.extensions.select { |ext| ext.state == "ratified" } #=> Array + +# all RISC-V instructions, implemented or not +arch_def.instructions #=> Array + +# all instructions defined by an implemented extension +arch_def.implemented_instructions #=> Array + +# the `addi` instruction +arch_def.instruction("addi") #=> Instruction + +# abstract syntax tree of the `addi` execution +arch_def.instruction("addi").operation_ast #=> Idl::AstNode + +# all CSRs, implemented or not +arch_def.csrs + +# all CSRs defined by an implemented extension +arch_def.implemented_csrs + +# the `mstatus.MPRV` CSR field +arch_def.csr("mstatus").field("MPRV") #=> CsrField + +---- \ No newline at end of file