A. APIs

A.1 API Classification

The APIs are primarily classified as:

• User exposed
  • Slice management service
  • Radio management service

• Internal
  • System Administration API
  • SM-Datapath API
  • RM-Datapath API
  • BSFB-Datapath API

User exposed APIs are those that will be available to slice users for allowing experiment configuration and permitting smooth automated experimentation. This API will allow the users of a virtualized system to have a standard interface for common activities while being independent of the technology used underneath. An example could be, that irrespective of the virtualization technology used to create virtual machines (KVM, OpenVZ or Xen), all standard API calls will allow the user to work oblivious to the underlying details. Slice management APIs allow the user to configure slice parameters such as settings of the VM. Radio resource management (RRM) parameters allow the user to monitor radio level information such as per client MCS.

The other set of APIs are classified as internal API. These API are useful for understanding the interaction between different components of the system and provide means for appending or changing functionality of the system. The SM-Datapath API describes the API used for communication between the slice manager grid service and the datapath controller. The RM-Datapath controller describes the API used for interaction between Radio resource grid service and the datapath generator. The BSFB-Datapath API is the API used for interaction between the BS Feedback mechanism, which is a part of the customized NEC R6 controller and the datapath manager.

The API specification is classified based on functionality. Each category of APIs has both:

• getters – responsible for reporting based on specified control information, and
• setters – responsible for setting the specified control information.

A.2 API Usage

A.2.1 Sample Experiment Setup Using API

A sample usage of the API for experiment setup is as shown in the Figure below.

As shown in the figure, the most basic tasks involve two operations:

1. Requesting the slice manager to create and start the slice – createSlice()
2. Adding a mobile client to the slice through the addClient() call.

On the completion of these two API and after the client registers with the system, the slice manager service should inform the Slice that the datapath setup is complete. Completion of the datapath setup indicates that there is a L2 link from the slice virtual machine to the mobile client. The addclient() API has an optional service class parameter that the user can specify. If the user does not specify the service class id, a default service class is allocated that has a single best effort type of service flow. After this sequence is complete, the user can direct traffic to the local virtual interface in the VM with the appropriate MAC address, and traffic will be automatically sent to the correct wireless client.

A.2.2 Sample Experiment: Custom Service Class Control

To demonstrate how the user could possibly create custom service classes we show an example of how system components will interact in the Figure below.

The process starts when the user requests the radio manager grid service for creation of a custom service class. As a part of this request we are assuming that the user intends to create the new service class using existing pre-defined service flows. The installation supports 5 pre-defined service flows which represent a typical setting with every traffic type. The user could also define a custom service flow and include it as a part of its customized service class. If the service class request by the user is valid, and all flows requested as a part of the service class request are valid, the system assigns the service class a service class id (SCID). The RM service will create an internal record of the service class parameters when it assigns the service class id (SCID). The slice user can actually start using the service class only after invoking the installServiceClass(MAC, SCID) API. This results in the addition of all service flows for the client by the modified BS controller, and appropriate datapath mapping by the datapath controller. In the illustration we see the addition of two service flows when the SCID is being installed for the MAC.

A.3 System Administrator API Specification (Internal)

These set of functions are exposed to the system administrator for managing and monitoring slice quotas from a virtualization perspective. More administrative functionality is provided on the RF side as discussed in the BS-RF API.

A.3.1 VM Administration

setSliceParams(SLICEID, disk_quota, cpu)

• This function is provided to the administrator for setting up slice level parameters such as total disk / cpu quota assigned to a slice.
• Successful setting of these parameters returns “ok”

getSliceParams(SLICEID)

• This function is provided to the administrator for getting slice level parameters such as total disk/CPU quota assigned to a slice.
• Online information such as current usage is also be made available.
• Returns XML with appropriate parameters on success, “nok” otherwise.

getTotalParams(SLICEID)

• This function is provided to the administrator for getting information on total available resources, such as disk space/ cpu quota available for allocation.
• This function is typically used by the administrator before the use of setSliceParams() function.
• Returns XML with appropriate parameters on success, “nok” otherwise.

A.4 Slice Manager API Specification (User Exposed)

The slice manager API are further classified into

1. VM control functions and
2. Client control functions.

A.4.1 SLICE (VM) Control Functions

These set of functions are responsible for managing context isolation of multiple slices through the use of virtual machines.

createSLICE

This function is invoked from a gateway machine by the slice user to instantiate its slice for experimentation.

createSLICE(used_id, passwd, image_type)
  - user_id is username used in slice creation.
  - passwd is password used for slice creation.
  - image_type is an integer which specifies the distribution to be loaded on the disk of the virtual machine.
	  image_type = 1 loads a Debian disk image
	  image_type = 2 loads a Ubuntu disk image
	  image_type = 3 loads a Fedora disk image
  - Return the IP of the SLICE to which the user can log into (when successful)
  - Failure returns “nok”, success returns SLICEID.

destroySLICE

This function is used to destroy instance of the SLICE for which IP is assigned; slice is destroyed only after authentication of the used_id and passwd.

destroySLICE(user_id, passwd, IP)
  - user_id is username used in slice creation.
  - passwd is password used for slice creation.
  - Returns status “ok” if command was executed correctly, “nok” otherwise.

startSLICE

This function is used to start the slice for which IP is assigned; can be invoked only after the the createSLICE() call is made and is successful only if the instance is owned by the issuing user. .

startSLICE ( SLICEID, user_id, passwd, IP)
- 	Returns status “ok” if command was executed correctly, “nok” otherwise.

stopSLICE

This function is used to stop the instance of the SLICE for which IP is assigned (SLICE instance is stopped only if the instance is owned by the issuing user).

stopSLICE ( SLICEID, user_id, passwd, IP)
- 	Returns status “ok” if command was executed correctly, “nok” otherwise.

setSLICEParams

Allows the user to set all controllable parameters for creation of SLICE. Features include the amount of disk space per SLICE template, percentage of CPU resources (number of parameters supported as a part of this API may vary with underlying virtualization technology).

setSLICEParams (SLICEID, used_id, passwd, tlv) 	
-	Successful setting returns “ok”, “nok” otherwise.

A.4.2 Client Control Functions

These set of functions allow the datapath controller to determine which WiMAX clients can associate with the BTS and vice-versa. These API are internal and are based on the input provided by the slice user.

addClient

This function is called by the user to add a client with MAC address MSID to the slice SliceID.

addClient (MSID, SliceID) 
-	Successful execution of this function returns “ok” from the grid service, “no” otherwise

deleteClient

Used to remove client with MAC address MSID from the slice with identifier as Slice ID.

deleteClient (MSID, SliceID)
-	Successful execution of this function returns “ok” from the grid service, “no” otherwise

A.5 Radio Management API (User Exposed)

These API define the calls that can be made by the system user for controlling radio-related features of the WiMAX system. These API are further classified based on the functionality they provide.

A.5.1 Custom Service Class Support

These APIs will allow the user to create user-defined service flow types apart from the 5 standard service flows supported as a part of the current model.

createServiceFlow(SlideID, direction, priority, classifier-ips, classifier-ports, service_type, service_params)

• Direction – Uplink or downlink for the class.
• Priority – priority of the service class
• Classifier-ips TLV - Source/Destination IP classifiers for flow classification
• Classifier-ports TLV – Source/Destination port classifiers for flow classification.
• Service_type - One of the five types – BE/UGS/rtPS/nrtPS/ertPS
• Service params is the TLV for each service type
• Return type: Service type id - STID (integer) > 6. 1-5 are reserved for the default service flow types.
• Note that the service type is created by the Radio management grid service for

a specific slice ID and hence it will be specific to that slice.

createServiceClass(SlideID,STIDs{})

• SliceID identifies the requesting slice.
• STIDs are the service type ids.
• Success returns the Service class ID (SCID), which can be used in install or remove.

installServiceClass(SlideID,SCID)

• SliceID identifies the requesting slice.
• Installs all the service flows that are part of the service class SCID.
• Success results in end – to – end datapath setup between wireless clients and virtual machine slice.

uninstallServiceClass(SlideID,SCID)

• SliceID identifies the requesting slice.
• Un-installs all the service flows that are part of the service class SCID.
• Success returns ok and nok otherwise.

deleteServiceClass(SlideID, SCID)

• Deletes the service class corresponding to the specification in the request.
• Returns success if the service class could be successfully deleted (none of the

flows are actively using these service classifiers).

deleteServiceFlow(SlideID, STID)

• Results in deletion of service flow type identified by STID if any such flow type exists.
• Success results in “ok” and “nok” otherwise.

A.5.2 Slice Radio Control

setMinimalMcs(SliceID, MSID, SCID, mcs)

• Used to set the minimal modulation and coding scheme (MCS) to be used for

that service class. An auto rate provision will select a better MCS based on the observed CINR conditions.

• The user can chose one among available MCSs as an option for that class.
• We are still exploring the possibility of setting this per class per MSID. As per our

current understanding, this is difficult.

setFixedMcs(SliceID, MSID, SCID, mcs)

• Used to set a fixed MCS for a particular service class.
• This disables the automatic MCS adjustment using measured CINR.
• If possible we wish to set this mcs value per MSID.

setRadioResource(SliceID, MSID, RR)

• Information provided by this function should be consulted during initial ranging and connection setup.
• RR – Radio resource uplink + downlink (set in % - 0 to 100)

setBandwithUlDlRatio(bandwidth UL_DL_ratio)

• Set supported bandwidth: 10M, 7.5M, 5M Hz
• Based on RR allocation in set_radio_resource(), this routine allows the user to set

the uplink-downlink ratio as a fraction of the RR.

• UL_DL_ratio is used as a key to select one among standard UL_DL ratio supported by the BS. All MS has to use the same ul_dl_ratio

A.5.3 Slice Radio Monitoring

getAllClientsInfo( SLICEID )

• Returns the number of WiMAX clients associated with a particular SLICEID.
• Return value ranges between 0 and maximum number of clients that can be owned by a slice on success, “nok” otherwise

getClientInfo(SLICE ID, MSID)

• Returns detailed information about a single client in the network.
• Information for individual MAC address includes the amount of disk quota, disk space used, and the CPU quota (reserved and used).
• Returns XML with appropriate parameters on success, “nok” otherwise

getSliceResource(SLICEID)

• This mechanism allows every slice to monitor its current usage, and the limits
• Values returned may vary based on the virtualization technology used - (disk space, CPU).
• Returns XML with appropriate parameters on success, “nok” otherwise

A.6 SM – Datapath API (Internal)

These set of API are responsible for dealing with the datapath creation after slice initialization and client registration.

addClient(VLAN, MSID)

• This function is invoked by the slice manager after the user requests it to add a client to the slice.
• The slice manager looks up the appropriate VLAN tag number and requests that the MAC MSID of the mobile client be added to the VLAN.
• This API facilitates half of the datapath creation, which will be completed when the MSID associates with the system.

removeClient(VLAN, MSID)

• Compliments the addClient() function.
• On the execution of this call the datapath manager removes the mapping from the slice virtual machine to the wireless mobile client.