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
62.. zephyr:board-supported-hw::
63
64BLE Software Link Layer experimental support
65==================================================
66This is an experimental feature supported on the Zephyr's RI5CY
67configuration, ``rv32m1_vega/openisa_rv32m1/ri5cy``. It  uses the Software Link Layer
68framework by Nordic Semi to enable the on-SoC radio and transceiver for
69implementing a software defined BLE controller. By using both the controller
70and the host stack available in Zephyr, the following BLE samples can be used
71with this board:
72
73- beacon
74- central
75- central_hr
76- eddystone
77- hci_uart
78- ibeacon
79- peripheral_csc (Cycling Speed Cadence)
80- peripheral_dis (Device Information Service)
81- peripheral_esp (Environmental Sensing Service)
82- peripheral_hr (Heart Rate)
83- peripheral_ht (Health Thermometer)
84- peripheral
85- scan_adv
86
87.. note::
88
89   BLE Software Link Layer limitations:
90
91   - no 512/256 Kbps PHY
92   - no TX power adjustment
93
94
95Connections and IOs
96===================
97
98RV32M1 SoC pins are brought out to Arduino-style expansion connectors.
99These are 2 pins wide each, adding an additional row of expansion pins
100per header compared to the standard Arduino layout.
101
102They are described in the tables in the following subsections. Since
103pins are usually grouped by logical function in rows on these headers,
104the odd- and even-numbered pins are listed in separate tables.  The
105"Port/bit" columns refer to the SoC PORT and GPIO peripheral
106naming scheme, e.g. "E/13" means PORTE/GPIOE pin 13.
107
108See the schematic and chip reference manual for details.
109(Documentation is available from the `OpenISA GitHub releases`_ page.)
110
111.. note::
112
113   Pins with peripheral functionality may also be muxed as GPIOs.
114
115**Top right expansion header (J1)**
116
117Odd/bottom pins:
118
119===   ========    =================
120Pin   Port/bit    Function
121===   ========    =================
1221     E/13        I2S_TX_BCLK
1233     E/14        I2S_TX_FS
1245     E/15        I2S_TXD
1257     E/19        I2S_MCLK
1269     E/16        I2S_RX_BCLK
12711    E/21        SOF_OUT
12813    E/17        I2S_RX_FS
12915    E/18        I2S_RXD
130===   ========    =================
131
132Even/top pins:
133
134===   ========   =================
135Pin   Port/bit   Function
136===   ========   =================
1372     A/25       UART1_RX
1384     A/26       UART1_TX
1396     A/27       GPIO
1408     B/13       PWM
14110    B/14       GPIO
14212    A/30       PWM
14314    A/31       PWM/CMP
14416    B/1        GPIO
145===   ========   =================
146
147**Top left expansion header (J2)**
148
149Odd/bottom pins:
150
151===   ========   =================
152Pin   Port/bit   Function
153===   ========   =================
1541     D/5        FLEXIO_D25
1553     D/4        FLEXIO_D24
1565     D/3        FLEXIO_D23
1577     D/2        FLEXIO_D22
1589     D/1        FLEXIO_D21
15911    D/0        FLEXIO_D20
16013    C/30       FLEXIO_D19
16115    C/29       FLEXIO_D18
16217    C/28       FLEXIO_D17
16319    B/29       FLEXIO_D16
164===   ========   =================
165
166Even/top pins:
167
168===   ========   =================
169Pin   Port/bit   Function
170===   ========   =================
1712     B/2        GPIO
1724     B/3        PWM
1736     B/6        SPI0_PCS2
1748     B/5        SPI0_SOUT
17510    B/7        SPI0_SIN
17612    B/4        SPI0_SCK
17714    -          GND
17816    -          AREF
17918    C/9        I2C0_SDA
18020    C/10       I2C0_SCL
181===   ========   =================
182
183**Bottom left expansion header (J3)**
184
185Note that the headers at the bottom of the board have odd-numbered
186pins on the top, unlike the headers at the top of the board.
187
188Odd/top pins:
189
190===   ========   ====================
191Pin   Port/bit   Function
192===   ========   ====================
1931     A/21       ARDUINO_EMVSIM_PD
1943     A/20       ARDUINO_EMVSIM_IO
1955     A/19       ARDUINO_EMVSIM_VCCEN
1967     A/18       ARDUINO_EMVSIM_RST
1979     A/17       ARDUINO_EMVSIM_CLK
19811    B/17       FLEXIO_D7
19913    B/16       FLEXIO_D6
20015    B/15       FLEXIO_D5
201===   ========   ====================
202
203Even/bottom pins: note that these are mostly power-related.
204
205===   ========   =================
206Pin   Port/bit   Function
207===   ========   =================
2082     -          SDA_GPIO0
2094     -          BRD_IO_PER
2106     -          RST_SDA
2118     -          BRD_IO_PER
21210    -          P5V_INPUT
21312    -          GND
21414    -          GND
21516    -          P5-9V VIN
216===   ========   =================
217
218**Bottom right expansion header (J4)**
219
220Note that the headers at the bottom of the board have odd-numbered
221pins on the top, unlike the headers at the top of the board.
222
223Odd/top pins:
224
225===   ========   ========================================
226Pin   Port/bit   Function
227===   ========   ========================================
2281     -          TAMPER2
2293     -          TAMPER1/RTC_CLKOUT
2305     -          TAMPER0/RTC_WAKEUP_b
2317     E/2        ADC0_SE19
2329     E/5        LPCMP1_IN2/LPCMP1_OUT
23311    -          DAC0_OUT/ADC0_SE16/LPCMP0_IN3/LPCMP1_IN3
234===   ========   ========================================
235
236Even/bottom pins:
237
238===   ========   ===========================================
239Pin   Port/bit   Function
240===   ========   ===========================================
2412     C/11       ADC0_SE6
2424     C/12       ADC0_SE7
2436     B/9        ADC0_SE3
2448     E/4        ADC0_SE21
24510    E/10       ADC0_SE19 (and E/10, I2C3_SDA via 0 Ohm DNP)
24612    E/11       ADC0_SE20 (and E/11, I2C3_SCL via 0 Ohm DNP)
247===   ========   ===========================================
248
249Additional Pins
250---------------
251
252For an up-to-date description of additional pins (such as buttons,
253LEDs, etc.) supported by Zephyr, see the board DTS files in the Zephyr
254source code, i.e.
255:zephyr_file:`boards/openisa/rv32m1_vega/rv32m1_vega_openisa_rv32m1_ri5cy.dts` for RI5CY and
256:zephyr_file:`boards/openisa/rv32m1_vega/rv32m1_vega_openisa_rv32m1_zero_riscy.dts` for
257ZERO-RISCY.
258
259See the schematic in the documentation available from the `OpenISA
260GitHub releases`_ page for additional details.
261
262System Clocks
263=============
264
265The RI5CY and ZERO-RISCY cores are configured to use the slow internal
266reference clock (SIRC) as the clock source for an LPTMR peripheral to manage
267the system timer, and the fast internal reference clock (FIRC) to generate a
26848MHz core clock.
269
270Serial Port
271===========
272
273The USB connector at the top left of the board (near the RESET button) is
274connected to an OpenSDA chip which provides a serial USB device. This is
275connected to the LPUART0 peripheral which the RI5CY and ZERO-RISCY cores use by
276default for console and logging.
277
278.. warning::
279
280   The OpenSDA chip cannot be used to flash or debug the RISC-V cores.
281
282   See the next section for flash and debug instructions for the
283   RISC-V cores using an external JTAG dongle.
284
285Programming and Debugging
286*************************
287
288.. _rv32m1-programming-hw:
289
290.. important::
291
292   To use this board, you will need:
293
294   - a `SEGGER J-Link`_ debug probe to debug the RISC-V cores
295   - a J-Link `9-Pin Cortex-M Adapter`_ board and ribbon cable
296   - the SEGGER `J-Link Software and Documentation Pack`_ software
297     installed
298
299   A JTAG dongle is not included with the board itself.
300
301Follow these steps to:
302
303#. Get a toolchain and OpenOCD
304#. Set up the board for booting RI5CY
305#. Compile a Zephyr application for the RI5CY core
306#. Flash the application to your board
307#. Debug the board using GDB
308
309.. _rv32m1-toolchain-openocd:
310
311Get the Toolchain and OpenOCD
312=============================
313
314Before programming and debugging, you first need to get a GNU
315toolchain and an OpenOCD build. There are vendor-specific versions of
316each for the RV32M1 SoC\ [#toolchain_openocd]_.
317
318Option 1 (Recommended): Prebuilt Toolchain and OpenOCD
319------------------------------------------------------
320
321The following prebuilt toolchains and OpenOCD archives are available
322on the `OpenISA GitHub releases`_ page:
323
324- :file:`Toolchain_Linux.tar.gz`
325- :file:`Toolchain_Mac.tar.gz`
326- :file:`Toolchain_Windows.zip`
327
328Download and extract the archive for your system, then extract the
329toolchain and OpenOCD archives inside.
330
331Linux::
332
333  tar xvzf Toolchain_Linux.tar.gz
334  tar xvzf openocd.tar.gz
335  tar xvzf riscv32-unknown-elf-gcc.tar.gz
336  mv openocd ~/rv32m1-openocd
337  mv riscv32-unknown-elf-gcc ~
338
339macOS (unfortunately, the OpenISA 1.0.0 release's Mac
340:file:`riscv32-unknown-elf-gcc.tar.gz` file doesn't expand into a
341:file:`riscv32-unknown-elf-gcc` directory, so it has to be created)::
342
343  tar xvzf Toolchain_Mac.tar.gz
344  tar xvzf openocd.tar.gz
345  mkdir riscv32-unknown-elf-gcc
346  mv riscv32-unknown-elf-gcc.tar.gz riscv32-unknown-elf-gcc
347  cd riscv32-unknown-elf-gcc/
348  tar xvzf riscv32-unknown-elf-gcc.tar.gz
349  cd ..
350  mv openocd ~/rv32m1-openocd
351  mv riscv32-unknown-elf-gcc ~
352
353Windows:
354
355#. Extract :file:`Toolchain_Windows.zip` in the file manager
356#. Extract the :file:`openocd.zip` and :file:`riscv32-unknown-elf-gcc.zip` files
357   in the resulting :file:`Toolchain_Windows` folder
358#. Move the extracted :file:`openocd` folder to :file:`C:\\rv32m1-openocd`
359#. Move the extracted :file:`riscv32-unknown-elf-gcc` folder to
360   :file:`C:\\riscv32-unknown-elf-gcc`
361
362For simplicity, this guide assumes:
363
364- You put the extracted toolchain at :file:`~/riscv32-unknown-elf-gcc`
365  on macOS or Linux, and :file:`C:\\riscv32-unknown-elf-gcc` on
366  Windows.
367- You put the extracted OpenOCD binary at :file:`~/rv32m1-openocd` on
368  macOS or Linux, and the OpenOCD folder into :file:`C:\\rv32m1-openocd`
369  on Windows.
370
371You can put them elsewhere, but be aware:
372
373- If you put the toolchain somewhere else, you will need to change
374  the ``CROSS_COMPILE`` value described below accordingly.
375- If you put OpenOCD somewhere else, you will need to change the
376  OpenOCD path in the flashing and debugging instructions below.
377- Don't use installation directories with spaces anywhere in the path;
378  this won't work with Zephyr's build system.
379
380Option 2: Building Toolchain and OpenOCD From Source
381----------------------------------------------------
382
383See :ref:`rv32m1_vega_toolchain_build`.
384
385.. _rv32m1-vega-jtag:
386
387JTAG Setup
388==========
389
390This section describes how to connect to your board via the J-Link
391debugger and adapter board. See the :ref:`above information
392<rv32m1-programming-hw>` for details on required hardware.
393
394#. Connect the J-Link debugger through the adapter board to the
395   VEGAboard as shown in the figure.
396
397   .. figure:: rv32m1_vega_jtag.jpg
398      :align: center
399      :alt: RV32M1-VEGA
400
401      VEGAboard connected properly to J-Link debugger.
402      VEGAboard connector J55 should be used. Pin 1 is on the bottom left.
403
404#. Power the VEGAboard via USB. The OpenSDA connector at the top left
405   is recommended for UART access.
406
407#. Make sure your J-Link is connected to your computer via USB.
408
409One-Time Board Setup For Booting RI5CY or ZERO-RISCY
410====================================================
411
412Next, you'll need to make sure your board boots the RI5CY or ZERO-RISCY core.
413**You only need to do this once.**
414
415The RV32M1 SoC on the VEGAboard has multiple cores, any of which can
416be selected as the boot core. Before flashing and debugging, you'll
417first make sure you're booting the right core.
418
419**Linux and macOS**:
420
421.. note::
422
423   Linux users: to run these commands as a normal user, you will need
424   to install the `60-openocd.rules`_ udev rules file (usually by
425   placing it in :file:`/etc/udev/rules.d`, then unplugging and
426   plugging the J-Link in again via USB).
427
428.. note::
429
430   These Zephyr-specific instructions differ slightly from the
431   equivalent SDK ones. The Zephyr OpenOCD configuration file does not
432   run ``init``, so you have to do it yourself as explained below.
433
4341. In one terminal, use OpenOCD to connect to the board::
435
436     ~/rv32m1-openocd -f boards/openisa/rv32m1_vega/support/openocd_rv32m1_vega_ri5cy.cfg
437
438   The output should look like this:
439
440   .. code-block:: console
441
442      $ ~/rv32m1-openocd -f boards/openisa/rv32m1_vega/support/openocd_rv32m1_vega_ri5cy.cfg
443      Open On-Chip Debugger 0.10.0+dev-00431-ge1ec3c7d (2018-10-31-07:29)
444      [...]
445      Info : Listening on port 3333 for gdb connections
446      Info : Listening on port 6666 for tcl connections
447      Info : Listening on port 4444 for telnet connections
448
4492. In another terminal, connect to OpenOCD's telnet server and execute
450   the ``init`` and ``ri5cy_boot`` commands **with the reset button on
451   the board (at top left) pressed down**::
452
453     $ telnet localhost 4444
454     Trying 127.0.0.1...
455     Connected to localhost.
456     Escape character is '^]'.
457     Open On-Chip Debugger
458     > init
459     > ri5cy_boot
460
461  To boot the ZERO-RISCY core instead, replace ``ri5cy_boot`` above with
462  ``zero_boot``.
463
464  The reset button is at top left, as shown in the following figure.
465
466  .. figure:: ri5cy_boot.jpg
467     :align: center
468     :alt: Reset button is pressed
469
470  Now quit the telnet session in this terminal and exit OpenOCD in the
471  other terminal.
472
4733. Unplug your J-Link and VEGAboard, and plug them back in.
474
475**Windows**:
476
477In one cmd.exe prompt in the Zephyr directory::
478
479 C:\rv32m1-openocd\bin\openocd.exe rv32m1-openocd -f boards\openisa\rv32m1_vega\support\openocd_rv32m1_vega_ri5cy.cfg
480
481In a telnet program of your choice:
482
483#. Connect to localhost port 4444 using telnet.
484#. Run ``init`` and ``ri5cy_boot`` as shown above, with RESET held down.
485#. Quit the OpenOCD and telnet sessions.
486#. Unplug your J-Link and VEGAboard, and plug them back in.
487
488  To boot the ZERO-RISCY core instead, replace ``ri5cy_boot`` above with
489  ``zero_boot``.
490
491Compiling a Program
492===================
493
494.. important::
495
496   These instructions assume you've set up a development system,
497   cloned the Zephyr repository, and installed Python dependencies as
498   described in the :ref:`getting_started`.
499
500   You should also have already downloaded and installed the toolchain
501   and OpenOCD as described above in :ref:`rv32m1-toolchain-openocd`.
502
503The first step is to set up environment variables to point at your
504toolchain and OpenOCD::
505
506  # Linux or macOS
507  export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
508  export CROSS_COMPILE=~/riscv32-unknown-elf-gcc/bin/riscv32-unknown-elf-
509
510  # Windows
511  set ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
512  set CROSS_COMPILE=C:\riscv32-unknown-elf-gcc\bin\riscv32-unknown-elf-
513
514.. note::
515
516   The above only sets these variables for your current shell session.
517   You need to make sure this happens every time you use this board.
518
519Now let's compile the :zephyr:code-sample:`hello_world` application. (You can try
520others as well; see :zephyr:code-sample-category:`samples` for more.)
521
522.. We can't use zephyr-app-commands to provide build instructions
523   due to the below mentioned linker issue.
524
525Due to a toolchain `linker issue`_, you need to add an option setting
526``CMAKE_REQUIRED_FLAGS`` when running CMake to generate a build system
527(see :ref:`application` for information about Zephyr's build system).
528
529Linux and macOS (run this in a terminal from the Zephyr directory)::
530
531  # Set up environment and create build directory:
532  source zephyr-env.sh
533
534.. zephyr-app-commands::
535   :zephyr-app: samples/hello_world
536   :tool: cmake
537   :cd-into:
538   :board: rv32m1_vega/openisa_rv32m1/ri5cy
539   :gen-args: -DCMAKE_REQUIRED_FLAGS=-Wl,-dT=/dev/null
540   :goals: build
541
542Windows (run this in a ``cmd`` prompt, from the Zephyr directory)::
543
544  # Set up environment and create build directory
545  zephyr-env.cmd
546  cd samples\hello_world
547  mkdir build & cd build
548
549  # Use CMake to generate a Ninja-based build system:
550  type NUL > empty.ld
551  cmake -GNinja -DBOARD=rv32m1_vega/openisa_rv32m1/ri5cy -DCMAKE_REQUIRED_FLAGS=-Wl,-dT=%cd%\empty.ld ..
552
553  # Build the sample
554  ninja
555
556Flashing
557========
558
559.. note::
560
561   Make sure you've done the :ref:`JTAG setup <rv32m1-vega-jtag>`, and
562   that the VEGAboard's top left USB connector is connected to your
563   computer too (for UART access).
564
565.. note::
566
567   Linux users: to run these commands as a normal user, you will need
568   to install the `60-openocd.rules`_ udev rules file (usually by
569   placing it in :file:`/etc/udev/rules.d`, then unplugging and
570   plugging the J-Link in again via USB).
571
572Make sure you've followed the above instructions to set up your board
573and build a program first.
574
575Since you need to use a special OpenOCD, the easiest way to flash is
576by using :ref:`west flash <west-build-flash-debug>` instead of ``ninja
577flash`` like you might see with other Zephyr documentation.
578
579Run these commands from the build directory where you ran ``ninja`` in
580the above section.
581
582Linux and macOS::
583
584  # Don't use "~/rv32m1-openocd". It won't work.
585  west flash --openocd=$HOME/rv32m1-openocd
586
587Windows::
588
589  west flash --openocd=C:\rv32m1-openocd\bin\openocd.exe
590
591If you have problems:
592
593- Make sure you don't have another ``openocd`` process running in the
594  background.
595- Unplug the boards and plug them back in.
596- On Linux, make sure udev rules are installed, as described above.
597
598As an alternative, for manual steps to run OpenOCD and GDB to flash,
599see the `SDK README`_.
600
601Debugging
602=========
603
604.. note::
605
606   Make sure you've done the :ref:`JTAG setup <rv32m1-vega-jtag>`, and
607   that the VEGAboard's top left USB connector is connected to your
608   computer too (for UART access).
609
610.. note::
611
612   Linux users: to run these commands as a normal user, you will need
613   to install the `60-openocd.rules`_ udev rules file (usually by
614   placing it in :file:`/etc/udev/rules.d`, then unplugging and
615   plugging the J-Link in again via USB).
616
617Make sure you've followed the above instructions to set up your board
618and build a program first.
619
620To debug with gdb::
621
622  # Linux, macOS
623  west debug --openocd=$HOME/rv32m1-openocd
624
625  # Windows
626  west debug --openocd=C:\rv32m1-openocd\bin\openocd.exe
627
628Then, from the ``(gdb)`` prompt, follow these steps to halt the core,
629load the binary (:file:`zephyr.elf`), and re-sync with the OpenOCD
630server::
631
632  (gdb) monitor init
633  (gdb) monitor reset halt
634  (gdb) load
635  (gdb) monitor gdb_sync
636  (gdb) stepi
637
638You can then set breakpoints and debug using normal GDB commands.
639
640.. note::
641
642   GDB can get out of sync with the target if you execute commands
643   that reset it. To reset RI5CY and get GDB back in sync with it
644   without reloading the binary::
645
646     (gdb) monitor reset halt
647     (gdb) monitor gdb_sync
648     (gdb) stepi
649
650If you have problems:
651
652- Make sure you don't have another ``openocd`` process running in the
653  background.
654- Unplug the boards and plug them back in.
655- On Linux, make sure udev rules are installed, as described above.
656
657References
658**********
659
660- OpenISA developer portal: http://open-isa.org
661- `OpenISA GitHub releases`_: includes toolchain and OpenOCD
662  prebuilts, as well as documentation, such as the SoC datasheet and
663  reference manual, board schematic and user guides, etc.
664- Base toolchain: `pulp-riscv-gnu-toolchain`_; extra toolchain patches:
665  `rv32m1_gnu_toolchain_patch`_ (only needed if building from source).
666- OpenOCD repository: `rv32m1-openocd`_ (only needed if building from
667  source).
668- Vendor SDK: `rv32m1_sdk_riscv`_. Contains HALs, non-Zephyr sample
669  applications, and information on using the board with Eclipse which
670  may be interesting when combined with the Eclipse Debugging
671  information in the :ref:`application`.
672
673.. _rv32m1_vega_toolchain_build:
674
675Appendix: Building Toolchain and OpenOCD from Source
676****************************************************
677
678.. note::
679
680   Toolchain and OpenOCD build instructions are provided for Linux and
681   macOS only.
682
683   Instructions for building OpenOCD have only been verified on Linux.
684
685.. warning::
686
687   Don't use installation directories with spaces anywhere in
688   the path; this won't work with Zephyr's build system.
689
690Ubuntu 18.04 users need to install these additional dependencies::
691
692  sudo apt-get install autoconf automake autotools-dev curl libmpc-dev \
693                       libmpfr-dev libgmp-dev gawk build-essential bison \
694                       flex texinfo gperf libtool patchutils bc zlib1g-dev \
695                       libusb-1.0-0-dev libudev1 libudev-dev g++
696
697Users of other Linux distributions need to install the above packages
698with their system package manager.
699
700macOS users need to install dependencies with Homebrew::
701
702  brew install gawk gnu-sed gmp mpfr libmpc isl zlib
703
704The build toolchain is based on the `pulp-riscv-gnu-toolchain`_, with
705some additional patches hosted in a separate repository,
706`rv32m1_gnu_toolchain_patch`_. To build the toolchain, follow the
707instructions in the ``rv32m1_gnu_toolchain_patch`` repository's
708`readme.md`_ file to apply the patches, then run::
709
710  ./configure --prefix=<toolchain-installation-dir> --with-arch=rv32imc --with-cmodel=medlow --enable-multilib
711  make
712
713If you set ``<toolchain-installation-dir>`` to
714:file:`~/riscv32-unknown-elf-gcc`, you can use the above instructions
715for setting ``CROSS_COMPILE`` when building Zephyr
716applications. If you set it to something else, you will need to update
717your ``CROSS_COMPILE`` setting accordingly.
718
719.. note::
720
721   Strangely, there is no separate ``make install`` step for the
722   toolchain. That is, the ``make`` invocation both builds and
723   installs the toolchain. This means ``make`` has to be run as root
724   if you want to set ``--prefix`` to a system directory such as
725   :file:`/usr/local` or :file:`/opt` on Linux.
726
727To build OpenOCD, clone the `rv32m1-openocd`_ repository, then run
728these from the repository top level::
729
730  ./bootstrap
731  ./configure --prefix=<openocd-installation-dir>
732  make
733  make install
734
735If ``<openocd-installation-dir>`` is :file:`~/rv32m1-openocd`, you
736should set your OpenOCD path to :file:`~/rv32m1-openocd/bin/openocd`
737in the above flash and debug instructions.
738
739.. _RI5CY:
740   https://github.com/pulp-platform/riscv
741.. _ZERO-RISCY:
742   https://github.com/pulp-platform/zero-riscy
743.. _PULP platform:
744   http://iis-projects.ee.ethz.ch/index.php/PULP
745
746.. _pulp-riscv-gnu-toolchain:
747   https://github.com/pulp-platform/pulp-riscv-gnu-toolchain
748.. _rv32m1_gnu_toolchain_patch:
749   https://github.com/open-isa-rv32m1/rv32m1_gnu_toolchain_patch
750.. _rv32m1-openocd:
751   https://github.com/open-isa-rv32m1/rv32m1-openocd
752.. _readme.md:
753   https://github.com/open-isa-rv32m1/rv32m1_gnu_toolchain_patch/blob/master/readme.md
754.. _OpenISA GitHub releases:
755   https://github.com/open-isa-org/open-isa.org/releases
756.. _rv32m1_sdk_riscv:
757   https://github.com/open-isa-rv32m1/rv32m1_sdk_riscv
758.. _linker issue:
759   https://github.com/pulp-platform/pulpino/issues/240
760.. _60-openocd.rules:
761   https://github.com/open-isa-rv32m1/rv32m1-openocd/blob/master/contrib/60-openocd.rules
762.. _SEGGER J-Link:
763   https://www.segger.com/products/debug-probes/j-link/
764.. _9-Pin Cortex-M Adapter:
765   https://www.segger.com/products/debug-probes/j-link/accessories/adapters/9-pin-cortex-m-adapter/
766.. _J-Link Software and Documentation Pack:
767   https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack
768.. _SDK README:
769   https://github.com/open-isa-rv32m1/rv32m1_sdk_riscv/blob/master/readme.md
770
771.. rubric:: Footnotes
772
773.. [#toolchain_openocd]
774
775   For Linux users, the RISC-V toolchain in the :ref:`Zephyr SDK
776   <toolchain_zephyr_sdk>` may work, but it hasn't been thoroughly tested with this
777   SoC, and will not allow use of any available RISC-V ISA extensions.
778
779   Support for the RV32M1 SoC is not currently available in the OpenOCD
780   upstream repository or the OpenOCD build in the Zephyr SDK.
781