Kernel Ring Buffer Project

by: burt rosenberg
at: university of miami
date: sep 2015
NAME
    rb_ioctl, rb_enqueue, rb_dequeue -- syslog, and ring buffer
    
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:
    	1 - return 1 if ring buffer is empty, 0 else.
    	2 - return 1 if ring buffer is full, 0 else.
	
    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 8.
    

HISTORY
    Introduced as Project 2 in CSC 421 session 151.

BUGS
    The code might not be thread safe; however see project 5 and 6.
  
-------------------
  
NAME
    my_syslog -- kernel syslog system call
    
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.

HISTORY
    Introduced as Project 2 in CSC521 session 131.
	
BUGS

Goals

The goals of this project are:

Specific steps

  1. Refer to class/proj4 for template files. Copy them into your _user_/proj4 directory as a starting point for your code.
  2. Modify the kernel files as required, and move the syscalls.c file into the kernel, as required. Build and install the new kernel.
  3. Using the given mysyslog-test, test my_syslog.
  4. Implement the code for the ring buffer; build, install, and test.
  5. Test the ring buffer using the Basic Test suggested by the Makefile.
  6. Do further testing to reasonably insure the correct implementation of the specified behavior.
Please commit:
  1. Run the kernel-diffs target, and add and commit the four _.diff files that result.
  2. A copy of your mysyscalls.c file.
  3. The modified files that are run as user files and are used in the test target:
    1. myringbuffer-test.c,
    2. mysyslog-test.c,
    3. mysyscall-test.h.
  4. Do not commit binaries, or your .out file.

Discussion

Please refer to the adding a syscall page for an overview.

You will need to modify the following files:

  1. KH/kernel/Makefile
  2. KH/include/linux/syscalls.h
  3. KH/arch/x86/syscalls/syscall_32.tbl
Where KH is the root of your linux source tree. On my machine it is: 
	KH= /usr/src/linux-source-3.13.0/linux-source-3.13.0

In order that your Makefile record the changes that you made, first copy each of these files to a file in the same directory, with the extension ".dist" appended. For instance, copy KH/kernel/Makefile to KH/kernel/Makefile.dist.

If this is done properly, (and the KH macro is corrected in the Make file), then make kernel-diffs will give the kernel diffs that you must submit for full credit for the project.

You kernel code will go into a new file KH/kernel/mysyscalls.c in the kernel source tree.

The diff of syscall_32.tbl should be as follows: 

+355    i386    my_syslog               sys_my_syslog
+356    i386    rb_ioctl                sys_rb_ioctl
+357    i386    rb_enqueue              sys_rb_enqueue
+358    i386    rb_dequeue              sys_rb_dequeue

Making these changes, you should be able to build a kernel that proves itself using make run-syslog.

You can then proceed to add code to kernel/mysyscalls.c to implement the ring buffer.

You have experience with the ring buffer, because of your previous assignment. In order not to deal with malloc in the kernel, the ring buffer struct, as well as the ring buffer buffer, will be static. That data structure and #define's are given to you in the template C file.

The files you will find in class/proj4, to serve as templates, are:

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

author: burton rosenberg
created: 27 sep 2015
update: 3 oct 2015