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 operating mode

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()