Merge pull request #22 from ucb-bar/patch-2

ADD: add docs from Gitbook

docs/README.md

@@ -0,0 +1,3 @@
+# Chipyard Baremetal-IDE Documentation
+
+{% embed url="https://github.com/ucb-bar/Baremetal-IDE" %}

docs/SUMMARY.md

@@ -0,0 +1,22 @@
+# Table of contents
+
+* [Chipyard Baremetal-IDE Documentation](README.md)
+* [Getting Started](getting-started/README.md)
+  * [Installing Baremetal-IDE](getting-started/installing-baremetal-ide.md)
+  * [Programming Blinky](getting-started/programming-blinky.md)
+  * [Directory Structure](getting-started/directory-structure.md)
+* [RISC-V Programming](risc-v-programming.md)
+* [Using Peripheral Devices](using-peripheral-devices/README.md)
+  * [Testchipip IPs](using-peripheral-devices/testchipip-ips/README.md)
+    * [Core-Local Interruptor (CLINT)](using-peripheral-devices/testchipip-ips/core-local-interruptor-clint.md)
+  * [SiFive IPs](using-peripheral-devices/sifive-ips/README.md)
+    * [General Purpose I/Os (GPIO)](using-peripheral-devices/sifive-ips/general-purpose-i-os-gpio.md)
+    * [Universal Asynchronous Receiver/Transmitter (UART)](using-peripheral-devices/sifive-ips/universal-asynchronous-receiver-transmitter-uart.md)
+    * [Inter-Integrated Circuit (I2C) Interface](using-peripheral-devices/sifive-ips/inter-integrated-circuit-i2c-interface.md)
+    * [Serial Peripheral Interface (SPI)](using-peripheral-devices/sifive-ips/serial-peripheral-interface-spi.md)
+* [Adding Support for New SoCs](adding-support-for-new-socs.md)
+* [Extensions](extensions/README.md)
+  * [Baremetal-NN](extensions/baremetal-nn.md)
+  * [Sensor Library](extensions/sensor-library.md)
+  * [Support for RTOS Environment](extensions/support-for-rtos-environment.md)
+  * [Support for Arduino Environment](extensions/support-for-arduino-environment.md)

docs/adding-support-for-new-socs.md

@@ -0,0 +1,26 @@
+# Adding Support for New SoCs
+
+To add support for new SoCs, create a new folder under `/bsp` directory with a unique `chip_name`.
+
+The `chip_name` should be all lower-case, and ideally consist only \[a-z] characters. No space is allowed.
+
+
+
+Under the `/bsp/<chip_name>` folder, create directories and files following the existing chip support file structure.
+
+
+
+Then, edit `/bsp/<chip_name>/inc/<chip_name>.h` file. Edit the "Memory Map Definition" section to match the SoC's memory layout. Also, update "Peripheral Pointer Definition" accordingly.&#x20;
+
+If new peripheral device is present in the SoC, add a new TypeDef struct in the "Peripheral Struct Definition" section, and add the corresponding bit position and mask definitions in the "Peripheral Bit Field Definition" section.
+
+
+
+Update `/bsp/<chip_name>/debug/<chip_name>.cfg` file to match the hart configuration on the SoC.
+
+
+
+Finally, edit the clock frequency and mtime scale in `/bsp/<chip_name>/inc/<chip_name>_hal.h` to match the value provided to the SoC.
+
+
+

docs/extensions/README.md

@@ -0,0 +1,2 @@
+# Extensions
+

docs/extensions/baremetal-nn.md

@@ -0,0 +1,2 @@
+# Baremetal-NN
+

docs/extensions/sensor-library.md

@@ -0,0 +1,2 @@
+# Sensor Library
+

docs/extensions/support-for-arduino-environment.md

@@ -0,0 +1,2 @@
+# Support for Arduino Environment
+

docs/extensions/support-for-rtos-environment.md

@@ -0,0 +1,2 @@
+# Support for RTOS Environment
+

docs/getting-started/README.md

@@ -0,0 +1,30 @@
+# Getting Started
+
+## 1. Installing Baremetal-IDE
+
+{% content-ref url="installing-baremetal-ide.md" %}
+[installing-baremetal-ide.md](installing-baremetal-ide.md)
+{% endcontent-ref %}
+
+
+
+## 2. Directory Structure
+
+{% content-ref url="directory-structure.md" %}
+[directory-structure.md](directory-structure.md)
+{% endcontent-ref %}
+
+
+
+## 3. Programming Blinky
+
+{% content-ref url="programming-blinky.md" %}
+[programming-blinky.md](programming-blinky.md)
+{% endcontent-ref %}
+
+
+
+## 4. Running and Debugging
+
+
+

docs/getting-started/directory-structure.md

@@ -0,0 +1,58 @@
+# Directory Structure
+
+### `/bsp`
+
+BSP stands for "Board-Specific Packages". This folder stores board-specific files. 
+
+The directory `bsp/<chip_name>` stores the files specific to this SoC.&#x20;
+
+Meanwhile, the common files that is shared across SoCs such as debugger configurations, are stored under `bsp/common`.&#x20;
+
+
+
+### `/bsp/<chip_name>/debug`
+
+This folder stores the configuration files used during SoC debugging.&#x20;
+
+`<chip_name>.cfg` contains the necessary information needed by the JTAG debugger about the hart and memory configuration of the SoC.&#x20;
+
+`<chip_name>.svd` file enables interactive live register view in VS Code.
+
+
+
+### `/bsp/<chip_name>/inc`
+
+This folder stores the header file of the SoC HAL (hardware-abstraction layer) library.
+
+`<chip_name>.h` contains the supported interrupt type, interrupt IDs, the memory layout of the peripheral devices, the memory map, and the bit definitions of the register of peripheral devices. It defines almost all the necessary information about the SoC. Therefore, it is possible to write low-level baremetal code with only this file when performance and optimization are needed.
+
+`<chip_name>_hal.h` contains the HAL library definitions. User can select which peripheral device HAL library to include by adding or removing the include definitions. This file also defines the system clock frequency and real-time time scale.
+
+`rv_**.h` contains RISC-V specific definitions.
+
+
+
+### `/bsp/<chip_name>/src`
+
+This folder stores the source file of the SoC HAL (hardware-abstraction layer) library.
+
+`<chip_name>_hal_system.c` contains definitions to available traps on the SoC. User can override these functions in the application code to perform interrupt handling.
+
+
+
+### `/bsp/<chip_name>/startup`
+
+This folder stores the startup procedure of the SoC.
+
+
+
+### `/core`
+
+This folder stores the application-specific code. Users can implement the application functionality either directly in `main.c`, or create hierarchies within this folder for more complicated applications.
+
+
+
+### `/lib`
+
+This folder stores third-party libraries.
+

docs/getting-started/installing-baremetal-ide.md

@@ -0,0 +1,42 @@
+# Installing Baremetal-IDE
+
+## 1. Prerequisites
+
+Baremetal-IDE uses [Microsoft Visual Studio Code](https://code.visualstudio.com/) as the editor and host of the integrated development environment. Install Microsoft VS Code from [here](https://code.visualstudio.com/download).
+
+
+
+## 2. Clone the Github Repository
+
+### Method 1: Install it with Chipyard
+
+Follow the Chipyard installation tutorial to set up Chipyard. The Baremetal-IDE environment is included as a submodule in Chipyard, located at `software/baremetal-ide`
+
+{% embed url="https://chipyard.readthedocs.io/en/stable/Chipyard-Basics/Initial-Repo-Setup.html" %}
+
+
+
+### Method 2: Install it as a standalone environment
+
+```bash
+git clone https://github.com/ucb-bar/Baremetal-IDE.git baremetal-ide
+```
+
+
+
+Execute the following commands to initialize the board support files.
+
+```bash
+cd baremetal-ide
+git submodule init
+git submodule update
+```
+
+
+
+## 3. Set up VS Code
+
+In Microsoft Visual Studio Code, search and install the extension "Cortex-Debug".
+
+<figure><img src="../.gitbook/assets/image (3).png" alt=""><figcaption></figcaption></figure>
+

docs/getting-started/programming-blinky.md

@@ -0,0 +1,4 @@
+# Programming Blinky
+
+nihao world
+

docs/risc-v-programming.md

@@ -0,0 +1,43 @@
+# RISC-V Programming
+
+## What is a RISC-V Toolchain? <a href="#what-is-a-risc-v-toolchain" id="what-is-a-risc-v-toolchain"></a>
+
+The `riscv64-unknown-elf-xxx` toolchain is specifically designed for the RISC-V instruction set architecture (ISA), and it’s used for developing bare-metal and applications for running on RISC-V targets. This toolchain typically runs on the host machine (e.g., an x86-based PC) to produce code that will run on a RISC-V machine (e.g., a RISC-V based SoC). This process is known as cross-compilation.
+
+Breaking down the name riscv64-unknown-elf-xxx:
+
+`riscv64`: This refers to the RISC-V architecture with a 64-bit address space. RISC-V is an open-standard ISA that’s been gaining traction in both academia and industry due to its flexibility and modularity.
+
+`unknown`: This indicates that the toolchain is not tied to a specific vendor or platform. It’s a generic term used to describe that the toolchain can be used across different RISC-V implementations.
+
+`elf`: Stands for Executable and Linkable Format. It’s the format used for the compiled binaries. ELF is a common binary file format that’s used on many Unix systems, including Linux.
+
+`xxx`: Typically, this would be replaced by specific tools within the toolchain, like:
+
+* gcc: The GNU Compiler Collection for RISC-V, also known as **the compiler**.
+* gdb: The GNU Debugger for debugging RISC-V applications, used for debugging programs.
+* ld: The **linker**.
+* objdump: A utility that displays information about object files.
+* … and so on
+
+## What is OpenOCD? <a href="#what-is-openocd" id="what-is-openocd"></a>
+
+OpenOCD, which stands for Open On-Chip Debugger, is a free, open-source software that provides debugging, in-system programming, and boundary-scan testing for embedded systems. It’s used to program and debug embedded systems using JTAG or SWD (Serial Wire Debug) interfaces.
+
+#### Main functionalities <a href="#main-functionalities" id="main-functionalities"></a>
+
+**Debugging**: Through OpenOCD, developers can control the JTAG state machine to run a program on an embedded target, halt the target at a breakpoint, and then inspect or modify variables to debug the software.
+
+**Flashing**: OpenOCD can be used to load program (also called “flash”) onto either internal or external Flash memory of the SoC.
+
+**Remote Debugging**: OpenOCD can function as a GDB (GNU Debugger) server. This means developers can use GDB or a GDB-compatible front-end to remotely debug an application running on an embedded target through OpenOCD.
+
+**Scriptable Interface**: OpenOCD provides a flexible and scriptable interface, which is valuable for automated testing and custom debugging routines.
+
+## Setting up RISC-V Environment <a href="#setting-up-risc-v-environment" id="setting-up-risc-v-environment"></a>
+
+In this tutorial, we will set up the RISC-V environment by installing necessary toolchains and other softwares.
+
+{% content-ref url="http://127.0.0.1:5000/o/QxuKWlObc6aI0kOw9xus/s/VJt4O1JTDNktDRwjb6Q8/" %}
+[Berkeley Humanoid Manual](http://127.0.0.1:5000/o/QxuKWlObc6aI0kOw9xus/s/VJt4O1JTDNktDRwjb6Q8/)
+{% endcontent-ref %}

docs/using-peripheral-devices/README.md

@@ -0,0 +1,2 @@
+# Using Peripheral Devices
+

docs/using-peripheral-devices/sifive-ips/README.md

@@ -0,0 +1,2 @@
+# SiFive IPs
+

docs/using-peripheral-devices/sifive-ips/general-purpose-i-os-gpio.md

@@ -0,0 +1,2 @@
+# General Purpose I/Os (GPIO)
+