Warning, /bsps/riscv/niosv/README.md is written in an unsupported language. File is not indexed.
0001 # Intel NIOSV BSP
0002
0003 The Intel NIOSV BSP implementation provides the base components needed for any
0004 NIOSV specific BSP: clock, console, irq, and timer. An example BSP for the Intel
0005 Cyclone 10 LP Evaluation Board is included as a reference design and test
0006 hardware. The base BSP assumes that the FPGA and NIOSV has the following
0007 devices/IP attached to the processor.
0008
0009 * Generic QUAD SPI Controlller II (EPCQ) - the serial flash memory device
0010 connected to the FPGA and contains the FPGA configuration, software image, and
0011 user data area.
0012 * On Chip ROM - an On-Chip Memory IP configured as ROM. Contains boot loader to
0013 load software image from the EPCQ device.
0014 * On Chip RAM - an On-Chip Memory IP configured as RAM. Used by the boot loader
0015 for data and bss. Can be used by software image as well.
0016 * External RAM Interface - an external memory device IP. In the case of the
0017 Cyclone 10 LP Evaluation Board, a hyperbus controller which is attached to a
0018 HyperRAM device.
0019 * Benchmark Timer - a modified Interval Timer IP which will be used as the BSPs
0020 benchmark timer.
0021 * Watchdog Timer - an Interval Timer IP configured as a watchdog which will be
0022 used to reset the NIOSV.
0023 * JTAG UART - an JTAG UART IP which will be used as the console port.
0024
0025 The following BSP parameters need to be set in the config.ini file when building
0026 RTEMS in order to set up the memory map for the NIOSV:
0027
0028 * NIOSV_EPCQ_ROM_REGION_BEGIN - the starting address of the EPCQ device
0029 attached to the NIOSV
0030 * NIOSV_EPCQ_ROM_REGION_SIZE - the size in bytes of the EPCQ device.
0031 * NIOSV_ONCHIP_ROM_REGION_BEGIN - the starting address of the onchip rom IP
0032 attached to the NIOSV
0033 * NIOSV_ONCHIP_ROM_REGION_SIZE - the size in bytes of the onchip rom IP device.
0034 * NIOSV_ONCHIP_RAM_REGION_BEGIN - the starting address of the onchip ram IP
0035 attached to the NIOSV
0036 * NIOSV_ONCHIP_RAM_REGION_SIZE - the size in bytes of the onchip ram IP device.
0037 * NIOSV_EXT_RAM_REGION_BEGIN - the starting address of the external ram
0038 interface IP attached to the NIOSV
0039 * NIOSV_EXT_RAM_REGION_SIZE - the size in bytes of the external ram interface
0040 IP device.
0041 * NIOSV_IS_NIOSVG - Whether or not the **NIOS V/g** processor is used.
0042 * NIOSV_HAS_FP - Whether or not the **NIOS V/g** processor has a FPU.
0043
0044 ## Intel Cyclone 10 LP Evaluation Board Example
0045
0046 The **rtems_vm.jic** file included with this BSP is a Cyclone 10 LP Evaluation
0047 Board programming file that can be downloaded to the board and has the following
0048 IP:
0049
0050 * NIOS V/m Microcontroller
0051 * timer_sw_agent - Data Master: 0x10000100 - 0x1000013f
0052 * dm_agent - Instruction Master: 0x10030000 - 0x1003ffff,
0053 Data Master: 0x10030000 - 0x1003ffff
0054 * Generic QUAD SPI Controlller II
0055 * avl_csr - Data Master: 0x10000140 - 0x1000017f
0056 * avl_mem - Data Master: 0x11000000 - 0x11ffffff
0057 * On-Chip Memory (RAM or ROM) configured as ROM
0058 * s1 - Instruction Master: 0x10010000 - 0x10010fff,
0059 Data Master: 0x10010000 - 0x10010fff
0060 * On-Chip Memory (RAM or ROM) configured as RAM
0061 * s1 - Instruction Master: 0x10020000 - 0x10021fff,
0062 Data Master: 0x10020000 - 0x10021fff
0063 * HyperBus Controller (x8) - Infineon HyperBus Controller IP which can control
0064 up to 2 HyperRAM devices. The Cyclone 10 LP Evaluation board has the HyperRAM
0065 connected to the 2nd device (chip select 2). The boot loader in the On-Chip ROM
0066 sets the HyperRAM base address to 0x01000000 in the slave register.
0067 * axi4_slave_memory - Instruction Master: 0x00000000 - 0x0fffffff,
0068 Data Master: 0x00000000 - 0x0fffffff
0069 * axi4_slave_register - Data Master: 0x10000000 - 0x100000ff
0070 * Interval Timer configured for free running benchmark timer. Modified from
0071 original Interval Timer to include a prescalar to adjust the clock rate.
0072 * s1 - Data Master: 0x10000180 - 0x1000019f
0073 * Interval Timer configured as watchdog timer
0074 * s1 - Data Master: 0x100001c0 - 0x100001df
0075 * System ID Peripheral
0076 * control_slave - Data Master: 0x10000200 - 0x10000207
0077 * JTAG UART
0078 * jtag_slave - Data Master: 0x10000208 - 0x1000020f
0079 * PIO (Parallel I/O) configured as outputs for turning on LEDs
0080 * s1 - Data Master: 0x100001a0 - 0x100001bf
0081 * PIO (Parallel I/O) configured as inputs for reading dip switch settings
0082 * s1 - Data Master: 0x100001f0 - 0x100001ff
0083 * PIO (Parallel I/O) configured as inputs for reading push buttons
0084 * s1 - Data Master: 0x100001e0 - 0x100001ef
0085
0086 Here are the associated config.ini entries:
0087
0088 [riscv/niosvc10lp]
0089 NIOSV_EPCQ_ROM_REGION_BEGIN = 0x11000000
0090 NIOSV_EPCQ_ROM_REGION_SIZE = 0x01000000
0091 NIOSV_ONCHIP_ROM_REGION_BEGIN = 0x10010000
0092 NIOSV_ONCHIP_ROM_REGION_SIZE = 4096
0093 NIOSV_ONCHIP_RAM_REGION_BEGIN = 0x10020000
0094 NIOSV_ONCHIP_RAM_REGION_SIZE = 8192
0095 NIOSV_EXT_RAM_REGION_BEGIN = 0x01000000
0096 NIOSV_EXT_RAM_REGION_SIZE = 0x00800000
0097 NIOSV_IS_NIOSVG = False
0098 NIOSV_HAS_FP = False
0099
0100 The **rtems_vg.jic** file included has the same peripheral IP but with a
0101 **NIOS V/g** processor.
0102
0103 Here are the associated config.ini entries:
0104
0105 [riscv/niosvc10lp]
0106 NIOSV_EPCQ_ROM_REGION_BEGIN = 0x11000000
0107 NIOSV_EPCQ_ROM_REGION_SIZE = 0x01000000
0108 NIOSV_ONCHIP_ROM_REGION_BEGIN = 0x10010000
0109 NIOSV_ONCHIP_ROM_REGION_SIZE = 4096
0110 NIOSV_ONCHIP_RAM_REGION_BEGIN = 0x10020000
0111 NIOSV_ONCHIP_RAM_REGION_SIZE = 8192
0112 NIOSV_EXT_RAM_REGION_BEGIN = 0x01000000
0113 NIOSV_EXT_RAM_REGION_SIZE = 0x00800000
0114 NIOSV_IS_NIOSVG = True
0115 NIOSV_HAS_FP = False
0116
0117 The **rtems_vgfp.jic** file included has the same peripheral IP but with a
0118 **NIOS V/g** processor with the FPU enabled.
0119
0120 Here are the associated config.ini entries:
0121
0122 [riscv/niosvc10lp]
0123 NIOSV_EPCQ_ROM_REGION_BEGIN = 0x11000000
0124 NIOSV_EPCQ_ROM_REGION_SIZE = 0x01000000
0125 NIOSV_ONCHIP_ROM_REGION_BEGIN = 0x10010000
0126 NIOSV_ONCHIP_ROM_REGION_SIZE = 4096
0127 NIOSV_ONCHIP_RAM_REGION_BEGIN = 0x10020000
0128 NIOSV_ONCHIP_RAM_REGION_SIZE = 8192
0129 NIOSV_EXT_RAM_REGION_BEGIN = 0x01000000
0130 NIOSV_EXT_RAM_REGION_SIZE = 0x00800000
0131 NIOSV_IS_NIOSVG = True
0132 NIOSV_HAS_FP = True
0133
0134 ### Intel Cyclone 10 LP Evaluation Board Implementation Details
0135
0136 In order to make it easier to create a RTEMS BSP for a NIOSV project built in
0137 Quartus Prime, this BSP used the **system.h** file that is generated by the
0138 Quartus Prime's BSP editor. The file was renamed to **bsp_system.h**. The header
0139 guard was modifed from **__SYSTEM_H_** to **__BSP_SYSTEM_H_** to reflect the new
0140 name of the file. The **#include "linker.h"** line was also removed as that is
0141 not needed.
0142
0143 This BSP also makes use of the device driver code generated from the Quartus
0144 Prime's BSP editor with some minor changes to make the code easier to read. A
0145 developer could use the same strategy or create something from scratch.
0146
0147 The hyperbus controller IP that comes with the Cyclone 10 LP Evaluation Board is
0148 proprietary and requires a license. Instead, the BSP uses a hyperbus controller
0149 IP that can be requested from Infineon (no link provided because it most likely
0150 will change). Just use your favorite search engine and you should be able find
0151 the request form. You may need to answer some marketing questions but I had no
0152 trouble getting it. The IP is written for Xilinx/AMD parts so you will have to
0153 write some Verilog code to connect it to a Cyclone 10 LP. I was a novice so it
0154 took me a while to get it to work. The biggest revelation that took me forever
0155 to figure out was that you have to use a Input Delay From Pin assignment to meet
0156 RWDS timing on a read. I was trying to use logic for this which was not the
0157 right approach.
0158
0159 The On-Chip Memory IP configured as ROM needs to have a boot loader pre-loaded.
0160 Follow the instructions outlined in the Quartus Prime software user guide to
0161 initialize the ROM with the **bootloader_niosvc10lp_xx.hex** file include with
0162 this BSP. This boot loader will initialize the hyperbus controller and load any
0163 application image found at offset 0x100000 within the EPCQ device to the
0164 HyperRAM (i.e. NIOSV_EXT_RAM_REGION_BEGIN). The boot loader will validate the
0165 application image before loading it into the HyperRAM using a CRC32 algorithm.
0166 If the image was loaded successfully in the HyperRAM, the first two LEDs will be
0167 on; otherwise, the first, second, and fourth LEDs will be on indicating a load
0168 failure.
0169
0170 The application image must have the following header information located at
0171 offset 0x100000 within the EPCQ device in order for the boot loader to load the
0172 application into the HyperRAM:
0173
0174 ```
0175 typedef struct
0176 {
0177 uint32_t offset; //The offset of binary code image relative to the start of
0178 //the header information
0179 uint32_t size; //The size of the binary code image in bytes
0180 uint32_t crc; //The calculated CRC value for the binary code image
0181 //(in accordance with crc.c/h)
0182 char version[11]; //A "C" string version of the binary code image
0183 //(i.e. "1.00.0000")
0184 }file_header_t;
0185 ```
0186
0187 This is the typical memory map within the EPCQ device.
0188
0189 0x000000: <FPGA configuration image>
0190 0x100000: <file_header_t><binary code image>
0191
0192 ### Intel Cyclone 10 LP Evaluation Board Build Environment
0193
0194 The following are the steps I performed to create the **rtems_vm.jic** file used
0195 to program the Cyclone 10 LP Evaluation Board. The process is broken down to
0196 three phases. The first phase is to generate BSP files from an initial
0197 compilation (SOF file) of the system to get the **system.h** and any C device
0198 driver code that could to be used in the RTEMS NIOSV BSP and boot loader. The
0199 second phase is to compile a final SOF file that contains a FPGA configuration
0200 with the On-Chip ROM loaded with the boot loader hex file. The third phase is to
0201 combine the FPGA configuration SOF file and an application HEX file into a JIC
0202 file that can be programmed on the FPGA EPCQ device.
0203
0204 #### Phase 1
0205 Here is an outline of the first phase to generate BSP source files from a SOF
0206 file (see the Cyclone 10 LP Evaluation Board project that comes with the board
0207 for more details). The main outputs from this process that are useful for a
0208 RTEMS BSP, is the **system.h** file and any C device driver source files that
0209 can be used as a basis for RTEMS device drivers.
0210
0211 * Create a new project in the Quartus Prime software (I used the 23.1std.0
0212 version)
0213 * Set the project device to the Cyclone 10 LP 10CL025YU256I7G (check you board
0214 to confirm)
0215 * Set the device and pins options (use the project that comes with the eval
0216 board for the correct settings).
0217 * Use Platform Designer within Quartus Prime to create a system that implemets
0218 the IP listed in the sections above.
0219 * I have placed pictures of my Platform Designer system in the BSP
0220 (see **Platform Designer X.png** files)
0221 * You will still need to setup each IP correctly (use the eval board
0222 reference design as guidance).
0223 * For the first compilation, the ROM memory will not be initialized as you
0224 will need to create a boot loader in the next phase.
0225 * After completing the design, generate the HDL.
0226 * Add a top level Verilog file to connect your generated system to the I/O pins
0227 (see **cl10lp_rtems.v** file in BSP for an example).
0228 * Add a SDC file to constrain the system (see **cl10lp_rtems.sdc** file in BSP
0229 for an example)
0230 * Compile the design.
0231 * In the Pin Planner, assign the location for each I/O pin (use the eval board
0232 reference design for the correct location and pin settings).
0233 * In the Assignment editor, add an "Input Delay From Pin" assignment
0234 (see **Assignment Editor.png** file in BSP).
0235 * Re-compile the design.
0236 * Use the **niosv-bsp-editor.exe** tool that comes with Quartus Prime to
0237 generate a software BSP using the compiled SOF file.
0238 * From the BSP generation process, the **system.h** and any C driver files can
0239 be used to make a RTEMS BSP and boot loader.
0240
0241
0242 This is the RTEMS build environment structure I used to create the RTEMS NIOSV
0243 BSP, boot loader, and application.
0244
0245 ```
0246 └── home directory // the home directory of the user
0247 └── sandbox2 // a sandbox directory for development
0248 ├── rtems // the rtems base directory for all things
0249 │ // RTEMS (source code and install directory)
0250 ├── 6 // the rtems install directory
0251 └── src // the rtems directory for gitlab repos
0252 ├── rsb // the rtems source builder repo directory
0253 ├── rtems // the rtems OS repo directory
0254 └── rtems-tools // the rtems tools repo directory
0255 ├── bin // the directory where the boot and app exe
0256 │ // outputs will be placed
0257 ├── gdb // the directory where the boot and app
0258 │ // debug ELF outputs will be placed
0259 ├── head_file // an application that will place the
0260 │ // <file_header_t> information in the binary
0261 │ // output
0262 ├── boot // the NIOSV bootloader directory for On-Chip
0263 │ // Memory (ROM)
0264 └── app // the user application directory (RTEMS
0265 // console app)
0266 ```
0267
0268 In your home directory, add a .gdbinit file to add the "sandbox/gdb" directory
0269 as a safe path for loading files with GDB.
0270 * add-auto-load-safe-path ~/sandbox/gdb
0271
0272 Please see the **boot.zip** file to see an example of a boot loader that can be
0273 used in the On-Chip ROM. This boot loader uses the RTEMS BSP header files that
0274 get installed after building RTEMS.
0275
0276 Please see the **app.zip** file that contains an application that is built using
0277 the RTEMS WAF system. This application is just a console app that can control
0278 some device driver features.
0279
0280 Please see the **head_file.zip** file that contains an application to add the
0281 <file_header_t> information to the binary image.
0282
0283 This is the RTEMS BSP build environment structure I used.
0284
0285 ```
0286 └── rtems src directory // the rtems top level directory
0287 ├── bsps // the rtems bsps directory
0288 ├── riscv // the rtems riscv bsp top level directory
0289 └── niosv // the rtems niosv bsp top level directory
0290 ├── cache // the niosv cache implementation
0291 ├── clock // the niosv clock device implementation
0292 ├── console // the niosv console implementation using
0293 │ // the JTAG UART
0294 ├── flash // the niosv EPCQ device implementation
0295 ├── include // the niosv base bsp include files
0296 ├── irq // the niosv IRQ implementation
0297 ├── niosvc10lp // the Intel Cyclone 10 LP evaluation board
0298 │ // bsp example
0299 ├── start // the niosv bsp start up implementation
0300 ├── README.md // this file
0301 └── supporting.zip // a zip file containing all the supporting
0302 // code and files referenced in
0303 // this README.md
0304 └── spec // the rtems spec directory
0305 └── build // the rtems spec build directory
0306 └── bsps // the rtems spec bsps directory
0307 └── riscv // the rtems spec riscv directory
0308 └── niosv // the rtems spec niosv directory containing
0309 // the configuration for all niosv bsps. Add
0310 // new BSP configurations here.
0311 ```
0312
0313 #### Phase 2
0314 Here is an outline of the second phase to generate a boot loader HEX file that
0315 can be loaded into the On-Chip ROM memory.
0316
0317 * Create the rtems src directory under ${HOME}/sandbox2
0318 (i.e. ${HOME}/sandbox2/rtems/src).
0319 * Follow the steps in the RTEMS documentation to download the RTEMS Resource
0320 Builder (RSB).
0321 * Use RSB to compile the riscv-rtems6 binaries.
0322 * Follow the steps in the RTEMS documentation to download the RTEMS RTOS.
0323 * Develop a BSP for the NIOSV by adding source files to the
0324 **bsps/riscv/niosv** and **spec/build/bsps/riscv/niosv** directories.
0325 * Add a **config.ini** to configure the NIOSV BSP.
0326 * Build the RTEMS NIOSV BSP.
0327 * Create the boot loader directory under ${HOME}/sandbox2
0328 (i.e. ${HOME}/sandbox2/boot).
0329 * Develop a boot loader that will fit in the On-Chip ROM memory that will load
0330 an application from the EPCQ device.
0331 * Build the boot loader HEX file output
0332 * Create the head_file directory under ${HOME}/sandbox2
0333 (i.e. ${HOME}/sandbox2/head_file).
0334 * Develop a Linux application that will put the **file_header_t** information
0335 in front of the binary code image.
0336 * Build the head_file Linux application.
0337 * Create the application directory under ${HOME}/sandbox2
0338 (i.e. ${HOME}/sandbox2/app).
0339 * Develop an application using the RTEMS WAF system that will fit in the EPCQ
0340 device (EPCQ size - maximum FPGA configuration size)
0341 and include the **file_header_t** information.
0342 * Build the application HEX file output.
0343
0344 Once the boot loader and application compiles succesfully, follow these steps to
0345 complete phase 2.
0346
0347 * Use the **elf2hex.exe** tool that comes with Quartus Prime to convert the
0348 boot loader output to a HEX file that can be loaded into the
0349 On-Chip ROM
0350 ```
0351 elf2hex.exe --width=32 --base=0x10010000 --end=0x10010fff
0352 --input=<full path to boot loader hex file>
0353 --output=<full path to Quartus Prime project hex file>
0354 ```
0355 * In Platform designer, intialize the On-Chip ROM memory with the generated HEX
0356 file from **elf2hex.exe**
0357 * Save the Platform Designer project and re-generated the HDL.
0358 * In Quartus Prime, re-compile the project.
0359 * You now have an SOF file which contains the boot loader.
0360
0361 #### Phase 3
0362
0363 Follow these steps to generate a JIC file that can be programmed on the FPGA.
0364
0365 * In Quartus Prime, select **File>Convert Programming Files** tool.
0366 * Change the Programming file type to .jic
0367 * Press the ellipse button next to the Configuration device and select the
0368 Cyclone 10 LP device family and the EPCQ128A device (verify on your own
0369 hardware).
0370 * Press OK.
0371 * Change the file name of the JIC file to **rtems_vm.jic**.
0372 * Select the **Flash Loader** input file and press the **Add Device** button.
0373 * Select **Cyclone 10 LP** and then **10CL025Y** (verify on your own hardware).
0374 * Press OK.
0375 * Select the **SOF Data** input file and press the **Add File** button.
0376 * Navigate to the generated SOF file from phase 2 and select it.
0377 * Press Open
0378 * Now, press the **Add Hex Data** button.
0379 * In the dialog, select **Relative addressing** and enter 0x100000 as the start
0380 address.
0381 * Press the ellipse button next to the Hex file box.
0382 * Navigate to the HEX file that was generated by the application build and
0383 select it.
0384 * Press OK.
0385 * Press the **Generate** button to produce the **rtems_vm.jic** file.
0386
0387 ### Programming the JIC file on the Cyclone 10 LP Evaluation Board
0388
0389 Make sure the Cyclone 10 LP Evaluation Board is powered up through the USB cable
0390 and connected to the computer running Quartus Prime. Also, make sure SW.4 is
0391 **On**. If the virtual JTAG chain is enabled, the programmer will be unable to
0392 program the EPCQ device.
0393
0394 * In Quartus Prime, select **Tools>Programmer**.
0395 * Select the currently loaded SOF file and press **Delete**.
0396 * Press **Add File**.
0397 * Navigate to the **rtems_vm.jic**, select it, and press **Open**.
0398 * select the Program/Configure checkbox on the JIC file.
0399 * Press **Start** to program the file onto the device.
0400
0401 Enjoy!
