From: Florent Kermarrec Date: Wed, 4 Mar 2020 09:53:44 +0000 (+0100) Subject: doc: remove partial doc imported from litex-buildenv-wiki: we'll create a LiteX wiki... X-Git-Tag: 24jan2021_ls180~604 X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=68f565420dbd40fda0609722576a2ad6de026b83;p=litex.git doc: remove partial doc imported from litex-buildenv-wiki: we'll create a LiteX wiki and doc. --- diff --git a/doc/BIOS.md b/doc/BIOS.md deleted file mode 100644 index f414c822..00000000 --- a/doc/BIOS.md +++ /dev/null @@ -1,9 +0,0 @@ -LiteX takes the philosophy of pushing as much onto the [[Soft CPU]] as possible. This means that most [[Gateware]] needs some accompanying code to initialize various settings and configurations. This specialized firmware is called the [[BIOS]]. - -The [[BIOS]] generally does tasks like; - * Train any external DDR memory - * Load the user's [[Firmware]] into external memory via; - * Communication channels like serial, tftp - * Other storage systems like external flash. - -This can make it very fast to do development as you can iterate on [[Firmware]] development quickly. \ No newline at end of file diff --git a/doc/Firmware.md b/doc/Firmware.md deleted file mode 100644 index 5324da75..00000000 --- a/doc/Firmware.md +++ /dev/null @@ -1,114 +0,0 @@ -# Firmware - -LiteX is normally used with custom firmware running on the Soft-CPU inside the gateware (although in some cases it can be used with software running on a computer connected to the FPGA). - -This firmware can either be custom bare metal C code or be built on top of an existing real time operating system or even full operating system. All Soft-CPUs let you write your own bare metal firmware, but only some configurations work with operating systems. - -[Firmware which runs on LiteX Google Doc](https://docs.google.com/document/d/11uzjWRWk9-KuBFc7chUNUluL5ajysY2qfXvt1vttl7k/edit) - -# Baremetal - -## Support Soft-CPU Configurations - -**All** Soft-CPUs let you write your own bare metal firmware. - - * `lm32` (any variant) - * `or1k` (any variant) - * `vexriscv` (any variant) - * `picorv32` (any variant) - * `minerva` (any variant) - ---- - -# MicroPython via [FuPy Project](https://fupy.github.io) - -From the FuPy website; -> The aim of this project is to make MicroPython run on FPGAs using the LiteX & Migen+MiSoC technologies. This allows you to do full stack development (FPGA gateware & soft CPU firmware) in Python! - -## When to use? - -MicroPython is great to use when ease and speed of development is more important than performance. When coupled with LiteX you can push MicroPython even further by moving performance critical parts into FPGA gateware. - -## Hardware Requirements - -MicroPython is very light on requirements; - * 32 kilobytes memory - can normally use internal block ram inside FPGA. - * 128 kilobytes of storage - can normally use spare space in SPI flash used to configure the FPGA. - -## Support Soft-CPU Configurations - - * `lm32` (any variant), in FuPy repository - * `or1k` (any variant), in FuPy repository - * (in progress) `vexriscv` (any variant), in FuPy repository - * (in progress) `picorv32` (any variant), in FuPy repository - ---- - -# [NuttX](http://www.nuttx.org/) - -From the NuttX website; -> NuttX is a real-time operating system (RTOS) with an emphasis on standards compliance and small footprint. Scalable from 8-bit to 32-bit microcontroller environments, the primary governing standards in NuttX are Posix and ANSI standards. Additional standard APIs from Unix and other common RTOS's (such as VxWorks) are adopted for functionality not available under these standards, or for functionality that is not appropriate for deeply-embedded environments (such as fork()). - -## When to use? - -NuttX is a good option if you are already using NuttX or need to use a function that is already available in the NuttX ecosystem. - -## Hardware Requirements - -Unknown. - -LiteEth networking is supported. - -## Support Soft-CPU Configurations - - * `lm32` (any variant), in upstream repository - ---- - -# [Zephyr](https://www.zephyrproject.org/) - -From the Zephyr website; -> The Zephyr Project is a scalable real-time operating system (RTOS) supporting multiple hardware architectures, optimized for resource constrained devices, and built with safety and security in mind. - -## When to use? - -Zephyr is a great choice if you don't want to write your own bare metal firmware. It is under active development and moving forward quickly. - -It also has a coding style which makes it easy to move to Linux at a later state if you outgrow the abilities of Zephyr. - -## Hardware Requirements - -Zephyr is very light on requirements; - * 32 kilobytes memory - can normally use internal block ram inside FPGA. - * Some storage - can normally use spare space in SPI flash used to configure the FPGA. - -## Support Soft-CPU Configurations - - * `vexriscv` (any variant), in upstream repository - * `picorv32` (any variant), out of tree port - ---- - -# [Linux](https://en.wikipedia.org/wiki/Linux) - -From Wikipedia; -> Linux is a family of free and open-source software operating systems based on the Linux kernel, an operating system kernel first released on September 17, 1991 by Linus Torvalds. ... -> Linux also runs on embedded systems, i.e. devices whose operating system is typically built into the firmware and is highly tailored to the system. This includes routers, automation controls, televisions, digital video recorders, video game consoles, and smartwatches. Many smartphones and tablet computers run Android and other Linux derivatives.[30] Because of the dominance of Android on smartphones, Linux has the largest installed base of all general-purpose operating systems. - -## When to use? - -Linux tends to run quite slowly on the soft-CPUs supported by LiteX and needs hardware acceleration to do most useful operations. Linux makes the most sense were the existing large pool of Linux drivers or software is helpful. - -## Hardware Requirements - -Linux operating support generally needs; - * Large and fast FPGA, something like Lattice ECP5 or Xilinx Artix 7 / Spartan 6. - * 32+ megabytes memory, generally meaning external SDRAM or DDR RAM. - * UART serial console. - * Fast Ethernet (100 Megabit or 1 Gigabit Ethernet). - * Some type of storage, large SPI flash or SD Card or SATA hard drives potential options. - -## Support Soft-CPU Configurations - - * `or1k` (`linux` variant), out of tree port being upstreamed - * `vexriscv` (`linux` variant), out of tree port being upstreamed diff --git a/doc/Soft-CPU.md b/doc/Soft-CPU.md deleted file mode 100644 index 92f31db1..00000000 --- a/doc/Soft-CPU.md +++ /dev/null @@ -1,276 +0,0 @@ -LiteX can create SoCs with or without CPU. Some simple SoCs don’t use any CPU (bridging SoCs for example), some SoCs use a CPU but external to the FPGA (PCIe SoCs for example where the CPU is directly the CPU of the Host machine) but in most of the cases the SoC embedded a "Soft CPU" to control the system and/or ease splitting tasks between software/hardware. - -# Summary of Soft CPUs - -Currently the supported Soft CPUs are: - - * [`lm32`](https://github.com/enjoy-digital/litex/tree/master/litex/soc/cores/cpu/lm32) -- a [LatticeMico32](https://en.wikipedia.org/wiki/LatticeMico32) soft core. - -* [`or1k`](https://github.com/enjoy-digital/litex/tree/master/litex/soc/cores/cpu/mor1kx) -- an [OpenRISC 1000](https://openrisc.io/or1k.html) soft core (see also [Open RISC on Wikipedia](https://en.wikipedia.org/wiki/OpenRISC)). - -* [`picorv32`](https://github.com/enjoy-digital/litex/tree/master/litex/soc/cores/cpu/picorv32) -- a [Small RISC V core by Clifford Wolf](https://github.com/cliffordwolf/picorv32), implementing the `rv32imc` instruction set (or configured subsets) - -* [`vexriscv`](https://github.com/enjoy-digital/litex/tree/master/litex/soc/cores/cpu/vexriscv) -- an [FPGA Friendly RISC V core by SpinalHDL](https://github.com/SpinalHDL/VexRiscv), implementing the `rv32im` instruction set (hardware multiply optional) - -* [`minerva`](https://github.com/enjoy-digital/litex/tree/master/litex/soc/cores/cpu/minerva) -- a CPU core that currently implements the RISC-V RV32I instruction set with its microarchitecture described in plain Python code using the [nMigen toolbox](https://github.com/m-labs/nmigen). - -# Soft CPU Variants - -Most of these CPUs have multiple configuration variants which customize the configuration to target a specific type of firmware, performance and resource usage. All these CPUs can be used with your own bare metal firmware. - -## `minimal` - -Aliases: `min` - -Minimal is the smallest possible working configuration for a given CPU type. These features frequently disables a large number of useful such as illegal instruction exceptions and similar. It should only be used if the absolute smallest configuration is needed. - -### Supported CPUs - - * lm32 - * picorv32 - * vexriscv - -## `lite` - -**Aliases**: `zephyr`, `nuttx`, `light` - -Lite is the configuration which should work okay for bare metal firmware and RTOS like NuttX or Zephyr on small big FPGAs like the Lattice iCE40 parts. It can also be used for designs which are more resource constrained. - -### Recommended FPGAs - - * Lattice iCE40 Series - iCE40HX, iCE40LP, iCE40UP5K - * Any resource constrained design. - -### Supported CPUs - - * lm32 - * vexriscv - -## `standard` - -**Aliases**: `std` - -Standard is the default configuration which should work well for bare metal firmware and RTOS like NuttX or Zephyr on modern big FPGAs. - -### Supported CPUs - - * lm32 - * minerva - * picorv32 - * or1k - * vexriscv - -### Recommended FPGAs - - * Xilinx 7-Series - Artix7, Kintex7, Spartan7 - * Xilinx Spartan6 - * Lattice ECP5 - -## `full` - -This target enables **all** features of each CPU. - -### Supported CPUs - - * (TODO) - lm32 - * (TODO) - minerva - * (TODO) - picorv32 - * (TODO) - or1k - * vexriscv - - -## `linux` - -This target enables CPU features such as MMU that are required to get Linux booting. - -### Supported CPUs - - * or1k - * vexriscv - ---- - -# Soft CPU Extensions - -Extensions are added to the CPU variant with a `+`. For example a `minimal` variant with the `debug` extension would be `minimal+debug`. - -## `debug` - -The debug extension enables extra features useful for debugging. This normally includes things like JTAG port. - -### Supported CPUs - - * vexriscv - -## TODO - `mmu` - -The `mmu` extension enables a memory protection unit. - -### Supported CPUs - - * lm32 (untested) - * vexriscv - * or1k - -## TODO - `hmul` - -The `hmul` extension enables hardware multiplication acceleration. - -## TODO - `fpu` - -The `fpu` extension enables a floating point acceleration unit. - -### Supported CPUs - - * or1k - - ---- - -# Binutils + Compiler - - * lm32 support was added to upstream GCC around ~2009, no clang support. - * or1k support was added to upstream GCC in version 9.0.0, clang support was added upstream in version XXX - * riscv support (VexRISCV, PicoRV32 and Minerva) was added to upstream GCC in version 7.1.0, clang support was added upstream in version 3.1 - -You can compile your own compiler, download a precompiled toolchain or use an environment like [TimVideos LiteX BuildEnv](https://github.com/timvideos/litex-buildenv/) which provides precompiled toolchain for all three architectures. - -Note: RISC-V toolchains support or require various extensions. Generally `rv32i` is used on smaller FPGAs, and `rv32im` on larger FPGAs -- the `rv32im` adds hardware multiplication and division (see [RISC V ISA base and extensions on Wikipedia](https://en.wikipedia.org/wiki/RISC-V#ISA_base_and_extensions) for more detail). - ---- - -# SoftCPU options - -## lm32 - [LatticeMico32](https://github.com/m-labs/lm32) - -[LatticeMico32](https://en.wikipedia.org/wiki/LatticeMico32) soft core, small and designed for an FPGA. - -### CPU Variants - - * minimal - * lite - * standard - -### Tooling support - - * Upstream GCC - * Upstream Binutils - -### OS Support - - * No upstream Linux, very old Linux port - * Upstream NuttX - * No Zephyr support - -### Community - - * No current new activity - ---- - -## [mor1k - OpenRISC](https://github.com/openrisc/mor1kx) - -An [OpenRISC 1000](https://openrisc.io/or1k.html) soft core (see also [Open RISC on Wikipedia](https://en.wikipedia.org/wiki/OpenRISC)). - -### CPU Variants - - * standard - * linux - -### Tooling support - - * Upstream GCC - * Upstream Binutils - * Upstream clang - -### OS support - - * No Zephyr support - * No NuttX support - * Upstream Linux - -### Community - - * Reasonable amount of activity. - ---- - -## RISC-V - [VexRiscv](https://github.com/SpinalHDL/VexRiscv) - -A [FPGA Friendly RISC V core by SpinalHDL](https://github.com/SpinalHDL/VexRiscv), implementing the `rv32im` instruction set (hardware multiply optional). - -### CPU Variants - - * minimal - * minimal_debug - * lite - * lite_debug - * standard - * standard_debug - * linux - -### Tooling support - - * Upstream GCC - * Upstream Binutils - * Upstream clang - -### OS support - - * Upstream Zephyr - * Unknown NuttX support - * Upstream Linux (in progress) - -### Community - - * Lots of current activity - * Currently supported under both LiteX & MiSoC - -## RISC-V - [picorv32](https://github.com/cliffordwolf/picorv32/) - -A [small RISC V core by Clifford Wolf](https://github.com/cliffordwolf/picorv32), implementing the `rv32imc` instruction set (or configured subsets). - -### CPU Variants - - * minimal - * standard - -### Tooling support - - * Upstream GCC - * Upstream Binutils - * Upstream clang - -### OS support - - * Out of tree Zephyr - * Unknown NuttX support - * Too small for Linux - -### Community - - * Some activity - -## RISC-V - [`minerva`](https://github.com/enjoy-digital/litex/tree/master/litex/soc/cores/cpu/minerva) - -The Minerva is a CPU core that currently implements the RISC-V RV32I instruction set with its microarchitecture described in plain Python code using the [nMigen toolbox](https://github.com/m-labs/nmigen). - -### CPU Variants - - * standard - -### Tooling support - - * Upstream GCC - * Upstream Binutils - * Upstream clang - -### OS support - - * Unknown Zephyr support - * Unknown NuttX support - * Unknown Linux support - -### Community - - * Some activity diff --git a/doc/pull-docs-from-buildenv-wiki.sh b/doc/pull-docs-from-buildenv-wiki.sh deleted file mode 100755 index 04690d64..00000000 --- a/doc/pull-docs-from-buildenv-wiki.sh +++ /dev/null @@ -1,14 +0,0 @@ -#!/bin/bash - -# Soft-CPU - Description about supported Soft-CPUs. -# BIOS - Information about the BIOS and what it is used for. -# Firmware - Information about compatible Firmware. - -for page in Soft-CPU BIOS Firmware; do - curl https://raw.githubusercontent.com/wiki/timvideos/litex-buildenv/${page}.md > ${page}.md - git add ${page}.md -done - -GIT_MSG=$(tempfile) || exit -trap "rm -f -- '$GIT_MSG'" EXIT -git commit --message "Updating documents from LiteX BuildEnv Wiki"