NDK 2.x to 3.x Migration Guide

Table of Contents

Introduction

The Network Developer’s Kit (NDK) 3.x includes changes and features that will require existing NDK 2.x users to update their code base. This document describes these changes (from NDK 2.26), and the rationale for them.

POSIX

The architectural approach to TI’s POSIX port to SYS/BIOS changed between SYS/BIOS 6.52 and 6.53. These POSIX changes enable improved per-toolchain support, as well as POSIX support for RTOS’s other than SYS/BIOS.

The changes are described in some detail in the SYS/BIOS 6.53 Release Notes. While technically not an NDK 3.x change, users migrating from NDK 2.x to 3.x will often hit this issue, so the 2 key POSIX-related changes are summarized here:

  1. The compiler include path has changed.
  2. For users of XDC config, some elements of the POSIX package have changed.

Include Path

The include path where POSIX headers are found has changed from packages/ti/sysbios/posix to one of these toolchain-specific directories:

Users will need to modify their include paths appropriately, according to their toolchain.

XDC Config Changes

The name of the package has changed from ti.sysbios.posix to ti.posix.tirtos. Also, the name of the supportsMutexPriority config parameter has been changed to enableMutexPriority.

SYS/BIOS 6.52

/* use the old ti.sysbios.posix module and enable mutex priority support */
var Settings = xdc.useModule('ti.sysbios.posix.Settings');
Settings.supportsMutexPriority = true;

SYS/BIOS 6.53+

/* use the new ti.posix.tirtos module and enable mutex priority support */
var Settings = xdc.useModule('ti.posix.tirtos.Settings');
Settings.enableMutexPriority = true;

Architecture

The general architecture of the NDK stack remains as is. However, in an effort to share application-level services (e.g. HTTP Clients, BSD/POSIX socket support, etc.) across different network stacks (e.g. TI’s CC32XX devices), some of these common services are migrating out of the NDK and into a new Component called Network Services (NS).

In addition, a key feature of the NS stacks is the ability to insulate differences in TLS implementations from users. For more details, see the NS documentation.

The following diagram shows the relationship between the NDK and NS Components.

Architecture

BSD/POSIX Networking Interface

As a result of the architecture changes, NDK 2.x users of the BSD/POSIX interfaces will require some changes when migrating to NDK 3.x. Examples of the BSD/POSIX APIs that have moved include traditional BSD-defined socket APIs (e.g. socket(), bind(), connect()), as well as BSD-defined utility APIs (e.g. inet_ntop() and inet_pton()).

The location of BSD/POSIX headers and libraries have moved (from NDK to NS), so the following build-related changes are needed:

NDK 2.x

# makefile, BSD include path in NDK
CFLAGS += -I$(NDK_INSTALL_DIR)/packages/ti/ndk/bsd/inc

# If not using XDC config, add the NDK stack libraries
LFLAGS += "-l$(NDK_INSTALL_DIR)/packages/ti/ndk/lib/...

NDK 3.x + NS

# makefile, BSD include path in NS
CFLAGS += -I$(NS_INSTALL_DIR)/source/ti/net/bsd

# add BSD-enabling libraries.  If using XDC config, add the NS library
# before the XDC-generated linker command file. (NS does not support
# XDC configuration)
#
# Also note that the libraries in this example are for the M4F ISA,
# TI/CCS toolchain.  The libraries you actually link will vary based
# on your ISA/toolchain.
LFLAGS += "-l$(NS_INSTALL_DIR)/ti/net/lib/ccs/m4f/slnetsock_release.a" \
          "-l$(NDK_INSTALL_DIR)/ti/ndk/slnetif/lib/slnetifndk.aem4f"

And NS requires runtime initialization to register the NDK:

NDK 2.x

    /* application C source code */
    #include <sys/socket.h>

    /* other than starting the NDK stack, no further initialization required */

NDK 3.x + NS

    /* application C source code */
    #include <sys/socket.h>   /* same! */

    /* ... after starting the NDK stack, initialize NS modules */
    SlNetIf_init(0);
    SlNetUtil_init(0);
    SlNetSock_init(0);

    /* ... and register NDK interface (no TLS, in this case) with SlNetIf */
    retval = SlNetIf_add(id, "eth0", &SlNetIfConfigNDK, priority);

After these changes, your application can use BSD/POSIX, and any other services, from the NS Component.

See the examples provided with your SDK for more details.

Namespace Collision

In an effort to reduce namespace collision, many of the NDK interfaces and definitions that would obviously collide with NS’s BSD/POSIX were prefixed with NDK_. For example, the error code ENETDOWN is now NDK_ENETDOWN.

Data Types

To better support 64-bit processors, many data types in the NDK needed to change. As part of this effort, custom data types (defined by the NDK) were converted to standards based data types (defined by C99).

As concrete examples, HANDLE, UINT32, and UNIT8 data types were replaced by C99-defined void * and uint32_t, and uint8_t respectively.

Wider RTOS Support

In some environments, TI supports several RTOS options (e.g. TI-RTOS and FreeRTOS are supported on TI’s Connected MCU devices, like the MSP432E4). As a result, some of the NDK’s OSAL (ti/ndk/os/*) was refactored. Most users will not see changes in this area.

Reduced OSAL

We want the NDK to be focused on being a great network stack, and not be distracted by being in the OS Abstraction Layer (OSAL) business. As a result, some of the NDK OSAL APIs that were not used internally by the NDK have been removed.

As of NDK 3.40, the following OSAL APIs have been removed (compared to what was provided in NDK 2.26):

Over time, as we determine other OSAL APIs are not intended to be used outside of NDK internals, this list may grow.

Future Development

Development of the NDK and NS continues. Please consult the Release Notes and Change Logs, both for the NDK and NS Components, for details on changes in specific releases.