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.

Command	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
TOOLCHAINPATH	Specifies the location of the GCC tools path, such as the compiler

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

set NNDK_ROOT=c:/nburn
set PLATFORM=MODM7AE70
set DEVIP=192.168.1.66
set TOOLCHAINPATH=c:/nburn/gcc/bin

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 Oveload feature. NBEclipse creates an overload folder automatically, but with command line it must be created manually.

Note

The overload example is located in \nburn\examples\Overload

Adding an overload folder to our HelloWorld project:

\NetBurner\Projects
    \- HelloWorld
          \- html
              |- index.html
          \- obj
              \- release
                   |- SimpleHtml.bin
          \- overload
          \- src
              |- main.cpp
          | makefile

Once you know which file you want to overload, the path in the overload folder must exactly match the system file path. For example, if we want to overload the predef.h include file located in the \nburn\nbrtos\include folder:

\NetBurner\Projects
    \- HelloWorld
          \- html
              |- index.html
          \- obj
              \- release
                   |- SimpleHtml.bin
          \- overload
                \- nbrtos
                     \- include
                          |- predef.h
          \- src
              |- main.cpp
          | makefile

Now the project's predef.h will be used along with any changes made to it.

Predef.h and predef-overload.h

These are unique and powerful files used to change base-level system options. We recommend overloading items in here sparingly and using predef-overload.h whenever possible since the predef.h file changes between NNDK releases and it can be hard to track what overloads you need to keep when they're all mixed together with the defaults.

So, just follow the above directions using a blank predef-overload.h file containing only the predef constants you want to change.

Important Overload Rules

• 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 executee 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\ folder.

ARM platforms

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