SeaMoby Working Group Kamel Baba Internet Draft Jack Cheng Document:draft-singh-l2trigger-api-00.txt Rodrigo Diaz Expires: March 2003 Shravan Mahidhara Ajay Mehta Venkatesh Pandurangi Ajoy Singh Fast Handoff L2 Trigger API Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC 2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt To view the list of Internet-Draft Shadow Directories, see http://www.ietf.org/shadow.html. The distribution of this memo is unlimited. It is filed as draft- singh-l2trigger-api-00.txt, and expires March 2003. Please send comments to the authors. Abstract To enable seamless L3 handover of a MN from one subnet to other, the MN or the AR is required to anticipate the identity of the target AR prior to initiation of the L3 handoff. To anticipate the identity of target AR, the L3 is required to receive a notification from L2 about the appropriate identity of target AP as soon as the L2 handoff is detected. To further optimize the L3 handoff, L3 is also required to receive indications about Link Up and Link Down events as soon as such events are detected by L2. The Link Down event is detected by L2 as soon as the MN loses connection with current AP. Similarly, the Singh, et.al. Expires - March 2003 [Page 1] draft-singh-l2trigger-api-00.txt October 2002 Link Up event is detected as soon as the MN re-connects with new AP. Depending upon the nature of access technologies, some of the various triggers can be available at MN, AR or both. Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 [1]. TABLE OF CONTENTS 1. Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . .4 3. Functional Overview. . . . . . . . . . . . . . . . . . . . . . . 5 4. Design Considerations. . . . . . . . . . . . . . . . . . . . . . 9 4.1. Data Types and Definitions. . . . . . . . . . . . . . . . . 9 4.2. Structures. . . . . . . . . . . . . . . . . . . . . . . . . 9 4.2.1. Mobile Trigger. . . . . . . . . . . . . . . . . . . . .9 4.2.2. Source Trigger. . . . . . . . . . . . . . . . . . . . 10 4.2.3. Target Trigger. . . . . . . . . . . . . . . . . . . . 10 4.2.4. Link Up Trigger. . . . . . . . . . . . . . . . . . . .10 4.2.5. Link Down Trigger. . . . . . . . . . . . . . . . . . .11 4.2.6. Trigger Table. . . . . . . . . . . . . . . . . . . . .11 5. Trigger Functions. . . . . . . . . . . . . . . . . . . . . . . .12 5.1. Registration Functions. . . . . . . . . . . . . . . . . . .12 5.1.1. trig_register( ) . . . . . . . . . . . . . . . . . . 12 5.1.2. deregister( ) . . . . . . . . . . . . . . . . . . . . 12 5.1.3. modify_register( ) . . . . . . . . . . . . . . . . . .13 5.2. Retrieval Functions. . . . . . . . . . . . . . . . . . . . 13 5.2.1. get_trig_info( ) . . . . . . . . . . . . . . . . . . .13 6. Sample Usage. . . . . . . . . . . . . . . . . . . . . . . . . . 14 7. Security Considerations. . . . . . . . . . . . . . . . . . . . .15 8. References. . . . . . . . . . . . . . . . . . . . . . . . . . . 15 9. Authors Addresses. . . . . . . . . . . . . . . . . . . . . . . .15 Singh et. al. Expires - March 2003 [Page 2] draft-singh-l2trigger-api-00.txt October 2002 1. Terminology AR Access Router AP Access Point L2 Link Layer or Layer 2 L3 Network Layer or Layer 3 API Application Programming Interface L2 Trigger An abstraction of notification from L2 to L3 that a certain event happened or is about to happen. L2 Handoff Change of MN's L2 connection from one AP to another. No change in MN's routing reaches ability. L3 Handoff Change of MN's routable address from one AR to another AR. Requires change in MN's routing reach ability. Source Trigger An L2 Trigger generated at the old AR, which indicates that the MN is moving from old AR to the new AR. Target Trigger An L2 Trigger generated at the new AR, which Indicates that the MN is moving from old AR to the new AR. Link Down Trigger An L2 Trigger generated at the old AR, which indicates that, the old link between MN and the old AR router is going down. Link Up Trigger An L2 Trigger generated at the new AR, indicates that the new link between MN and the new AR is up. Mobile Trigger An L2 trigger generated at the MN, which indicates that the MN is moving from old AR to the new AR. Trigger Table A table containing the data required to notify the L3 when a particular trigger event happens. Singh et. al. Expires - March 2003 [Page 3] draft-singh-l2trigger-api-00.txt October 2002 The table is managed and maintained by L2. LDT Link Down Trigger LUT Link Up Trigger ST Source Trigger TT Target Trigger MN Mobile Node 2. Introduction Mobile IP describes how a MN can perform L3 handoff between subnets served by different ARs. The latency observed during standard L3 handoff is way above the desired threshold required to support delay sensitive real time services. To reduce the L3 handoff latency, Mobile IP working group is working to standardize fast handoff protocols. The fast handoff protocols require AR or MN to anticipate the identity of target AR prior to initiation of the L3 handoff. The fast handoff protocols require the help of L2 to anticipate the timing of L3 handoff as well obtain the identity of target AR. The interaction of L3 with L2 in order to anticipate the timing of L3 handoff as well as obtain identity of target AR is the primary focus of l2 trigger work. Additionally, the L2 triggers may also indicate the occurrence of L2 Link Up as well as Link Down events to the L3 as soon as such events are detected by the lower layer entities. For example, during handoff, Link Down event is detected when MN looses L2 connection with old AP whereas the Link Up is detected when the MN establishes L2 connections with new AP. The document defines a set of C API that can be used by L3 to receive appropriate L2 trigger event notifications from a wireless link layer. To enable the notifications of L2 events to L3, first L3 registers the appropriate triggers with L2 trigger handler. Subsequently, when L2 trigger handler detects any registered trigger events, it informs L3 by sending a pre-defined real time signal. Upon receiving the real time signal from L2 trigger handler, L3 calls appropriate API to collect additional information associated with the L2 trigger. 3. Functional Overview This section describes the functional overview of L2 trigger API. The operation of the trigger API and inter-working between L2 and L3 is summarized in Figure 1-3 below. Singh et. al. Expires - March 2003 [Page 4] draft-singh-l2trigger-api-00.txt October 2002 Step 1: Registration Registration is a method by which the L3 will register for the L2 triggers. L3 can register for one or more L2 triggers as required. L3 registers with L2 using the trig_register () API call. Figure 1: Registration --------------------------------------------------------------------- ^ | -------------------------- ------------------------------ | | Process1 | | Process2 | | | | | | | -------------------------- ------------------------------ | | | | | | |L3 [1]Register [1]Register [1]Register [1]Register [1]Register | for for for for for | LDT ST LUT TT LDT | | | | | | | | | | | | v v v v v v -------------------------------------------------------------------- ^ | | | | v | -------------------------------------- | | Make an entry in the Trigger Table | | -------------------------------------- | | |L2 | | v | ----------------- | | Trigger Table | | -------------------------------------------------- | |Index| PID |Trigger Type|Interface ID |Pointer| | -------------------------------------------------- ---------- | | 1 | PID1 | LDT | CDMA | ------|----> |LDT Data| | -------------------------------------------------- ---------- | | 2 | PID1 | ST | CDMA | ------|----> |ST Data| | -------------------------------------------------- ---------- | | 3 | PID2 | LUT | WLAN | ------|----> |LUT Data| | -------------------------------------------------- ---------- | | 4 | PID2 | TT | WLAN | ------|----> |TT Data| | -------------------------------------------------- ---------- | | 5 | PID2 | LDT | WLAN | ------|----> |LDT Data| | ------------------------------------------------------------------ v -------------------------------------------------------------------- Singh et. al. Expires - March 2003 [Page 5] draft-singh-l2trigger-api-00.txt October 2002 Step 2: L2 Notifies L3 L2 must notify L3 whenever the registered event takes place. L2 must detect the L2 Trigger events and notify L3 if the event is registered by L3. For example, L2 will detect the Link Down event as soon as MN looses its L2 link and L2 will detect the Link Up event as soon as MN establishes its L2 link. A user defined signal will be used to notify the L3. Step 3: Get Trigger Data The registered processes will receive a signal from L2, indicating the L2 Trigger Type. The L3 module has to use the get_trigger_info() API to get the detailed trigger data. The trigger data contains information like MNs L2 address, oAR address, nAR address, which is used to do the L3 handoff. Figure 2: L2 Notifies L3 and L3 Gets trigger data --------------------------------------------------------------------- ^ | -------------------------- ------------------------------ | | Process1 | | Process2 | | -------------------------- ------------------------------ | ^ ^ ^ ^ |L3 | | | | | | | | | | [2]SIGNAL [3]Get Trigger [3]Get Trigger [2]SIGNAL | | Info Info | v | | | | --------------------------------------------------------------------- ^ | | | | | ----------------------------------------------------------- | | L2 Trigger Handler | | ----------------------------------------------------------- | | | | | | | v v | | | ------------------------------------- | | | |Read Trigger Info using the Pointer| | | | |from Trigger Table and pass it to | | | | |the invoked process | | | | ------------------------------------- | |L2 | | | ------------------------------- ------------------------------- | | Notify the Process by PID | | Notify the Process by PID | | | who has registered for LUT | | who has registered for LDT | | ------------------------------- ------------------------------- Singh et. al. Expires - March 2003 [Page 6] draft-singh-l2trigger-api-00.txt October 2002 | ^ ^ | | | | | | | ------------------------- ---------------------------- | |Detect CDMA Link is up | | Detect WLAN Link is down | | ------------------------- ---------------------------- v --------------------------------------------------------------------- _____________________________________________________________________ Step 4: Deregister API used by L3 module to clean up the registry entries made in the Trigger Table. After L3 deregisters using deregister() API call, no L2 trigger notification will be sent to that L3 module. L2 should do all necessary clean up when this function is invoked by L3. Figure 3: Deregister --------------------------------------------------------------------- ^ | -------------------------- ------------------------------ | | Process1 | | Process2 | | | Terminates | | Terminates | | -------------------------- ------------------------------ |L3 | | | | | | | | | [4]deregister [4]deregister | | | | | | v | | --------------------------------------------------------------------- ^ | | | | | | v V | ------------------------------------------------- | |Delete all entries or requested entry from | |L2 |the Trigger Table | | ------------------------------------------------- | | v --------------------------------------------------------------------- The above scenario describes (figure 1-3) the case where L2 and L3 modules are on the same logical entity. Singh et. al. Expires - March 2003 [Page 7] draft-singh-l2trigger-api-00.txt October 2002 The other scenario is where L2 and L3 modules may be on different logical entities at different physical locations. In such cases, a protocol for L2-L3 communication may have to be defined. Definition of such protocol is out of scope for this document. During initialization, L3 notifies L2 of its interest in receiving trigger notifications by calling trig_register () API, with the appropriate trigger parameters. L3 must call trig_register () for each type of L2 trigger event for which notifications are anticipated. L2 keeps track of L3 process-specific data in a structure known as the L2 Trigger Table. An example of an L2 TT is shown in Figure 4 below. Figure 4: L2 Trigger Table -------------------------------------------------------------------- |Index|PID |Trigger Type|L2 Interface ID|Pointer to Trigger Data | -------------------------------------------------------------------- | 1 |PID1| TT | CDMA IF (eth0)|-->(MN L2 addr, oAR addr, | | | | | | nAR addr) | -------------------------------------------------------------------- | 2 |PID2| ST | CDMA IF |-->(MN L2 addr, oAR addr, | | | | | | nAR addr) | -------------------------------------------------------------------- | 3 |PID2| LUT | WLAN IF |-->(MN L2 addr, oAR addr, | | | | | | nAR addr) | -------------------------------------------------------------------- | 4 |PID2| LDT | WLAN IF |-->(MN L2 addr, oAR addr, | | | | | | nAR addr) | -------------------------------------------------------------------- Trigger Data may be different for different triggers. L2 maintains a trigger queue for each L3 module. Upon L3's request, it returns trigger data from the head of the queue. During registration, L3 provides information that is used by L2 to populate the L2 Trigger Table. The L2 trigger handler later uses this information to notify the appropriate L3 module about the occurrence of trigger events. In Figure 4, the first entry contains information about a Target Trigger. L2 interface ID is the name of the interface (eth0) on which the trigger is expected. This value can be numeric or alphanumeric. The PID is the process ID of the L3 module that registered to receive notification for a Target Trigger. The trigger data structure contains information specific to the Target Trigger, for example, the L2 address of MN and IP address of the nAR. The trigger specific information is populated in the Trigger Table by L2, whenever a Target Trigger is received at eth0 interface and a real time trigger notification signal is sent to L3 module with the process identifier Singh et. al. Expires - March 2003 [Page 8] draft-singh-l2trigger-api-00.txt October 2002 PID. In case multiple L3 modules register for a Target Trigger, all of them will receive notification. L2 also maintains a queue of received triggers - one for every L3 module. Upon receiving the notification, L3 queries L2 to obtain trigger data by calling get trigger_info(). L2 then retrieves data for the trigger at the head of that L3 module queue and returns it to L3. 4. Design Consideration Following sections describe the detailed design of the L2 Trigger API. 4.1 Data Types and Definitions Data types in this document follow the Posix .1g format: uint_N_t means an unsigned int of exactly N bits (e.g. uint32_t). The data types of structure elements are intended to be examples, not absolute requirements. 4.2 Structures The members shown in structures are ones that MUST appear in an implementation. Additional non-standard members MAY also be defined. The trigger-specific structures are designed based on the parameters in [1]. 4.2.1 Mobile Trigger A structure that can hold parameters required for a Mobile Trigger is defined as follows: 4.2.1.1 Definition struct mob_trig_param { uint32_t nAR_ipaddr; }; 4.2.1.2 Member Description The 'nAR_ipaddr' field contains the new AR's IP address, which is used as an identifier for the new AR. 4.2.2 Source Trigger A structure that can hold parameters required for a Source Trigger is defined as follows: 4.2.2.1 Definition struct src_trig_param { Singh et. al. Expires - March 2003 [Page 9] draft-singh-l2trigger-api-00.txt October 2002 uint32_t nAR_ipaddr; uint32_t MN_ipaddr; }; 4.2.2.2 Member Description The 'MN_ipaddr' field contains the MN's IP address, which is used as an identifier for the MN. The 'nAR_ipaddr' field contains the new AR's IP address, which is used as an identifier for the new AR. 4.2.3 Target Trigger A structure that can hold parameters required for a Target Trigger is defined as follows: 4.2.3.1 Definition struct tar_trig_param { uint32_t oAR_ipaddr; uint32_t MN_ipaddr; }; 4.2.3.2 Member Description The 'oAR_ipaddr' field contains the old AR's IP address, which is used as an identifier for the old AR. The 'oAR_ipaddr' field contains the old AR's IP address, which is used as an identifier for the old AR. 4.2.4 Link UP Trigger A structure that can hold parameters required for a Link Up Trigger is defined as follows: 4.2.4.1 Definition struct lu_trig_param { uint32_t MN_ipaddr; }; 4.2.4.2 Member Description The 'MN_ipaddr' field contains the MN's IP address, which is used as an identifier for the MN. Singh et. al. Expires - March 2003 [Page 10] draft-singh-l2trigger-api-00.txt October 2002 4.2.5 Link Down Trigger A structure that can hold parameters required for a Link Down Trigger is defined as follows: 4.2.5.1 Definition struct ld_trig_param { uint32_t MN_ipaddr; }; 4.2.5.2 Member Description The 'MN_ipaddr' field contains the MN's IP address, which is used as an identifier for the MN. Although this structure is defined the same as the one in the previous section, it is provided as a means to differentiate between the two in case implementation-specific members are added. 4.2.6 Trigger Table A structure for the L2 Trigger Table is defined as follows: 4.2.6.1 Definition struct trig table { uint16_t index; char intf_id [MAX_SZ_INTERFACE_NAME]; uint16_t type; (Since trig_data already has the trigger type, having a separate type field in this structure may be redundant) pid_t pid; void *trig_data; }; 4.2.6.2 Member Description The 'index' field contains the handle that is returned to L3 by trig_register (). This is unique and sequentially increasing. The 'intf_id' field is an array that can contain a numeric or alphanumeric interface identifier. MAX_SZ_INTERFACE_NAME is implementation defined. The 'type' field holds the trigger type. The 'pid' field contains the process identifier for the L3 process. Singh et. al. Expires - March 2003 [Page 11] draft-singh-l2trigger-api-00.txt October 2002 The 'trig_data' field holds the trigger data that L2 receives with the trigger. 5. Trigger Functions The L2 trigger functions can be categorized into two classes, those used to register for a trigger and those used to retrieve data once a trigger notification signal arrives. 5.1 Registration Functions These routines are used by L3 to register/deregister for specific triggers with L2 trigger handler module. Three functions have been defined namely trig_register(), deregister() and modify_register 5.1.1 trig_register () Prototype : uint16_t trig_register (char *intf_id, uint16_t type, pid_t pid); Description : This function is called by L3 to register a trigger event with L2 trigger handler module. It returns a non-zero integer t_handle on success or 0 on failure. When this function is first called, a new entry is created in the Trigger Table and populated with the L2 interface id, trigger type and process id. Also, memory is allocated for trigger information structure and its pointer is stored in the Trigger Table entry. The return value uniquely identifies this particular entry and can later be used by L3 to deregister () or modify_register (). Parameters: intf_id points to a character array that contains the name of the interface on which trigger is expected. type is the trigger type for which L3 is registering. e.g. source, target etc. pid is the L3 process identifier L2 uses to send a trigger notification signal. 5.1.2 deregister () Prototype : Singh et. al. Expires - March 2003 [Page 12] draft-singh-l2trigger-api-00.txt October 2002 int deregister (uint16_ t t_handle, pid_t pid); Description : This function must be called by L3 to deregister a specific trigger event with the L2 trigger handler module. Upon successful de-registration it returns 0 or -1 on failure. L3 uses this function to remove the Trigger Table entry associated with the passed-in index t_handle. This function de-allocates memory allocated after trig_register function call. Its behavior is dependent on the values of the parameters that are passed to it. If the pid is NULL, only the entry corresponding to t_handle will be deleted. If t_handle is NULL, all triggers corresponding to the process with pid will be deleted. Parameters : t_handle is a non-zero integer identifying the trigger to deregister. pid is the process identifier of the L3 process. 5.1.3 modify_register() Prototype : int modify_register (uint16_t t_handle, char *intf_id, uint16_t type, pid_t pid); Description : This function is called by L3 to modify a specific trigger entry in the L2 Trigger Table. It returns 0 on success or -1 on failure. L3 calls this function to modify any of the information associated with a particular trigger that it registered for. Based upon the parameters, L2 modifies the data in the Trigger Table to reflect the changes. Parameters : t_handle is a non-zero integer identifying the trigger to deregister. intf_id points to a character array that contains the name of the interface on which trigger is expected. Singh et. al. Expires - March 2003 [Page 13] draft-singh-l2trigger-api-00.txt October 2002 type is the trigger type which L3 is interested in modifying. pid is the process identifier of the L3 process. 5.2 Retrieval Functions These functions are used by L3 to obtain trigger information whenever a trigger notification signal is received from L2. 5.2.1 get_trigger_info () Prototype : int get_trigger_info (void *trig_param, int *more_flag); Description : This function is called by L3 to retrieve detailed information about the trigger in L2. It returns 0 on success or -1 on failure. Parameters : trig_param is a pointer to void, which points to the trigger data. more_flag is set by L2 if more trigger events for this L3 application are pending in the L2 trigger queue. 6. Sample Usage The following pseudo-code illustrates a sample usage of the L2 trigger API. #include #include /* Contains the type definitions for L2 trigger API */ int retval,sigval; sigset_t look_for_these; int sig, i, more_flag=0; pid_t pid; uint16_t handle0; struct tar_trig_param *target_trig_msg; struct src_trig_param *source_trig_msg; void *trigger_params; /* Get pid of L3 process */ Singh et. al. Expires - March 2003 [Page 14] draft-singh-l2trigger-api-00.txt October 2002 pid = getpid(); /* Allocate memory for data structures */ /* struct gen_trig_param is assumed to be long enough to hold the L2 data returned by L2 */ trigger_params = (void *)malloc(sizeof(struct gen_trig_param)); /* Register for triggers */ handle0 = trig_register (xl0,source trigger,pid); /* Modify previous trigger registration */ modify_register (handle0, xl0, target trigger, pid); retval = sigemptyset(&look_for_these); /*Add user-defined signal for L2-L3 signalling to the signal set */ retval = sigaddset(&look_for_these,SIGUSR1); retval = sigprocmask(SIG_BLOCK,&look_for_these,NULL); while(1) { sigval = sigwait(&look_for_these,&sig); if (sigval != 0) continue; /* If we get a signal from L2, obtain detailed trigger information */ do { retval = get_trigger_info(trigger_params, &more_flag, pid); if (trigger_params == target trigger ) process_target_trigger(trigger_params); } while (flag == 1); } /* L3 deregisters for all triggers */ deregister (NULL, pid ); 7. Security Considerations There is no additional security threat introduced by this proposed L2 API. 8. References 1 Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997 2 Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997 3 Rajeev Koodli, "Fast Handovers for Mobile IPv6", Internet Draft. 4 Karim El Malki,Pat R. Calhoun, Tom Hiller,James Kempf,Peter J. McCann,Ajoy Singh,Hesham Soliman,Sebastian Thalanany., "Low Latency Handoffs in Mobile IPv4". Internet Draft. Singh et. al. Expires - March 2003 [Page 15] draft-singh-l2trigger-api-00.txt October 2002 5 James Kempf, Daichi Funato, Karim El Malki, Youngjune Gwon, Mattias Pettersson, Phil Roberts, Hesham Soliman, Atsushi Takeshita, Alper Yegin., "Requirements for Layer 2 Protocols to Support Optimized Handover for IP Mobility". 6 R.Gilligan, S.Thompson, J.Bound, W.Stevens, "Basic Socket Interface Extensions for Ipv6 ", RFC 2133, April 1997 7 W.Stevens, M.Thomas, "Advanced Sockets API for Ipv6 ", RFC 2292, February 1998 9. Author's Addresses Kamel Baba 1501 West Shure DR Arlington Heights, IL-60004 Email:kbaba1@email.mot.com Jack Cheng 1501 West Shure DR Arlington Heights, IL-60004 Email:Jack.Cheng@motorola.com Rodrigo Diaz 1501 West Shure DR Arlington Heights, IL-60004 Email:Rodrigo.Diaz@motorola.com Shravan Mahidhara 1501 West Shure DR Arlington Heights, IL-60004 Email:shravan@motorola.com Ajay Mehta 1501 West Shure DR Arlington Heights, IL-60004 Email: ajay.mehta@motorola.com Venkatesh Pandurangi 1501 West Shure DR Arlington Heights, IL-60004 Singh et. al. Expires - March 2003 [Page 16] draft-singh-l2trigger-api-00.txt October 2002 Email: venkatesh.pandurangi@motorola.com Ajoy Singh 1501 West Shure DR Arlington Heights, IL-60004 Email: asingh1@email.mot.com Singh et. al. Expires - March 2003 [Page 17]