Преглед изворни кода

docs: README.md update

Reformat to fit lines within 80 chars, fix hyperlinks, etc.

Signed-off-by: Damien Le Moal <damien.lemoal@wdc.com>
Damien Le Moal пре 5 година
родитељ
комит
fba7e7c3ea
1 измењених фајлова са 131 додато и 67 уклоњено
  1. 131 67
      README.md

+ 131 - 67
README.md

@@ -1,138 +1,202 @@
 RISC-V Open Source Supervisor Binary Interface (OpenSBI)
 ========================================================
 
-The **RISC-V Supervisor Binary Interface (SBI)** is a recommended
-interface between:
+The **RISC-V Supervisor Binary Interface (SBI)** is a recommended interface
+between:
 
-1. A platform specific firmware (M-mode) and a general purpose
-   OS or hypervisor or bootloader (S-mode or HS-mode).
-2. A hypervisor (HS-mode) and a general purpose OS or bootloader (VS-mode)
+1. A platform specific firmware running in M-mode and a general purpose OS,
+   hypervisor or bootloader running in S-mode or HS-mode.
+2. A hypervisor running in HS-mode and a general purpose OS or bootloader
+   executed in VS-mode.
 
-The *RISC-V SBI specification* is maintained as an independent project
-by the RISC-V Foundation in [Github](https://github.com/riscv/riscv-sbi-doc)
+The *RISC-V SBI specification* is maintained as an independent project by the
+RISC-V Foundation in [Github].
 
-OpenSBI aims to provides an open-source and extensible implementation of
-the RISC-V SBI specification for case 1 mentioned above. OpenSBI
-implementation can be easily extended by RISC-V platform or System-on-Chip
-vendors to fit a particular hardware configuration.
-
-OpenSBI provides three components:
+OpenSBI aims to provides an open-source and extensible implementation of the
+RISC-V SBI specification for case 1 mentioned above. OpenSBI implementation
+can be easily extended by RISC-V platform or System-on-Chip vendors to fit a
+particular hardware configuration.
 
+OpenSBI provides three different components:
 1. *libsbi.a* - A generic OpenSBI static library
-2. *libplatsbi.a* - Platform specific OpenSBI static library, that is,
+2. *libplatsbi.a* - A platform specific OpenSBI static library, that is,
                     libsbi.a plus platform specific hooks
 3. *firmwares* - Platform specific bootable firmware binaries
 
-Building and Installing generic *libsbi.a*
-------------------------------------------
+Building and Installing the generic OpenSBI static library
+----------------------------------------------------------
+
+*libsbi.a* can be natively compiled or cross-compiled on a host with a
+different base architecture than RISC-V.
 
-For cross-compiling, the environment variable *CROSS_COMPILE* must
-be defined to specify the toolchain executable name prefix, e.g.
-*riscv64-unknown-elf-* if the gcc executable used is
-*riscv64-unknown-elf-gcc*.
+For cross-compiling, the environment variable *CROSS_COMPILE* must be defined
+to specify the name prefix of the RISC-V compiler toolchain executables, e.g.
+*riscv64-unknown-elf-* if the gcc executable used is *riscv64-unknown-elf-gcc*.
 
 To build the generic OpenSBI library *libsbi.a*, simply execute:
 ```
 make
 ```
 
-All compiled binaries will be placed in the *build* directory.
-To specify an alternate build directory target, run:
+All compiled binaries as well as the result *libsbi.a* static library file will
+be placed in the *build/lib* directory. To specify an alternate build root
+directory path, run:
 ```
 make O=<build_directory>
 ```
 
-To generate files to be installed for using *libsbi.a* in other projects,
-run:
+To generate files to be installed for using *libsbi.a* in other projects, run:
 ```
 make install
 ```
+
 This will create the *install* directory with all necessary include files
-and binary files under it. To specify an alternate installation directory,
-run:
+copied under the *install/include* directory and library file copied in the
+*install/lib* directory. To specify an alternate installation root directory
+path, run:
 ```
 make I=<install_directory> install
 ```
 
-Building and Installing platform specific *libsbi.a* and firmwares
-------------------------------------------------------------------
+Building and Installing the platform specific static library and firmwares
+--------------------------------------------------------------------------
 
-The libplatsbi.a and firmware files are only built if the
-*`PLATFORM=<platform_subdir>`* argument is specified on make command lines.
-*`<platform_subdir>`* must specify the path to one of the leaf directories
-under the *`platform`* directory. For example, to compile the library and
-firmware for QEMU RISC-V *virt* machine, *`<platform_subdir>`*
-should be *`qemu/virt`*.
+The platform specific *libplatsbi.a* static library and the platform firmwares
+are only built if the *PLATFORM=<platform_subdir>* argument is specified on
+the make command line. *<platform_subdir>* must specify the relative path from
+OpenSBI code directory to one of the leaf directories under the *platform*
+directory. For example, to compile the platform library and firmwares for QEMU
+RISC-V *virt* machine, *<platform_subdir>* should be *qemu/virt*.
 
-To build *libsbi, libplatsbi, and firmwares* for a specific platform, run:
+To build *libsbi.a*, *libplatsbi.a* and the firmwares for a specific platform,
+run:
 ```
 make PLATFORM=<platform_subdir>
-or
+```
+
+An alternate build directory path can also be specified.
+```
 make PLATFORM=<platform_subdir> O=<build_directory>
 ```
 
-To install *libsbi, headers, libplatsbi, and firmwares*, run:
+The platform specific library *libplatsbi.a* will be generated in the
+*build/platform/<platform_sub_dir>/lib* directory. The platform firmware files
+will be under the *build/platform/<platform_sub_dir>/firmware* directory.
+The compiled firmwares will be available in two different format: an ELF file
+and an expanded image file.
+
+To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run:
 ```
 make PLATFORM=<platform_subdir> install
-or
+```
+
+This will copy the compiled platform specific libraries and firmware files
+under the *install/platform/<platform_sub_dir>/* directory. An alternate
+install root directory path can be specified as follows.
+```
 make PLATFORM=<platform_subdir> I=<install_directory> install
 ```
 
-In addition, platform specific make command-line options to top-level make
-, such as *PLATFORM_<xyz>* or *FW_<abc>* can also be specified. These
-options are described under *`docs/platform/<platform_name>.md`* and
-*`docs/firmware/<firmware_name>.md`*.
+In addition, platform specific configuration options can be specified with the
+top-level make command line. These options, such as *PLATFORM_<xyz>* or
+*FW_<abc>*, are platform specific and described in more details in the
+*docs/platform/<platform_name>.md* files and
+*docs/firmware/<firmware_name>.md* files.
 
 License
--------------
-The software is provided under a BSD-2-Clause license. Contributions to this
-project are accepted under the same license with developer sign-off as
-described in the [Contributing Guidelines](docs/contributing.md).
+-------
+
+OpenSBI is distributed under the terms of the BSD 2-clause license
+("Simplified BSD License" or "FreeBSD License", SPDX: *BSD-2-Clause*).
+A copy of this license with OpenSBI copyright can be found in the file
+[COPYING.BSD].
+
+All source files in OpenSBI contain the 2-Clause BSD license SPDX short
+indentifier in place of the full license text.
+
+```
+SPDX-License-Identifier:    BSD-2-Clause
+```
+
+This enables machine processing of license information based on the SPDX
+License Identifiers that are available on the [SPDX] web site.
+
+OpenSBI source code also contains code reused from other projects as listed
+below. The original license text of these projects is included in the source
+files where the reused code is present.
 
-This project also contains code from other projects as listed below. The original
-license text is included in those source files.
+1. The libfdt source code is disjunctively dual licensed
+   (GPL-2.0+ OR BSD-2-Clause). Some of this project code is used in OpenSBI
+   under the terms of the BSD 2-Clause license. Any contributions to this
+   code must be made under the terms of both licenses.
 
-1. The libfdt source code is disjunctively dual licensed (GPL-2.0+ OR BSD-2-Clause). It is
-   used by this project under the terms of the BSD-2-Clause license. Any contributions to
-   this code must be made under the terms of both licenses.
+Contributing to OpenSBI
+-----------------------
+
+The OpenSBI project encourages and welcomes contributions. Contributions should
+follow the rules described in OpenSBI [Contribution Guideline] document.
+In particular, all patches sent should contain a Signed-off-by tag.
 
 Documentation
 -------------
 
-A more detailed documentation is under the *docs* directory and organized
-as follows.
+Detailed documentation of various aspects of OpenSBI can be found under the
+*docs* directory. The documentation covers the following topics.
 
-* *`docs/contributing.md`* - Guidelines for contributing to OpenSBI project
-* *`docs/platform_guide.md`* - Guidelines for adding new platform support
-* *`docs/library_usage.md`* - Guidelines for using the static library
-* *`docs/platform/<platform_name>.md`* - Documentation for the platform *<platform_name>*
-* *`docs/firmware/<firmware_name>.md`* - Documentation for the firmware *<firmware_name>*
+* [Contribution Guideline]: Guideline for contributing code to OpenSBI project
+* [Platform Support Guide]: Guideline for implementing support for new platforms
+* [Library Usage]: API documentation of OpenSBI static library *libsbi.a*
+* [Platform Documentation]: Documentation of the platforms currently supported.
+* [Firmware Documentation]: Documentation for the different types of firmware
+  build supported by OpenSBI.
 
-The source code is also well documented. For source level documentation,
+OpenSBI source code is also well documented. For source level documentation,
 doxygen style is used. Please refer to [Doxygen manual] for details on this
 format.
 
-[Doxygen manual]: http://www.stack.nl/~dimitri/doxygen/manual.html
-
-The Doxygen can be installed on your debian build system using following:
+Doxygen can be installed on Linux distributions using *.deb* packages using
+the following command.
 ```
 sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
 ```
 
-To build a consolidated `refman.pdf` of all documentation, run:
+For *.rpm* based Linux distributions, the following commands can be used.
+```
+sudo yum install doxygen doxygen-latex doxywizard graphviz
+```
+or
+```
+sudo yum install doxygen doxygen-latex doxywizard graphviz
+```
+
+To build a consolidated *refman.pdf* of all documentation, run:
 ```
 make docs
+```
 or
+```
 make O=<build_directory> docs
 ```
 
-**NOTE:** `refman.pdf` will be available under `<build_directory>/docs/latex`.
-
-To install a consolidated `refman.pdf` of all documentation, run:
+the resulting *refman.pdf* will be available under the directory
+*<build_directory>/docs/latex*. To install this file, run:
 ```
 make install_docs
+```
 or
+```
 make I=<install_directory> install_docs
 ```
 
-**NOTE:** `refman.pdf` will be installed under `<install_directory>/docs`.
+*refman.pdf* will be installed under *<install_directory>/docs*.
+
+[Github]: https://github.com/riscv/riscv-sbi-doc
+[COPYING.BSD]: COPYING.BSD
+[SPDX]: http://spdx.org/licenses/
+[Contribution Guideline]: docs/contributing.md
+[Platform Support Guide]: docs/platform_guide.md
+[Library Usage]: docs/library_usage.md
+[Platform Documentation]: docs/platform/platform.md
+[Firmware Documentation]: docs/firmware/fw.md
+[Doxygen manual]: http://www.stack.nl/~dimitri/doxygen/manual.html
+