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  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)