Extending TokenMAC

Recall in the 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 wlan_mac_high.c​ and 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:

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:

    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:

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.

        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;

---

Next, we need to make a small addition to an existing struct definition that tracks details about each associated device to an AP. The reasons behind this addition will be clear once we make our changes to the AP code. In the meantime, find the definition of station_info in wlan_mac_high.h​. Simply add the following element somewhere after the MY_STATION_INFO_COMMON_FIELDS:

u8  token_res_mult_factor;

Next, let us add a few new definitions that will act as parameters for our new TokenMAC extensions. The easiest place to add these is to the top of [browser:ReferenceDesigns/w3_802.11/c/wlan_mac_high_framework/include/wlan_mac_high.h wlan_mac_high.h]. This will ensure that both the MAC High Framework as well as the AP has visibility of these definitions.

#define TOKEN_RES_MULT_FACTOR_MIN 1
#define TOKEN_RES_MULT_FACTOR_MAX 50

#define DEFAULT_RESERVATION_DURATION_USEC 2000

//Ignoring all overhead, a 6 Mbps PHY rate
//could theoretically deliver (6e6*2000e-6) = 12 kBytes
//in 2ms. Let's define our "success" threshold at (an arbitrary) 1/6 of that: 2000 bytes.
//Delivering more than this threshold in 2ms will grant access to the larger
//token reservation period
#define TOKEN_RES_BYTES_EFFICIENCY_THRESH 2000

Note that we moved the DEFAULT_RESERVATION_DURATION_USEC definition to the above code snippet. We will remove it from the AP code in the next section.

Finally, we should set this new token_res_mult_factor field to TOKEN_RES_MULT_FACTOR_MIN whenever a station_info is created. To do this, add the following line to wlan_mac_high_add_association() just prior to the entry->data = (void*)station; line.

station->token_res_mult_factor = TOKEN_RES_MULT_FACTOR_MIN;

---

Access Point (AP)

Changes should be made to wlan_mac_ap.c​.

---

First, we need to add a few global variables to the top of the AP code. Add the following code snippet:

u8      token_addr[6];
u64     token_ap_num_tx_bytes;
u8      token_ap_res_mult_factor;

u64     token_sta_num_rx_bytes_start;

We will use these variables in the coming sections. Furthermore, add the following line somewhere in the AP's main() function to give it a sane default:

token_ap_res_mult_factor = TOKEN_RES_MULT_FACTOR_MIN;

---

Next we will let set_new_reservation set the reservation duration as a function of a per-station multiplication factor. In the existing function find the ipc_payload.res_duration = DEFAULT_RESERVATION_DURATION_USEC; line within the if(curr_station_info_entry == NULL){ clause. Replaces this line with

ipc_payload.res_duration = DEFAULT_RESERVATION_DURATION_USEC * token_ap_res_mult_factor;

Here, token_ap_res_mult_factor is the top-level variable we just added. If we make no other changes, then this value will be fixed at TOKEN_RES_MULT_FACTOR_MIN.

---

Characterizing Extended TokenMAC

TokenMAC	Extended TokenMAC

1. Transition A: Beginning of Time

Extended TokenMAC: Transition A Timeline

2. Transition B: Start of a Contending Traffic Flow

Extended TokenMAC: Transition B Timeline

3. Transition C: Removal of a Contending Traffic Flow

Extended TokenMAC: Transition C Timeline