# 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:

- TI/CCS - `packages/ti/posix/ccs`
- IAR - `packages/ti/posix/iar`
- GCC - `packages/ti/posix/gcc`

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.

### 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):

- `OEMCacheClean()`
- `OEMCacheCleanSync()`
- `Interrupt_add()`
- `Interrupt_delete()`
- `Interrupt_enable()`
- `Interrupt_disable()`

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.