Read Me

ushr   userspace Shared memory system
====================================================================================
Author J.Keidel ( WizAnt)
Mail: keidel@users.sourceforge.net
License:  GPL


Driver Function:
====================================================================================

A buffer, created by an application via posix_memalign (malloc) will be tranferred via ioctl
to the driver. Here the memory range is converted into pages and held in an internal structure.
The buffer must be page-aligned and its size should be a multiple of pages.
The stored pages will be presented via the "page-fault"-method to the mmap system, so following
a mmap call, this buffer ist present in user-space with a new address. This address may be
fixed (see man mmap). As the address is held within the driver, any application may mmap
the same pages. It is not recommended to free the buffer before end of the application, as
the malloc system won't recognize, that the physical memory is used by someone else.
Togethe with holding the page-table, some additional information can be held in the internal
structure to identify this shared region. 
It is possible, even from a different task, to expand the memory region later.

Functions:
IOCTL:          SHAR_CREATE             create and initialize a memory region
                SHAR_EXPAND             expand the memory region by new pages
                SHAR_STATUS             retrieve status information
                SHAR_ID                 set the identifying ID
                
MMAP            activate the mapping of previous defined pages
READ/WRITE      retrieve or store 128 bytes of information 
OPEN/CLOSE      open and close the device
FASYNC          add signal creation in case of expansion. All associated tasks should be 
                informed.

At loading the module, a parameter is honored to set the created number of devices,
one device per shared region. shared_devs=n , the default is 4 devices.


Api functions  lib/:
====================================================================================

In order t make the usage a bit easier, a set of functions is prepared to fullfill the 
primary requirements of usage. Using theses functions will avoid several errors which could be
made and it is strongly recommended to use this api.

void *shared_create     (int  *Id   , int *Size , void *Targetaddr);
This function will create a buffer of the requested size, checking if the given id is already
used. If no id given, a random one will be created. The size shall be given in bytes and will be
corrected to a multiple of pages, this one will be returned. If a Targetaddress is given (not NULL)
it will be stored together with id. After creating, the area is transferred to the device
and finally mapped back into user-space, the mapped address is returned.

void *shared_attach     (int   Id   , int *Size);
The given id is searched within all devices of type ushr. If found, the area is mapped in,
either to the stored fixed address or to any address the system will provide. The address is 
then returned.

int   shared_expand     (int   Id   , int  size);
As any user may expand the shared area, this function will do this, First finding an area
with the given id, a additional buffer is created (page-aligned) and added to the page-table
of the actual area. Returned is either 0 on success or a negative value indicating the error.

As shared_create and shared_attach will add a signal handler to remap in case of expanding,
the expansion function will send SIGIO to all tasks sharing the area.

void  shared_setinfo    (int   Id   , void *info, int  size);
void  shared_getinfo    (int   Id   , void *info, int  *size);
The two functions will copy a maximum of 128 bytes to the area, or retrieving the stored info.
The info may be of any type (text, a complete structure or else)

void  shared_getstatus  (char *dev  , int *Id , long int *Target , int *Size , int *infobytes);
returns some status inrmation. as the device is needed, it is mainly used internally.

Demonstration programs  Demo/:

there are three programs to demonstrate the functionality:
test_master creates an area, starts a checking loop for the shared members doing something
and wait for any input . The input is stored into shared memory.
test_slave attaches the area, starts the same checking thread as the master, so printing
all input from the shared area. It waits reading standard input and stores the input into the 
area.
test_slave_expand will do the same as test_slave, but will expand the area first.

master and slave_expand should be started only once, whereas slave may be started several times
in parallel. Start each on in a separate shell, and type in something. this should be printed
from all others. To termina a task, type <cntrl>D.


INSTALLATION:
====================================================================================

driver:
==============

type in "make", this will generate the driver as a module using the linux kernel-build system
using a kenel 2.6.27 or newer will compile without errors, using any older kernel of 2.26.
may result in some warnings. with elder kernels it will NOT compile. 

after compiling you should change to root (su ) and try to load the generated module.
Have a look at the script "load_shared", you may want to modify the device name, but in this case
you have to modify api_shared.h as well. The loading uses shared_devs=4 (which is the default
anyway) If you want to change this, don't forget to add the corresponding mknod's in the script.

Now run: ./load_shared
typing lsmod, you will find the module, if not, please check /var/log/messages for error
notes.

Now, it is a good time to enter the Demo director, compile and link the Demos and try them.

Finally, type make install  to install the driver in the place for the system.
add the load_shared to some script in /etc/init.d, write your own initializer there or
use another method to start the driver.

api:
==============

enter the lib/ directory.
if you want to install somewhere else than /usr/local, edit the Makefile and change the three
definitions in the beginning lines to your target.

Then type "make"

Now you may try the Demo first?

intalling, jest become root and type "make install" in the lib directory.


Demo:
==============

change to the Demo directory and run ./compile
do a "ls" and you should see the three executables: master  slave  slave_expand

create some shell and change to the Demo directory. Run "master" first, than in different shells
"slave". type something in, you should see it in all other shells.
After a while, start "slave_expand" in an other shell, type in something and you should see
it in the other shells. Terminate the tasks by typing <cntrl>d.
If there are no side-effects, check /var/log/messages (or use dmesg) to see any error messages.
If everything is well, continue installing the packet finally.