1.. highlight:: sh 2 3.. zephyr:board:: rv32m1_vega 4 5Overview 6******** 7 8The VEGAboard contains the RV32M1 SoC, featuring two RISC-V CPUs, 9on-die XIP flash, and a full complement of peripherals, including a 102.4 GHz multi-protocol radio. It also has built-in sensors and 11Arduino-style expansion connectors. 12 13The two RISC-V CPUs are named RI5CY and ZERO-RISCY, and are 14respectively based on the `PULP platform`_ designs by the same names: 15`RI5CY`_ and `ZERO-RISCY`_. RI5CY is the "main" core; it has more 16flash and RAM as well as a more powerful CPU design. ZERO-RISCY is a 17"secondary" core. The main ZERO-RISCY use-case is as a wireless 18coprocessor for applications running on RI5CY. The two cores can 19communicate via shared memory and messaging peripherals. 20 21Currently, Zephyr supports RI5CY with the ``rv32m1_vega/openisa_rv32m1/ri5cy`` board 22configuration name, and ZERO_RISCY with the ``rv32m1_vega/openisa_rv32m1/zero_riscy`` board 23configuration name. 24 25Hardware 26******** 27 28The VEGAboard includes the following features. 29 30RV32M1 multi-core SoC: 31 32- 1 MiB flash and 192 KiB SRAM (RI5CY core) 33- 256 KiB flash and 128 KiB SRAM (ZERO-RISCY core) 34- Low power modes 35- DMA support 36- Watchdog, CRC, cryptographic acceleration, ADC, DAC, comparator, 37 timers, PWM, RTC, I2C, UART, SPI, external memory, I2S, smart 38 card, USB full-speed, uSDHC, and 2.4 GHz multiprotocol radio 39 peripherals 40 41On-board sensors and peripherals: 42 43- 32 Mbit SPI flash 44- 6-axis accelerometer, magnetometer, and temperature sensor (FXOS8700) 45- Ambient light sensor 46- RGB LED 47- microSD card slot 48- Antenna interface 49 50Additional features: 51 52- Form-factor compatible with Arduino Uno Rev 3 expansion connector 53 layout (not all Arduino shields may be pin-compatible) 54- UART via USB using separate OpenSDA chip 55- RISC-V flash and debug using external JTAG dongle (not included) via 56 2x5 5 mil pitch connector (commonly called the "ARM 10-pin JTAG" 57 connector) 58 59Supported Features 60================== 61 62Zephyr's RI5CY configuration, ``rv32m1_vega/openisa_rv32m1/ri5cy``, currently supports 63the following hardware features: 64 65+-----------+------------+-------------------------------------+ 66| Interface | Controller | Driver/Component | 67+===========+============+=====================================+ 68| EVENT | on-chip | event unit interrupt controller | 69+-----------+------------+-------------------------------------+ 70| INTMUX | on-chip | level 2 interrupt controller | 71+-----------+------------+-------------------------------------+ 72| LPTMR | on-chip | lptmr-based system timer | 73+-----------+------------+-------------------------------------+ 74| PINMUX | on-chip | pinmux | 75+-----------+------------+-------------------------------------+ 76| GPIO | on-chip | gpio | 77+-----------+------------+-------------------------------------+ 78| UART | on-chip | serial | 79+-----------+------------+-------------------------------------+ 80| I2C(M) | on-chip | i2c | 81+-----------+------------+-------------------------------------+ 82| SPI | on-chip | spi | 83+-----------+------------+-------------------------------------+ 84| TPM | on-chip | pwm | 85+-----------+------------+-------------------------------------+ 86| SENSOR | off-chip | fxos8700 polling; | 87| | | fxos8700 trigger; | 88+-----------+------------+-------------------------------------+ 89 90Zephyr's ZERO-RISCY configuration, ``rv32m1_vega/openisa_rv32m1/zero_riscy``, currently 91supports the following hardware features: 92 93+-----------+------------+-------------------------------------+ 94| Interface | Controller | Driver/Component | 95+===========+============+=====================================+ 96| EVENT | on-chip | event unit interrupt controller | 97+-----------+------------+-------------------------------------+ 98| INTMUX | on-chip | level 2 interrupt controller | 99+-----------+------------+-------------------------------------+ 100| LPTMR | on-chip | lptmr-based system timer | 101+-----------+------------+-------------------------------------+ 102| PINMUX | on-chip | pinmux | 103+-----------+------------+-------------------------------------+ 104| GPIO | on-chip | gpio | 105+-----------+------------+-------------------------------------+ 106| UART | on-chip | serial | 107+-----------+------------+-------------------------------------+ 108| I2C(M) | on-chip | i2c | 109+-----------+------------+-------------------------------------+ 110| TPM | on-chip | pwm | 111+-----------+------------+-------------------------------------+ 112| SENSOR | off-chip | fxos8700 polling; | 113| | | fxos8700 trigger; | 114+-----------+------------+-------------------------------------+ 115 116BLE Software Link Layer experimental support 117================================================== 118This is an experimental feature supported on the Zephyr's RI5CY 119configuration, ``rv32m1_vega/openisa_rv32m1/ri5cy``. It uses the Software Link Layer 120framework by Nordic Semi to enable the on-SoC radio and transceiver for 121implementing a software defined BLE controller. By using both the controller 122and the host stack available in Zephyr, the following BLE samples can be used 123with this board: 124 125- beacon 126- central 127- central_hr 128- eddystone 129- hci_uart 130- ibeacon 131- peripheral_csc (Cycling Speed Cadence) 132- peripheral_dis (Device Information Service) 133- peripheral_esp (Environmental Sensing Service) 134- peripheral_hr (Heart Rate) 135- peripheral_ht (Health Thermometer) 136- peripheral 137- scan_adv 138 139.. note:: 140 141 BLE Software Link Layer limitations: 142 143 - no 512/256 Kbps PHY 144 - no TX power adjustment 145 146 147Connections and IOs 148=================== 149 150RV32M1 SoC pins are brought out to Arduino-style expansion connectors. 151These are 2 pins wide each, adding an additional row of expansion pins 152per header compared to the standard Arduino layout. 153 154They are described in the tables in the following subsections. Since 155pins are usually grouped by logical function in rows on these headers, 156the odd- and even-numbered pins are listed in separate tables. The 157"Port/bit" columns refer to the SoC PORT and GPIO peripheral 158naming scheme, e.g. "E/13" means PORTE/GPIOE pin 13. 159 160See the schematic and chip reference manual for details. 161(Documentation is available from the `OpenISA GitHub releases`_ page.) 162 163.. note:: 164 165 Pins with peripheral functionality may also be muxed as GPIOs. 166 167**Top right expansion header (J1)** 168 169Odd/bottom pins: 170 171=== ======== ================= 172Pin Port/bit Function 173=== ======== ================= 1741 E/13 I2S_TX_BCLK 1753 E/14 I2S_TX_FS 1765 E/15 I2S_TXD 1777 E/19 I2S_MCLK 1789 E/16 I2S_RX_BCLK 17911 E/21 SOF_OUT 18013 E/17 I2S_RX_FS 18115 E/18 I2S_RXD 182=== ======== ================= 183 184Even/top pins: 185 186=== ======== ================= 187Pin Port/bit Function 188=== ======== ================= 1892 A/25 UART1_RX 1904 A/26 UART1_TX 1916 A/27 GPIO 1928 B/13 PWM 19310 B/14 GPIO 19412 A/30 PWM 19514 A/31 PWM/CMP 19616 B/1 GPIO 197=== ======== ================= 198 199**Top left expansion header (J2)** 200 201Odd/bottom pins: 202 203=== ======== ================= 204Pin Port/bit Function 205=== ======== ================= 2061 D/5 FLEXIO_D25 2073 D/4 FLEXIO_D24 2085 D/3 FLEXIO_D23 2097 D/2 FLEXIO_D22 2109 D/1 FLEXIO_D21 21111 D/0 FLEXIO_D20 21213 C/30 FLEXIO_D19 21315 C/29 FLEXIO_D18 21417 C/28 FLEXIO_D17 21519 B/29 FLEXIO_D16 216=== ======== ================= 217 218Even/top pins: 219 220=== ======== ================= 221Pin Port/bit Function 222=== ======== ================= 2232 B/2 GPIO 2244 B/3 PWM 2256 B/6 SPI0_PCS2 2268 B/5 SPI0_SOUT 22710 B/7 SPI0_SIN 22812 B/4 SPI0_SCK 22914 - GND 23016 - AREF 23118 C/9 I2C0_SDA 23220 C/10 I2C0_SCL 233=== ======== ================= 234 235**Bottom left expansion header (J3)** 236 237Note that the headers at the bottom of the board have odd-numbered 238pins on the top, unlike the headers at the top of the board. 239 240Odd/top pins: 241 242=== ======== ==================== 243Pin Port/bit Function 244=== ======== ==================== 2451 A/21 ARDUINO_EMVSIM_PD 2463 A/20 ARDUINO_EMVSIM_IO 2475 A/19 ARDUINO_EMVSIM_VCCEN 2487 A/18 ARDUINO_EMVSIM_RST 2499 A/17 ARDUINO_EMVSIM_CLK 25011 B/17 FLEXIO_D7 25113 B/16 FLEXIO_D6 25215 B/15 FLEXIO_D5 253=== ======== ==================== 254 255Even/bottom pins: note that these are mostly power-related. 256 257=== ======== ================= 258Pin Port/bit Function 259=== ======== ================= 2602 - SDA_GPIO0 2614 - BRD_IO_PER 2626 - RST_SDA 2638 - BRD_IO_PER 26410 - P5V_INPUT 26512 - GND 26614 - GND 26716 - P5-9V VIN 268=== ======== ================= 269 270**Bottom right expansion header (J4)** 271 272Note that the headers at the bottom of the board have odd-numbered 273pins on the top, unlike the headers at the top of the board. 274 275Odd/top pins: 276 277=== ======== ======================================== 278Pin Port/bit Function 279=== ======== ======================================== 2801 - TAMPER2 2813 - TAMPER1/RTC_CLKOUT 2825 - TAMPER0/RTC_WAKEUP_b 2837 E/2 ADC0_SE19 2849 E/5 LPCMP1_IN2/LPCMP1_OUT 28511 - DAC0_OUT/ADC0_SE16/LPCMP0_IN3/LPCMP1_IN3 286=== ======== ======================================== 287 288Even/bottom pins: 289 290=== ======== =========================================== 291Pin Port/bit Function 292=== ======== =========================================== 2932 C/11 ADC0_SE6 2944 C/12 ADC0_SE7 2956 B/9 ADC0_SE3 2968 E/4 ADC0_SE21 29710 E/10 ADC0_SE19 (and E/10, I2C3_SDA via 0 Ohm DNP) 29812 E/11 ADC0_SE20 (and E/11, I2C3_SCL via 0 Ohm DNP) 299=== ======== =========================================== 300 301Additional Pins 302--------------- 303 304For an up-to-date description of additional pins (such as buttons, 305LEDs, etc.) supported by Zephyr, see the board DTS files in the Zephyr 306source code, i.e. 307:zephyr_file:`boards/openisa/rv32m1_vega/rv32m1_vega_openisa_rv32m1_ri5cy.dts` for RI5CY and 308:zephyr_file:`boards/openisa/rv32m1_vega/rv32m1_vega_openisa_rv32m1_zero_riscy.dts` for 309ZERO-RISCY. 310 311See the schematic in the documentation available from the `OpenISA 312GitHub releases`_ page for additional details. 313 314System Clocks 315============= 316 317The RI5CY and ZERO-RISCY cores are configured to use the slow internal 318reference clock (SIRC) as the clock source for an LPTMR peripheral to manage 319the system timer, and the fast internal reference clock (FIRC) to generate a 32048MHz core clock. 321 322Serial Port 323=========== 324 325The USB connector at the top left of the board (near the RESET button) is 326connected to an OpenSDA chip which provides a serial USB device. This is 327connected to the LPUART0 peripheral which the RI5CY and ZERO-RISCY cores use by 328default for console and logging. 329 330.. warning:: 331 332 The OpenSDA chip cannot be used to flash or debug the RISC-V cores. 333 334 See the next section for flash and debug instructions for the 335 RISC-V cores using an external JTAG dongle. 336 337Programming and Debugging 338************************* 339 340.. _rv32m1-programming-hw: 341 342.. important:: 343 344 To use this board, you will need: 345 346 - a `SEGGER J-Link`_ debug probe to debug the RISC-V cores 347 - a J-Link `9-Pin Cortex-M Adapter`_ board and ribbon cable 348 - the SEGGER `J-Link Software and Documentation Pack`_ software 349 installed 350 351 A JTAG dongle is not included with the board itself. 352 353Follow these steps to: 354 355#. Get a toolchain and OpenOCD 356#. Set up the board for booting RI5CY 357#. Compile a Zephyr application for the RI5CY core 358#. Flash the application to your board 359#. Debug the board using GDB 360 361.. _rv32m1-toolchain-openocd: 362 363Get the Toolchain and OpenOCD 364============================= 365 366Before programming and debugging, you first need to get a GNU 367toolchain and an OpenOCD build. There are vendor-specific versions of 368each for the RV32M1 SoC\ [#toolchain_openocd]_. 369 370Option 1 (Recommended): Prebuilt Toolchain and OpenOCD 371------------------------------------------------------ 372 373The following prebuilt toolchains and OpenOCD archives are available 374on the `OpenISA GitHub releases`_ page: 375 376- :file:`Toolchain_Linux.tar.gz` 377- :file:`Toolchain_Mac.tar.gz` 378- :file:`Toolchain_Windows.zip` 379 380Download and extract the archive for your system, then extract the 381toolchain and OpenOCD archives inside. 382 383Linux:: 384 385 tar xvzf Toolchain_Linux.tar.gz 386 tar xvzf openocd.tar.gz 387 tar xvzf riscv32-unknown-elf-gcc.tar.gz 388 mv openocd ~/rv32m1-openocd 389 mv riscv32-unknown-elf-gcc ~ 390 391macOS (unfortunately, the OpenISA 1.0.0 release's Mac 392:file:`riscv32-unknown-elf-gcc.tar.gz` file doesn't expand into a 393:file:`riscv32-unknown-elf-gcc` directory, so it has to be created):: 394 395 tar xvzf Toolchain_Mac.tar.gz 396 tar xvzf openocd.tar.gz 397 mkdir riscv32-unknown-elf-gcc 398 mv riscv32-unknown-elf-gcc.tar.gz riscv32-unknown-elf-gcc 399 cd riscv32-unknown-elf-gcc/ 400 tar xvzf riscv32-unknown-elf-gcc.tar.gz 401 cd .. 402 mv openocd ~/rv32m1-openocd 403 mv riscv32-unknown-elf-gcc ~ 404 405Windows: 406 407#. Extract :file:`Toolchain_Windows.zip` in the file manager 408#. Extract the :file:`openocd.zip` and :file:`riscv32-unknown-elf-gcc.zip` files 409 in the resulting :file:`Toolchain_Windows` folder 410#. Move the extracted :file:`openocd` folder to :file:`C:\\rv32m1-openocd` 411#. Move the extracted :file:`riscv32-unknown-elf-gcc` folder to 412 :file:`C:\\riscv32-unknown-elf-gcc` 413 414For simplicity, this guide assumes: 415 416- You put the extracted toolchain at :file:`~/riscv32-unknown-elf-gcc` 417 on macOS or Linux, and :file:`C:\\riscv32-unknown-elf-gcc` on 418 Windows. 419- You put the extracted OpenOCD binary at :file:`~/rv32m1-openocd` on 420 macOS or Linux, and the OpenOCD folder into :file:`C:\\rv32m1-openocd` 421 on Windows. 422 423You can put them elsewhere, but be aware: 424 425- If you put the toolchain somewhere else, you will need to change 426 the ``CROSS_COMPILE`` value described below accordingly. 427- If you put OpenOCD somewhere else, you will need to change the 428 OpenOCD path in the flashing and debugging instructions below. 429- Don't use installation directories with spaces anywhere in the path; 430 this won't work with Zephyr's build system. 431 432Option 2: Building Toolchain and OpenOCD From Source 433---------------------------------------------------- 434 435See :ref:`rv32m1_vega_toolchain_build`. 436 437.. _rv32m1-vega-jtag: 438 439JTAG Setup 440========== 441 442This section describes how to connect to your board via the J-Link 443debugger and adapter board. See the :ref:`above information 444<rv32m1-programming-hw>` for details on required hardware. 445 446#. Connect the J-Link debugger through the adapter board to the 447 VEGAboard as shown in the figure. 448 449 .. figure:: rv32m1_vega_jtag.jpg 450 :align: center 451 :alt: RV32M1-VEGA 452 453 VEGAboard connected properly to J-Link debugger. 454 VEGAboard connector J55 should be used. Pin 1 is on the bottom left. 455 456#. Power the VEGAboard via USB. The OpenSDA connector at the top left 457 is recommended for UART access. 458 459#. Make sure your J-Link is connected to your computer via USB. 460 461One-Time Board Setup For Booting RI5CY or ZERO-RISCY 462==================================================== 463 464Next, you'll need to make sure your board boots the RI5CY or ZERO-RISCY core. 465**You only need to do this once.** 466 467The RV32M1 SoC on the VEGAboard has multiple cores, any of which can 468be selected as the boot core. Before flashing and debugging, you'll 469first make sure you're booting the right core. 470 471**Linux and macOS**: 472 473.. note:: 474 475 Linux users: to run these commands as a normal user, you will need 476 to install the `60-openocd.rules`_ udev rules file (usually by 477 placing it in :file:`/etc/udev/rules.d`, then unplugging and 478 plugging the J-Link in again via USB). 479 480.. note:: 481 482 These Zephyr-specific instructions differ slightly from the 483 equivalent SDK ones. The Zephyr OpenOCD configuration file does not 484 run ``init``, so you have to do it yourself as explained below. 485 4861. In one terminal, use OpenOCD to connect to the board:: 487 488 ~/rv32m1-openocd -f boards/openisa/rv32m1_vega/support/openocd_rv32m1_vega_ri5cy.cfg 489 490 The output should look like this: 491 492 .. code-block:: console 493 494 $ ~/rv32m1-openocd -f boards/openisa/rv32m1_vega/support/openocd_rv32m1_vega_ri5cy.cfg 495 Open On-Chip Debugger 0.10.0+dev-00431-ge1ec3c7d (2018-10-31-07:29) 496 [...] 497 Info : Listening on port 3333 for gdb connections 498 Info : Listening on port 6666 for tcl connections 499 Info : Listening on port 4444 for telnet connections 500 5012. In another terminal, connect to OpenOCD's telnet server and execute 502 the ``init`` and ``ri5cy_boot`` commands **with the reset button on 503 the board (at top left) pressed down**:: 504 505 $ telnet localhost 4444 506 Trying 127.0.0.1... 507 Connected to localhost. 508 Escape character is '^]'. 509 Open On-Chip Debugger 510 > init 511 > ri5cy_boot 512 513 To boot the ZERO-RISCY core instead, replace ``ri5cy_boot`` above with 514 ``zero_boot``. 515 516 The reset button is at top left, as shown in the following figure. 517 518 .. figure:: ri5cy_boot.jpg 519 :align: center 520 :alt: Reset button is pressed 521 522 Now quit the telnet session in this terminal and exit OpenOCD in the 523 other terminal. 524 5253. Unplug your J-Link and VEGAboard, and plug them back in. 526 527**Windows**: 528 529In one cmd.exe prompt in the Zephyr directory:: 530 531 C:\rv32m1-openocd\bin\openocd.exe rv32m1-openocd -f boards\openisa\rv32m1_vega\support\openocd_rv32m1_vega_ri5cy.cfg 532 533In a telnet program of your choice: 534 535#. Connect to localhost port 4444 using telnet. 536#. Run ``init`` and ``ri5cy_boot`` as shown above, with RESET held down. 537#. Quit the OpenOCD and telnet sessions. 538#. Unplug your J-Link and VEGAboard, and plug them back in. 539 540 To boot the ZERO-RISCY core instead, replace ``ri5cy_boot`` above with 541 ``zero_boot``. 542 543Compiling a Program 544=================== 545 546.. important:: 547 548 These instructions assume you've set up a development system, 549 cloned the Zephyr repository, and installed Python dependencies as 550 described in the :ref:`getting_started`. 551 552 You should also have already downloaded and installed the toolchain 553 and OpenOCD as described above in :ref:`rv32m1-toolchain-openocd`. 554 555The first step is to set up environment variables to point at your 556toolchain and OpenOCD:: 557 558 # Linux or macOS 559 export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile 560 export CROSS_COMPILE=~/riscv32-unknown-elf-gcc/bin/riscv32-unknown-elf- 561 562 # Windows 563 set ZEPHYR_TOOLCHAIN_VARIANT=cross-compile 564 set CROSS_COMPILE=C:\riscv32-unknown-elf-gcc\bin\riscv32-unknown-elf- 565 566.. note:: 567 568 The above only sets these variables for your current shell session. 569 You need to make sure this happens every time you use this board. 570 571Now let's compile the :zephyr:code-sample:`hello_world` application. (You can try 572others as well; see :zephyr:code-sample-category:`samples` for more.) 573 574.. We can't use zephyr-app-commands to provide build instructions 575 due to the below mentioned linker issue. 576 577Due to a toolchain `linker issue`_, you need to add an option setting 578``CMAKE_REQUIRED_FLAGS`` when running CMake to generate a build system 579(see :ref:`application` for information about Zephyr's build system). 580 581Linux and macOS (run this in a terminal from the Zephyr directory):: 582 583 # Set up environment and create build directory: 584 source zephyr-env.sh 585 586.. zephyr-app-commands:: 587 :zephyr-app: samples/hello_world 588 :tool: cmake 589 :cd-into: 590 :board: rv32m1_vega/openisa_rv32m1/ri5cy 591 :gen-args: -DCMAKE_REQUIRED_FLAGS=-Wl,-dT=/dev/null 592 :goals: build 593 594Windows (run this in a ``cmd`` prompt, from the Zephyr directory):: 595 596 # Set up environment and create build directory 597 zephyr-env.cmd 598 cd samples\hello_world 599 mkdir build & cd build 600 601 # Use CMake to generate a Ninja-based build system: 602 type NUL > empty.ld 603 cmake -GNinja -DBOARD=rv32m1_vega/openisa_rv32m1/ri5cy -DCMAKE_REQUIRED_FLAGS=-Wl,-dT=%cd%\empty.ld .. 604 605 # Build the sample 606 ninja 607 608Flashing 609======== 610 611.. note:: 612 613 Make sure you've done the :ref:`JTAG setup <rv32m1-vega-jtag>`, and 614 that the VEGAboard's top left USB connector is connected to your 615 computer too (for UART access). 616 617.. note:: 618 619 Linux users: to run these commands as a normal user, you will need 620 to install the `60-openocd.rules`_ udev rules file (usually by 621 placing it in :file:`/etc/udev/rules.d`, then unplugging and 622 plugging the J-Link in again via USB). 623 624Make sure you've followed the above instructions to set up your board 625and build a program first. 626 627Since you need to use a special OpenOCD, the easiest way to flash is 628by using :ref:`west flash <west-build-flash-debug>` instead of ``ninja 629flash`` like you might see with other Zephyr documentation. 630 631Run these commands from the build directory where you ran ``ninja`` in 632the above section. 633 634Linux and macOS:: 635 636 # Don't use "~/rv32m1-openocd". It won't work. 637 west flash --openocd=$HOME/rv32m1-openocd 638 639Windows:: 640 641 west flash --openocd=C:\rv32m1-openocd\bin\openocd.exe 642 643If you have problems: 644 645- Make sure you don't have another ``openocd`` process running in the 646 background. 647- Unplug the boards and plug them back in. 648- On Linux, make sure udev rules are installed, as described above. 649 650As an alternative, for manual steps to run OpenOCD and GDB to flash, 651see the `SDK README`_. 652 653Debugging 654========= 655 656.. note:: 657 658 Make sure you've done the :ref:`JTAG setup <rv32m1-vega-jtag>`, and 659 that the VEGAboard's top left USB connector is connected to your 660 computer too (for UART access). 661 662.. note:: 663 664 Linux users: to run these commands as a normal user, you will need 665 to install the `60-openocd.rules`_ udev rules file (usually by 666 placing it in :file:`/etc/udev/rules.d`, then unplugging and 667 plugging the J-Link in again via USB). 668 669Make sure you've followed the above instructions to set up your board 670and build a program first. 671 672To debug with gdb:: 673 674 # Linux, macOS 675 west debug --openocd=$HOME/rv32m1-openocd 676 677 # Windows 678 west debug --openocd=C:\rv32m1-openocd\bin\openocd.exe 679 680Then, from the ``(gdb)`` prompt, follow these steps to halt the core, 681load the binary (:file:`zephyr.elf`), and re-sync with the OpenOCD 682server:: 683 684 (gdb) monitor init 685 (gdb) monitor reset halt 686 (gdb) load 687 (gdb) monitor gdb_sync 688 (gdb) stepi 689 690You can then set breakpoints and debug using normal GDB commands. 691 692.. note:: 693 694 GDB can get out of sync with the target if you execute commands 695 that reset it. To reset RI5CY and get GDB back in sync with it 696 without reloading the binary:: 697 698 (gdb) monitor reset halt 699 (gdb) monitor gdb_sync 700 (gdb) stepi 701 702If you have problems: 703 704- Make sure you don't have another ``openocd`` process running in the 705 background. 706- Unplug the boards and plug them back in. 707- On Linux, make sure udev rules are installed, as described above. 708 709References 710********** 711 712- OpenISA developer portal: http://open-isa.org 713- `OpenISA GitHub releases`_: includes toolchain and OpenOCD 714 prebuilts, as well as documentation, such as the SoC datasheet and 715 reference manual, board schematic and user guides, etc. 716- Base toolchain: `pulp-riscv-gnu-toolchain`_; extra toolchain patches: 717 `rv32m1_gnu_toolchain_patch`_ (only needed if building from source). 718- OpenOCD repository: `rv32m1-openocd`_ (only needed if building from 719 source). 720- Vendor SDK: `rv32m1_sdk_riscv`_. Contains HALs, non-Zephyr sample 721 applications, and information on using the board with Eclipse which 722 may be interesting when combined with the Eclipse Debugging 723 information in the :ref:`application`. 724 725.. _rv32m1_vega_toolchain_build: 726 727Appendix: Building Toolchain and OpenOCD from Source 728**************************************************** 729 730.. note:: 731 732 Toolchain and OpenOCD build instructions are provided for Linux and 733 macOS only. 734 735 Instructions for building OpenOCD have only been verified on Linux. 736 737.. warning:: 738 739 Don't use installation directories with spaces anywhere in 740 the path; this won't work with Zephyr's build system. 741 742Ubuntu 18.04 users need to install these additional dependencies:: 743 744 sudo apt-get install autoconf automake autotools-dev curl libmpc-dev \ 745 libmpfr-dev libgmp-dev gawk build-essential bison \ 746 flex texinfo gperf libtool patchutils bc zlib1g-dev \ 747 libusb-1.0-0-dev libudev1 libudev-dev g++ 748 749Users of other Linux distributions need to install the above packages 750with their system package manager. 751 752macOS users need to install dependencies with Homebrew:: 753 754 brew install gawk gnu-sed gmp mpfr libmpc isl zlib 755 756The build toolchain is based on the `pulp-riscv-gnu-toolchain`_, with 757some additional patches hosted in a separate repository, 758`rv32m1_gnu_toolchain_patch`_. To build the toolchain, follow the 759instructions in the ``rv32m1_gnu_toolchain_patch`` repository's 760`readme.md`_ file to apply the patches, then run:: 761 762 ./configure --prefix=<toolchain-installation-dir> --with-arch=rv32imc --with-cmodel=medlow --enable-multilib 763 make 764 765If you set ``<toolchain-installation-dir>`` to 766:file:`~/riscv32-unknown-elf-gcc`, you can use the above instructions 767for setting ``CROSS_COMPILE`` when building Zephyr 768applications. If you set it to something else, you will need to update 769your ``CROSS_COMPILE`` setting accordingly. 770 771.. note:: 772 773 Strangely, there is no separate ``make install`` step for the 774 toolchain. That is, the ``make`` invocation both builds and 775 installs the toolchain. This means ``make`` has to be run as root 776 if you want to set ``--prefix`` to a system directory such as 777 :file:`/usr/local` or :file:`/opt` on Linux. 778 779To build OpenOCD, clone the `rv32m1-openocd`_ repository, then run 780these from the repository top level:: 781 782 ./bootstrap 783 ./configure --prefix=<openocd-installation-dir> 784 make 785 make install 786 787If ``<openocd-installation-dir>`` is :file:`~/rv32m1-openocd`, you 788should set your OpenOCD path to :file:`~/rv32m1-openocd/bin/openocd` 789in the above flash and debug instructions. 790 791.. _RI5CY: 792 https://github.com/pulp-platform/riscv 793.. _ZERO-RISCY: 794 https://github.com/pulp-platform/zero-riscy 795.. _PULP platform: 796 http://iis-projects.ee.ethz.ch/index.php/PULP 797 798.. _pulp-riscv-gnu-toolchain: 799 https://github.com/pulp-platform/pulp-riscv-gnu-toolchain 800.. _rv32m1_gnu_toolchain_patch: 801 https://github.com/open-isa-rv32m1/rv32m1_gnu_toolchain_patch 802.. _rv32m1-openocd: 803 https://github.com/open-isa-rv32m1/rv32m1-openocd 804.. _readme.md: 805 https://github.com/open-isa-rv32m1/rv32m1_gnu_toolchain_patch/blob/master/readme.md 806.. _OpenISA GitHub releases: 807 https://github.com/open-isa-org/open-isa.org/releases 808.. _rv32m1_sdk_riscv: 809 https://github.com/open-isa-rv32m1/rv32m1_sdk_riscv 810.. _linker issue: 811 https://github.com/pulp-platform/pulpino/issues/240 812.. _60-openocd.rules: 813 https://github.com/open-isa-rv32m1/rv32m1-openocd/blob/master/contrib/60-openocd.rules 814.. _SEGGER J-Link: 815 https://www.segger.com/products/debug-probes/j-link/ 816.. _9-Pin Cortex-M Adapter: 817 https://www.segger.com/products/debug-probes/j-link/accessories/adapters/9-pin-cortex-m-adapter/ 818.. _J-Link Software and Documentation Pack: 819 https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack 820.. _SDK README: 821 https://github.com/open-isa-rv32m1/rv32m1_sdk_riscv/blob/master/readme.md 822 823.. rubric:: Footnotes 824 825.. [#toolchain_openocd] 826 827 For Linux users, the RISC-V toolchain in the :ref:`Zephyr SDK 828 <toolchain_zephyr_sdk>` may work, but it hasn't been thoroughly tested with this 829 SoC, and will not allow use of any available RISC-V ISA extensions. 830 831 Support for the RV32M1 SoC is not currently available in the OpenOCD 832 upstream repository or the OpenOCD build in the Zephyr SDK. 833
