Kernel Ring Buffer Project

by: burt rosenberg
at: university of miami
date: sep 2016

  
   
NAME
    my_syslog -- kernel syslog system call
    mysyslog -- command line interface to my_syslog
    
SYNOPSIS
    takes a string argument, and kernel syslogs th string

DESCRIPTION
    The my_syslog takes a string argument, and kernel syslogs the argument. 
    It always returns 0.
    
    The mysyslog command calls my_syslog on the first argument.

HISTORY
    Introduced as Project 2 in CSC521 session 131.
	
BUGS
   
-------------------
  
NAME
    rb_ioctl, rb_enqueue, rb_dequeue -- ring buffer syscalls
    ringbuf -- command line interface to the rb_* system calls
    
SYNOPSIS
    rb_enqueue enqueues characters to a single, in-kernel ring buffer; re_dequeue 
    dequeues an enqueued character. rb_ioctl implements the control functions return
    if the queue is empty or full, depending on the control argument.

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:
        0 - return the size of the ring buffer.
    	1 - return 1 if ring buffer is empty, 0 else.
    	2 - return 1 if ring buffer is full, 0 else.
    	3 - 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.

Goals

• To build a custom Linux kernel.
• To learn the syscall interface, and to add a system call.
• To interface to the system calls by user programs and libraries.

Specific steps

1. Build the linux kernel. Here are hints.
2. Modify the kernel files to introduce the system calls. Here are hints.
3. Rebuild and reboot on the new kernel.
4. Using the given template files from the class/proj2 folder, you now should have a working my_syslog system call and mysyslog command line program. Test.
5. Implement the ringbuffer system call by modifying the mysyscalls.c file in the kernel. Your work in project 1 is relevant.
6. Rebuild and reboot on the new kernel.
7. Implement the user interface in ringbuf-sub.c. Build ringbuf and test.

Testing and submission

• Test-mysyslog sends the string "hello kernel!" to the system log. It then saves the return value of mysyslog and the most recent occurence of a syslog essage containing "hello kernel!" to a mysyslog.out file. Because the output can vary, there is no mysyslog.ref file. The file mysyslog.out will be judged informally.
• Test-ringbuf runs the ringbuffer test and saves the output to ringbuf.out. The test is the same as project 1, and the provided ringbuf.ref is identical to the one used in project 1. Note however that the implement should be by syscalls to code in the kernel. Because the ring buffer is persistent between runs of ringbuf, it must be emptied for the test. The Empty-ringbuf makefile target empties the ringbuffer by performing 16 dequeue operations.

You will submit "evidence" that your project ran, as well as the sources so that we can reproduce your project.

The makefile target evidence collects the evidence into an evidence.tar file, which you will add and commit to the repository. The evidence includes of the 5 kernel files and the output file:

• kernel/mysyscalls.h
• kernel/mysyscalls.c
• entry/syscalls/syscall_32.tbl
• linux/syscalls.h
• kernel/Makefile
• evidence.out

• Makefile
• ringbuf.c
• ringbuf-sub.c
• ringbuf.h
• mysyslog.c
• ringbuf.ref.

Discussion

Please refer to the in-class discussion concerning this project.

This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

author: burton rosenberg
created: 27 sep 2015
update: 13 sep 2016