#ifndef _aplmt_networking_uip_inetapi_h_ #define _aplmt_networking_uip_inetapi_h_ /*---------------------------------------------------------------------------- ** SUMMARY: APLMT Network Application for the uIP Network Stack (UIPINET) ** ** DESCRIPTION: ** This file defines the interface for running uIP in its own "network" ** thread. The basic concept here is that the uIP stack and the network ** application(s) that use the stack all run in a single thread. In ** addition this framework allows the platform to have an interrupt ** driven (with respect to receiving packets) ethernet driver instead of ** a dedicated polling loop that uIP requires when running with out ** some kind of thread/task scheduler. ** ** ** uIP: ** ---- ** What is uIP? The following is a excerpt from the uIP project home page ** (http://dunkels.com/adam/uip/index.html): ** ** "The uIP TCP/IP stack makes it possible to connect even small 8-bit ** microcontrollers to a TCP/IP network such as the global Internet, ** without sacrificing interoperability or RFC standards compliance." ** ** If you haven't read the uIP documentation, do so now. The following ** descriptions assume the reader is familiar with uIP. ** ** This framework preserves the uIP model of calling back into the ** application (i.e. APPCALL) as well as it use of global variables. Any ** application written for the "standard" uIP stack will run without any ** modifications. However, if you need those existing application to ** interact with other threads, you will have to add new code. ** ** This framework does not impose or define any values in the uIP ** configuration header file 'uipopt.h'. The application is still ** responsible for its content. ** ** uIP has two timing mechanisms, uip_periodic() and uip_arp_timer(). These ** functions must be called by the low-level device driver on a periodic ** basis. The framework calls these functions based on the application ** defined value for: OPTION_APLMTUIP_PERIODIC_TICK_SYSTIME and ** OPTION_APLMTUIP_NUM_TICKS_PER_ARP_PERIOD ** Note: These values should be based on settings made in the uIP ** configuration header file 'uipopt.h' ** ** ** THREADING: ** ---------- ** The hardware specific network driver, the uIP stack code, and the ** application function "APPCALL" all RUN IN THE CONTEXT OF THE ** NETWORK THREAD. The responsibility of protecting shared data and/or ** resources between the network thread and other threads is the ** responsibility of the application. The recommended paradigm for ** interaction between the thread is to use ITC. The framework optionally ** provides the network thread with an ITC mailbox to support this ** approach. ** ** RECIEVING PACKETS: ** ------------------ ** Typically, the low-level driver is setup to make use of the RX interrupts ** provided by the LAN hardware. If this is the case, then the network is ** signaled every time a RX interrupt is received. If the low-level driver ** is a polling-only model, then the application should signal the network ** thread periodically so it can wake-up and poll for packets. NOTE: This ** periodic rate is DIFFERENT (and should be faster) than the rate defined ** for OPTION_APLMTUIP_PERIODIC_TICK_SYSTIME. ** ** TRANSMITTING PACKETS: ** --------------------- ** There are two basic ways for transmitting packets: 1) in response to ** a received packet (i.e. server application) or 2) the application ** initiates (i.e. client application) a connection and/or transaction. ** The original uIP model handles scenerio '1' well, but not '2'. uIP ** only allows 'new' activity when uip_periodic() is called. However, ** to reduce the 'transmit' latency, the application can signal the network ** at ANY TIME. This effectively provides the same functional uip_periodic() ** without effecting uIP's time-out counters and does not have to be done ** at a fixed frequency. NOTE: The uIP stack is/was slightly modified to ** support this behavior. ** ** ITC: ** ---- ** By default, the framework does not support ITC for the network thread. ** Support is enabled by using the compile switch: USE_APLMTUIP_SUPPORT_NETWORK_MESSAGES ** The network processing itself does not use/need ITC messages, it makes ** use of the mailbox-signal interface. The applicaiton defines, sends, ** receives, and processes all ITC messages posted to the network thread. ** Enabling ITC support does the following: ** - It provides a mailbox and message-processing loop for the network ** thread. ** - Generation of a callback (AplmtUIP_cbInetNextITCMessage) into the ** application for ALL messages received. Note: The callback function ** executes in the context of the network thread. ** ** If using ITC models: XSMALL, SMALL, or NORMAL, the application is ** required to: ** - Allocate/reserve a mailbox for the network thread. ** - Implement the following function (note the leading underbar): ** AplmtImboxHdl _AplmtUIP_inetGetMboxHdl(void); ** ** ** CONFIGURATION ** ------------- ** COMPILE: USE_APLMTUIP_SUPPORT_NETWORK_MESSAGES ** ** APPLICATION: OPTION_APLMTUIP_PERIODIC_TICK_SYSTIME ** OPTION_APLMTUIP_NUM_TICKS_PER_ARP_PERIOD ** ** PLATFORM: none. ** ** ** NOTES: ** 1. Unless explicitly stated otherwise, NONE of the following methods may be ** called from interrupt service routines. ** 2. Unless explicitly stated otherwise, NONE of the following methods may be ** called before the platform's kernel is running. ** 3. Unless explicitly stated otherwise, all of the following methods assume ** that interrupts are enabled at the time of the call. ----------------------------------------------------------------------------*/ #include "aplcfg.h" /* For: Application configuration */ #include "apl/types/types.h" /* For: basic types */ #include "aplmt/os/kernelapi.h" #ifdef USE_APLMTUIP_SUPPORT_NETWORK_MESSAGES #include "aplmt/itc/imsgapi.h" /* For: ITC message type */ #include "aplmt/itc/imboxapi.h" /* For: ITC mailbox type */ #endif #ifdef __cplusplus extern "C" { #endif /*-------------- CONSTANTS -------------------------------------------------*/ /** This is the periodic rate for polling uIP timers. The default is 500msec. The value is specified as the number of AplmtSysTime ticks in the desired period. */ #ifndef OPTION_APLMTUIP_PERIODIC_TICK_SYSTIME #define OPTION_APLMTUIP_PERIODIC_TICK_SYSTIME 500 #endif /** This is the periodic rate for uIP's ARP timer. The recommended (and default) period is 10secs. The value is specified as the number of 'uIP Periodic Ticks' in the desired period. */ #ifndef OPTION_APLMTUIP_PERIODIC_TICK_SYSTIME #define OPTION_APLMTUIP_PERIODIC_TICK_SYSTIME 20 #endif /*-------------- INLINE IMPLEMENTATION -------------------------------------*/ #include "aplmt/networking/uip/inet.h" /*-------------- PUBLIC/PUBLISHED API --------------------------------------*/ /** This method is used to perform initialization for the networking engine BEFORE the network thread is created. Prototype: void AplmtUIP_inetInitialize(void); */ #define AplmtUIP_inetInitialize _AplmtUIP_inetInitialize /** This is the main-entry function for the network thread. The application is responsible for creating the network thread. The amount of stack space required for the network thread varies by platform. */ void AplmtUIP_inetMain(void* notUsed); /** This method returns the handle to the network thread. The application is responsible for implementing this method since it is also responsible for creating the network thread. NOTES: o Obviously this method can not be called until after the network thread has been created. */ AplmtThreadHdl AplmtUIP_inetGetThreadHdl(void); /** This method is callback into the application from the network stack. This method allows the application to perform initialization in the context of the network thread. NOTES: o This method is called AFTER uip_init() is called and BEFORE uIP make the first call to UIP_APPCALL. o Since this method is called from the context of the network's thread, it is the RESPONSIBILITY of the application to ensure the integrity of its data with respect to other threads. o It is OK for the application to make uip_xxx() calls within the scope of this method. */ void AplmtUIP_cbInetApplicationInit(void); /** This method is used to wake up the network thread and have it go through its processing cycle. This method can only be called from the context of a thread. This method can be used 'on-demand' by the application to force low-level packets reads and/or for a uip_poll() 'event' so the app can transmit data immediately. Prototype: void AplmtUIP_inetSignal(void); */ #define AplmtUIP_inetSignal _AplmtUIP_inetSignal /** This method is the same as AplmtUIP_inetSignal(), except that it can only be called from an interrupt service routine. This method is typically called when the applicaiton receives a incoming-packet interrupt and/or the periodic timer interrupt fires. Prototype: void AplmtUIP_isr_inetSignal(void); */ #define AplmtUIP_isr_inetSignal _AplmtUIP_isr_inetSignal /*-------------- PUBLIC/PUBLISHED API --------------------------------------*/ #ifdef USE_APLMTUIP_SUPPORT_NETWORK_MESSAGES /** This method is an OPTIONAL callback into the application from the network stack. This method allows the application to hook into the network stack's ITC message loop and process/send messages from the network thread context. NOTES: o The application enables the use of this method by using the compile switch: USE_APLMTUIP_SUPPORT_NETWORK_MESSAGES o The application is responsible for calling Aplmt_imsgReturnToSender() on the message once it is done with it. o It is OK for the application to make uip_xxx() calls within the scope of this method. o This method EXECUTES IN THE CONTEXT of the network thread. */ void AplmtUIP_cbInetNextITCMessage( AplmtImsgHdl _msg ); /** This method returns the handle of the network thread's ITC mailbox. The applicaiton may then post "poll-connection" messages or its own application specific message(s) to the network thread. NOTES: o When using ITC models XS, S, or N, the application is REQUIRED to implement this method. When using the ITC LARGE model, this method is provided by the networking sub-system. o This method can NOT be called BEFORE AplmtUIP_inetInitialize() is called. o WARNING: Be carefull on posting synchronous ITC message(s) to the network thread. If your application make synchronous ITC calls FROM within the context of the network thread (i.e. while processing UIP_APPCALL), then to avoid deadlock scenerios, NO threads can post synchronous ITC messages TO the network thread. Prototype: AplmtImboxHdl AplmtUIP_inetGetMboxHdl(void); */ #define AplmtUIP_inetGetMboxHdl _AplmtUIP_inetGetMboxHdl #endif /* end USE_APLMTUIP_SUPPORT_NETWORK_MESSAGES */ #ifdef __cplusplus } #endif /*--------------------------------------------------------------------------*/ #endif /* end _aplmt_networking_uip_inetapi_h_ */