This file contains a description of the cello-specific system calls and their usage. There are ten cello specific system calls which have been added to the kernel namely : These are available to any user cello_open cello_close cello_read cello_write cello_set_class cello_get_class These are available for use only to the root cello_start cello_stop cello_admin cello_round The description of each of the system calls : 1. cello_open : __________ long cello_open(const char * filename, int flags, int mode, int app_class) This is a modification of the open system call. The description of the first three fields is the unchanged. There is an additional field which allows one to specify the application class (app_class) in which the file is to be opened. Any I/O's corresponding to the file descriptor returned by cello_open will then get queued by the queue corresponding to app_class. The application class could be one of Interactive best effort (IBE), Throughput-intensive best effort (TIBE) or Real time class (RTP). These are defined in . The values of the three are IBE 1 TIBE 2 RTP 3 One could either use 1, 2, 3 etc. to define the class or the constant definitions IBE, TIBE, RTP etc. to define the class. If the user uses the plain system call open, the job gets serviced through the IBE queue. Also, if the user specifies a value other than 1,2,3 it defaults to the IBE class. The return value has the same meaning as in open. 2. cello_close : __________ long cello_close(unsigned int fd) This is a modification of the close system call. This call basically de-allocates cello specific memory allocated in the file structure in the open system call. The plain close system call has also been modified to de-allocate any such memory allocated in the cello_open system call, to take care in the event that the user opens the file using cello_open and closes it using the close system call (instead of cello_close). The return value has the same meaning as in close. 3. cello_read : __________ ssize_t cello_read(int fd, void *buf, size_t count, int deadline) This is a modification of the read system call. This has an additional argument (int deadline). In the case the file has been opened associated with the real-time class, this argument helps the user specify the deadline of the request. The deadline should be specified in jiffy units that is tens of ms. So, a value of 1 would mean the deadline is 10ms. In the case a negative deadline is specified, the deadline is taken to be 100 jiffies or 1000 ms or 1 sec. In the case the user has associated a file with an application class and does not specify the deadline in the case of the real time class the deadline is taken to be 200 jiffies or 2 secs. In the case of the IBE or TIBE class the deadline is ignored. (and replaced with a high value of 10 mins). The return value has the same meaning as in read. 4. cello_write : ___________ ssize_t cello_write(int fd, void *buf, size_t count, int deadline) This is a modification of the write system call. The description for the additional argument deadline is the same as in cello_read above. The return value has the same meaning as in write. 5. cello_set_class : _______________ int cello_set_class(pid_t pid, int x) This a cello specific system call which allows the user to associate all I/O's for a process with PID pid with application class x (IBE, TIBE or RTP). This is done by modifying a variable cello_class added to the task structure. The default value for this is 0, which means that all I/O's for the process will default to the IBE class. All children of this process would also be associated with the same class x, unless the class is changed by an exclusive call to the cello_set_class for some child process. This call can only be made by the owner of the process or root, otherwise it returns a -1. The call returns 1 on success and -1 on failure. It returns failure if the process does not exist or the above mentioned reason. 6. cello_get_class : _______________ int cello_get_class(pid_t pid) This system call helps the user query the class associated with a process. This call can only be made by the owner of the process or root, else it returns a -1. The call returns the class associated with the process (0,1,2 or 3) on success and -1 on failure. It returns failure if the process does not exist or the above mentioned reason. 7. cello_start : ___________ int cello_start(int major, struct cello_devparams *cello_d_user) This system call can be made only by root. This call sets up the cello scheduling hierarchy for a device with major number "major". The "struct cello_devparams" is used to provide to the kernel the device parameters for which cello disk scheduling is desired. The structure as defined in is as follows. struct cello_devparams{ int diskParam_bytesSector; int diskParam_sectorsTrack; int diskParam_tracksCyl; int diskParam_numCyl; double diskParam_minSeek; // Single Cylinder Seek time double diskParam_avgSeek; // All are in ms double diskParam_maxSeek; double diskParam_rotLatency; double diskParam_maxXfrRate; // MB / sec double diskParam_A, diskParam_B, diskParam_C; }; The variables in the structure are self-explanatory. The call returns 1 on success and -1 on failure. Note that after this call has been made successfully, all I/O's made by kernel processes get served through the IBE class. The cello thread is started with a round duration of 3 seconds and weights for each class as 1. These can be changed using the cello_admin and cello_round system calls (see below). The call could fail for one of the following reasons in order : The caller is not root. There is no request queue for this device. The cello thread for this device already exists. No memory left to allocate for the cello specific storage. 8. cello_stop : __________ int cello_stop(int major) This system call can only be made by root. The call can be used to stop the cello scheduling hierarchy for the device with major number "major". The call returns 1 on success and -1 on failure. The call could fail for one of the following reasons in order : The caller is not root. There is no request queue for this device. The cello thread for this device does no exist. 9. cello_admin : ___________ int cello_admin(int major, int w_IBE, int w_TIBE, int w_RTP) This system call can only be made by root. The call can be used to modify the weights of the application classes. The call is made for the device with major number "major" and the new weights desired for the classes IBE, TIBE and RTP are w_IBE, w_TIBE and w_RTP respectively. The change in weights take effect when the next round begins. The call returns 1 on success and -1 on failure. The call could fail for one of the following reasons in order : The caller is not root. There is no request queue for this device. The cello thread for this device does no exist. 10. cello_round ___________ int cello_round(int major, int round_length) This call can only be made by root. The call can be used to modify the round duration over which disk bandwidth is partitioned. The call is made for the device with major number "major" and "round_length" is the desired round duration in ms (milli-seconds). So, 2000 corresponds to a round duration of 2 sec. The minimum value of the round duration is 1 second. If a lower value is specified it is ignored and the round duration is taken as 1 second. The change in round duration takes effect only when a new round begins. The call returns 1 on success and -1 on failure. The call could fail for one of the following reasons on order : The caller is not root. There is no request queue for this device. The cello thread for this device does no exist. _________________________________________________________________ A note on usage : _______________ The usage of cello_open, cello_close, cello_read and cello_write follows from the usage of open, close, read and write system calls. For the usage of the other system calls a utility is provided in cello_config.c Refer to the files newcall.c newcall.h cello_config.c To be able to use the aliases IBE, TIBE and RTP one has to include the header file To be able to specify the device parameters using struct cello_deviceparams for the cello_start system call one has to include While using the cello-specific calls edit your_run and replace "yourfilename" with the name of the your file in which you make cello specific system calls. And replace "yourexecutable" with the name you desire for your executable. For an example see cello_run/cello_config.c and sample_run/sample_cello.c. _________________________________________________________________