Network Developers Kit API 3.61.01.01

Macros | Functions
Network Control Initialization Procedure

The stack library includes code to perform system initialization based on the configuration. Initialization of the scheduling routines is performed by a network control layer called NETCTRL. More...

## Macros
#define | NC_PRIORITY_LOW OS_SCHEDULER_LOWPRI
#define | NC_PRIORITY_HIGH OS_SCHEDULER_HIGHPRI
#define | NC_OPMODE_POLLING 1
#define | NC_OPMODE_INTERRUPT 2
#define | NC_OPEN_SUCCESS 0
#define | NC_OPEN_ILLEGAL_PRIORITY -1
#define | NC_OPEN_ILLEGAL_OPMODE -2
#define | NC_OPEN_MEMINIT_FAILED -3
#define | NC_OPEN_EVENTINIT_FAILED -4

## Functions
int | NC_SystemOpen (int Priority, int OpMode)
| Initiate a system session. More...
void | NC_SystemClose ()
| Shutdown the system. More...
int | NC_NetStart (void *hCfg, void(*NetStartCb)(), void(*NetStopCb)(), void(*NetIPCb)(uint32_t, uint32_t, uint32_t))
| Start network. More...
void | NC_NetStop (int rc)
| Stop the network. More...

## Detailed Description

The stack library includes code to perform system initialization based on the configuration. Initialization of the scheduling routines is performed by a network control layer called NETCTRL.

## Macro Definition Documentation

## § NC_PRIORITY_LOW

#define NC_PRIORITY_LOW OS_SCHEDULER_LOWPRI

## § NC_PRIORITY_HIGH

#define NC_PRIORITY_HIGH OS_SCHEDULER_HIGHPRI

## § NC_OPMODE_POLLING

#define NC_OPMODE_POLLING 1

## § NC_OPMODE_INTERRUPT

#define NC_OPMODE_INTERRUPT 2

## § NC_OPEN_SUCCESS

#define NC_OPEN_SUCCESS 0

Success

## § NC_OPEN_ILLEGAL_PRIORITY

#define NC_OPEN_ILLEGAL_PRIORITY -1

Illegal priority

## § NC_OPEN_ILLEGAL_OPMODE

#define NC_OPEN_ILLEGAL_OPMODE -2

Illegal opmode

## § NC_OPEN_MEMINIT_FAILED

#define NC_OPEN_MEMINIT_FAILED -3

Memory initialization failure

## § NC_OPEN_EVENTINIT_FAILED

#define NC_OPEN_EVENTINIT_FAILED -4

Event initialization failure

## Function Documentation

## § NC_SystemOpen()

int NC_SystemOpen | ( | int | Priority,
|  | int | OpMode
| ) |  |

Initiate a system session.

This is the first function that should be called when using the stack. It initializes the stack's memory manager, and the OS (or OS adaptation layer). It also configures the network event scheduler's task priority and operating mode.

Parameters

  [in] | Priority | Network event scheduler task priority
  [in] | OpMode | Network event scheduler operating mode

Remarks
  `Priority` must be set to either NC_PRIORITY_LOW or NC_PRIORITY_HIGH, and determines the scheduler task's priority relative to other networking tasks in the system.
  `OpMode` must be set to either NC_OPMODE_POLLING or NC_OPMODE_INTERRUPT, and determines when the scheduler attempts to execute. The interrupt mode is used in the vast majority of applications.
  Note that polling operating mode attempts to run continuously, so when polling is used, `Priority` must be set to NC_PRIORITY_LOW.

Returns
  Success: 0
  Failure:
  - NC_OPEN_ILLEGAL_PRIORITY
  - NC_OPEN_ILLEGAL_OPMODE
  - NC_OPEN_MEMINIT_FAILED
  - NC_OPEN_EVENTINIT_FAILED

See also
  NC_SystemClose()

## § NC_SystemClose()

void NC_SystemClose | ( |  | ) |

Shutdown the system.

This is the last function that should be called when using the stack. It shuts down the memory manager and performs a final memory analysis.

See also
  NC_SystemOpen()

## § NC_NetStart()

int NC_NetStart | ( | void * | hCfg,
|  | void(*)() | NetStartCb,
|  | void(*)() | NetStopCb,
|  | void(*)(uint32_t, uint32_t, uint32_t) | NetIPCb
| ) |  |

Start network.

This function is called to boot up the network using the network configuration supplied in `hCfg`. Along with the network configuration, three callback function pointers are provided. These callback functions are called at distinct times.

- `NetStartCb` is called when the system is first ready for the creation of application supplied network tasks.
- `NetStopCb` is called when the network is about to shut down.
- `NetIPCb` is called when an IP address is added or removed from the system.

If any of these callback functions are not required, the function pointers can be set to NULL.

Parameters

  [in] | hCfg | Handle to network configuration
  [in] | NetStartCb | Optional pointer to callback function called when network stack is started
  [in] | NetStopCb | Optional pointer to callback function called when network is stopped
  [in] | NetIPCb | Optional pointer to callback function called when an IP address is added or removed from the system

Remarks
  `NC_NetStart()` will not return until the entire network session has completed. Thus, all user supplied network code (creation of user tasks) should be included in the `NetStartCb` function.
  When `NetStartCb` is called, the configuration handle supplied in `hCfg` is the default configuration handle for the system. The execution thread on which `NetStartCb` is called is not critical to event scheduling, but it should return eventually; i.e., the application should not take control of the thread. If system shutdown is initiated before this callback function returns, some resources may not be freed.
  Excluding critical errors, NC_NetStart() will return only if an application calls the NC_NetStop() function. The parameter passed to NC_NetStop() becomes the return value returned by NC_NetStart().
  Sometime after NC_NetStop() is called, but before NC_NetStart() returns, the NC_NetStart() thread will make a call to the application's NetStopCb callback function. In this callback function, the application should shut down any task initiated in its `NetStartCb` callback.
  When an IP addressing change is made to the system, the `NetIPCb` function is called. The callback function is declared as:
  void NetIPCb(uint32_t IPAddr, uint32_t IfIndex, uint32_t fAdd);
  where:
  - IPAddr: IP Address being added or removed
  - IfIndex: Index of physical interface gaining or losing the IP address
  - fAdd: Set to 1 when adding an address, or 0 when removing an address
  The `NetIPCb` callback is purely informational, and no processing is necessary on the information provided.
  There is an option for immediately calling NC_NetStart() again upon return, which provides a good stack reboot function. Optionally, the configuration can also be reloaded, which allows the stack to be restarted after a major configuration change.

Returns
  The integer passed to NC_NetStop()

See also
  NC_NetStop()

## § NC_NetStop()

void NC_NetStop | ( | int | rc | ) |

Stop the network.

This function is called to shut down a network initiated with NC_NetStart(). The return value supplied in the StopCode parameter becomes the return value for NC_NetStart(). See the description of NC_NetStart() for more detail.

Parameters

  [in] | rc | return code to be returned by NC_NetStart()

See also
  NC_NetStart()

© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale