[[TOC(Internal/WiMAX/WiMAXAPI*, depth=2)]] = A. APIs = == A.1 API Classification and Usage == The APIs are primarily classified as: * User exposed * [wiki:WiMAX/16/3 Slice management service] * [wiki:WiMAX/16/4 Radio management service] * Internal * [wiki:WiMAX/16/1 System Administration API] * [wiki:WiMAX/16/5 SM-Datapath API] * [wiki:WiMAX/WiMAXAPI/05RMDpApi RM-Datapath API] * [wiki:WiMAX/WiMAXAPI/06BSFBDpApi 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.1.1 Sample Experiment Setup Using API === A sample usage of the API for experiment setup is as shown in the Figure below. [[Image(BasicSetup.jpg,600)]] As shown in the figure, the most basic tasks involve two operations: 1. Requesting the slice manager to create and start the slice – [wiki:Internal/WiMAX/WiMAXAPI/aSliceMgmt#createSLICE createSlice()] 2. Adding a mobile client to the slice through the [wiki:Internal/WiMAX/WiMAXAPI/aSliceMgmt#addClient() 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.1.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. [[Image(CustomFlow.jpg,600)]] 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.2 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.2.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. = Slice Manager API Specification (User Exposed) = The slice manager API are further classified into 1. VM control functions and 2. Client control functions. == 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. }}} == 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 }}}