diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml new file mode 100644 index 0000000..018e4b2 --- /dev/null +++ b/.github/workflows/build-pdf.yml @@ -0,0 +1,83 @@ +--- +name: Create Specification Document + +# The workflow is triggered by pull request, push to main, and manual dispatch. +on: + workflow_dispatch: + inputs: + version: + description: 'Release version, e.g. X.Y, for instance, 0.1:' + required: true + type: string + revision_mark: + description: 'Set revision mark as Draft, Stable, Frozen or Ratified:' + required: true + type: choice + options: + - Draft + - Stable + - Frozen + - Ratified + default: Draft + prerelease: + description: Tag as a pre-release? + required: false + type: boolean + default: true + draft: + description: Create release as a draft? + required: false + type: boolean + default: false + pull_request: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + + steps: + # Checkout the repository + - name: Checkout repository + uses: actions/checkout@v4 + with: + submodules: recursive + + # Pull the latest RISC-V Docs container image + - name: Pull Container + run: docker pull riscvintl/riscv-docs-base-container-image:latest + + # Override VERSION and REVMARK for manual workflow dispatch + - name: Update environment variables + run: | + echo "VERSION=v${{ github.event.inputs.version }}" >> "$GITHUB_ENV" + echo "REVMARK=${{ github.event.inputs.revision_mark }}" >> "$GITHUB_ENV" + if: github.event_name == 'workflow_dispatch' + + # Build Files + - name: Build Files + run: make + + # Upload the built PDF files as a single artifact + - name: Upload Build Artifacts + uses: actions/upload-artifact@v4 + with: + name: Build Artifacts + path: ${{ github.workspace }}/build/*.pdf + retention-days: 30 + + # Create Release + - name: Create Release + uses: softprops/action-gh-release@v2 + with: + files: ${{ github.workspace }}/build/*.pdf + tag_name: v${{ github.event.inputs.version }} + name: Release ${{ github.event.inputs.version }} + draft: ${{ github.event.inputs.draft }} + prerelease: ${{ github.event.inputs.prerelease }} + env: + GITHUB_TOKEN: ${{ secrets.GHTOKEN }} + if: github.event_name == 'workflow_dispatch' + # This condition ensures this step only runs for workflow_dispatch events. diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml new file mode 100644 index 0000000..74b9ec3 --- /dev/null +++ b/.github/workflows/pre-commit.yml @@ -0,0 +1,15 @@ +--- +name: pre-commit + +on: + pull_request: + push: + branches: [main] + +jobs: + pre-commit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + - uses: pre-commit/action@v3.0.0 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..28df974 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +/build/* +/images/* diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..cde1eb5 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "docs-resources"] + path = docs-resources + url = https://github.com/riscv/docs-resources.git diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..63fae1b --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,26 @@ +--- +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: check-json + - id: check-symlinks + - id: check-yaml + - id: end-of-file-fixer + - id: trailing-whitespace + args: [--markdown-linebreak-ext=md] + + - repo: local + hooks: + - id: forbidden-file-extensions + name: forbidden-file-extensions + entry: disallow these file extensions + language: fail + # Disallow other asciidoc extensions except .adoc + files: .*\.(asciidoc|asc)$ + + - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt + rev: 0.2.3 + hooks: + - id: yamlfmt + args: [--mapping, '2', --sequence, '4', --offset, '2'] diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c604eca --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,15 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +**_NOTE:_** PROJECTS BUILT USING THE TEMPLATE SHOULD UPDATE THE BELOW SECTIONS AS-NEEDED. + +## [Unreleased] + +## [4.0.0] - 2004-01-27 +- Workflow improvements +- Makefile refactoring +- Readme updates diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..f0c2967 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,2 @@ +# RISC-V Code of Conduct +All RISC-V International projects are governed by the RISC-V Code of Conduct found at https://riscv.org/community/community-code-of-conduct/. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab2007c..1d98c72 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,26 +1,23 @@ # Contribution Guidelines -As an open-source project, we welcome and encourage the community to submit patches directly to the project. In our collaborative open source environment, standards and methods for submitting changes help reduce the chaos that can result from an active development community. +As an open-source project, we appreciate and encourage community members to submit patches directly to the project. To maintain a well-organized development environment, we have established standards and methods for submitting changes. This document outlines the process for submitting patches to the project, ensuring that your contribution is swiftly incorporated into the codebase. -This document explains how to submit patches to the project so your patch will be accepted quickly in the codebase. +# Licensing -## Licensing +Licensing is crucial for open-source projects, as it guarantees that the software remains available under the conditions specified by the author. -Licensing is very important to open source projects. It helps ensure the software continues to be available under the terms that the author desired. +This project employs the Creative Commons Attribution 4.0 International license, which can be found in the LICENSE file within the project's repository. -This project uses the Creative Commons Attribution 4.0 International license, as found in the [LICENSE](https://github.com/riscv/docs-spec-template/blob/main/LICENSE) file in the project's repo. +Licensing defines the rights granted to you as an author by the copyright holder. It is essential for contributors to fully understand and accept these licensing rights. In some cases, the copyright holder may not be the contributor, such as when the contributor is working on behalf of a company. -A license tells you what rights you have as an author, as provided by the copyright holder. It is important that the contributor fully understands the licensing rights and agrees to them. Sometimes the copyright holder isn't the contributor, such as when the contributor is doing work on behalf of a company. +# Developer Certificate of Origin (DCO) +To uphold licensing criteria and demonstrate good faith, this project mandates adherence to the Developer Certificate of Origin (DCO) process. -## Developer Certification of Origin (DCO) +The DCO is an attestation appended to every contribution from each author. In the commit message of the contribution (explained in greater detail later in this document), the author adds a Signed-off-by statement, thereby accepting the DCO. -To make a good faith effort to ensure licensing criteria are met, this project requires the Developer Certificate of Origin (DCO) process to be followed. +When an author submits a patch, they affirm that they possess the right to submit the patch under the designated license. The DCO agreement is displayed below and at https://developercertificate.org. -The DCO is an attestation attached to every contribution made by every author. In the commit message of the contribution (described more fully later in this document), the author simply adds a ``Signed-off-by`` statement and thereby agrees to the DCO. -When an author submits a patch, it is a commitment that the contributor has the right to submit the patch per the license. The DCO agreement is shown below and at https://developercertificate.org. - -``` Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: @@ -38,7 +35,7 @@ By making a contribution to this project, I certify that: in the file; or (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified + person who certified (a), (b), or (c), and I have not modified it. (d) I understand and agree that this project and the contribution @@ -46,19 +43,16 @@ By making a contribution to this project, I certify that: personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. -``` - -### DCO Sign-Off Methods - -The DCO requires that a sign-off message, in the following format, appears on each commit in the pull request: -`Signed-off-by: Stephano Cetola ` +# DCO Sign-Off Methods +The DCO necessitates the inclusion of a sign-off message in the following format for each commit within the pull request: -You are required to use your real name in the sign-off message. +Signed-off-by: Stephano Cetola -The DCO text can either be manually added to your commit body, or you can add either ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget to add the sign-off you can also amend a previous commit with the sign-off by running ``git commit --amend -s``. If you've pushed your changes to GitHub already you'll need to force push your branch after this with ``git push -f``. +Please use your real name in the sign-off message. +You can manually add the DCO text to your commit body or include either -s or --signoff in your standard Git commit commands. If you forget to incorporate the sign-off, you can also amend a previous commit with the sign-off by executing git commit --amend -s. If you have already pushed your changes to GitHub, you will need to force push your branch afterward using git push -f. -**Note:** +Note: -The name and email address of the account you use to submit your PR must match the name and email address on the ``Signed-off-by`` line in your commit message. +Ensure that the name and email address associated with your GitHub account match the name and email address in the Signed-off-by line of your commit message. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..651404c --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,8 @@ +# Governance +This project for the template specification is governed by the Documentation SIG. + +The group can be joined by RISC-V members at: https://lists.riscv.org/g/sig-documentation. + +Mailing list archives are available at: https://lists.riscv.org/g/sig-documentation/topics. + +**_NOTE:_** PROJECTS BUILT USING THE TEMPLATE SHOULD UPDATE THE ABOVE TEXT AS-NEEDED. diff --git a/LICENSE b/LICENSE index 53883b1..2f244ac 100644 --- a/LICENSE +++ b/LICENSE @@ -49,7 +49,7 @@ exhaustive, and do not form part of our licenses. such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. More_considerations - for the public: + for the public: wiki.creativecommons.org/Considerations_for_licensees ======================================================================= @@ -393,4 +393,3 @@ the avoidance of doubt, this paragraph does not form part of the public licenses. Creative Commons may be contacted at creativecommons.org. - diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..f218343 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,6 @@ +# Maintainers +This project is maintained by the following people: + +- Bill Traynor ([wmat](https://github.com/wmat)) + +**_NOTE:_** PROJECTS BUILT USING THE TEMPLATE SHOULD UPDATE THE ABOVE TEXT AS-NEEDED. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..4e75401 --- /dev/null +++ b/Makefile @@ -0,0 +1,95 @@ +# Makefile for RISC-V Doc Template +# +# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 +# International License. To view a copy of this license, visit +# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to +# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. +# +# SPDX-License-Identifier: CC-BY-SA-4.0 +# +# Description: +# +# This Makefile is designed to automate the process of building and packaging +# the Doc Template for RISC-V Extensions. + +DOCS := \ + clic.adoc + +DATE ?= $(shell date +%Y-%m-%d) +VERSION ?= v0.9 +REVMARK ?= Draft +DOCKER_IMG := riscvintl/riscv-docs-base-container-image:latest +ifneq ($(SKIP_DOCKER),true) + DOCKER_CMD := docker run --rm -v ${PWD}:/build -w /build \ + ${DOCKER_IMG} \ + /bin/sh -c + DOCKER_QUOTE := " +endif + +SRC_DIR := src +BUILD_DIR := build + +DOCS_PDF := $(DOCS:%.adoc=%.pdf) +DOCS_HTML := $(DOCS:%.adoc=%.html) + +XTRA_ADOC_OPTS := +ASCIIDOCTOR_PDF := asciidoctor-pdf +ASCIIDOCTOR_HTML := asciidoctor +OPTIONS := --trace \ + -a compress \ + -a mathematical-format=svg \ + -a revnumber=${VERSION} \ + -a revremark=${REVMARK} \ + -a revdate=${DATE} \ + -a pdf-fontsdir=docs-resources/fonts \ + -a pdf-theme=docs-resources/themes/riscv-pdf.yml \ + $(XTRA_ADOC_OPTS) \ + -D build \ + --failure-level=ERROR +REQUIRES := --require=asciidoctor-bibtex \ + --require=asciidoctor-diagram \ + --require=asciidoctor-lists \ + --require=asciidoctor-mathematical + +.PHONY: all build clean build-container build-no-container build-docs + +all: build + +build-docs: $(DOCS_PDF) $(DOCS_HTML) + +vpath %.adoc $(SRC_DIR) + +%.pdf: %.adoc + $(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE) + +%.html: %.adoc + $(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE) + +build: + @echo "Checking if Docker is available..." + @if command -v docker >/dev/null 2>&1 ; then \ + echo "Docker is available, building inside Docker container..."; \ + $(MAKE) build-container; \ + else \ + echo "Docker is not available, building without Docker..."; \ + $(MAKE) build-no-container; \ + fi + +build-container: + @echo "Starting build inside Docker container..." + $(MAKE) build-docs + @echo "Build completed successfully inside Docker container." + +build-no-container: + @echo "Starting build..." + $(MAKE) SKIP_DOCKER=true build-docs + @echo "Build completed successfully." + +# Update docker image to latest +docker-pull-latest: + docker pull ${DOCKER_IMG} + +clean: + @echo "Cleaning up generated files..." + rm -rf $(BUILD_DIR) + @echo "Cleanup completed." diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..d89c32d --- /dev/null +++ b/README.adoc @@ -0,0 +1,111 @@ += RISC-V Specification Template + +This repository serves as a template for creating GitHub repositories within the RISC-V organization for the purpose of developing specifications. It aims to facilitate and standardize the process of specification development. + +NOTE: If you are viewing this in a specification repository, kindly update the title for this section and provide an introduction relevant to your repository. + +== License + +This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the link:LICENSE[LICENSE] file. + +== Maintainers + +The list of maintainers of this specification is maintained in the link:MAINTAINERS.md[MAINTAINERS] file. + +== Contributors + +The list of contributors to this specification is maintained in the link:src/contributors.adoc[contributors] file. + +For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUTING] file. + +== Governance + +The governance for this project is defined in the link:GOVERNANCE.md[GOVERNANCE] file. + +Community information, including meeting (if held) and mailing lists are detailed in this file. + +== Building the Document + +=== Directory Structure + +The following directories are used to organize the contents of this repo: + +* `dependencies/`: software dependencies needed to build the specification +* `docs-resources/`: resources for all specifications sourced from link:.gitmodules[git submodule] +* `src/`: source files for the specification +* `build/`: default directory where the build artifacts are generated + +=== Prerequisites + +To build the document, you'll need the following tools installed on your system: + +* Make +* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, and asciidoctor-mathematical +* Docker + +=== Cloning the Repository + +```shell +git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git +``` + +All in one single line: + +```shell +git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git && cd docs-spec-template && git submodule update --init --recursive + +``` + +=== Building the Documentation + +To start the build process, run: + +```shell +cd ./docs-spec-template && make build +``` + +The link:Makefile[] script will check the availability of Docker on your system: + +* If Docker is available, the documentation will be built inside a Docker container using the image riscvintl/riscv-docs-base-container-image:latest. This ensures a consistent build environment across different systems. +* If Docker is not available, the documentation will be built directly on your system using the installed tools. + +The documentation is generated from the AsciiDoctor source files in your project. The primary source file is specified by the `HEADER_SOURCE` variable in the Makefile. + +The build process utilizes several options, including theming and font settings, and generates a PDF document as output. + +=== Cleaning up + +To clean up the generated files, run: + +```shell +make clean +``` + +== Enabling pre-commit checks locally + +The repository has some basic commit checks set up with https://pre-commit.com/[pre-commit] that will be enforced by the GitHub CI. +To ensure these checks are also run in the local repository while making changes the following can be done: + +.Installing pre-commit tool +[source,shell] +---- +# Do once on your system +pip3 install pre-commit +---- + +.Installing pre-commit git hook in repo +[source,shell] +---- +# Do once in local repo +pre-commit install +---- + +Rather than doing the above `pre-commit install` in every repo that uses it, you can do it https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories[once on your system.] + +When enabling additional checks https://pre-commit.com/#plugins[by editing .pre-commit-config.yaml], it is recommended running the newly added check on all files in the repository. This can be done with the following command: + +.Running all pre-commit hooks on all files +[source,shell] +---- +pre-commit run --all-files +---- diff --git a/README.md b/README.md deleted file mode 100644 index 43ea0b9..0000000 --- a/README.md +++ /dev/null @@ -1,8 +0,0 @@ -This repository contains the [proposal for a RISC-V Core-Local -Interrupt Controller (CLIC)](clic.adoc). - -This work is licensed under a Creative Commons Attribution 4.0 International -License. See the LICENSE file for details. - -Charter: -The Core-Local Interrupt Controller (CLIC) is designed to provide low-latency, vectored, pre-emptive interrupts for RISC-V systems. When activated the CLIC subsumes and replaces the original RISC-V basic local interrupt scheme. The CLIC has a base design that requires minimal hardware, but supports additional extensions to provide hardware acceleration. The goal of the CLIC is to provide support for a variety of software ABI and interrupt models, without complex hardware that can impact high-performance processor implementations. diff --git a/clic.pdf b/clic.pdf deleted file mode 100644 index 6d5fa86..0000000 Binary files a/clic.pdf and /dev/null differ diff --git a/dependencies/Gemfile b/dependencies/Gemfile new file mode 100644 index 0000000..8cf7a50 --- /dev/null +++ b/dependencies/Gemfile @@ -0,0 +1,14 @@ +source 'https://rubygems.org' +gem 'asciidoctor' +gem 'asciidoctor-bibtex' +gem 'asciidoctor-diagram' +gem 'asciidoctor-mathematical' +gem 'asciidoctor-pdf' +gem 'citeproc-ruby' +gem 'coderay' +gem 'csl-styles' +gem 'json' +gem 'pygments.rb' +gem 'rghost' +gem 'rouge' +gem 'ruby_dev' diff --git a/dependencies/README.md b/dependencies/README.md new file mode 100644 index 0000000..f64a366 --- /dev/null +++ b/dependencies/README.md @@ -0,0 +1,2 @@ +Dependencies for the build environment for various package managers. Used in +`.github/workflows/`. diff --git a/dependencies/apt_packages.txt b/dependencies/apt_packages.txt new file mode 100644 index 0000000..6ddd571 --- /dev/null +++ b/dependencies/apt_packages.txt @@ -0,0 +1,31 @@ +bison +build-essential +python3-pip +cmake +curl +flex +fonts-lyx +git +graphviz +default-jre +libcairo2-dev +libffi-dev +libgdk-pixbuf2.0-dev +libpango1.0-dev +libxml2-dev +libglib2.0-dev +make +pkg-config +ruby +ruby-dev +libgif-dev +libwebp-dev +libzstd-dev +ruby-full +gem +npm +texlive-latex-base +texlive-fonts-recommended +texlive-fonts-extra +texlive-latex-extra +texlive-science diff --git a/dependencies/package.json b/dependencies/package.json new file mode 100644 index 0000000..7347d43 --- /dev/null +++ b/dependencies/package.json @@ -0,0 +1,8 @@ +{ + "dependencies": { + "bytefield-svg": "^1.8.0", + "wavedrom-cli": "^2.6.8" + }, + "name": "local", + "version": "0.0.1" +} diff --git a/docs-resources b/docs-resources new file mode 160000 index 0000000..35203a4 --- /dev/null +++ b/docs-resources @@ -0,0 +1 @@ +Subproject commit 35203a4f123d0be162b6b5ea213a657b594f8c36 diff --git a/images/risc-v_logo.png b/images/risc-v_logo.png deleted file mode 100644 index d754746..0000000 Binary files a/images/risc-v_logo.png and /dev/null differ diff --git a/src/bibliography.adoc b/src/bibliography.adoc new file mode 100644 index 0000000..4cc3eb7 --- /dev/null +++ b/src/bibliography.adoc @@ -0,0 +1,4 @@ +[bibliography] +== Bibliography + +bibliography::[] diff --git a/src/chapter2.adoc b/src/chapter2.adoc new file mode 100644 index 0000000..856334b --- /dev/null +++ b/src/chapter2.adoc @@ -0,0 +1,48 @@ +[[chapter2]] +== The Second Chapter + +. The first item. + +. The second item. ++ +.. The first sub item. + +.. The second sub item. ++ +[CAUTION] +==== +A moment of caution is required for this block of text must be read and apreciated for its importance. +==== + +. Yet another item. + +. Again, an item. + +.. A multi-line item. ++ +This item has multiple lines. ++ +By multiple lines, this is what we mean. ++ +Seriously, multiple. + +=== An example table + +.Nonsensical table +[cols="^1,^1,^1,^1,^3,^3",stripes=even,options="header"] +|=== +4+|Letters _and_ bits {set:cellbgcolor:green} 2+|A much longer area +|L|R|W|X|Quarter 1|Quarter 2 +|{set:cellbgcolor:!} 0|0|0|0 2+|Rows alternate colors +|0|0|0|1|Thing 1|Thing 2 +|1|0|0|0|Thing 3|Thing 4 +|1|1|1|1 2+|Span Thing 1 and 2 +|=== + +=== Sub section + +Diam donec adipiscing tristique risus indexterm:[risus]. Nisl rhoncus mattis rhoncus urna. Egestas egestas fringilla phasellus faucibus scelerisque eleifend donec pretium vulputate. Porta non pulvinar neque laoreet suspendisse interdum consectetur libero id. Massa vitae tortor condimentum lacinia quis vel. Donec ac odio tempor orci. Mi sit amet mauris commodo quis imperdiet massa tincidunt. Quis enim lobortis scelerisque fermentum dui. Lacus viverra vitae congue eu. Sed faucibus turpis in eu mi bibendum neque. Sit amet porttitor eget dolor. Aliquet eget sit amet tellus cras adipiscing enim. Id cursus metus aliquam eleifend mi. Vestibulum lorem sed risus ultricies tristique nulla aliquet. + +=== Yet another subsection + +Quam lacus suspendisse faucibus interdum posuere lorem ipsum. Nulla aliquet enim tortor at auctor urna nunc id cursus. Massa massa ultricies mi quis hendrerit dolor magna. Integer enim neque volutpat ac tincidunt. Dolor magna eget est lorem ipsum dolor. Urna neque viverra justo nec. Neque gravida in fermentum et. Fringilla ut morbi tincidunt augue interdum velit euismod. Dolor sit amet consectetur adipiscing elit. Eu facilisis sed odio morbi. In cursus turpis massa tincidunt dui. Orci indexterm:[orci] phasellus egestas tellus rutrum tellus. Semper eget duis at tellus at urna condimentum. Orci porta non pulvinar neque laoreet suspendisse interdum consectetur. diff --git a/clic.adoc b/src/clic.adoc similarity index 99% rename from clic.adoc rename to src/clic.adoc index 8f331ad..d9e86cd 100644 --- a/clic.adoc +++ b/src/clic.adoc @@ -35,39 +35,41 @@ [[riscv-doc-template]] = Core-Local Interrupt Controller (CLIC) RISC-V Privileged Architecture Extensions -:stem: latexmath -:description: RISC-V Core-Local Interrupt Controller -:company: RISC-V.org -:revdate: 03/14/2024 -:revnumber: 0.9-draft -:revremark: This document is in the Stable state. Assume anything could still change, but limited change should be expected. See https://wiki.riscv.org/display/HOME/Specification+States -:url-riscv: http://riscv.org -:doctype: book -//:doctype: report +include::../docs-resources/global-config.adoc[] +:docgroup: RISC-V Task Group +:description: RISC-V Example Specification Document (Zexmpl) +:revdate: 1/2023 +:revnumber: 1.0 +:revremark: This document is under development. Expect potential changes. Visit http://riscv.org/spec-state for further details. +:revinfo: :preface-title: Preamble :colophon: :appendix-caption: Appendix -:imagesdir: images -:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] -//:page-background-image: image:draft.svg[opacity=20%] -//:title-page-background-image: none +// https://docs.asciidoctor.org/asciidoc/latest/macros/images-directory/ +:imagesdir: ../docs-resources/images +:title-logo-image: image:risc-v_logo.png["RISC-V International Logo",pdfwidth=3.25in,align=center] // Settings: :experimental: :reproducible: -// needs to be changed -:wavedrom: - +//:WaveDromEditorApp: app/wavedrom-editor.app :imagesoutdir: images +//:srcdir: src +:bibtex-file: src/example.bib +:bibtex-order: alphabetical +:bibtex-style: apa :icons: font :lang: en :listing-caption: Listing +:sectnums: +:toc: left +:toclevels: 4 :source-highlighter: pygments ifdef::backend-pdf[] :source-highlighter: coderay endif::[] :data-uri: :hide-uri-scheme: -:stem: +:stem: latexmath :footnote: :xrefstyle: short diff --git a/src/contributors.adoc b/src/contributors.adoc new file mode 100644 index 0000000..13fd776 --- /dev/null +++ b/src/contributors.adoc @@ -0,0 +1,7 @@ +== Contributors + +This RISC-V specification has been contributed to directly or indirectly by: + +[%hardbreaks] +* Author1 +* Author2 diff --git a/src/example.bib b/src/example.bib new file mode 100644 index 0000000..4c368b1 --- /dev/null +++ b/src/example.bib @@ -0,0 +1,36 @@ +@inproceedings{riscI-isca1981, + title = {{RISC I}: {A} Reduced Instruction Set {VLSI} Computer}, + author = {David A. Patterson and Carlo H. S\'{e}quin}, + booktitle = {ISCA}, + location = {Minneapolis, Minnesota, USA}, + pages = {443-458}, + year = {1981} +} + +@inproceedings{Katevenis:1983, + author = {Manolis G.H. Katevenis and Robert W. Sherburne Jr. and David A. Patterson and Carlo H. S\'{e}quin}, + title = {The {RISC II} micro-architecture}, + booktitle = {Proceedings VLSI 83 Conference}, + year = {1983}, + month = {August} +} + +@inproceedings{Ungar:1984, + author = {David Ungar and Ricki Blau and Peter Foley and Dain Samples and David Patterson}, + title = {Architecture of {SOAR}: {Smalltalk} on a {RISC}}, + booktitle = {ISCA}, + address = {Ann Arbor, MI}, + year = {1984}, + pages = {188-197} +} + +@article{spur-jsscc1989, + author = {David D. Lee and Shing I. Kong and Mark D. Hill and George S. Taylor and David A. Hodges and Randy H. Katz and David A. Patterson}, + title = {A {VLSI} Chip Set for a Multiprocessor Workstation--{Part I}: An {RISC} Microprocessor with Coprocessor Interface and Support for Symbolic Processing}, + journal = {IEEE JSSC}, + year = {1989}, + volume = {24}, + number = {6}, + pages = {1688-1698}, + month = {December} +} diff --git a/src/index.adoc b/src/index.adoc new file mode 100644 index 0000000..4abaca2 --- /dev/null +++ b/src/index.adoc @@ -0,0 +1,2 @@ +[index] +== Index diff --git a/src/intro.adoc b/src/intro.adoc new file mode 100644 index 0000000..9b6292b --- /dev/null +++ b/src/intro.adoc @@ -0,0 +1,43 @@ +[[intro]] +== Introduction + +Lorem ipsum indexterm:[Lorem ipsum] dolor sit amet, consectetur adipiscing elit, sed do *eiusmod tempor* incididunt ut labore et dolore magna aliqua. Felis imperdiet proin fermentum leo vel orci porta. Volutpat lacus laoreet non curabitur indexterm:[curabitur] gravida indexterm:[gravida]. Posuere urna nec tincidunt praesent semper feugiat nibh. Elit ``ullamcorper`` dignissim cras tincidunt lobortis. Malesuada fames ac turpis egestas integer eget. Tristique sollicitudin nibh sit amet commodo. Sed felis eget velit aliquet. Sit amet aliquam id diam maecenas ultricies mi. Consectetur purus ut faucibus pulvinar. Lectus urna duis convallis convallis tellus id. Fermentum iaculis eu non diam. Feugiat in fermentum posuere urna nec tincidunt praesent semper feugiat. Urna nec tincidunt praesent semper feugiat nibh. + +.Nonsensical code +[source, python] +---- +def banana_apple(): + x = "banana" + y = "apple" + for i in range(len(x)): + print(x[i], y[i]) + z = x + y + return z + +result = banana_apple() +print("Result:", result) +---- + +Commodo viverra maecenas accumsan lacus. Vulputate odio ut enim blandit indexterm:[blandit] volutpat maecenas volutpat blandit. Urna porttitor rhoncus dolor purus non. Tellus mauris a diam maecenas sed. Vitae auctor eu augue ut lectus. Ridiculus mus mauris vitae ultricies leo integer. Consequat semper viverra nam *libero* justo laoreet sit amet. Pellentesque pulvinar pellentesque habitant morbi tristique senectus et netus et. Ac placerat vestibulum lectus mauris ``ultrices`` eros in cursus turpis. Accumsan in nisl nisi scelerisque eu ultrices vitae. Cras ornare arcu dui vivamus. Vitae congue mauris rhoncus aenean. Consequat mauris nunc congue nisi vitae suscipit tellus. Tempus egestas sed sed risus pretium quam vulputate dignissim. Quis varius quam quisque id diam vel. Mattis nunc sed blandit libero volutpat sed cras ornare arcu. Amet mauris commodo quis imperdiet massa tincidunt nunc. + +[NOTE] +==== +The name RISC-V indexterm:[RISC-V] was chosen to represent the fifth major RISC ISA design from UC Berkeley (RISC-I cite:[riscI-isca1981], RISC-II cite:[Katevenis:1983], SOAR cite:[Ungar:1984], and SPUR cite:[spur-jsscc1989] were the first four). We also pun on the use of the Roman numeral "V" to signify "variations" and "vectors", as support for a range of architecture research, including various data-parallel accelerators, is an explicit goal of the ISA design. +==== + +=== Sub Section of Introduction + +Pellentesque habitant morbi *tristique* senectus et netus et. Aliquam purus sit amet luctus. Odio eu ``feugiat`` pretium nibh ipsum consequat nisl vel. Euismod lacinia at quis risus sed vulputate odio ut. Eu sem integer vitae justo eget. Cursus euismod quis viverra nibh. Tempus egestas sed sed risus. Quis imperdiet massa tincidunt nunc pulvinar. Id venenatis a condimentum vitae sapien pellentesque habitant. + +.Nonsensical wavedrom signals +[wavedrom, svg] +.... +{ + "signal": [ + { "name": "Clock", "wave": "P.......P" }, + { "name": "Data", "wave": "x.x..xx.x" }, + { "name": "Control", "wave": "0.1.01..0" }, + { "name": "Error", "wave": "zZzZzZzZz" } + ] +} +....