[[Include(wiki:802.11/wlan_exp/app_notes/tutorial_token_mac/TOC)]]

[[TracNav(802.11/TOC)]]

= Extending TokenMAC =

Recall in the [wiki:802.11/wlan_exp/app_notes/tutorial_token_mac/characterization characterization section of this tutorial] that we noted a significant weakness in the design of TokenMAC -- when there is no contention between multiple flows, the token reservation periods for idle nodes are wasted. The design really only starts to show any gains when devices are backlogged and have a lot of traffic to send. This isn't a realistic assumption for typical traffic profiles.

In this section, we propose a simple extension to TokenMAC to address this problem. By default, a TokenMAC AP issues a reservation to each device on the network in a round-robing sequence for a fixed {{{DEFAULT_RESERVATION_DURATION_USEC}}} microseconds. Our extension will make this parameter adaptive. Rather than be fixed value, an AP will give longer reservation periods to devices that are actively using the time allocated to them. Conversely, idle or near-idle devices will be given a smaller duration of the medium until they demonstrate a need for more. We can implement this behavior entirely in CPU_HIGH and leave the low-level frame exchange behavior alone. Specifically, will augment the AP so that it audits how well each reservation period is utilized. If this audit deems that the device used a sufficient amount of the allocation given to it, a multiplication factor will increase the duration of the allocation the device's next turn.

== Specific Changes ==

=== MAC High Framework ===

Changes should be made to [browser:ReferenceDesigns/w3_802.11/c/wlan_mac_high_framework/wlan_mac_high.c wlan_mac_high.c] and [browser:ReferenceDesigns/w3_802.11/c/wlan_mac_high_framework/include/wlan_mac_high.h wlan_mac_high.h].

----
CPU_LOW is already configured to send the {{{IPC_MBOX_TOKEN_NEW_RESERVATION}}} IPC message back up to CPU_HIGH as a confirmation when a new reservation period starts. It will also send the {{{IPC_MBOX_TOKEN_END_RESERVATION}}} IPC message up to CPU_HIGH when the reservation period is over (which is how CPU_HIGH currently knows when to rotate to the next device for its reservation period). These messages demarcate the intervals that the AP should audit performance. The first change we will make to the MAC High Framework is to add two new callbacks that will be called upon the reception of these IPC messages. Add the following top-level global function pointers to the MAC High Framework:

{{{
#!c

volatile function_ptr_t      token_stats_start_callback;
volatile function_ptr_t      token_stats_end_callback;
}}}

In {{{wlan_mac_high_init()}}}, make sure to set these callbacks to the default nullCallback with the following two lines of code:

{{{
#!c

	token_stats_start_callback = (function_ptr_t)nullCallback;
	token_stats_end_callback = (function_ptr_t)nullCallback;
}}}

Finally, add the following setters for these callbacks so we can assign them in the AP code:

{{{
#!c

void wlan_mac_high_set_token_stats_start_callback(function_ptr_t callback){
	token_stats_start_callback = callback;
}

void wlan_mac_high_set_token_stats_end_callback(function_ptr_t callback){
	token_stats_end_callback = callback;
}
}}}

Next, we need to call the new callbacks upon the receipt of the two relevant IPC messages. We already have the case of {{{IPC_MBOX_TOKEN_END_RESERVATION}}} from our previous implementation of TokenMAC. This function called the {{{token_new_reservation_callback()}}} function pointer to let the AP know that it should issue a new token reservation period. We want to keep this behavior, but now we should additionally call the new {{{token_stats_end_callback}}} callback. We should also add the {{{IPC_MBOX_TOKEN_NEW_RESERVATION}}} case to the switch statement can call the {{{token_stats_start_callback()}}} function pointer. Furthermore, we should pass the address of the whichever device owns this reservation period as well as the duration of the reservation period as arguments to the call.

{{{
#!c

		case IPC_MBOX_TOKEN_END_RESERVATION:
			token_stats_end_callback();
			token_new_reservation_callback();
		break;
		case IPC_MBOX_TOKEN_NEW_RESERVATION:
			token_stats_start_callback( ((ipc_token_new_reservation*)msg->payload_ptr)->addr,
								   ((ipc_token_new_reservation*)msg->payload_ptr)->res_duration );
		break;
}}}

----

== Characterizing Extended TokenMAC ==

||  [[Image(wiki:802.11/wlan_exp/app_notes/tutorial_token_mac/figs:token_xput.png, width=600)]]  ||  [[Image(wiki:802.11/wlan_exp/app_notes/tutorial_token_mac/figs:token_extended_xput.png, width=600)]]  ||
||  '''TokenMAC'''  ||  '''Extended TokenMAC'''  ||

===  1. Transition A: Beginning of Time  ===

||  [[Image(wiki:802.11/wlan_exp/app_notes/tutorial_token_mac/figs:token_extended_A.png, width=1200)]]  ||
||  '''Extended TokenMAC: Transition A Timeline'''  ||

===  2. Transition B: Start of a Contending Traffic Flow  ===

||  [[Image(wiki:802.11/wlan_exp/app_notes/tutorial_token_mac/figs:token_extended_B.png, width=1200)]]  ||
||  '''Extended TokenMAC: Transition B Timeline'''  ||

===  3. Transition C: Removal of a Contending Traffic Flow  ===

||  [[Image(wiki:802.11/wlan_exp/app_notes/tutorial_token_mac/figs:token_extended_C.png, width=1200)]]  ||
||  '''Extended TokenMAC: Transition C Timeline'''  ||