NetBurner 3.3.3
PDF Version
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 clean Delete a project's libraries and object files


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 it's 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 makfile 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
iprintf("Web Application: %s\r\nNNDK Revision: %s\r\n", AppName, GetReleaseTag());
while (1)
{
OSTimeDly(TICKS_PER_SECOND);
}
}
void OSTimeDly(uint32_t to_count)
Delay the task until the specified value of the system timer ticks. The number of system ticks per se...
Definition: nbrtos.h:1388
const char * GetReleaseTag()
Returns the NNDK release tag information.
Definition: release_tag.cpp:8
void StartHttp(uint16_t port, bool RunConfigMirror)
Start the HTTP web server. Further documentation in the Initialization section Initialization - Syste...
void init()
System initialization. Normally called at the beginning of all applications.
Definition: init.cpp:29
bool WaitForActiveNetwork(uint32_t ticks_to_wait=120 *TICKS_PER_SECOND, int interface=-1)
Wait for an active network connection on at least one interface.
Definition: dhcpc.cpp:1550
NetBurner System Initialization Header File.
NetBurner Real-Time Operating System API.
NetBurner System Functions.

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.

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 MODM7AE70 and SBE70LC: arm-eabi-gdb -se obj/debug/<elf.file>
    • For MODM7AE70, SBE70LC, and SOMRT1061 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 varibles 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>