Merge pull request #460 from sifive/misc-cleanup1

Minor cleaning up sphinx doc to get ready

doc/sphinx/contents.rst

@@ -48,13 +48,23 @@ within a single target directory in ``bsp/<target>/``. For example, the HiFive 1
 board support files for Freedom Metal are entirely within ``bsp/sifive-hifive1/``
 and consist of the following:
 
-* ``design.dts``
+* ``core.dts``
 
   - The DeviceTree description of the target. This file is used to parameterize
     the Freedom Metal library to the target device. It is included as reference
     so that users of Freedom Metal are aware of what features and peripherals
     are available on the target.
 
+* ``design.dts``
+
+  - The DeviceTree Overlay for describing the chosen node, and testrams.
+
+* ``design.svd``
+
+  - CMSIS SVD XML file used for describing the design peripherals, their
+    registers register-fields in the device with offset information on where
+    they are all mapped into the memory space.
+
 * ``metal.h``
 
   - The Freedom Metal machine header which is used internally to Freedom Metal
@@ -100,70 +110,100 @@ Example Programs
 
 The example programs can be found under the ``software/`` directory.
 
-- empty
+- atomics
 
-  - An empty project. Serves as a good starting point for your own program.
+  - Demonstrates how to use the Metal Atomic API to leverage the RISC-V atomic
+    instruction set.
 
-- hello
+- cflush
 
-  - Prints "Hello, World!" to stdout, if a serial device is present on the target.
+  - A simple example demo how to use cflush (Data) L1 and use FENCE to ensure flush
+    complete. 
 
-- sifive-welcome
+- clic-hardware-vector-interrupts
 
-  - Prints a welcome message and interacts with the LEDs.
+  - A simple example demonstrating the use of CLIC hardware vector interrupts
 
-- return-pass
+- clic-nested-interrupts
 
-  - Returns status code 0 indicating program success.
+  - A simple example demonstrating how to use CLIC preemptive vector interrupts
 
-- return-fail
+- clic-nonvector-interrupts
 
-  - Returns status code 1 indicating program failure.
+  - A simple example demonstrating how to use CLIC non vector interrupts
 
-- example-itim
+- clic-selective-vector-interrupts
 
-  - Demonstrates how to statically link application code into the Instruction
-    Tightly Integrated Memory (ITIM) if an ITIM is present on the target.
+  - A simple example demonstrating how to use CLIC selective vector interrupts
 
-- software-interrupt
+- coremark
 
-  - Demonstrates how to register a handler for and trigger a software interrupt
+  - "CoreMark" Benchmark Program that measures the performance of embedded
+    microcrontrollers (MCU)
 
-- timer-interrupt
+- csr
 
-  - Demonstrates how to register a handler for and trigger a timer interrupt
+  - A simple example demonstrating the use of metal APIs for CSR register set
+    and get.
 
-- local-interrupt
+- dhrystone
 
-  - Demonstrates how to register a handler for and trigger a local interrupt
+  - "Dhrystone" Benchmark Program by Reinhold P. Weicker
 
-- example-pmp
+- empty
 
-  - Demonstrates how to configure a Physical Memory Protection (PMP) region
+  - An empty project. Serves as a good starting point for your own program.
 
-- example-spi
+- example-buserror
 
-  - Demonstrates how to use the SPI API to transfer bytes to a peripheral
+  - Demonstrates how to use the SiFive Bus Error Unit in Freedom Metal
 
-- dhrystone
+- example-freertos-blinky
 
-  - "Dhrystone" Benchmark Program by Reinhold P. Weicker
+  - A simple blinky starter application create just two tasks, one queue
 
-- coremark
+- example-freertos-blinky-systemview
 
-  - "CoreMark" Benchmark Program that measures the performance of embedded
-    microcrontrollers (MCU)
+  - A simple blinky starter application create just two tasks, one queue
+    (based on example-freertos-blinky example) in addition this example
+    init and use the SEGGER sytemView trace.
 
-- cflush
+- example-freertos-minimal
 
-  - A simple example demo how to use cflush (Data) L1 and use FENCE to ensure flush
-    complete. 
+  - A simple starter example application to start FreeRTOS application
+
+- example-freertos-pmp-blinky
+
+  - A simple blinky starter application create just two tasks, one queue.
+    In this example we use the PMP in order to restrict the acces to peripheral,
+    in order to access to global variable we grant access to bss to each task.
+
+- example-i2c
+
+  - Demonstrates usage of the I2C API to communicate with I2C slaves.
+
+- example-itim
+
+  - Demonstrates how to statically link application code into the Instruction
+    Tightly Integrated Memory (ITIM) if an ITIM is present on the target.
+
+- example-pmp
+
+  - Demonstrates how to configure a Physical Memory Protection (PMP) region
+
+- example-pwm
+
+  - Demonstrates usage of the PWM API for waveform generation.
 
 - example-rtc
 
   - Demonstrates how to use the RTC API to start a Real-Time Clock, set a compare
     value, and handle an interrupt when the clock matches the compare value.
 
+- example-spi
+
+  - Demonstrates how to use the SPI API to transfer bytes to a peripheral
+
 - example-watchdog
 
   - Demonstrates how to use the Watchdog API to set a watchdog timer to trigger an
@@ -178,49 +218,67 @@ The example programs can be found under the ``software/`` directory.
   - Demonstrates how to register a handler for the "syscall from user mode" exception,
     drop to the user mode privilege level, and then issue a syscall.
 
-- plic-interrupts
-
-  - A simple example demonstrating how PLIC interrupts get uses on an Arty board. 
-
-- test-coreip
+- example-watchdog
 
-  - Assembly test code which executes instructions and checks for expected results.
-    The tests are designed to work on SiFive CPU designs in RTL simulation or on the
-    Arty FPGA board. 
+  - Demonstrates how to use the Watchdog API to set a watchdog timer to trigger an
+    interrupt on timeout.
 
-- clic-nonvector-interrupts
+- hello
 
-  - A simple example demonstrating how to use CLIC non vector interrupts
+  - Prints "Hello, World!" to stdout, if a serial device is present on the target.
 
-- clic-selective-vector-interrupts
+- local-interrupt
 
-  - A simple example demonstrating how to use CLIC selective vector interrupts
+  - Demonstrates how to register a handler for and trigger a local interrupt
 
-- clic-hardware-vector-interrupts
+- local-vector-interrupt
 
-  - A simple example demonstrating the use of CLIC hardware vector interrupts
+  - A simple example using "Timer and Software Interrupts" in CLINT vector mode.
 
-- clic-nested-interrupts
+- mem-latency
 
-  - A simple example demonstrating how to use CLIC preemptive vector interrupts
+  - A memory test that measure the latency at different cache layers and memory blocks
 
 - minimal-boot
 
   - Demonstrates how to replace the Metal constructors and replace them with your own.
 
-- atomics
+- multicore-hello
 
-  - Demonstrates how to use the Metal Atomic API to leverage the RISC-V atomic
-    instruction set.
+  - An example which demonstrates how to run code on multiple CPU harts and to use
+    the Metal Lock API to use a spinlock as a mutex.
 
-- example-i2c
+- plic-interrupts
+
+  - A simple example demonstrating how PLIC interrupts get uses on an Arty board.
 
-  - Demonstrates usage of the I2C API to communicate with I2C slaves.
+- return-fail
 
-- example-pwm
+  - Returns status code 1 indicating program failure.
 
-  - Demonstrates usage of the PWM API for waveform generation.
+- return-pass
 
-- mem-latency
+  - Returns status code 0 indicating program success.
+
+- sifive-welcome
+
+  - Prints a welcome message and interacts with the LEDs.
+
+- software-interrupt
+
+  - Demonstrates how to register a handler for and trigger a software interrupt
+
+- test-coreip
+
+  - Assembly test code which executes instructions and checks for expected results.
+    The tests are designed to work on SiFive CPU designs in RTL simulation or on the
+    Arty FPGA board.
+
+- timer-interrupt
+
+  - Demonstrates how to register a handler for and trigger a timer interrupt
+
+- uart-interrupt
+
+  - A simple "UART Interrupt" example using metal-interrupts APIs for ARTY board.
 
-  - A memory test that measure the latency at different cache layers and memory blocks

doc/sphinx/userguide/buildingdevboard.rst

@@ -8,7 +8,7 @@ To compile a bare-metal RISC-V program:
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=sifive-hifive1] [CONFIGURATION=debug] software
+   make PROGRAM=hello TARGET=sifive-hifive1 CONFIGURATION=debug software
 
 The square brackets in the above command indicate optional parameters for the
 Make invocation. As you can see, the default values of these parameters tell
@@ -33,7 +33,7 @@ the development board into your computer and running the following command:
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=sifive-hifive1] [CONFIGURATION=debug] upload
+   make PROGRAM=hello TARGET=sifive-hifive1 CONFIGURATION=debug upload
 
 Debugging a Target Program
 --------------------------
@@ -50,7 +50,7 @@ the development board into your computer and running the following command:
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=sifive-hifive1] [CONFIGURATION=debug] debug
+   make PROGRAM=hello TARGET=sifive-hifive1 CONFIGURATION=debug debug
 
 Cleaning a Target Program Build Directory
 -----------------------------------------
@@ -59,5 +59,5 @@ The ``clean`` target can be used to restore a target program's directory to a cl
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=sifive-hifive1] [CONFIGURATION=debug] clean
+   make PROGRAM=hello TARGET=sifive-hifive1 CONFIGURATION=debug clean
 

doc/sphinx/userguide/qemusimulation.rst

@@ -17,13 +17,12 @@ any other target in Freedom E SDK
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=qemu-sifive-e31] [CONFIGURATION=debug] software
+   make PROGRAM=hello TARGET=qemu-sifive-e31 CONFIGURATION=debug software
 
-The square brackets in the above command indicate optional parameters for the
-Make invocation. As you can see, the default values of these parameters tell
-the build script to build the ``hello`` example for the ``qemu-sifive-e31`` target
-using the ``debug`` build configuration. If, for example, you wished to build
-the ``timer-interrupt`` example for the ``qemu-sifive-u54mc`` target using
+One can choose to replace the ``hello`` PROGRAM with any other examples,
+the ``debug`` build CONFIGRATION with the ``release``, and the ``qemu-sifive-e31`
+target with others QEMU like ``qemu-sifive-u54``. For example, if you wished to
+build the ``timer-interrupt`` example for the ``qemu-sifive-u54mc`` target using
 the ``release`` build configuration, you would instead run the command
 
 .. code-block:: bash
@@ -38,7 +37,7 @@ make target:
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=qemu-sifive-e31] [CONFIGURATION=debug] simulate
+   make PROGRAM=hello TARGET=qemu-sifive-e31 CONFIGURATION=debug simulate
 
 Cleaning a Target Program Build Directory
 -----------------------------------------
@@ -47,5 +46,5 @@ The ``clean`` target can be used to restore a target program's directory to a cl
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=qemu-sifive-e31] [CONFIGURATION=debug] clean
+   make PROGRAM=hello TARGET=qemu-sifive-e31 CONFIGURATION=debug clean
 

doc/sphinx/userguide/spikesimulation.rst

@@ -13,14 +13,11 @@ target in Freedom E SDK
 
 .. code-block:: bash
 
-   make TARGET=spike [PROGRAM=hello] [CONFIGURATION=debug] software
+   make TARGET=spike PROGRAM=hello CONFIGURATION=debug software
 
-The square brackets in the above command indicate optional parameters for the
-Make invocation. As you can see, the default values of these parameters tell
-the build script to build the ``hello`` example for the ``spike`` target
-using the ``debug`` build configuration. If, for example, you wished to build
-the ``timer-interrupt`` example for using the ``release`` build configuration,
-you would instead run the command
+One can choose to replace the ``hello`` PROGRAM with any other examples,
+like ``timer-interrupt`` example, and the ``debug`` build CONFIGRATION
+with the ``release`` for an optimize build configuration.
 
 .. code-block:: bash
 
@@ -47,7 +44,7 @@ easy as invoking the ``simulate`` make target:
 
 .. code-block:: bash
 
-   make TARGET=spike [PROGRAM=hello] [CONFIGURATION=debug] simulate
+   make TARGET=spike PROGRAM=hello CONFIGURATION=debug simulate
 
 Cleaning a Target Program Build Directory
 -----------------------------------------
@@ -56,5 +53,5 @@ The ``clean`` target can be used to restore a target program's directory to a cl
 
 .. code-block:: bash
 
-   make TARGET=spike [PROGRAM=hello] [CONFIGURATION=debug] clean
+   make TARGET=spike PROGRAM=hello CONFIGURATION=debug clean
 

doc/sphinx/userguide/standalone.rst

@@ -10,5 +10,5 @@ Legacy Freedom E SDK.
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=sifive-hifive1] STANDALONE_DEST=/path/to/desired/location standalone
+   make PROGRAM=hello TARGET=sifive-hifive1 STANDALONE_DEST=/path/to/desired/location standalone