commit 9a0aa90fb05959f2322665896e03e01f1c2e15ca
parent 6b796b0292d03c1e9e96e2e81ae164ca849931ed
Author: Roberto E. Vargas Caballero <k0ga@shike2.com>
Date: Fri, 11 Sep 2020 17:47:58 +0200
doc: Remove old DESGN document
This document does not apply anymore.
Change-Id: I132633a2b08f520a64a4b7a2ab01d459cb2bdc33
Diffstat:
| D | doc/DESIGN | | | 332 | ------------------------------------------------------------------------------- |
1 file changed, 0 insertions(+), 332 deletions(-)
diff --git a/doc/DESIGN b/doc/DESIGN
@@ -1,332 +0,0 @@
-rcode design document
-=====================
-
-0) Overview
------------
-
-rcode was designed to be the reference implementation of the Bowmore
-rcode specification. Due to the change of direction of the Bowmore
-project, rcode was not finalized.
-
-What remains is basically a generic firmware implementation that can
-be used as a starting point for any firmware project. rcode was
-designed to be split into two parts, the ROM firmware and the runtime
-firmware.
-
-The sections below explain a bit about how the code is organized.
-
-1) Directory structure
-----------------------
-.
-|-- config
-| `-- toolchain
-
-rcode contains a primitive configuration system that operates on top
-of the build system. The config directory contains the various
-configurations. The file names are a pair that describes the
-architecture and OS ABI of the configurations.
-
-The toolchain directory contains the toolchain specific
-configurations. The toolchain configuration is independent of the
-higher level configurations.
-
-|-- doc
-
-The doc/ directory contains rcode documentation as well as the
-licenses of all code that is used in rcode.
-
-|-- drivers
-
-Top-level driver model as well as generic driver implementations.
-There is a section below that describes the driver model in more
-detail.
-
-|-- include
-| |-- bits
-| | |-- amd64
-| | | `-- arch
-| | |-- arm32
-| | | `-- arch
-| | |-- arm64
-| | | `-- arch
-| | |-- darwin
-| | | `-- sys
-| | |-- dragonfly
-| | | `-- sys
-| | |-- i386
-| | | `-- arch
-| | |-- linux
-| | | `-- sys
-| | |-- netbsd
-| | | `-- sys
-| | |-- openbsd
-| | | `-- sys
-| | |-- rcode
-| | | `-- sys
-| | `-- z80
-| | `-- arch
-| `-- rcode
-
-Top-level include headers. include/bits/ contains the target specific
-header definitions. This is used by libc.
-
-include/rcode/ contains generic definitions used by all rcode targets.
-
-|-- scripts
-
-Various helper scripts that are used as part of the build/config
-system.
-
-|-- src
-| |-- lib9p
-
-Generic 9p implementation. This is used by the generic driver model
-to serialize/deserialize access to devices that live outside of the
-rcode image.
-
-| |-- libc
-| | |-- arch
-| | | |-- amd64
-| | | | |-- darwin
-| | | | |-- dragonfly
-| | | | |-- linux
-| | | | |-- netbsd
-| | | | `-- openbsd
-| | | |-- arm32
-| | | | `-- linux
-| | | |-- arm64
-| | | | |-- linux
-| | | | `-- rcode
-| | | `-- posix
-| | |-- assert
-| | |-- ctype
-| | |-- locale
-| | |-- stdio
-| | |-- stdlib
-| | |-- string
-| | `-- time
-
-Generic C99 libc implementation. Only a small subset of this library
-is used when rcode is built to run natively. This code is derived
-from the scc[0] project.
-
-| |-- libhdl
-
-libhdl is an abstraction used when handling RMC calls. It sits
-between the runtime firmware dispatch code and the librmu library.
-It hides the details of how the RMC calls are implemented in the
-ABI and translate between external types and internal types.
-
-| |-- libk
-
-Auxiliary routines augmenting those of libc that are used when rcode
-is built to run natively. It provides facilities similar of those of
-libc but simpler and more space efficient.
-
-| |-- librmu
-
-RMU command handling library. This is where all the RMU commands were
-to be implemented. This library is architecture agnostic.
-
-| |-- libtypes
-
-A library to serialize/deserialize types. In the original
-implementation Bowmore specified some fairly complex packing
-semantics. libtypes provides the pack()/unpack() abstractions that
-take a high level type and serialize/deserialize it to/from a
-bitstream.
-
-| |-- ramfw
-
-Generic runtime firmware implementation.
-
-| `-- romfw
-
-Generic ROM firmware implementation.
-
-|-- target
-| |-- hosted
-| `-- native
-
-rcode supports hosted and native targets. The hosted target builds
-rcode to execute as a userspace application on a UNIX-like system.
-This mode of operation makes it easy to debug, profile and test the
-code.
-
-`-- test
- |-- functional
- |-- fuzzing
- |-- integration
- |-- model
- `-- unit
-
-This is where the test framework lives. There are 5 types of tests.
-
-2) System initialization
-------------------------
-
-The native target begins execution in rom-crt.s. This is the cold
-boot entrypoint of the ROM firmware.
-
-The idea is to do as much of the initialization process within the C
-environment.
-
-In crt.s the following steps are performed:
-
- - Set up vector table
- - Set up initial stack for entry to the C environment
- - Clear BSS
- - Call main()
-
-The main() function performs the following actions:
-
- - Initialize the machine structure by calling imach()
- - Initialize the device driver subsystem by calling idev()
- - Enable interrupts
- - Populate initial namespace
- - Print some diagnostic information
- - Drop into the debug language interface
-
-The imach() function will populate the struct mach structure with the
-stack pointer location and size, as well as the environment variable
-location and size.
-
-Environment variables are used to pass information between images
-within the same exception level.
-
-The trapframe is populated for initial exit to the lower exception
-level. The key registers are SP, ELR and SPSR.
-
-At the end of imach() the instruction and data caches are invalidated.
-
-3) RMC handling flow
---------------------
-
-The vector table is installed in target/native/crt.s. The vector
-table definition is in target/native/arch.s.
-
-The exception handling code only uses the SP_EL3 stack pointer. The
-code does not use SP-EL0 at all.
-
-When an exception is received, the code jumps to the `exception()'
-function in target/native/arch.s. The code pushes the CPU context on
-the SP_EL3 stack and then jumps to the `trap()' function which is the
-generic top-level exception handler defined in src/romfw/rmc.c.
-
-The `trap()' function receives a pointer to the trapframe. The
-trapframe type is described in include/rcode/rcode.h and it is
-basically an array of registers.
-
-Within `trap()' the ESR is decoded and if it is not an RMC then the
-code will panic. This is because in the original r-mode specification
-only certain synchronous exceptions were defined. This part of the
-code is not complete yet.
-
-The RMU command is decoded based on the RMC class and function and the
-code jumps through a dispatch table to the corresponding libhdl
-handler. The libhdl handler will call through to the librmu handler.
-If there is an error, `badcmd()' is called by the librmu handler.
-This forces the code to do an early return without unwinding through
-all intermediate calls. `badcmd()' will set the x0 register in the
-trapframe to indicate the error and call the low level `swtch()'
-function which is defined in target/native/arch.s. If there is no
-error, the code will unwind all the way back to `trap()' and then call
-the low level `switch()' function.
-
-`swtch()' receives a trapframe pointer which points to the stored CPU
-context which is the same pointer as the one received from `trap()'.
-It will restore the context as needed and then perform an exception
-return.
-
-4) Driver model
----------------
-
-TBD
-
-5) Debug language
------------------
-
-Rcode has a builtin debug language that can be used to test different
-features of the code. The language is composed by a set of commands
-that can receive several parameters:
-
- - Set a register: set <reg> <value>
- It sets a value in a register
- - Get a register: get <reg>
- it prints the value of a register
- - Dump trapframe: dump
- Dump the full trapframe
- - Call trap handler: trap
- Calls the trap handler passing the trapframe
- - Call RMC handler: rmc imm1 imm2
- Calls the RMC handler with the specific imm1 and imm2 values
- - Call RMU handler: rmu rmucmd|?
- Calls one specific RMU handler. If a question mark is passed as
- parameter then it prints the list of available RMU handlers
- - Exit debug environment: exit [status]
- Exits from the debug environment with an optional status value
- - Print the help menu: help
- - Print the content of an entry: cat path
- It opens a path in the namespace and prints the content of the
- entry
- - list content of a directory: ls path
- It lists all the entries contained in a directory of the namespace
- - write content to a file: echo path string ...
- It writes all the arguments separated by one space to the path
- represented by the first parameter and append a new line at
- the end.
-
-The debug language uses the character '>' as a way to synchronize.
-Every time that it is ready to accept a new command it prints the
-string '> READY' including a new line at the end. The errors are marked
-with '> ERR' and some message including a new line at the end.
-
-
-6) Build system
----------------
-
-The rcode build system is based in fully portable POSIX Makefiles. They
-are structured in a recursive fashion, having a Makefile per directory
-that in case of being needed recurse in the appropiate subdirectories.
-Every Makefile begins with lines similar to:
-
-.POSIX:
-PROJECTDIR=../..
-include $(PROJECTDIR)/scripts/rules.mk
-
-The first line specifies to the make program that this is a POSIX
-Makefile, switching on the POSIX mode of the tool in case of accepting
-different modes. The second line specifies where is the root of the
-project related to the current directory and the third line includes the
-file rules.mk. The file rules.mk uses the definition of PROJECTDIR to
-define a set of macros and rules that will be used by all the Makefiles
-of the project.
-
-The build process depends of three variables:
-
- - CONF: This variable specifies the system configuration of
- the target. By default it has the value "arm64-rcode".
-
- - TOOL: This variable specifies the toolchain used to build
- the target. By default it has the value "gnu".
-
- - CROSS_COMPILE: This variable specifies a prefix used
- for the binaries of the toolchain. By default it
- has an empty value.
-
-There are several make variables that must be exported to the shell
-because there are shell scripts that use them, and for this reason the
-top Makefile generates the file scripts/env.sh which is sourced before
-recursing. For this reason, some Makefiles may not work when make is
-executed in one subdirectory (unless the user sources them in his shell).
-Anyway, the build system only guarantees a correct build when make
-is executed from the root directory of the project, otherwise some
-dependencies may be not correctly tracked.
-
-There are several Makefiles (drivers, src/romfw, src/ramfw) that produce
-a filed called builtin.o as target. This file is the composition of
-all the object files compiled in that directory. This avoid having
-dependencies between the top Makefile and the lower Makefiles as
-the top Makefile doesn't need to know what object files must be linked.
-
-[0] http://www.simple-cc.org
