Command Line Tools

Introduction

As an alternative to NBEclipse, you can use the command line tools to build your NetBurner projects. In fact, all the example programs are built and tested internally with command line tools. You will find a makefile in each example folder, so any of the examples can be used as a demonstration of how to use command line tools. Windows, Mac and Linux are supported. The command line tools can also be used to invoke the NetBurner tools from the development environment of your choice.

Command Line Summary

Command	Description
make	Build a project using the makefile in the project directory
make -j	Make using multiple cores to speed up the process
make load	Build project and load into device
make -j load	Build project with multiple cores and load into device
make clean	Delete a project's libraries and object files

Note

The command you will use 99% of the time is: "make -j load". If you have build errors that are difficult to track down, doing a single core "make" will cause the build to stop at the first error.

Command Line Environment Variables

There are a number of environment variables that can be set to effect the command line build when you do a make. For example, you can specify the target device IP address in which to download the application with a make -j load.

On the command line, typing "set <variable>" will display the current value. Typing "set <variable>=<value>" will set the environment variable. For example, "set DEVIP" will display the current target IP address. Typing "set DEVIP=10.1.1.1" will set DEVIP to the specified IP address.

Variable	Description
DEVIP	Causes a make with the "load" parameter to download to the specified IP address
PLATFORM	Specifies the NetBurner platform to build for
NNDK_ROOT	Specifies the location of your NetBurner development tools installation
PATH	Specifies folders to search for system binaries, like make and other compiler tools

For example, to reference a standard NetBurner tools installation on Windows (also see "\nburn\setenv.bat" for an example):

set NNDK_ROOT=c:/nburn
set PLATFORM=MODM7AE70
set DEVIP=192.168.1.66
set PATH=C:/nburn/gcc/bin;C:/nburn/pcbin;C:/nburn/gcc/msys/1.0/bin;%path%

Create a New Project From an Example

The easiest way to create a new project is to copy an existing one and modify it:

• Open a command prompt at the location where you keep your projects, such as \NetBurner\Projects
• Create a folder for your project, lets use HelloWorld as an example
• Move to the HelloWorld folder
• Copy an example, such as "\nburn\examples\web\SimpleHtml"
• At this point your project structure will look like:
  • \NetBurner\Projects
    • HelloWorld
      • html
        • index.html
      • src
        • main.cpp
      • makefile
• Run "make -j" to build the project. The "-j" options uses multiple cores for the build
• When the build completes, an obj folder is created with the object files and .bin application image file: \NetBurner\Projects\HelloWorld\obj\release\SimpleHtml.bin (and also .s19 for SREC platforms).
  • \NetBurner\Projects
    • HelloWorld
      • html
        • index.html
      • obj
        • release
          • SimpleHtml.bin
      • src
        • main.cpp
      • makefile
• To load the application into your device, use the "make -j load" command.

There are many files and folders under the obj folder, including the compiled libraries and object files.

Note

Each project has its own build of the libraries and system files. That way if any changes need to be made (which is rare), it can be done on a per-project basis. This will be discussed in the overload section of this document.

We named our project HelloWorld, but are running SimpleHtml at this point. To customize the project:

• Edit the makefile to change the application image file name to HelloWorld
• Edit main.cpp to change the application name to HelloWorld
• Run "make -j load" to build and load the application into the device

Edit the makefile

The example makefile is shown below:

NAME = SimpleHtml
 
CPP_SRC = src/main.cpp 
 
CREATEDTARGS += src/htmldata.cpp
CPP_SRC += src/htmldata.cpp
src/htmldata.cpp : $(wildcard html/*.*)
    comphtml html -osrc/htmldata.cpp
 
include $(NNDK_ROOT)/make/boilerplate.mk

Changing the NAME from SimpleHtml to HelloWorld will create the image file as HelloWorld.bin (and .s19)

The CPP_SRC is a list of all .cpp files to build. In this case there is only one, but if there were more it would look like:

CPP_SRC  = src/main.cpp \
        += src/file2.cpp \
        += src/file3.cpp \
        += src/file4.cpp 

If you have .c source files you can add them with C_SRC in the same manor.

The html related lines auto-generate a cpp file from the code in the project's html directory.

The final line calls the boilerplate makefile which includes the platform specific make instructions. While you can drill down into the details, this type of makefile structure makes creating projects much easier since you only need to list the source files of your project.

Edit main.cpp

A fully functional application with the web server enables is actually very few lines of code:

#include <init.h>
#include <nbrtos.h>
#include <system.h>
 
const char *AppName = "Simple HTML Example";
 
void UserMain(void *pd)
{
    init();                                       // Initialize network stack
    StartHttp();                                  // Start web server, default port 80
    WaitForActiveNetwork();
 
    iprintf("Web Application: %s\r\nNNDK Revision: %s\r\n", AppName, GetReleaseTag());
    while (1)
    {
        OSTimeDly(TICKS_PER_SECOND);
    }
}

This example just initializes the system, starts the web server, prints out some information, and loops forever with a 1 second delay. Changing the AppName to HelloWorld will change the name that shows up in the find and configuration utilities.

Modifying System Files with Overload

There can be instances in which you need to modify a NetBurner system file. This is accomplished using the Overload feature. NBEclipse creates an overload folder automatically, but with command line builds it must be created manually.

Note

The overload example is located in \nburn\examples\OverloadDirectory. See Overload Directory & System Files.

Overloading Any System File

Add an overload folder to your project. Then, for the file you want to overload, the filename and path inside the overload folder must exactly match the system file path relative to NNDK_ROOT. For example, to overload the timezones.cpp file located in the \nburn\nbrtos\source folder:

• \NetBurner\Projects
  • HelloWorld
    • html
      • index.html
    • obj
      • release
        • SimpleHtml.bin
    • overload
      • nbrtos
        • source
          • timezones.cpp
    • src
      • main.cpp
    • makefile

Copy the real system file into that path, then edit the copy. The project's timezones.cpp is used in place of the system one. The same applies to any header, any .cpp, and any web asset under the NNDK root.

Overloading System Configuration with predef-overload.h

Most projects only need to change a #define in nbrtos/include/predef.h. That header is large and changes between NNDK releases, so copying and maintaining the whole file can be complex.

The SDK provides a shortcut. The last line of predef.h is:

#include <predef-overload.h>

nbrtos/include/predef-overload.h ships empty. It exists only so a project can replace it. Create your own copy at <project root>/overload/nbrtos/include/predef-overload.h and put in only the lines you want to change:

#define NBRTOS_STACKCHECK     (1)

Because predef.h includes it last, your definitions get the final word over the SDK defaults, and a later NNDK release cannot silently revert them. Use this method rather than overloading predef.h itself.

If the predef-overload.h hook did not exist, you would copy the whole predef.h to <project root>/overload/nbrtos/include/predef.h and edit it there. That is what earlier releases required, and it is still what you do for every other system file.

constants.h offers the same convenience through constants-overload.h, included near the top of constants.h, and constants-overload-undefs.h, included after the header guard closes.

Overloading wolfSSL Settings with user_settings-overload.h

The wolfSSL settings for each platform are in libraries/include/crypto/platform/<PLATFORM>/user_settings.h. Each of those files includes user_settings-overload.h after all of its settings, and the SDK ships that file empty. Create your own copy at <project root>/overload/libraries/include/crypto/platform/user_settings-overload.h and put in only the lines you want to change:

#define WOLFSSL_SP_4096               // turn on an option that is off
#undef  HAVE_AESCCM                   // turn off an option that is on
#undef  WOLFSSL_TLS_SRAM_KB           // change a value
#define WOLFSSL_TLS_SRAM_KB 64
#define NB_TLS_KEYLOG                 // select a switch

Switches such as NB_TLS_KEYLOG and the crypto profiles take effect in user_settings_switches.h, which comes after it, so they work from your file too. See TLS Key Logging for a project that uses it.

Include Order and Feature Sub-Options

Warning

predef.h evaluates its own conditional blocks before it includes predef-overload.h on the last line. A macro you define in predef-overload.h cannot switch on an #ifdef block that appears earlier in predef.h.

If a feature has sub-options that predef.h sets inside #ifdef FEATURE, define those sub-options yourself in predef-overload.h. For example, enabling ENABLE_AUTOCERT_REGEN this way also requires defining AUTO_CERT_GEN_CHECK, because predef.h had already skipped its #ifdef ENABLE_AUTOCERT_REGEN block by the time the overload was read. See On-board Cert Generation - Simple.

constants.h behaves the opposite way. It includes constants-overload.h before its #ifndef X / #define X default blocks, so a plain #define there simply wins.

Important Overload Rules

• The folder must be named overload, not override.
• Command line builds need no makefile change. The build system finds the folder by name.
• The first time a file is added to the overload folder, a "make clean" is required. From that point on, any modifications to that file will automatically handle building all necessary system files.

If a system include folder is overloaded, this folder should be added to your project include paths. Right click on the project and select project properties. Under C/C++ Build->Settings, select GNU C++ Compiler->Includes and add the overload include folder. If utilizing C code, then GNU C Compiler->Includes should also be added.

GNU Debugger (GDB)

To load an application and start GDB from the command line:

• Build and load a debug build of the application make loaddebug -j.
• Start GDB:
  • For ARM devices such as the SOMRT1061, MODM7AE70 and SBE70LC: arm-eabi-gdb -se obj/debug/<elf.file>
  • For MOD5441X, NANO54415, and SB800EX platforms: m68k-elf-gdb -se obj/debug/<elf.file>
• Connect to the target device with: target remote <ipaddress>:2159

To end the GDB session and leave the target running use detach. To end the GDB session use quit. The GDB command reference is located here: http://www.gnu.org/software/gdb/documentation/.

Example GDB Session

An GDB session running the SimpleHtml example on a MOD54417 is shown below. The example has been modified to add some variables that do simple counting.

void UserMain(void *pd)
{
    init();                                       // Initialize network stack
    StartHttp();                                  // Start web server, default port 80
    WaitForActiveNetwork(TICKS_PER_SECOND * 5);
 
    iprintf("Web Application: %s\r\nNNDK Revision: %s\r\n", AppName, GetReleaseTag());
 
    uint32_t i = 0;
    uint32_t j = 0;
    while (1)
    {
        OSTimeDly(TICKS_PER_SECOND);
        i++;
        j = j + 1;
        iprintf("i: %ld, j: %ld\r\n", i, j);
    }
}

Load the application. Note that the DEVIP environment variable is set to the device's IP address 10.1.1.169. The application will begin execution and wait for GDB to connect.

C:\NetBurner\projects\SimpleHtml>make loaddebug -j
C:/nburn/pcbin/nbupdate obj/debug/DBSimpleHtml.bin 10.1.1.169
uriReq: http://10.1.1.169:20034/appupdate.htm
 
urlStr: http://10.1.1.169:20034/appupdate.htm
200
 
C:\NetBurner\projects\SimpleHtml>

Start GDB:

C:\NetBurner\projects\SimpleHtml>m68k-elf-gdb -se obj/debug/DBSimpleHtml.elf
GNU gdb (GDB) 8.2
Copyright (C) 2018 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
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=i686-w64-mingw32 --target=m68k-unknown-elf".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.
 
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from obj/debug/DBSimpleHtml.elf...done.
(gdb)

Connect to the MOD54417 target on port 2159. This will pause the application at whatever line of code it happens to be on. For simple examples that will typically be the NBRTOS idle task.

(gdb) target remote 10.1.1.169:2159
Remote debugging using 10.1.1.169:2159
OSTaskIdle (data=0x0) at C:/nburn/arch/coldfire/source/nbrtosmain.cpp:425
425             asm ( " NOP" );
(gdb)

At this point you can do whatever type of GDB commands you wish. To set a break point at the i++; at line 29 of main.cpp and use the continue command to execute until the break point is reached:

(gdb) break main.cpp:29
Breakpoint 1 at 0x40009282: file src/main.cpp, line 29.
(gdb) info break
Num     Type           Disp Enb Address    What
1       breakpoint     keep y   0x40009282 in UserMain(void*) at src/main.cpp:29
(gdb) continue
Continuing.
[Switching to Thread 2]
 
Thread 2 hit Breakpoint 1, UserMain (pd=0x0) at src/main.cpp:29
29                      i++;
(gdb)

The list command can be used to view the source code around the breakpoint:

Thread 2 hit Breakpoint 1, UserMain (pd=0x0) at src/main.cpp:29
29                      i++;
(gdb) list
24              uint32_t i = 0;
25              uint32_t j = 0;
26          while (1)
27          {
28              OSTimeDly(TICKS_PER_SECOND);
29                      i++;
30                      j = j + 1;
31                      iprintf("i: %ld, j: %ld\r\n", i, j);
32          }
33      }
(gdb)
\code
 
\latexonly \end{tcolorbox} \endlatexonly
 
 
 
\n
Now view the variables with print, as well as all local variables:
 
\latexonly \begin{tcolorbox} \endlatexonly
 
\code
(gdb) print i
$1 = 2
(gdb) info local
i = 2
j = 2
(gdb)

Use next to go to the next line without stepping into a function (the step command steps into a function). GDB commands can typically use just the first letter, in this case n:

(gdb) n
30                      j = j + 1;
(gdb) info local
i = 3
j = 2
(gdb)

To make changes to your code use the detach command do that the application can resume and will be ready for your next code download:

(gdb) detach
Detaching from program: C:\NetBurner\projects\SimpleHtml\obj\debug\DBSimpleHtml.elf, Remote target
Ending remote debugging.
[Inferior 1 (Remote target) detached]
(gdb)

To exit GDB, use the quit command:

(gdb) quit
 
C:\NetBurner\projects\SimpleHtml>

Addr2line

Note

On Windows and ColdFire-based modules, you can use WinAddr2Line instead.

To get line numbers and function names from trap memory addresses, you can use addr2line on the command line like this:

addr2line -ifCe Release/YourProject.elf 00001111 11112222

Replace "addr2line" with the path to the appropriate program below, and replace the numbers with memory addresses you want to find.

ColdFire platforms

For ColdFire based platforms, use m68k-elf-addr2line. This is distributed in the \nburn\gcc\bin\\endiskip folder.

ARM platforms

For ARM-based platforms, use arm-unknown-eabi-addr2line. This is distributed in the \nburn\gcc\bin\\endiskip folder.