From 9d47032f4d6d4191719eaaf5e4a9dcba3db573e2 Mon Sep 17 00:00:00 2001 From: Harrison Mutai Date: Wed, 18 Sep 2024 14:37:34 +0000 Subject: [PATCH] Add additional information to README Provide a reference to the rendered documentation, CI status, and releases. Update the status section to reflect things as they are. Signed-off-by: Harrison Mutai --- README.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ readme.rst | 47 ---------------------------------------------- 2 files changed, 55 insertions(+), 47 deletions(-) create mode 100644 README.md delete mode 100644 readme.rst diff --git a/README.md b/README.md new file mode 100644 index 0000000..2bcc31e --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +[![Build Status](https://github.com/FirmwareHandoff/firmware_handoff/actions/workflows/main.yml/badge.svg)](https://github.com/FirmwareHandoff/firmware_handoff/actions/workflows/main.yml) +[![Release Version](https://img.shields.io/github/v/release/FirmwareHandoff/firmware_handoff?label=release)](https://github.com/FirmwareHandoff/firmware_handoff/releases) + +This repository contains the Firmware Handoff specification, which defines a +data structure to transfer essential configuration information between firmware +stages during platform initialization. + +The documentation is generated using the Sphinx framework. A version of this +specification, rendered in HTML, is available +[here](https://firmwarehandoff.github.io/firmware_handoff/). + +Project dependencies +==================== + +For an Ubuntu development machine, install the following packages to build the specification: + +- `librsvg2-bin` +- `python3-sphinx` +- `python3-sphinxcontrib.svg2pdfconverter` +- `python3-sphinx-rtd-theme` +- `latexmk` +- `texlive-latex-extra` + +**Note:** This list has been tested on Ubuntu 20.04 LTS and 22.04 LTS running on AArch64 and AMD64. + +Building the document +===================== + +The following are use to generate the specification: + +- pdf: + +``` sh +make latexpdf +``` + +- html: + +``` sh +make html +``` + +The output of these build commands goes into subdirectory `build`. + +Status +====== + +The first release of the specification has been published. We are currently in +the implementation phase, looking at various target projects, including U-Boot, +coreboot, TF-A and Tianocore. Once this is done we will review the result to see +if any serious flaws have come to light, meaning that changes are needed. If +so, these will be undertaken in each project. + +By the end of 2024, the spec will be considered stable and will be published +as version 1. From there on, backwards compatibility will be maintained. diff --git a/readme.rst b/readme.rst deleted file mode 100644 index 4e7f639..0000000 --- a/readme.rst +++ /dev/null @@ -1,47 +0,0 @@ -This repository contains the Firmware Handoff specification. - -This specification is generated using the sphinx framework. - -Project dependencies -==================== - -For a ubuntu development machine, the following packages must be installed to -enable building the specification: - -- librsvg2-bin -- python3-sphinx -- python3-sphinxcontrib.svg2pdfconverter -- python3-sphinx-rtd-theme -- latexmk -- texlive-latex-extra - -Note: the list above was tested on Ubuntu 20.04 LTS and 22.04 LTS running on -AArch64 and Amd64. - -Building the document -===================== - -The following are use to generate the specification: - -- pdf: - - .. code:: - make latexpdf - -- html: - - .. code:: - make html - -Status -====== - -As of February 2023 the spec is in the process of being finalised. Once this is -complete and everyone is in agreement with the content, we will issue a 0.9 -release. We will then look to implement it in various target projects, including -U-Boot, coreboot, TF-A and Tiancore. Once this is done we will review the result -to see if any serious flaws have come to light, meaning that changes are needed. -If so, these will be undertaken in each project. - -By the end of 2023, the spec will be considered stable and will be published -as version 1. From there on, backwards compatibility will be maintained.