CSC421 Kernel Extensions

NAME
    rb_ioctl, rb_enqueue, rb_dequeue -- ring buffer syscalls
    ringbuf -- command line interface to the rb_* system calls
    
SYNOPSIS
    #include "ringbuf.h"
    
    int rb_ioctl(int op) ; 
    int rb_enqueue(int ele) ;
    int rb_dequeue(void) ;
    
DESCRIPTION

    The rb_enqueue syscall takes a single character argument and returns the argument
    if the character can be enqueued, -1 else. For instance, it will return -1 if the
    ring buffer is full. 
    
    The rb_dequeue syscall takes no arguments are returns a single integer value, which
    is the dequeued character, -1 else. For instance, if will return -1 if the ring 
    buffer is empty.
    
    The rb_ioctl takes an integer argument giving the operation, as follows:
    
    Argument value:
        RB_Q_SIZE   - return the size of the ring buffer.
        RB_IS_EMPTY - return 1 if ring buffer is empty, 0 else.
        RB_IS_FULL  - return 1 if ring buffer is full, 0 else.
        RB_Q_COUNT  - return the current number of characters in the ring buffer

    On error, or an invalid argument value, return -1.

    The ring buffer is of fixed size. The kernel needs to be rebuilt if the ring buffer 
    is to be of a different size. For this project, the size is 16.
    

HISTORY
    Introduced as Project 2 in CSC 421 session 151.

BUGS
    The code might not be thread safe.

NAME
    my_monitor -- monitor syscall
    
SYNOPSIS
    #include "mymonitor.h"
    
    int my_monitor(int op) ;
    
DESCRIPTION

    Argument values:
        MONITOR_OP_ENTER  - enter the monitor
        MONITOR_OP_LEAVE  - leave the monitor
        MONITOR_OP_WAIT   - go into a wait while leaving the monitor
        MONITOR_OP_NOTIFY - notify a single thread waiting on in the monitor,
                            the notify is lost if there is no waiting thread. 
        MONITOR_OP_NOTIFY_ALL - notify all thread waiting on the monitor

    The monitor uses Mesa semantics. The notify and notify-all release one or all
    waiting threads, respectively, and the thread or threads contend for re-entry
    into the monitor.

    The caller of notify and notify-all remains in the monitor after the call to 
    notify or notify-all.

    The programmer must guarantee that leave, wait, notify and notify-all are only 
    called by a thread that is in the monitor. The monitor is not assured to be
    re-entrant: the thread in the monitor must not call enter.

HISTORY
    The kernel monitor first appeared as project 3 in csc521.111 (2011-2012).

BUGS
    Reset does not work.

Notes on the monitor API

If a thread attempts to enter a monitor that is occupied, it sleeps until the monitor becomes available. The programer must that care that their code always calls the leave operation on the monitor, else it will remain locked.

If a thread is occupying the monitor but it cannot proceed just yet, but will want to reenter the monitor when signaled, it can call the wait operation. Once in a wait the thread will sleep until a notify or notify-all allows it to content again to enter the monitor. In practice, when the code reaches the line after the wait, the thread has been awakened and as well it has re-entered the monitor.

A thread occupying the monitor can notify a thread waiting the monitor, or notify all threads waiting for the monitor. The notifying thread remains in the monitor after either types of notify, but one or all threads that were waiting at the moment the notify or notify all was issued, are now contending to enter the monitor, once the notifying thread leaves.

If a notify or notify all is issued when there are no waiting threads, the notify is lost.

Because a notify or notify all only begins the process of a thread re-entering the monitor, it is a fault of logic to believe that the thread once re-entered into the monitor must have the situation for which it was notified. For instance, if it were waiting on a character in a buffer, and a character producing thread notifies on the production of one character, the notified thread might not find a character in the buffer once it has re-entered the monitor. Another notified thread could have re-entered first and consumed the character.

CSC421 Kernel Extensions

by: burt rosenbergat: university of miami date: oct 2020

Notes on the monitor API

by: burt rosenberg
at: university of miami
date: oct 2020