1.. _altera_max10: 2 3Altera MAX10 4############ 5 6Overview 7******** 8 9 10The Zephyr kernel is supported on the Altera MAX10 Rev C development kit, using 11the Nios II Gen 2 soft CPU. 12 13.. figure:: img/altera_max10.jpg 14 :align: center 15 :alt: Altera's MAX* 10 16 17 Altera's MAX* 10 (Credit: Altera) 18 19Hardware 20******** 21 22DIP Switch settings 23=================== 24 25There are two sets of switches on the back of the board. Of particular 26importance is SW2: 27 28* Switch 2 (CONFIG_SEL) should be in the OFF (up) position so that the first 29 boot image is CFM0 30* Switch 3 (VTAP_BYPASS) needs to be in the ON (down) position or the flashing 31 scripts won't work 32* Switch 4 (HSMC_BYPASSN) should be OFF (up) 33 34.. image:: img/Altera_MAX10_switches.jpg 35 :align: center 36 :alt: Altera's MAX* 10 Switches 37 38Other switches are user switches, their position is application-specific. 39 40Necessary Software 41================== 42 43You will need the Altera Quartus SDK in order to work with this device. The 44`Altera Lite Distribution`_ of Quartus may be obtained without 45charge. 46 47For your convenience using the SDK tools (such as ``nios2-configure-sof``), 48you should put the binaries provided by the SDK 49in your path. Below is an example, adjust ALTERA_BASE to where you installed the 50SDK: 51 52.. code-block:: console 53 54 export ALTERA_BASE=/opt/altera_lite/16.0 55 export PATH=$PATH:$ALTERA_BASE/quartus/bin:$ALTERA_BASE/nios2eds/bin 56 57You may need to adjust your udev rules so that you can talk to the USB Blaster 58II peripheral, which is the built-in JTAG interface for this device. 59 60The following works for Fedora 23: 61 62.. code-block:: console 63 64 # For Altera USB-Blaster permissions. 65 SUBSYSTEM=="usb",\ 66 ENV{DEVTYPE}=="usb_device",\ 67 ATTR{idVendor}=="09fb",\ 68 ATTR{idProduct}=="6010",\ 69 MODE="0666",\ 70 NAME="bus/usb/$env{BUSNUM}/$env{DEVNUM}",\ 71 RUN+="/bin/chmod 0666 %c" 72 SUBSYSTEM=="usb",\ 73 ENV{DEVTYPE}=="usb_device",\ 74 ATTR{idVendor}=="09fb",\ 75 ATTR{idProduct}=="6810",\ 76 MODE="0666",\ 77 NAME="bus/usb/$env{BUSNUM}/$env{DEVNUM}",\ 78 RUN+="/bin/chmod 0666 %c" 79 80You can test connectivity with the SDK jtagconfig tool, you should see something 81like: 82 83.. code-block:: console 84 85 $ jtagconfig 86 1) USB-BlasterII [1-1.2] 87 031050DD 10M50DA(.|ES)/10M50DC 88 020D10DD VTAP10 89 90 91Reference CPU 92============= 93 94A reference CPU design of a Nios II/f core is included in the Zephyr tree 95in the :zephyr_file:`soc/nios2/nios2f-zephyr/cpu` directory. 96 97Flash this CPU using the ``nios2-configure-sof`` SDK tool with the FPGA 98configuration file 99:zephyr_file:`soc/nios2/nios2f-zephyr/cpu/ghrd_10m50da.sof`: 100 101.. code-block:: console 102 103 $ nios2-configure-sof ghrd_10m50da.sof 104 105This CPU is a Nios II/F core with a 16550 UART, JTAG UART, and the Avalon Timer. 106For any Nios II SOC definition, you can find out more details about the CPU 107configuration by inspecting system.h in the SOC's include directory. 108 109Console Output 110============== 111 11216550 UART 113---------- 114 115By default, the kernel is configured to send console output to the 16550 UART. 116You can monitor this on your workstation by connecting to the top right mini USB 117port on the board (it will show up in /dev as a ttyUSB node), and then running 118minicom with flow control disabled, 115200-8N1 settings. 119 120JTAG UART 121--------- 122 123You can also have it send its console output to the JTAG UART. 124Enable ``jtag_uart`` node in :file:`altera_max10.dts` or overlay file: 125 126.. code-block:: devicetree 127 128 &jtag_uart { 129 status = "okay"; 130 current-speed = <115200>; 131 }; 132 133To view these messages on your local workstation, run the terminal application 134in the SDK: 135 136.. code-block:: console 137 138 $ nios2-terminal 139 140Programming and Debugging 141************************* 142 143Flashing 144======== 145 146Flashing Kernel into UFM 147------------------------ 148 149The usual ``flash`` target will work with the ``altera_max10`` board 150configuration. Here is an example for the :ref:`hello_world` 151application. 152 153.. zephyr-app-commands:: 154 :zephyr-app: samples/hello_world 155 :board: altera_max10 156 :goals: flash 157 158Refer to :ref:`build_an_application` and :ref:`application_run` for 159more details. 160 161This provisions the Zephyr kernel and the CPU configuration onto the board, 162using the scripts/support/quartus-flash.py script. After it completes the kernel 163will immediately boot. 164 165 166Flashing Kernel directly into RAM over JTAG 167------------------------------------------- 168 169The SDK included the nios2-download tool which will let you flash a kernel 170directly into RAM and then boot it from the __start symbol. 171 172In order for this to work, your entire kernel must be located in RAM. Make sure 173the following config options are disabled: 174 175.. code-block:: console 176 177 CONFIG_XIP=n 178 CONFIG_INCLUDE_RESET_VECTOR=n 179 180Then, after building your kernel, push it into device's RAM by running 181this from the build directory: 182 183.. code-block:: console 184 185 $ nios2-download --go zephyr/zephyr.elf 186 187If you have a console session running (either minicom or nios2-terminal) you 188should see the application's output. There are additional arguments you can pass 189to nios2-download so that it spawns a GDB server that you can connect to, 190although it's typically simpler to just use nios2-gdb-server as described below. 191 192Debugging 193========= 194 195The Altera SDK includes a GDB server which can be used to debug a MAX10 board. 196You can either debug a running image that was flashed onto the device in User 197Flash Memory (UFM), or load an image over the JTAG using GDB. 198 199Debugging With UFM Flashed Image 200-------------------------------- 201 202You can debug an application in the usual way. Here is an example. 203 204.. zephyr-app-commands:: 205 :zephyr-app: samples/hello_world 206 :board: altera_max10 207 :goals: debug 208 209You will see output similar to the following: 210 211.. code-block:: console 212 213 Nios II GDB server running on port 3335 214 Ignoring --stop option because --tcpport also specified 215 GNU gdb (GDB) 7.11.0.20160511-git 216 Copyright (C) 2016 Free Software Foundation, Inc. 217 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> 218 This is free software: you are free to change and redistribute it. 219 There is NO WARRANTY, to the extent permitted by law. Type "show copying" 220 and "show warranty" for details. 221 This GDB was configured as "--host=x86_64-pokysdk-linux --target=nios2-zephyr-elf". 222 Type "show configuration" for configuration details. 223 For bug reporting instructions, please see: 224 <http://www.gnu.org/software/gdb/bugs/>. 225 Find the GDB manual and other documentation resources online at: 226 <http://www.gnu.org/software/gdb/documentation/>. 227 For help, type "help". 228 Type "apropos word" to search for commands related to "word"... 229 Reading symbols from /projects/zephyr/samples/hello_world/build/zephyr/zephyr.elf...done. 230 Remote debugging using :3335 231 Using cable "USB-BlasterII [3-1.3]", device 1, instance 0x00 232 Resetting and pausing target processor: OK 233 Listening on port 3335 for connection from GDB: accepted 234 isr_tables_syms () at /projects/zephyr/arch/common/isr_tables.c:63 235 63 GEN_ABSOLUTE_SYM(__ISR_LIST_SIZEOF, sizeof(struct _isr_list)); 236 (gdb) b _PrepC 237 Breakpoint 1 at 0xdf0: file /projects/zephyr/arch/nios2/core/prep_c.c, line 36. 238 (gdb) b z_cstart 239 Breakpoint 2 at 0x1254: file /projects/zephyr/kernel/init.c, line 348. 240 (gdb) c 241 Continuing. 242 243 Breakpoint 2, _Cstart () at /projects/zephyr/kernel/init.c:348 244 348 { 245 (gdb) 246 247To start debugging manually: 248 249 250.. code-block:: console 251 252 nios2-gdb-server --tcpport 1234 --stop --reset-target 253 254And then connect with GDB from the build directory: 255 256 257.. code-block:: console 258 259 nios2-poky-elf-gdb zephyr/zephyr.elf -ex "target remote :1234" 260 261Debugging With JTAG Flashed Image 262--------------------------------- 263 264In order for this to work, execute-in-place must be disabled, since the GDB 265'load' command can only put text and data in RAM. Ensure this is in your 266configuration: 267 268.. code-block:: console 269 270 CONFIG_XIP=n 271 272It is OK for this procedure to leave the reset vector enabled, unlike 273nios2-download (which errors out if it finds sections outside of SRAM) it will 274be ignored. 275 276In a terminal, launch the nios2 GDB server. It doesn't matter what kernel (if 277any) is on the device, but you should have at least flashed a CPU using 278nios2-configure-sof. You can leave this process running. 279 280.. code-block:: console 281 282 $ nios2-gdb-server --tcpport 1234 --tcppersist --init-cache --reset-target 283 284Build your Zephyr kernel, and load it into a GDB built for Nios II (included in 285the Zephyr SDK) from the build directory: 286 287.. code-block:: console 288 289 $ nios2-poky-elf-gdb zephyr/zephyr.elf 290 291Then connect to the GDB server: 292 293.. code-block:: console 294 295 (gdb) target remote :1234 296 297And then load the kernel image over the wire. The CPU will not start from the 298reset vector, instead it will boot from the __start symbol: 299 300 301.. code-block:: console 302 303 (gdb) load 304 Loading section reset, size 0xc lma 0x0 305 Loading section exceptions, size 0x1b0 lma 0x400020 306 Loading section text, size 0x8df0 lma 0x4001d0 307 Loading section devconfig, size 0x30 lma 0x408fc0 308 Loading section rodata, size 0x3f4 lma 0x408ff0 309 Loading section datas, size 0x888 lma 0x4093e4 310 Loading section initlevel, size 0x30 lma 0x409c6c 311 Loading section _k_task_list, size 0x58 lma 0x409c9c 312 Loading section _k_task_ptr, size 0x8 lma 0x409cf4 313 Loading section _k_event_list, size 0x10 lma 0x409cfc 314 Start address 0x408f54, load size 40184 315 Transfer rate: 417 KB/sec, 368 bytes/write. 316 After this is done you may set breakpoints and continue execution. If you ever want to reset the CPU, issue the 'load' command again. 317 318 319 320References 321********** 322 323* `CPU Documentation <https://www.altera.com/en_US/pdfs/literature/hb/nios2/n2cpu-nii5v1gen2.pdf>`_ 324* `Nios II Processor Booting Methods in MAX 10 FPGA Devices <https://www.altera.com/en_US/pdfs/literature/an/an730.pdf>`_ 325* `Embedded Peripherals IP User Guide <https://www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_embedded_ip.pdf>`_ 326* `MAX 10 FPGA Configuration User Guide <https://www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/hb/max-10/ug_m10_config.pdf>`_ 327* `MAX 10 FPGA Development Kit User Guide <https://www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug-max10m50-fpga-dev-kit.pdf>`_ 328* `Nios II Command-Line Tools <https://www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/hb/nios2/edh_ed51004.pdf>`_ 329* `Quartus II Scripting Reference Manual <https://www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/manual/tclscriptrefmnl.pdf>`_ 330 331 332.. _Altera Lite Distribution: https://www.intel.com/content/www/us/en/collections/products/fpga/software/downloads.html 333
