```
Copyright 2012-2021 / Enjoy-Digital & LiteX developers
```
[](https://github.com/enjoy-digital/litex/actions)
# Welcome to LiteX!
The LiteX framework provides a convenient and efficient infrastructure to create FPGA Cores/SoCs, to explore various digital design architectures and create [full FPGA based systems](https://github.com/enjoy-digital/litex/wiki/Projects).
**Want to get started and/or looking for documentation? Make sure to visit the [Wiki](https://github.com/enjoy-digital/litex/wiki)!**
**A question or want to get in touch? Our IRC channel is [#litex at irc.libera.chat]**.
LiteX provides all the common components required to easily create an FPGA Core/SoC:
- :heavy_check_mark: Buses and Streams (Wishbone, AXI, Avalon-ST) and their interconnect.
- :heavy_check_mark: Simple cores: RAM, ROM, Timer, UART, JTAG, etc….
- :heavy_check_mark: Complex cores through the ecosystem of cores: [LiteDRAM](https://github.com/enjoy-digital/litedram), [LitePCIe](https://github.com/enjoy-digital/litepcie), [LiteEth](https://github.com/enjoy-digital/liteeth), [LiteSATA](https://github.com/enjoy-digital/litesata), etc...
- :heavy_check_mark: Various CPUs & ISAs: RISC-V, OpenRISC, LM32, Zynq, X86 (through a PCIe), etc...
- :heavy_check_mark: Mixed languages support with VHDL/Verilog/(n)Migen/Spinal-HDL/etc... integration capabilities.
- :heavy_check_mark: Powerful debug infractrusture through the various [bridges](https://github.com/enjoy-digital/litex/wiki/Use-Host-Bridge-to-control-debug-a-SoC) and [Litescope](https://github.com/enjoy-digital/litescope).
- :heavy_check_mark: Direct/Fast simulation through [Verilator](https://www.veripool.org/verilator/).
- :heavy_check_mark: Build backends for open-source and vendors toolchains.
- :heavy_check_mark: And a lot more... :)
By combining LiteX with the ecosystem of cores, creating complex SoCs becomes a lot easier than with traditional approaches while providing better portability and flexibility: Here is for example a Multi-core Linux Capable SoC based on VexRiscv-SMP CPU, LiteDRAM, LiteSATA built and integrated with LiteX, running on a cheap repurposed [Acorn CLE215+ Mining Board](https://github.com/enjoy-digital/litex/wiki/Use-LiteX-on-the-Acorn-CLE-215):
For more info, have a look at [Linux-on-LiteX-Vexriscv](https://github.com/litex-hub/linux-on-litex-vexriscv) project and try running Linux on your FPGA board!
LiteX's digital logic is currently described with [Migen](https://github.com/m-labs/migen) which does not prevent users to create mixed language projects:
- It's very common and easy to integrate VHDL/Verilog/SystemVerilog/nMigen/Spinal-HDL code in LiteX!
- It's also very common to do the opposite and generate the LiteX design as a verilog file and integrate it in a traditional flow.
LiteX was initially developed by [Enjoy-Digital](http://enjoy-digital.fr/) to create projects for clients (and we are still using it for that :)) and trying to take the different clients' requirements/needs consideration made, we think, the framework very flexible:
- Some users only want to use it to easily interconnect their existing VHDL/Verilog/SV cores.
- Some users are only interested to reuse the PCIe/Ethernet/SATA/etc cores as regular core and just integrate them in their traditional flow.
- Some users with a hardware background start with the above approaches and then switch later to the full Python flow since find it more efficient.
- Some users with a software background and fluent with Python start playing with FPGAs while they would probably never touch FPGA otherwise :)
- Etc...
We are well aware that everyone has a different background, so it's up to you to pick the right approach with LiteX that will be convenient for you!
To get started we encourage you to read the [wiki](https://github.com/enjoy-digital/litex/wiki).
You already have a FPGA board(s)? Visit [LiteX-Boards](https://github.com/litex-hub/litex-boards) to see if your board(s) is already supported!
The framework is also far from perfect and we'll be happy to have your [feedback or/and contributions](https://github.com/enjoy-digital/litex/wiki/Feedback-Contribution-Support).
Have fun! :wink:
# Typical LiteX design flow:
```
+---------------+
|FPGA toolchains|
+----^-----+----+
| |
+--+-----v--+
+-------+ | |
| Migen +--------> |
+-------+ | | Your design
| LiteX +---> ready to be used!
| |
+----------------------+ | |
|LiteX Cores Ecosystem +--> |
+----------------------+ +-^-------^-+
(Eth, SATA, DRAM, USB, | |
PCIe, Video, etc...) + +
board target
file file
```
LiteX already supports various softcores CPUs: VexRiscv, Rocket, LM32, Mor1kx, PicoRV32, BlackParrot and is compatible with the LiteX's Cores Ecosystem:
| Name | Build Status | Description |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [LiteX-Boards](http://github.com/litex-hub/litex-boards) | [](https://github.com/litex-hub/litex-boards/actions) | Boards support |
| [LiteDRAM](http://github.com/enjoy-digital/litedram) | [](https://github.com/enjoy-digital/litedram/actions) | DRAM |
| [LiteEth](http://github.com/enjoy-digital/liteeth) | [](https://github.com/enjoy-digital/liteeth/actions) | Ethernet |
| [LitePCIe](http://github.com/enjoy-digital/litepcie) | [](https://github.com/enjoy-digital/litepcie/actions) | PCIe |
| [LiteSATA](http://github.com/enjoy-digital/litesata) | [](https://github.com/enjoy-digital/litesata/actions) | SATA |
| [LiteSDCard](http://github.com/enjoy-digital/litesdcard) | [](https://github.com/enjoy-digital/litesdcard/actions) | SD card |
| [LiteICLink](http://github.com/enjoy-digital/liteiclink) | [](https://github.com/enjoy-digital/liteiclink/actions) | Inter-Chip communication |
| [LiteJESD204B](http://github.com/enjoy-digital/litejesd204b) | [](https://github.com/enjoy-digital/litejesd204b/actions) | JESD204B |
| [LiteVideo](http://github.com/enjoy-digital/litevideo) | [](https://github.com/enjoy-digital/litevideo/actions) | VGA, DVI, HDMI |
| [LiteScope](http://github.com/enjoy-digital/litescope) | [](https://github.com/enjoy-digital/litescope/actions) | Logic analyzer |
# Examples of designs built with LiteX:
Custom PCIe SDI Capture/Playback board built around LitePCIe and integrated with LiteX, allowing full control of the SDI flow and very low latency.
Alternative firmware/gateware for the SDS1104X-E Scope:
HBM2 test infrastructure on Forest Kitten 33:
To discover more products/projects built with LiteX, visit the [projects page](https://github.com/enjoy-digital/litex/wiki/Projects) on the Wiki.
# Papers, Presentations, Tutorials, Links
**FPGA lessons/tutorials:**
- https://github.com/enjoy-digital/fpga_101
**Migen tutorial:**
- https://m-labs.hk/migen/manual
**OSDA 2019 paper/slides:**
- https://osda.gitlab.io/19/1.1.pdf
- https://osda.gitlab.io/19/1.1-slides.pdf
**Linux on LiteX-Vexriscv:**
- https://github.com/litex-hub/linux-on-litex-vexriscv
**RISC-V Getting Started Guide:**
- https://risc-v-getting-started-guide.readthedocs.io/en/latest/
**LiteX vs. Vivado First Impressions:**
- https://www.bunniestudios.com/blog/?p=5018
**35C3 - Snakes and Rabbits - How CCC shaped an open hardware success:**
- https://www.youtube.com/watch?v=AlmVxR0417c
**Tim has to many projects - LatchUp Edition:**
https://www.youtube.com/watch?v=v7WrTmexod0
# Sub-packages
**litex.gen**
Provides specific or experimental modules to generate HDL that are not integrated in Migen.
**litex.build:**
Provides tools to build FPGA bitstreams (interface to vendor toolchains) and to simulate HDL code or full SoCs.
**litex.soc:**
Provides definitions/modules to build cores (bus, bank, flow), cores and tools to build a SoC from such cores.
# Quick start guide
1. Install Python 3.6+ and FPGA vendor's development tools and/or [Verilator](http://www.veripool.org/).
2. Install Migen/LiteX and the LiteX's cores:
```sh
$ wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
$ chmod +x litex_setup.py
$ ./litex_setup.py init install --user (--user to install to user directory)
```
Later, if you need to update all repositories:
```sh
$ ./litex_setup.py update
```
> **Note:** On MacOS, make sure you have [HomeBrew](https://brew.sh) installed. Then do, ``brew install wget``.
> **Note:** On Windows, it's possible you'll have to set `SHELL` environment variable to `SHELL=cmd.exe`.
3. Install a RISC-V toolchain (Only if you want to test/create a SoC with a CPU):
```sh
$ ./litex_setup.py gcc
```
4. Build the target of your board...:
Go to litex-boards/litex_boards/targets and execute the target you want to build.
5. ... and/or install [Verilator](http://www.veripool.org/) and test LiteX directly on your computer without any FPGA board:
On Linux (Ubuntu):
```sh
$ sudo apt install libevent-dev libjson-c-dev verilator
$ lxsim --cpu-type=vexriscv
```
On MacOS:
```sh
$ brew install json-c verilator libevent
$ brew cask install tuntap
$ lxsim --cpu-type=vexriscv
```
6. Run a terminal program on the board's serial port at 115200 8-N-1.
You should get the BIOS prompt like the one below.
# Community
Over the years a friendly community has grown around LiteX and the ecosystem of cores. Feedbacks and contributions have already greatly improved the project, EnjoyDigital still leads the development but it is now a community project and collaborative projects created around/with LiteX can be found at https://github.com/litex-hub.
# Contact
E-mail: florent@enjoy-digital.fr