os-workshop

same materials and sample source for RV32 OS projects
git clone http://frotz.net/git/os-workshop.git
Log | Files | Refs

hardware-setup.md (6743B)


      1 # Setting up the FPGA development board
      2 
      3 IMPORTANT: The USB and HDMI connectors on the FPGA board and the breakout board are surface-mount.
      4 Avoid using excess force when plugging cables in.  Consider holding the connector steady with one
      5 hand while plugging in a cable.
      6 
      7 IMPORTANT: Be careful not to zap the board with static electricity.  
      8 
      9 IMPORTANT: Use the USB connector on the SODIMM sized module, not on the breakout board.
     10 
     11 ![muselab icesugar pro fpga board](hardware.jpg)
     12 
     13 # Installing the Ethernet PMOD
     14 
     15 Consult the above image for the proper installation location.  You'll need to solder down
     16 the header at P6.  The FPGA bitstream is configured to support the Ethernet PMOD as installed
     17 aligned with the left side of this header (again, as illustrated above).  Installing it
     18 incorrectly could short power and ground and possibly damage the PMOD or the FPGA board.
     19 
     20 ## Install Tools
     21 
     22 You need the `sconsole` utility -- a very simple serial terminal that also knows how to download
     23 code to the bootloader running on the CPU on the FPGA.
     24 
     25 ```
     26 $ git clone https://github.com/swetland/sconsole.git
     27 $ cd sconsole
     28 $ make
     29 ```
     30 
     31 ## Updating the FPGA bitstream
     32 
     33 The FPGA's "code" is stored in a flash memory on the module.
     34 
     35 The USB debug interface exposes a serial port (typically `/dev/ttyACM0`) and
     36 a USB Mass Storage Device with a FAT partition.
     37 
     38 You can copy an appropriate `fpga.bit` file to the FAT partition to update the FPGA.
     39 
     40 The latest bitstream is in this repository at `prebuilt/fpga.bit.gz` -- it needs to
     41 be decompressed with gzip into `fpga.bit` before installation.
     42 
     43 ## Booting the FPGA from micro sdcard
     44 
     45 If a micro sdcard with a FAT filesystem is installed (in the socket in the underside
     46 of the FPGA board) and there is a `boot.bin` file, that file will be copied to 0x40000000
     47 and executed after the BIOS initializes the hardware.
     48 
     49 ## Building the FPGA bitstream from scratch
     50 
     51 This is complicated. TBD.
     52 
     53 ## Using sconsole to run software on the FPGA
     54 
     55 To just talk to something over the serial port, you can run sconsole like this:
     56 ```
     57 $ sconsole -t /dev/ttyACM0 1000000
     58 ```
     59 Which will connect to the specified serial port at 1Mbps
     60 
     61 The `-t` option allows non-printable characters through (so the ANSI escape
     62 sequences the Litex BIOS uses display properly).  By default sconsole maps
     63 non-printables to `.` to avoid messing up your terminal if there's a burst
     64 of noise on the serial line.
     65 
     66 To exit sconsole hit `ESC` twice and then `x` at the prompt.
     67 
     68 If you run sconsole against the FPGA module serial port and reset it
     69 (push the button on the module), you should see the Litex BIOS start up:
     70 ```
     71         __   _ __      _  __
     72        / /  (_) /____ | |/_/
     73       / /__/ / __/ -_)>  <
     74      /____/_/\__/\__/_/|_|
     75    Build your hardware, easily!
     76 
     77  (c) Copyright 2012-2022 Enjoy-Digital
     78  (c) Copyright 2007-2015 M-Labs
     79 
     80  BIOS built on May  7 2022 13:34:42
     81  BIOS CRC passed (a41aa094)
     82 
     83  LiteX git sha1: 4694916e
     84 
     85 --=============== SoC ==================--
     86 CPU:            VexRiscv_Linux @ 50MHz
     87 BUS:            WISHBONE 32-bit @ 4GiB
     88 CSR:            32-bit data
     89 ROM:            128KiB
     90 SRAM:           8KiB
     91 FLASH:          32768KiB
     92 SDRAM:          32768KiB 16-bit @ 50MT/s (CL-2 CWL-2)
     93 
     94 --========== Initialization ============--
     95 Initializing SDRAM @0x40000000...
     96 Switching SDRAM to software control.
     97 Switching SDRAM to hardware control.
     98 Memtest at 0x40000000 (2.0MiB)...
     99   Write: 0x40000000-0x40200000 2.0MiB     
    100    Read: 0x40000000-0x40200000 2.0MiB     
    101 Memtest OK
    102 Memspeed at 0x40000000 (Sequential, 2.0MiB)...
    103   Write speed: 20.4MiB/s
    104    Read speed: 10.8MiB/s                                                                                                 ...
    105                                                                                                                          ...
    106 Initializing W25Q256 SPI Flash @0x02000000...                                                                            ...
    107 Enabling Quad mode...
    108 SPI Flash clk configured to 25 MHz
    109 Memspeed at 0x2000000 (Sequential, 4.0KiB)...
    110    Read speed: 2.4MiB/s
    111 Memspeed at 0x2000000 (Random, 4.0KiB)...
    112    Read speed: 1.4MiB/s
    113 
    114 --============== Boot ==================--
    115 Booting from serial...
    116 Press Q or ESC to abort boot completely.
    117 sL5DdSMmkekro
    118 Timeout
    119 Booting from SDCard in SPI-Mode...
    120 Booting from boot.json...
    121 Booting from boot.bin...
    122 SDCard boot failed.
    123 No boot medium found
    124 
    125 --============= Console ================--
    126 
    127 litex>
    128 ```
    129 
    130 You can type `help` at this console and see commands to read/write memory, etc.
    131 
    132 For example, `mem_write 0xf0001000 5` will turn the module LED blue.
    133 
    134 If you want to run a program on the FPGA board, you need to tell sconsole about it:
    135 ```
    136 $ sconsole -t -b/stuff/os-workshop/out/boot.bin@0x40000000 -b/stuff/os-workshop/out/mandelbrot-fb.bin@0x40008000 /dev/ttyACM0 1000000
    137 ```
    138 This tells sconsole that if it sees the "start serial download" handshake from the
    139 board to first send `boot.bin` down to memory at 0x40000000 (the start of SDRAM) and
    140 then send `mandelbrot-fb.bin` to 0x40008000 (where the workshop bootloader will transfer
    141 control when it's done) and start executing `boot.bin`.
    142 
    143 If the board is already running you can type `serialboot` to kick this process off.
    144 
    145 When the board is reset, it will automatically send the download handshake as well.
    146 
    147 ```
    148 litex> serialboot
    149 Booting from serial...
    150 Press Q or ESC to abort boot completely.
    151 sL5DdSMmkekro
    152 [ serial boot requested ]
    153 
    154 [ sending '/stuff/os-workshop/out/boot.bin' to 0x40000000 ]
    155 KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
    156 [ sending '/stuff/os-workshop/out/mandelbrot-fb.bin' to 0x40008000 ]
    157 KKKKKKKKKKK
    158 [ jump to 0x40000000 ]
    159 KExecuting booted program at 0x40000000
    160 
    161 --============= Liftoff! ===============--
    162 
    163 ** Frobozz Magic Bootloader v0.2 **
    164 
    165 SVC ENTRY @0x40008000
    166 
    167 Hello, Mandelbrot!
    168 ```
    169 
    170 The messages in square brackets are sconsole telling you what it's done.
    171 The messages after the "Liftoff!" banner are from `boot.bin` and `mandelbrot-fb.bin`
    172 
    173 ## Network Booting 
    174 
    175 Install the Ethernet PMOD.
    176 
    177 Ensure the FPGA board and your development computer are on the same local link -- either
    178 using a direct cable between their ethernet ports or both plugged into the same switch.
    179 
    180 Run the network boot binary on the FPGA board -- either by copying `out/boot.net.bin` to
    181 `boot.bin` on a FAT partition on a micro sdcard installed in the FPGA board, or by using
    182 serial boot to run it on startup, like so:
    183 
    184 ```
    185 $ sconsole -t -b/stuff/os-workshop/out/boot.net.bin@0x40000000 /dev/ttyACM0 1000000
    186 ```
    187 
    188 Use the netboot agent to send your app down over the network:
    189 ```
    190 $ out/netboot -i enx000ec66b9271 out/mandelbrot-fb.bin@40008000
    191 ```
    192 
    193 (use the name of your local ethernet interface as the argument to the `-i` option)