README

   1                        __   _ __      _  __
   2                       / /  (_) /____ | |/_/
   3                      / /__/ / __/ -_)>  <
   4                     /____/_/\__/\__/_/|_|
   5                          Migen inside
   6
   7                 Build your hardware, easily!
   8               Copyright 2012-2018 / EnjoyDigital
   9
  10 [> Intro
  11 --------
  12 LiteX is a FPGA design/SoC builder that can be used to build cores, create
  13 SoCs and full FPGA designs.
  14
  15 LiteX is based on Migen and provides specific building/debugging tools for
  16 a higher level of abstraction and compatibily with the LiteX core ecosystem.
  17
  18 Think of Migen as a toolbox to create FPGA designs in Python and LiteX as a
  19 toolbox to create/develop/debug FPGA SoCs in Python.
  20
  21
  22 Typical LiteX design flow:
  23 --------------------------
  24
  25                         +---------------+
  26                         |FPGA toolchains|
  27                         +----^-----+----+
  28                              |     |
  29                           +--+-----v--+
  30          +-------+        |           |
  31          | Migen +-------->           |
  32          +-------+        |           |        Your design
  33                           |   LiteX   +---> ready to be used!
  34                           |           |
  35 +----------------------+  |           |
  36 |LiteX Cores Ecosystem +-->           |
  37 +----------------------+  +-^-------^-+
  38  (Eth, SATA, DRAM, USB,     |       |
  39   PCIe, Video, etc...)      +       +
  40                            board   target
  41                            file    file
  42
  43
  44 LiteX already supports various softcores CPUs: LM32, Mor1kx, PicoRV32, VexRiscv
  45 and is compatible with the LiteX's Cores Ecosystem:
  46
  47 - LiteDRAM: https://github.com/enjoy-digital/litedram
  48 - LiteEth: https://github.com/enjoy-digital/liteeth
  49 - LitePCIe: https://github.com/enjoy-digital/litepcie
  50 - LiteSATA: https://github.com/enjoy-digital/litesata
  51 - LiteUSB: https://github.com/enjoy-digital/liteusb
  52 - LiteSDCard: https://github.com/enjoy-digital/litesdcard
  53 - LiteICLink: https://github.com/enjoy-digital/liteiclink
  54 - LiteJESD204B: https://github.com/enjoy-digital/litejesd204b
  55 - LiteVideo: https://github.com/enjoy-digital/litevideo
  56 - LiteScope: https://github.com/enjoy-digital/litescope
  57
  58
  59 [> Sub-packages
  60 ---------------
  61 gen:
  62   Provides specific or experimental modules to generate HDL that are not integrated
  63   in Migen.
  64
  65 build:
  66   Provides tools to build FPGA bitstreams (interface to vendor toolchains) and to
  67   simulate HDL code or full SoCs.
  68
  69 soc:
  70   Provides definitions/modules to build cores (bus, bank, flow), cores and tools
  71   to build a SoC from such cores.
  72
  73 boards:
  74   Provides platforms and targets for the supported boards. All Migen's platforms
  75   can also be used in LiteX.
  76
  77 [> Very Quick start guide (for newcomers)
  78 -----------------------------------------
  79 TimVideos.us has done an awesome job for setting up a LiteX environment easily in
  80 the litex-buildenv repo: https://github.com/timvideos/litex-buildenv
  81
  82 It's recommended for newcomers to go this way. Various FPGA boards are supported
  83 and multiple examples provided! You can even run Linux on your FPGA using LiteX
  84 very easily!
  85
  86 Migen documentation can be found here: https://m-labs.hk/migen/manual
  87
  88 FPGA lessons/tutorials can be found at: https://github.com/enjoy-digital/fpga_101
  89
  90 [> Medium Quick start guide with Conda
  91 -----------------------------------------
  92
  93 0. Get miniconda by following instructions at https://conda.io/miniconda.html
  94
  95 1. Clone LiteX
  96   git clone --recurse-submodules https://github.com/enjoy-digital/litex.git
  97
  98 2. Create a LiteX environment from environment.yml
  99   conda env create -f environment.yml
 100
 101 3. Enter conda environment
 102   conda activate litex
 103
 104 4. Build the target of your board...:
 105   Go to boards/targets and execute the target you want to build
 106
 107
 108 [> Quick start guide (for advanced users)
 109 -----------------------------------------
 110 0. Install Python 3.5+ and FPGA vendor's development tools.
 111
 112 1. Get litex_setup.py script and execute:
 113    ./litex_setup.py init install
 114    This will clone and install Migen, LiteX and LiteX's cores.
 115    To update all repositories execute:
 116    ./litex_setup.py update
 117
 118 2. Compile and install binutils. Take the latest version from GNU.
 119   mkdir build && cd build
 120   ../configure --target=lm32-elf
 121   make
 122   make install
 123
 124 3. (Optional, only if you want to use a lm32 CPU in you SoC)
 125   Compile and install GCC. Take gcc-core and gcc-g++ from GNU
 126   (version 4.5 or >=4.9).
 127   rm -rf libstdc++-v3
 128   mkdir build && cd build
 129   ../configure --target=lm32-elf --enable-languages="c,c++" --disable-libgcc \
 130     --disable-libssp
 131   make
 132   make install
 133
 134 4. Build the target of your board...:
 135   Go to boards/targets and execute the target you want to build
 136
 137 5. ... and/or install Verilator and test LiteX on your computer:
 138   Download and install Verilator: http://www.veripool.org/
 139   On Fedora:
 140       sudo dnf install libevent-devel json-c-devel
 141   On Ubuntu:
 142       sudo apt install libevent-dev libjson-c-dev
 143   run: litex_sim
 144
 145 6. Run a terminal program on the board's serial port at 115200 8-N-1.
 146   You should get the BIOS prompt.
 147
 148 [> Contact
 149 ----------
 150 E-mail: florent [AT] enjoy-digital.fr