blob: f96710075f56464ab6f761b3f6018be0bb4d75d1 [file] [log] [blame]
.. _altera_max10:
Altera MAX10
The Zephyr kernel is supported on the Altera MAX10 Rev C development kit, using
the Nios II Gen 2 soft CPU.
.. figure:: img/altera_max10.jpg
:width: 442px
:align: center
:alt: Altera's MAX* 10
Altera's MAX* 10 (Credit: Altera)
DIP Switch settings
There are two sets of switches on the back of the board. Of particular
importance is SW2:
* Switch 2 (CONFIG_SEL) should be in the OFF (up) position so that the first
boot image is CFM0
* Switch 3 (VTAP_BYPASS) needs to be in the ON (down) position or the flashing
scripts won't work
* Switch 4 (HSMC_BYPASSN) should be OFF (up)
.. image:: img/Altera_MAX10_switches.jpg
:width: 442px
:align: center
:alt: Altera's MAX* 10 Switches
Other switches are user switches, their position is application-specific.
Necessary Software
You will need the Altera Quartus SDK in order to work with this device. The
`Altera Lite Distribution`_ of Quartus may be obtained without
For your convenience using the SDK tools (such as ``nios2-configure-sof``),
you should put the binaries provided by the SDK
in your path. Below is an example, adjust ALTERA_BASE to where you installed the
.. code-block:: console
export ALTERA_BASE=/opt/altera_lite/16.0
export PATH=$PATH:$ALTERA_BASE/quartus/bin:$ALTERA_BASE/nios2eds/bin
You may need to adjust your udev rules so that you can talk to the USB Blaster
II peripheral, which is the built-in JTAG interface for this device.
The following works for Fedora 23:
.. code-block:: console
# For Altera USB-Blaster permissions.
RUN+="/bin/chmod 0666 %c"
RUN+="/bin/chmod 0666 %c"
You can test connectivity with the SDK jtagconfig tool, you should see something
.. code-block:: console
$ jtagconfig
1) USB-BlasterII [1-1.2]
031050DD 10M50DA(.|ES)/10M50DC
020D10DD VTAP10
Reference CPU
A reference CPU design of a Nios II/f core is included in the Zephyr tree
in the :zephyr_file:`soc/nios2/nios2f-zephyr/cpu` directory.
Flash this CPU using the ``nios2-configure-sof`` SDK tool with the FPGA
configuration file
.. code-block:: console
$ nios2-configure-sof ghrd_10m50da.sof
This CPU is a Nios II/F core with a 16550 UART, JTAG UART, and the Avalon Timer.
For any Nios II SOC definition, you can find out more details about the CPU
configuration by inspecting system.h in the SOC's include directory.
Console Output
16550 UART
By default, the kernel is configured to send console output to the 16550 UART.
You can monitor this on your workstation by connecting to the top right mini USB
port on the board (it will show up in /dev as a ttyUSB node), and then running
minicom with flow control disabled, 115200-8N1 settings.
You can also have it send its console output to the JTAG UART.
Enable ``jtag_uart`` node in :file:`altera_max10.dts` or overlay file:
.. code-block:: devicetree
&jtag_uart {
status = "okay";
current-speed = <115200>;
To view these messages on your local workstation, run the terminal application
in the SDK:
.. code-block:: console
$ nios2-terminal
Programming and Debugging
Flashing Kernel into UFM
The usual ``flash`` target will work with the ``altera_max10`` board
configuration. Here is an example for the :ref:`hello_world`
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: altera_max10
:goals: flash
Refer to :ref:`build_an_application` and :ref:`application_run` for
more details.
This provisions the Zephyr kernel and the CPU configuration onto the board,
using the scripts/support/ script. After it completes the kernel
will immediately boot.
Flashing Kernel directly into RAM over JTAG
The SDK included the nios2-download tool which will let you flash a kernel
directly into RAM and then boot it from the __start symbol.
In order for this to work, your entire kernel must be located in RAM. Make sure
the following config options are disabled:
.. code-block:: console
Then, after building your kernel, push it into device's RAM by running
this from the build directory:
.. code-block:: console
$ nios2-download --go zephyr/zephyr.elf
If you have a console session running (either minicom or nios2-terminal) you
should see the application's output. There are additional arguments you can pass
to nios2-download so that it spawns a GDB server that you can connect to,
although it's typically simpler to just use nios2-gdb-server as described below.
The Altera SDK includes a GDB server which can be used to debug a MAX10 board.
You can either debug a running image that was flashed onto the device in User
Flash Memory (UFM), or load an image over the JTAG using GDB.
Debugging With UFM Flashed Image
You can debug an application in the usual way. Here is an example.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: altera_max10
:goals: debug
You will see output similar to the following:
.. code-block:: console
Nios II GDB server running on port 3335
Ignoring --stop option because --tcpport also specified
GNU gdb (GDB)
Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=x86_64-pokysdk-linux --target=nios2-zephyr-elf".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
Find the GDB manual and other documentation resources online at:
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from /projects/zephyr/samples/hello_world/build/zephyr/zephyr.elf...done.
Remote debugging using :3335
Using cable "USB-BlasterII [3-1.3]", device 1, instance 0x00
Resetting and pausing target processor: OK
Listening on port 3335 for connection from GDB: accepted
isr_tables_syms () at /projects/zephyr/arch/common/isr_tables.c:63
63 GEN_ABSOLUTE_SYM(__ISR_LIST_SIZEOF, sizeof(struct _isr_list));
(gdb) b _PrepC
Breakpoint 1 at 0xdf0: file /projects/zephyr/arch/nios2/core/prep_c.c, line 36.
(gdb) b z_cstart
Breakpoint 2 at 0x1254: file /projects/zephyr/kernel/init.c, line 348.
(gdb) c
Breakpoint 2, _Cstart () at /projects/zephyr/kernel/init.c:348
348 {
To start debugging manually:
.. code-block:: console
nios2-gdb-server --tcpport 1234 --stop --reset-target
And then connect with GDB from the build directory:
.. code-block:: console
nios2-poky-elf-gdb zephyr/zephyr.elf -ex "target remote :1234"
Debugging With JTAG Flashed Image
In order for this to work, execute-in-place must be disabled, since the GDB
'load' command can only put text and data in RAM. Ensure this is in your
.. code-block:: console
It is OK for this procedure to leave the reset vector enabled, unlike
nios2-download (which errors out if it finds sections outside of SRAM) it will
be ignored.
In a terminal, launch the nios2 GDB server. It doesn't matter what kernel (if
any) is on the device, but you should have at least flashed a CPU using
nios2-configure-sof. You can leave this process running.
.. code-block:: console
$ nios2-gdb-server --tcpport 1234 --tcppersist --init-cache --reset-target
Build your Zephyr kernel, and load it into a GDB built for Nios II (included in
the Zephyr SDK) from the build directory:
.. code-block:: console
$ nios2-poky-elf-gdb zephyr/zephyr.elf
Then connect to the GDB server:
.. code-block:: console
(gdb) target remote :1234
And then load the kernel image over the wire. The CPU will not start from the
reset vector, instead it will boot from the __start symbol:
.. code-block:: console
(gdb) load
Loading section reset, size 0xc lma 0x0
Loading section exceptions, size 0x1b0 lma 0x400020
Loading section text, size 0x8df0 lma 0x4001d0
Loading section devconfig, size 0x30 lma 0x408fc0
Loading section rodata, size 0x3f4 lma 0x408ff0
Loading section datas, size 0x888 lma 0x4093e4
Loading section initlevel, size 0x30 lma 0x409c6c
Loading section _k_task_list, size 0x58 lma 0x409c9c
Loading section _k_task_ptr, size 0x8 lma 0x409cf4
Loading section _k_event_list, size 0x10 lma 0x409cfc
Start address 0x408f54, load size 40184
Transfer rate: 417 KB/sec, 368 bytes/write.
After this is done you may set breakpoints and continue execution. If you ever want to reset the CPU, issue the 'load' command again.
* `CPU Documentation <>`_
* `Nios II Processor Booting Methods in MAX 10 FPGA Devices <>`_
* `Embedded Peripherals IP User Guide <>`_
* `MAX 10 FPGA Configuration User Guide <>`_
* `MAX 10 FPGA Development Kit User Guide <>`_
* `Nios II Command-Line Tools <>`_
* `Quartus II Scripting Reference Manual <>`_
.. _Altera Lite Distribution: