Upgrade Specification

Signed-off-by: Rafael Sene <rafael@riscv.org>

.github/workflows/build-pdf.yml

@@ -0,0 +1,73 @@
+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.Z:'
+        required: true
+        type: string
+      revision_mark: 
+          description: 'Set revision mark as Draft, Release or Stable:'
+          required: true
+          type: string
+          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:
+    # Step 1: Checkout the repository
+    - name: Checkout repository
+      uses: actions/checkout@v3
+      with:
+        submodules: 'recursive'
+
+    # Step 2: Pull the latest RISC-V Docs container image
+    - name: Pull Container
+      run: docker pull riscvintl/riscv-docs-base-container-image:latest
+
+    # Step 3: Build Files
+    - name: Build Files
+      run: make
+      env:
+        VERSION: v${{ github.event.inputs.version }}
+        REVMARK: ${{ github.event.inputs.revision_mark }}
+
+    # Step 4: Upload the built PDF files as a single artifact
+    - name: Upload Build Artifacts
+      uses: actions/upload-artifact@v3
+      with:
+        name: Build Artifacts
+        path: ${{ github.workspace }}/*.pdf
+        retention-days: 30
+
+    # Create Release
+    - name: Create Release
+      uses: softprops/action-gh-release@v1
+      with:
+        files: ${{ github.workspace }}/*.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.

CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contribution Guidelines
+
+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.
+
+# Licensing
+
+Licensing is crucial for open-source projects, as it guarantees that the software remains available under the conditions specified by the author.
+
+This project employs the Creative Commons Attribution 4.0 International license, which can be found in the LICENSE file within the project's repository.
+
+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.
+
+# 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.
+
+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.
+
+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.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    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
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    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 necessitates the inclusion of a sign-off message in the following format for each commit within the pull request:
+
+Signed-off-by: Stephano Cetola <scetola@linuxfoundation.org>
+
+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:
+
+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.

Makefile

@@ -6,6 +6,65 @@
 #
 
 .SUFFIXES: .adoc .pdf .html
+# 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.
+
+DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \
+riscvintl/riscv-docs-base-container-image:latest
+
+HEADER_SOURCE := header.adoc
+PDF_RESULT := semihosting.pdf
+
+ASCIIDOCTOR_PDF := asciidoctor-pdf
+OPTIONS := --trace \
+           -a compress \
+           -a mathematical-format=svg \
+           -a pdf-fontsdir=docs-resources/fonts \
+           -a pdf-theme=docs-resources/themes/riscv-pdf.yml \
+           --failure-level=ERROR
+REQUIRES := --require=asciidoctor-bibtex \
+            --require=asciidoctor-diagram \
+            --require=asciidoctor-mathematical
+
+.PHONY: all build clean build-container build-no-container
+
+all: build
+
+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..."
+	$(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)"
+	@echo "Build completed successfully inside Docker container."
+
+build-no-container:
+	@echo "Starting build..."
+	$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)
+	@echo "Build completed successfully."
+
+clean:
+	@echo "Cleaning up generated files..."
+	rm -f $(PDF_RESULT)
+	@echo "Cleanup completed."
 
 ADOC_FILES=riscv-semihosting-spec.adoc
 PDF_FILES=$(ADOC_FILES:.adoc=.pdf)

bibliography.adoc

@@ -0,0 +1,4 @@
+[bibliography]
+== Bibliography
+
+bibliography::[]

contributors.adoc

@@ -0,0 +1,10 @@
+== Contributors
+
+This RISC-V specification has been contributed to directly or indirectly by:
+
+[%hardbreaks]
+* Krste Asanovic <krste@sifive.com>
+* Palmer Dabbelt <palmer@dabbelt.com>
+* Liviu Ionescu <ilg@livius.net>
+* Keith Packard <keith.packard@sifive.com>
+* Megan Wachs <megan@sifive.com>

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'

dependencies/README.md

@@ -0,0 +1,2 @@
+Dependencies for the build environment for various package managers.  Used in
+`.github/workflows/`.

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

dependencies/package.json

@@ -0,0 +1,8 @@
+{
+  "dependencies": {
+    "bytefield-svg": "^1.8.0",
+    "wavedrom-cli": "^2.6.8"
+  },
+  "name": "local",
+  "version": "0.0.1"
+}

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}
+}

header.adoc

@@ -0,0 +1,66 @@
+= RISC-V Semihosting
+Krste Asanovic <krste@sifive.com>; Palmer Dabbelt <palmer@dabbelt.com>; Liviu Ionescu <ilg@livius.net>; Keith Packard <keith.packard@sifive.com>; Megan Wachs <megan@sifive.com>
+:docgroup: RISC-V Extension
+:description: Semihosting
+:company: RISC-V.org
+:revdate: 4/2020
+:revnumber: 0.2
+:revremark: This document is under development. Expect potential changes.
+:revinfo:
+:url-riscv: http://riscv.org
+:doctype: book
+:preface-title: Preamble
+:colophon:
+:appendix-caption: Appendix
+:imagesdir: docs-resources/images
+:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center]
+// Settings:
+:experimental:
+:reproducible:
+//:WaveDromEditorApp: app/wavedrom-editor.app
+:imagesoutdir: docs-resources/images
+:bibtex-file: 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: latexmath
+:footnote:
+:xrefstyle: short
+
+[WARNING]
+.This document is in the link:http://riscv.org/spec-state[Development state]
+====
+Expect potential changes. This draft specification is likely to evolve before
+it is accepted as a standard. Implementations based on this draft
+may not conform to the future standard.
+====
+
+[preface]
+== Copyright and license information
+This specification is licensed under the Creative Commons
+Attribution 4.0 International License (CC-BY 4.0). The full
+license text is available at
+https://creativecommons.org/licenses/by/4.0/.
+
+Copyright 2024 by RISC-V International.
+
+[preface]
+include::contributors.adoc[]
+
+include::intro.adoc[]
+include::semihosting.adoc[]
+
+// The index must precede the bibliography
+include::index.adoc[]
+include::bibliography.adoc[]

index.adoc

@@ -0,0 +1,2 @@
+[index]
+== Index

intro.adoc

@@ -0,0 +1,11 @@
+[[intro]]
+== Introduction
+
+Semihosting is a technique where an application running in a debug or
+simulation environment can access elements of the system hosting the
+debugger or simulator including console, file system, time and other
+functions. This allows for diagnostics, interaction and measurement of
+a target system without requiring significant infrastructure to exist
+in that target environment.
+
+