From ef1f669cb7db5e3aebc390f5bd228cd88ed31a66 Mon Sep 17 00:00:00 2001
From: Anup Patel <anup.patel@wdc.com>
Date: Thu, 20 Dec 2018 18:23:52 +0530
Subject: [PATCH] top: More detailed top-level README.md

This patch adds more details to top-level README.md based on
current state of OpenSBI.

Signed-off-by: Anup Patel <anup.patel@wdc.com>
---
 README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 65 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 3892273..82084c3 100644
--- a/README.md
+++ b/README.md
@@ -1,37 +1,81 @@
 RISC-V Open Source Supervisor Binary Interface (OpenSBI)
 ========================================================
 
-The RISC-V Supervisor Binary Interface (SBI) is a recommended
+The **RISC-V Supervisor Binary Interface (SBI)** is a recommended
 interface between:
-1. platform specific firmware running in M-mode and bootloader
-   running in S-mode
-2. platform specific firmware running in M-mode and general
-   purpose operating system running in S-mode
-3. hypervisor runnng in HS-mode and general purpose operating
-   system running in VS-mode.
 
-The RISC-V SBI spec is maintained as independent project by
-RISC-V Foundation at https://github.com/riscv/riscv-sbi-doc
+1. Platform specific firmware running in M-mode and
+   general-purpose-os/hypervisor/bootloader running in S-mode/HS-mode
+2. Hypervisor runnng in HS-mode and general-purpose-os/bootloader
+   running in VS-mode
 
-The RISC-V OpenSBI project aims to provides an open-source and
-extensible implementation of the SBI spec. This project can be
-easily extended by RISC-V platform or RISC-V System-on-Chip vendors.
+The **RISC-V SBI specification** is maintained as independent project
+by RISC-V Foundation on [Github](https://github.com/riscv/riscv-sbi-doc)
 
+The **RISC-V OpenSBI project** aims to provides an open-source and
+extensible implementation of the **RISC-V SBI specification** for
+point 1) mentioned above. It can be easily extended by RISC-V platform
+or RISC-V System-on-Chip vendors.
+
+We can create three things using the RISC-V OpenSBI project:
+
+1. **libsbi.a** - Generic OpenSBI static library
+2. **libplatsbi.a** - Platform specific OpenSBI static library
+   (It is libsbi.a plus platform specific hooks represented
+    by "platform" symbol)
+3. **blobs** - Platform specific firware blobs
 
 How to Build?
 -------------
 
-Below are the steps to cross-compile and install RISC-V OpenSBI:
+For cross-compiling, please ensure that CROSS_COMPILE environment
+variable is set before starting build system.
+
+The libplatsbi.a and blobs are optional and only built when
+`PLAT=<platform_subdir>` parameter is specified to top-level make.
+(**NOTE**: `<platform_subdir>` is sub-directory under plat/ directory)
 
-1. Setup build environment
-$ CROSS_COMPILE=riscv64-unknown-linux-gnu-
+To build and install Generic OpenSBI library do the following:
 
-2. Build sources
-$ make PLAT=<platform_name>
+1. Build **libsbi.a**:
+`make`
 OR
-$ make PLAT=<platform_name> O=<build_directory>
+`make O=<build_directory>`
+2. Install **libsbi.a and headers**:
+`make install`
+OR
+`make I=<install_directory> install`
+
+To build and install platform specific OpenSBI library and blobs
+do the following:
 
-3. Install blobs
-$ make PLAT=<platform_name> install
+1. Build **libsbi, libplatsbi, and blobs**:
+`make PLAT=<platform_subdir>`
+OR
+`make PLAT=<platform_subdir> O=<build_directory>`
+2. Install **libsbi, headers, libplatsbi, and blobs**:
+`make PLAT=<platform_subdir> install`
 OR
-$ make PLAT=<platform_name> I=<install_directory> install
+`make PLAT=<platform_subdir> I=<install_directory> install`
+
+In addition, we can also specify platform specific command-line
+options to top-level make (such as `PLAT_<xyz>` or `FW_<abc>`)
+which are described under `docs/plat/<platform_name>.md` OR
+`docs/blob/<blob_name>.md`.
+
+Documentation
+-------------
+
+All our documenation is under `docs` directory organized in following
+manner:
+
+* `docs/platform_guide.md` - Guidelines for adding new platform support
+* `docs/library_usage.md` - Guidelines for using static library
+* `docs/plat/<platform_name>.md` - Documentation for `<platform_name>` platform
+* `docs/blob/<blob_name>.md` - Documentation for firmware blob `<blob_name>`
+
+We also prefer source level documentation, so wherever possible we describe
+stuff directly in the source code. This helps us maintain source and its
+documentation at the same place. For source level documentation we strictly
+follow Doxygen style. Please refer [Doxygen manual]
+(http://www.stack.nl/~dimitri/doxygen/manual.html) for details.
\ No newline at end of file
-- 
2.7.4