How the Library Works
The Manager module of the TCP/IP stack is the central module in the stack. It is this module that allows the client to configure and initialize the stack and also to get current status and parameters of the network interfaces that the stack supports.
The stack manager controls the communication to the underlying virtual MAC driver that implements the interface to a specific network channel. The various network interfaces that the TCP/IP stack supports are brought up or torn down by the stack manager in response to the stack client commands.
The manager is also responsible for providing the TCP/IP client with notifications of the events that occur in the stack at the network interface level. A dynamic registration mechanism is provided for this.
Another important functionality of the stack manager is the dispatch of the incoming network packets. The manager is notified by the underlying interface drivers of the traffic related event (transmit, receive, errors, etc.) As a response to those events the manager gets the pending receive packets from the virtual MAC driver and, based on their type, dispatches them to the appropriate higher level protocol for further processing (IPv4, ARP, IPv6).
As part of the event notification provided by the MAC driver the TCP/IP stack manager calls back into the MAC driver when this one needs processing time and can maintain statistics counters, link status, etc.
The MPLAB Harmony framework on the system running the TCP/IP stack interfaces to the stack manager mainly by using three functions, TCPIP_STACK_Initialize and TCPIP_STACK_Deinitialize for TCP/IP stack initialization, and TCPIP_STACK_Task for periodic processing and the advance of the stack state machine.
The stack is capable of running either under an Operating System (RTOS) or in a bare-metal environment. When running in a bare-metal environment a "cooperative multi-tasking" approach is needed by the TCP/IP stack, meaning that control has to reach the TCPIP_STACK_Task function. That is the system will need to make periodic calls to this function which allows the TCP/IP stack to dequeue incoming packets and the corresponding state machines in the stack to advance. The application has to be aware that it cannot monopolize the processor for long periods of time, and needs to relinquish control so that the system loops perform their tasks.
In an RTOS environment it is preferred to have the stack manager run in its own thread. This thread will be blocked waiting for network interface events and when such an event occurs it will wake up and process the data. This is a more efficient way of using the CPU resources.
Refer to MPLAB Harmony Framework Reference for information on configuring the MPLAB Harmony framework to run in a RTOS or bare-metal environment.
Core Functionality
The following diagram provides an overview for the operation and use of the Manager module in a typical MPLAB Harmony framework (bare-metal, non-OS environment).
The TCP/IP stack is initialized as a part of the system initialization by a call to TCPIP_STACK_Initialize. By configuring the stack, the application can pass run-time initialization data to the stack to select both the network parameters of the interfaces (network addresses, masks, physical addresses, NetBIOS names, DHCP operation, etc.) and the parameters for the modules contained in the stack (TCP, UDP, ARP, IPv4, IPv6, etc.).
Once the stack is initialized the application can use the stack manager calls to inquire about the stack current settings (current addresses obtained by DHCP or IPv6 advertisements messages, etc.), to check the physical link status or to set new parameters to the stack.
It should be noted that different interfaces can be stopped and restarted dynamically (TCPIP_STACK_NetDown, TCPIP_STACK_NetUp) without the stack being killed. When a particular interface is brought up only the network parameters for that interface need to be supplied (no parameters for the TCP/IP stack modules are needed).
The entire stack can be stopped and restarted (TCPIP_STACK_Deinitialize, TCPIP_STACK_Initialize). Reinitializing the stack allows the stack initialization with a complete new set of network and/or module parameters.
The stack processing is done in the TCPIP_STACK_Task function. As explained in the previous paragraph, processing time is required by the stack, meaning that periodic calls have to be made by the system/framework to the TCPIP_STACK_Task function. When execution reaches this function the stack maintains and advances its internal state machine. The most important part of this is the processing of the events that are reported by the underlying MAC drivers (through the use of the virtual MAC driver, which provides an interrupt signaling/event notification mechanism). As a response to the MAC events, the stack manager will retrieve packets from the internal MAC receive queues and dispatch them for processing. It will also call into MAC processing functions if required and provide processing for the stack modules that are the recipients of the dispatched network packets. The stack manager will also notify the application of the network events if the application dynamically registered an event notification handler with the stack.
It should be noted that the stack manager also requires a periodic tick signal for which it uses the MPLAB Harmony system timer services (see Timer System Service Library).
If the application no longer uses the TCP/IP stack, it is important that it calls the TCPIP_STACK_Deinitialize function. This function closes any open network connections (sockets, etc.), closes the underlying MAC and PHY drivers and all of the modules in the stack, and frees all of the resources that were internally allocated by the stack as part of the initialization and run-time processing.