VisualOS

Programer Reference

Manuel Estrada Sainz

  ranty@atdot.org
  ranty@soon.com

Copyright  2000 by Manuel Estrada Sainz

-------------------------------------------------------------------------------

Table of Contents
1. Introduction
2. SubSystems

    Procesor

        Procesor Interface -- CPU interface to the other subsystems.
        Procesor Configuration -- Internal configuration.
        Procesor Simulation -- Simulation of the processor
        Processes -- Process Handling.
        Processor Status -- Status of the processor.
        Process Queues -- Process Queue Handling.
        Processor Algorithms -- Interface for Algorithms.

    I/O

        IO Interface -- IO interface to the other subsystems.
        Geometry -- Geometry of the device.
        IO Simulation -- Simulation of the device
        Request Queues -- IO Request Queue Handling.
        IO Algorithms -- Interface for Algorithms.
        IO Miscelaneous -- Other interesting functions.

    Memory

        Memory Interface -- MEM interface to the other subsystems.
        Memory Configuration -- Internal configuration.
        Memory Algorithms -- Interface for Algorithms.
        Swap -- Swapping system.
        Memory Status -- Status of the memory.
        Memory Miscelaneous -- Other interesting functions.

    Clock

        Clock Interface -- CLOCK interface to the other subsystems.

    Requestor

-------------------------------------------------------------------------------

Chapter 1. Introduction

This is a programers reference, so you will find lots of C code and tecnical
explanations all of it, as you can see, writen in english, as I spect to share
all this with the rest of the world via The Internet so if you don't what to
modify the code or find out how the program works internaly, then the user
manual will provably benefit you most.

-------------------------------------------------------------------------------

Chapter 2. SubSystems

The program is divided into Subsystems, which communicate with each other via a
messaging facility.

-------------------------------------------------------------------------------

Procesor

Table of Contents
Procesor Interface -- CPU interface to the other subsystems.
Procesor Configuration -- Internal configuration.
Procesor Simulation -- Simulation of the processor
Processes -- Process Handling.
Processor Status -- Status of the processor.
Process Queues -- Process Queue Handling.
Processor Algorithms -- Interface for Algorithms.

This is the subsystem responsable of executing the processes and, usualy, is
the one which generates all activity in the other subsystems as their client.

Procesor Interface

Name

Procesor Interface -- CPU interface to the other subsystems.

Synopsis



void        cpu_register_proc_creat         (proc_creat_callback_t func);
void        cpu_register_proc_finish        (proc_finish_callback_t func);
void        (*proc_creat_callback_t)        (gint pid);
void        (*proc_finish_callback_t)       (gint pid);
void        CPU_terminate_proc              (gint pid);

Description

This functions allow the other subsystems to interact, througth the messaging
service, with the CPU.

Details

cpu_register_proc_creat ()

void        cpu_register_proc_creat         (proc_creat_callback_t func);

Registers func to be called when ever a new process gets created.

          func : function to be called.

cpu_register_proc_finish ()

void        cpu_register_proc_finish        (proc_finish_callback_t func);

Registers func to be called when ever a process is terminated.

          func : function to be called.

proc_creat_callback_t ()

void        (*proc_creat_callback_t)        (gint pid);

Function pointer type for the callback used on cpu_register_proc_creat.

           pid : Process ID of the created process.

proc_finish_callback_t ()

void        (*proc_finish_callback_t)       (gint pid);

Function pointer type for the callback used on cpu_register_proc_finish.

           pid : Process ID of the terminated process.

CPU_terminate_proc ()

void        CPU_terminate_proc              (gint pid);

Terminate process pid.

           pid : Process to terminates.

Procesor Configuration

Name

Procesor Configuration -- Internal configuration.

Synopsis



typedef     cpu_config_t;
extern      const cpu_config_t *CPU_config;
cpu_config_t* get_CPU_config                (void);

Description

This is the way to find out CPU internal configuration.

Details

cpu_config_t

typedef struct {
        gboolean stop_clock;    /* clock should be stoped when something
                                   interesting happens */
        gboolean auto_fill_procs;       /* process properties should be
                                           filled automaticly without any
                                           user interaction */
        prop_io_params_t prop_io_params;   /* current parameters for processes
                                              IO parameters autofilling */
        prop_mem_params_t prop_mem_params; /* current parametes for processes
                                              Memory parametes autofilling */
        struct {                        /* parameters related with the
                                           graphical representation of the
                                           subsystem */
                gint max_graph_history; /* Maximun pixmap width for the
                                           different representations */
                gint pix_size_step;
        } drawing;
} cpu_config_t;

CPU_config

extern const cpu_config_t *CPU_config;

This is a pointer to the configuration data, but should be used only for
reading.

get_CPU_config ()

cpu_config_t* get_CPU_config                (void);

This is the right way to modify the configuration.

       Returns : a writable pointer to the configuration data.

Procesor Simulation

Name

Procesor Simulation -- Simulation of the processor

Synopsis



typedef     simul_data_t;
typedef     simul_io_event_t;
typedef     simul_mem_t;
typedef     event_data_t;
void        init_CPU_simulation             (void);
void        init_CPU_simulation_in_proc     (proc_t *proc);
void        end_CPU_simulation_in_proc      (proc_t *proc);
void        cpy_CPU_simulation_data         (simul_data_t *dest,
                                             simul_data_t *src);
simul_data_t* dup_CPU_simulation_data       (simul_data_t *data);
void        free_CPU_simulation_data        (simul_data_t *data);
void        free_CPU_proc_simulation_data   (proc_t *proc);
void        next_CPU_simulation_in_proc     (proc_t *proc);
gint        CPU_proc_current_page           (proc_t *proc);
gint        CPU_proc_next_page              (proc_t *proc);
gboolean    CPU_proc_current_page_is_write  (proc_t *proc);
void        fix_simulation_in_proc          (proc_t *proc);
#define     IO_BLOCK                        (event)

Description

This functions serve to manage the CPU's simulation and it's data structures.

Details

simul_data_t

typedef struct {                /* simulation data for a process */
        gint start_time;        /* time of creation */
        gint end_time;          /* length of the process */
        /* IO properties */
        /* this list is never modified until process destruction */
        simul_io_event_t *io_events;            /* list of all io events */
        simul_io_event_t *next_io_event;        /* pointer to the next event */
        simul_io_event_t *last_io_event;        /* pointer to the last event */
        /* MEM properties */
        simul_mem_t *pages;     /* list of memory accesses */
        gint n_pages;           /* number of memory accesses */
        gint cur_access;        /* index to the current access */
} simul_data_t;

simul_io_event_t

typedef struct {        /* data for an IO event */
        gint block;     /* block to read */
        gint time;      /* time to read @block */
} simul_io_event_t;

simul_mem_t

typedef struct {        /* data for a page access */
        gint8 page;     /* page to access */
        gint8 write;    /* is it a write access? */
} simul_mem_t;

event_data_t

typedef struct {        /* io event data known by all the code */
        gint io_block;  /* block to access */
} event_data_t;

init_CPU_simulation ()

void        init_CPU_simulation             (void);

Initializes the simulation code.

init_CPU_simulation_in_proc ()

void        init_CPU_simulation_in_proc     (proc_t *proc);

prepares the data structures for simulation in process proc.

          proc : process involved.

end_CPU_simulation_in_proc ()

void        end_CPU_simulation_in_proc      (proc_t *proc);

cleans up simulation data in proc to prepare it for termination.

Note: currently does nothing.

          proc : the process involved.

cpy_CPU_simulation_data ()

void        cpy_CPU_simulation_data         (simul_data_t *dest,
                                             simul_data_t *src);

Copies the contents of src into dest, allocating dynamic memory when needed.

          dest : the target of the copy
           src : the source for the copy

dup_CPU_simulation_data ()

simul_data_t* dup_CPU_simulation_data       (simul_data_t *data);

Duplicates a simul_data_t structure.

          data : a pointer to the data to be copied
       Returns : a pointer to newly allocated memory with the same content of
                 data

free_CPU_simulation_data ()

void        free_CPU_simulation_data        (simul_data_t *data);

Frees all dynamic memory asociated to data, including data itself.

          data : the data to be freed

free_CPU_proc_simulation_data ()

void        free_CPU_proc_simulation_data   (proc_t *proc);

Free all simulation related dynamic memory from the proc structure.

          proc : a pointer to a proc_t structure

next_CPU_simulation_in_proc ()

void        next_CPU_simulation_in_proc     (proc_t *proc);

Once the process had an event it prepares the process for its next event,
making it a termination event if necesary.

          proc : the process involved.

CPU_proc_current_page ()

gint        CPU_proc_current_page           (proc_t *proc);

          proc : the process involved.
       Returns : the page which proc is using on this very moment.

CPU_proc_next_page ()

gint        CPU_proc_next_page              (proc_t *proc);

Makes the process move to its next memory page and should be called once for
each "clock tick" that proc is running.

          proc : the process involved.
       Returns : the new page which the process is using.

CPU_proc_current_page_is_write ()

gboolean    CPU_proc_current_page_is_write  (proc_t *proc);

Checks if proc is writing to memory or only reading.

          proc : the process involved.
       Returns : TRUE when proc is writing to its current page.

fix_simulation_in_proc ()

void        fix_simulation_in_proc          (proc_t *proc);

Makes the simulation parameters of a process coherent, prevents: multiple
events at the same time, events after process termination, determines the next
event ...

          proc : process whose simulation data should be fixed.

IO_BLOCK()

#define IO_BLOCK(event) (((event_data_t *)(event.data))->io_block)

Extracts the block from a IO event.

         event : process event.

Processes

Name

Processes -- Process Handling.

Synopsis



proc_t*     create_process                  (void);
proc_t*     new_process                     (void);
void        insert_process                  (proc_t *proc);
void        free_process                    (proc_t *proc);
gint        destroy_process                 (proc_t *proc);
proc_queue_t get_proc_list                  (void);
proc_t*     get_proc_by_pid                 (gint pid);
void        select_process                  (proc_t *proc);
proc_t*     get_CPU_selected_proc           (void);
void        save_processes_to_file          (void);
void        load_processes_from_file        (void);
#define     burst                           (proc)

Description

This functions provide general process handling. Creation, insertion into the
system, destruction, finding a certain process...

Details

create_process ()

proc_t*     create_process                  (void);

Do everything necesary to have a new process in the system.

       Returns : the newly created process.

new_process ()

proc_t*     new_process                     (void);

Allocate data for new process.

Note: the process will have to be inserted to have any efect.

       Returns : the newly allocate process data.

insert_process ()

void        insert_process                  (proc_t *proc);

Inserts process proc in the system.

Note: proc can be obtained with new_process.

          proc : the process involved.

free_process ()

void        free_process                    (proc_t *proc);

Definitely free all data related to proc.

Note: proc will be gone for good.

          proc : process involved.

destroy_process ()

gint        destroy_process                 (proc_t *proc);

Start considering proc a terminated process and remove it from the system.

Note: the data of proc is not freed, and proc will be saved by
save_processes_to_file.

          proc : process involved.
       Returns : nothing important.

get_proc_list ()

proc_queue_t get_proc_list                  (void);

       Returns : the list of all currently running processes.

get_proc_by_pid ()

proc_t*     get_proc_by_pid                 (gint pid);

           pid : process ID
       Returns : the data of process pid or NULL if there is no process with
                 PID pid.

select_process ()

void        select_process                  (proc_t *proc);

Makes proc the selected process.

Note: some code will do things to the selected process.

          proc : process involved.

get_CPU_selected_proc ()

proc_t*     get_CPU_selected_proc           (void);

Find out which is the currently selected process

       Returns : the currently selected process.

save_processes_to_file ()

void        save_processes_to_file          (void);

Asks the user for a filename and saves all processes on the current session to
a file, ready to be loaded in a new session.

Note: Both terminated and not yet running processes will be written.

load_processes_from_file ()

void        load_processes_from_file        (void);

Asks the user for a filename and loads all processes it can find it it.

Note: Not all processes will be visible at once, they will be inserted at the
right time.

burst()

#define burst(proc) (proc->next_event.time - proc->time)

Calculates the current burst (time until next voluntary event) for proc.

          proc : process involved.

Processor Status

Name

Processor Status -- Status of the processor.

Synopsis



typedef     proc_queues_t;
const proc_queues_t* get_CPU_queues         (void);
proc_t*     get_CPU_current_proc            (void);
proc_queue_t get_CPU_queue                  (gint nqueue);
proc_queue_t get_CPU_wait_queue             (void);
gint        request_nqueues                 (gint nqueues);
void        move_proc_to_queue              (proc_t *proc,
                                             gint new_queue);
void        move_proc_to_CPU                (proc_t *proc);
gint        suspend_proc                    (proc_t *proc);
gint        wakeup_proc                     (proc_t *proc);

Description

Here is descrived show to find out the status of the processor, the currently
running process and all the ready queues.

There are also functions to move processes around and change the number of
ready queues.

Details

proc_queues_t

typedef struct {                /* Processor status */
        gint nqueues;           /* Number of queues */
        proc_t *current;        /* Currently running process */
        proc_queue_t *queue;    /* Ready process queues */
        proc_queue_t wait;      /* Blocked processes */
} proc_queues_t;

get_CPU_queues ()

const proc_queues_t* get_CPU_queues         (void);

Retrive the processor's status.

       Returns : a pointer to the proc_queues_t structure.

get_CPU_current_proc ()

proc_t*     get_CPU_current_proc            (void);

       Returns : The currently running process, which may be NULL if the
                 processor is idle.

get_CPU_queue ()

proc_queue_t get_CPU_queue                  (gint nqueue);

        nqueue : requested queue.
       Returns : ready queue number nqueue.

get_CPU_wait_queue ()

proc_queue_t get_CPU_wait_queue             (void);

       Returns : the blocked process queue.

request_nqueues ()

gint        request_nqueues                 (gint nqueues);

Sets the number of queues for handling ready processes.

NOTE: when shrinking the lower queues, those which will be deleted, must be
empty or otherwise they will be concatenated to the first queue.

       nqueues : requested number of queues.
       Returns : nothing important.

move_proc_to_queue ()

void        move_proc_to_queue              (proc_t *proc,
                                             gint new_queue);

Move proc to queue number new_queue.

NOTE: The proc should not be blocked.

          proc : process to be moved.
     new_queue : target queue for proc.

move_proc_to_CPU ()

void        move_proc_to_CPU                (proc_t *proc);

Starts running process proc.

NOTE: the processor should be idle.

          proc : process to run.

suspend_proc ()

gint        suspend_proc                    (proc_t *proc);

Move proc out of the way when it blocks.

          proc : process involved.
       Returns : nothing important.

wakeup_proc ()

gint        wakeup_proc                     (proc_t *proc);

Move a process back when it becomes ready again letting the current algorithm
decide were to put it.

          proc : process involved.
       Returns : nothing important.

See Also

Process Queues

    How to inspect process queues.

Process Queues

Name

Process Queues -- Process Queue Handling.

Synopsis



typedef     proc_queue_t;
#define     DECLARE_PROC_QUEUE              (queue)
#define     proc_queue_empty                (queue)
#define     proc_data                       (element)
#define     proc_queue_next                 (element)
#define     proc_queue_find                 (queue, proc)
#define     proc_queue_len                  (queue)
#define     proc_queue_init                 (queue)
#define     proc_queue_foreach              (queue, func, data)
#define     proc_queue_concat               (dest, orig1, orig2)
#define     proc_queue_remove               (queue, proc)
#define     proc_queue_append               (queue, proc)
#define     proc_queue_nth                  (queue, n)
#define     proc_queue_end                  (element)

Description

This are the functions to use when working with any queue of processes in the
CPU.

Details

proc_queue_t

DECLARE_PROC_QUEUE()

#define     DECLARE_PROC_QUEUE(queue)

Declares a new and empty process queue with name queue.

         queue : name for the queue.

proc_queue_empty()

#define     proc_queue_empty(queue)

Is queue empty?

         queue : process queue involved.

proc_data()

#define     proc_data(element)

Retrives the process data from the queue element.

       element : process queue element involved.

proc_queue_next()

#define     proc_queue_next(element)

Gets the next element on the queue starting at element.

       element : process queue element involved.

proc_queue_find()

#define     proc_queue_find(queue, proc)

Find the queue element for process proc.

         queue : process queue involved.
          proc : process involved.

proc_queue_len()

#define     proc_queue_len(queue)

Calculate the number of elements on queue.

         queue : process queue involved.

proc_queue_init()

#define     proc_queue_init(queue)

Initializes process queue queue.

Note: applyed to a non empty queue will loose all its elements.

         queue : process queue involved.

proc_queue_foreach()

#define     proc_queue_foreach(queue, func, data)

Will call func for every process on queue using the process pointer as the
first arguemt and data as the second.

         queue : process queue involved.
          func : function to be called.
          data : second argument to func.

proc_queue_concat()

#define     proc_queue_concat(dest, orig1, orig2)

Concatenates orig1 and orig2 into dest.

          dest : Target queue.
         orig1 : First source queue.
         orig2 : Second source queue.

proc_queue_remove()

#define     proc_queue_remove(queue, proc)

Remove proc from queue.

         queue : process queue involved.
          proc : process to be removed.

proc_queue_append()

#define     proc_queue_append(queue, proc)

Append proc to queue.

         queue : process queue involved.
          proc : process to be appended.

proc_queue_nth()

#define     proc_queue_nth(queue, n)

Get element number n from queue.

         queue : queue involved.
             n : element index.

proc_queue_end()

#define proc_queue_end(element) proc_queue_empty(element)

Is this element the end of the queue?

       element : process queue element involved.

Processor Algorithms

Name

Processor Algorithms -- Interface for Algorithms.

Synopsis



typedef     cpu_algorithm_t;
cpu_algorithm_t* get_CPU_current_algorithm  (void);
GSList*     init_CPU_algorithms             (void);
gint        register_CPU_algorithm          (cpu_algorithm_t *algorithm);
gint        deallocate_algorithm_private_data
                                            (proc_queue_t proc_list);
gint        set_CPU_heart_beat              (gint freq);
gint        reset_CPU_timer                 (void);

Description

Great effort has been devoted to making the addicion of new algorithms as easy
as posible, here is documented what there is to know to be able to write your
own algorithms.

Details

cpu_algorithm_t

typedef struct { /*This struct is all that we know about each algorithm*/
        gchar * name;
        gint (*select) (void);
        gint (*unselect) (void);                /* These two functions will be
                                                   called before and after the
                                                   use of an algorithm to let
                                                   it keep a low memory usage
                                                   when not in use.*/
        gint (*clock) (void);                   /* timer interrupt. */
        gint (*select_proc) (proc_t *proc);     /* notifies the algorithm of a
                                                   process selection by the
                                                   user */
        GtkWidget * process_properties;
        GtkWidget * properties;                 /* Each algorithm will maintain
                                                   it's own properties widgets.
                                                   NULL means "no properties".
                                                   They should be set to NULL
                                                   when destroyed. If not
                                                   destroyed in "unselect" the
                                                   system will destroy them.*/
        gint (*init_proc) (proc_t *proc);       /* This function should allocate
                                                   and initialice algorith data
                                                   and anything else to get
                                                   a new process going, like
                                                   sticking it into a queue. */
        gint (*end_proc) (proc_t *proc);        /* This function should free the
                                                   algorithm specific data of
                                                   proc but should not take it
                                                   out of its queue */
        gint (*event) (proc_t *proc);           /* This function is called when
                                                   ever a process gets waked up
                                                   by an event and we have to
                                                   put it in some queue. */
        gint (*next) (proc_t *proc);            /* This function is called when
                                                   ever the current process gets
                                                   suspended waiting for some
                                                   event and we have to choose
                                                   another one to run.
                                                   It receives the suspended
                                                   process as argument just in
                                                   case its needed. */
} cpu_algorithm_t;

get_CPU_current_algorithm ()

cpu_algorithm_t* get_CPU_current_algorithm  (void);

Find out which is the current algorithm.

       Returns : the struct which descrives the current algorithm.

init_CPU_algorithms ()

GSList*     init_CPU_algorithms             (void);

Initializes the CPU algorithms code.

Mainly will call init functions for each algorithm.

       Returns : a pointer to the algorithm structs linked list

register_CPU_algorithm ()

gint        register_CPU_algorithm          (cpu_algorithm_t *algorithm);

Each algorithm should call this function in it's initialization function to
register its algorithm struct.

     algorithm : algorithm struct to register.
       Returns : nothing important.

deallocate_algorithm_private_data ()

gint        deallocate_algorithm_private_data
                                            (proc_queue_t proc_list);

This function uses the algorithm's private data of each process as argument to
g_free.

This is for convinience of algorithm writers.

     proc_list : queue of processes.
       Returns : nothing important.

set_CPU_heart_beat ()

gint        set_CPU_heart_beat              (gint freq);

Set timer interrupt frequency. Which means, the calling frequency of algorithm
function clock.

Zero means that the timer interupt is not desired.

          freq : new frequency in "time units".
       Returns : nothing important.

reset_CPU_timer ()

gint        reset_CPU_timer                 (void);

Resets the "time unit" counter so we will have a full timeslice until the next
interupt.

       Returns : nothing important.

See Also

Process Queues

    How to inspect process queues.

Processor Simulation

    How simulation works.

Property Widget Facility

    How to hadle numerical algorithm properties with the user without learning
    GTK+.



-------------------------------------------------------------------------------

I/O

Table of Contents
IO Interface -- IO interface to the other subsystems.
Geometry -- Geometry of the device.
IO Simulation -- Simulation of the device
Request Queues -- IO Request Queue Handling.
IO Algorithms -- Interface for Algorithms.
IO Miscelaneous -- Other interesting functions.

This subsystem is responsable of accepting block disk accesses, simulating them
and reporting its client when done.

IO Interface

Name

IO Interface -- IO interface to the other subsystems.

Synopsis



void        (*block_ready_callback_t)       (gint block);
gint        io_register_block_ready         (block_ready_callback_t func);
void        io_request_block                (gint block);
void        io_request_swap_block           (gint block);

Description

This functions allow the other subsystems to interact, througth the messaging
service, with the I/O subsystem.

Details

block_ready_callback_t ()

void        (*block_ready_callback_t)       (gint block);

Function pointer type for the callback used on io_register_block_ready.

Function pointer type for the callback used on io_register_block_ready.

         block : block number of the fulfilled IO access.

io_register_block_ready ()

gint        io_register_block_ready         (block_ready_callback_t func);

Instructs the IO subsystem to call func when a block access is finished.

          func : function to be called when a requested block access is
                 finished.
       Returns : nothing important.

io_request_block ()

void        io_request_block                (gint block);

Instructs the IO subsystem to accesses block from the data area.

         block : data block to be accessed.

io_request_swap_block ()

void        io_request_swap_block           (gint block);

Instructs the IO subsystem to accesses block from the swap area.

         block : swap block to be accessed.

Geometry

Name

Geometry -- Geometry of the device.

Synopsis



gint        get_IO_blocks_per_track         (void);
gint        get_IO_max_data_block           (void);
gint        get_IO_max_swap_block           (void);
gint        get_IO_ntracks                  (void);
gint        get_IO_last_data_track          (void);
gint        IO_request_track                (io_request_t *request);
void        init_IO_geometry                (void);

Description

This functions serve to find out the geometry of the disk and do some
translations based on it.

Details

get_IO_blocks_per_track ()

gint        get_IO_blocks_per_track         (void);

       Returns : the number of blocks per track.

get_IO_max_data_block ()

gint        get_IO_max_data_block           (void);

       Returns : the maximun data block number.

get_IO_max_swap_block ()

gint        get_IO_max_swap_block           (void);

       Returns : the maximun swap block number.

get_IO_ntracks ()

gint        get_IO_ntracks                  (void);

       Returns : the number of tracks on the disk.

get_IO_last_data_track ()

gint        get_IO_last_data_track          (void);

       Returns : the last data track number.

IO_request_track ()

gint        IO_request_track                (io_request_t *request);

Calculates the track of a certain request.

       request : IO request involved.
       Returns : the track number corespoinding to request.

init_IO_geometry ()

void        init_IO_geometry                (void);

Initialices the geometry calculation code.

IO Simulation

Name

IO Simulation -- Simulation of the device

Synopsis



gint        init_IO_simulation              (void);
gint        IO_algorithm_event              (io_request_t *request);
gint        get_IO_head_pos                 (void);
io_queue_t  get_IO_reading_queue            (void);
void        set_IO_reading_queue            (io_queue_t new_reading);
io_queue_t  get_IO_requested_queue          (void);

Description

This functions serve to manage the disk's simulation and it's data structures.

Details

init_IO_simulation ()

gint        init_IO_simulation              (void);

initialices the IO simulation code.

       Returns : nothing important.

IO_algorithm_event ()

gint        IO_algorithm_event              (io_request_t *request);

Insert a new request in the IO subsystem using the current algorith.

Mainly passes request over to the current algorithm and puts it the the queue
of requested blocks.

       request : request to be inserted.
       Returns : nothing important.

get_IO_head_pos ()

gint        get_IO_head_pos                 (void);

       Returns : the track number over which the head is currently flying.

get_IO_reading_queue ()

io_queue_t  get_IO_reading_queue            (void);

Get all pending requests as ordered by the current algoritym.

       Returns : the request's "reading" queue (ordered by the current
                 algorithm).

set_IO_reading_queue ()

void        set_IO_reading_queue            (io_queue_t new_reading);

Sets the request's "reading" queue.

This function should be called when ever the reading queue is modified by
external means, even if the pointer to the queue is not changed.

   new_reading : newly ordered "reading" queue.

get_IO_requested_queue ()

io_queue_t  get_IO_requested_queue          (void);

Get all pending requests in order of arrival.

       Returns : the request's "requested" queue (in chronological ordered).

Request Queues

Name

Request Queues -- IO Request Queue Handling.

Synopsis



typedef     io_queue_t;
#define     DECLARE_IO_QUEUE                (queue)
#define     io_queue_empty                  (queue)
#define     io_request_data                 (element)
#define     io_queue_next                   (element)
#define     io_queue_len                    (queue)
#define     io_queue_init                   (queue)
#define     io_queue_foreach                (queue, func, data)
#define     io_queue_concat                 (dest, orig1, orig2)
#define     io_queue_remove                 (queue, request)
#define     io_queue_append                 (queue, request)
#define     io_queue_end                    (element)

Description

This are the functions to use when working with any queue of requests in the IO
subsystem.

Details

io_queue_t

DECLARE_IO_QUEUE()

#define     DECLARE_IO_QUEUE(queue)

Declares a new and empty request queue with name queue.

         queue : name for the queue.

io_queue_empty()

#define     io_queue_empty(queue)

Is queue empty?

         queue : request queue involved.

io_request_data()

#define     io_request_data(element)

Retrives the request data from the queue element.

       element : request queue element involved.

io_queue_next()

#define     io_queue_next(element)

Gets the next element on the queue starting at element.

       element : request queue element involved.

io_queue_len()

#define     io_queue_len(queue)

Calculate the number of elements on queue.

         queue : request queue involved.

io_queue_init()

#define     io_queue_init(queue)

Initializes request queue queue.

Note: applyed to a non empty queue will loose all its elements.

         queue : request queue involved.

io_queue_foreach()

#define     io_queue_foreach(queue, func, data)

Will call func for every request on queue using the request pointer as the
first arguemt and data as the second.

         queue : request queue involved.
          func : function to be called.
          data : second argument to func.

io_queue_concat()

#define     io_queue_concat(dest, orig1, orig2)

Concatenates orig1 and orig2 into dest.

          dest : Target queue.
         orig1 : First source queue.
         orig2 : Second source queue.

io_queue_remove()

#define     io_queue_remove(queue, request)

Remove request from queue.

         queue : request queue involved.
       request : request to be removed.

io_queue_append()

#define     io_queue_append(queue, request)

Append request to queue.

         queue : request queue involved.
       request : request to be appended.

io_queue_end()

#define io_queue_end(element) io_queue_empty(element)

Is this element the end of the queue?

       element : request queue element involved.

IO Algorithms

Name

IO Algorithms -- Interface for Algorithms.

Synopsis



typedef     io_algorithm_t;
io_algorithm_t* get_IO_current_algorithm    (void);
GSList*     init_IO_algorithms              (void);
gint        register_IO_algorithm           (io_algorithm_t *algorithm);

Description

Great effort has been devoted to making the addicion of new algorithms as easy
as posible, here is documented what there is to know to be able to write your
own algorithms.

Details

io_algorithm_t

typedef struct {                                /* This struct is all we know
                                                   about each algorithm */
        gchar * name;
        gint (*select) (void);
        gint (*unselect) (void);                /* These two functions will be
                                                   called before and after the
                                                   use of an algorithm to let
                                                   it keep a low memory usage
                                                   when not in use.*/
        GtkWidget * properties;                 /* Each algorithm will maintain
                                                   it's own properties widget.
                                                   NULL means "no properties".
                                                   It should be set to NULL
                                                   when destroyed. If not
                                                   destroyed in "unselect" the
                                                   system will destroy it.*/
        gint (*event) (io_request_t *request);  /* This is called to inform the
                                                   algorithm of block request*/
        gint (*done_reading) (void);            /* This ia called to inform the
                                                   algorithm about all requested
                                                   reads been done */
} io_algorithm_t;

get_IO_current_algorithm ()

io_algorithm_t* get_IO_current_algorithm    (void);

Find out which is the current algorithm.

       Returns : the struct which descrives the current algorithm.

init_IO_algorithms ()

GSList*     init_IO_algorithms              (void);

Initializes the IO algorithms code.

Mainly will call init functions for each algorithm.

       Returns : a pointer to the algorithm structs linked list.

register_IO_algorithm ()

gint        register_IO_algorithm           (io_algorithm_t *algorithm);

Each algorithm should call this function in it's initialization function to
register its algorithm struct.

     algorithm : algorithm struct to register.
       Returns : nothing important.

See Also

IO Simulation

    How to inspect and manage requests.

Geometry

    How manage geometry.

Property Widget Facility

    How to hadle numerical algorithm properties with the user without learning
    GTK+.

Request Queues

    How to hadle request queues.



IO Miscelaneous

Name

IO Miscelaneous -- Other interesting functions.

Synopsis



gint        io_server_init                  (void);
gint        io_block_ready_server           (io_request_t *io_request);

Description

This functions wouldn't make a proper section, but I believe that they are
relevant enough to be mencioned.

Details

io_server_init ()

gint        io_server_init                  (void);

Called from the subsystem's code to initialize the interface code.

       Returns : nothing important.

io_block_ready_server ()

gint        io_block_ready_server           (io_request_t *io_request);

Called from the subsystem's code to tell the client about a fulfilled request.

    io_request : the fulfilled request.
       Returns : nothing important.

-------------------------------------------------------------------------------

Memory

Table of Contents
Memory Interface -- MEM interface to the other subsystems.
Memory Configuration -- Internal configuration.
Memory Algorithms -- Interface for Algorithms.
Swap -- Swapping system.
Memory Status -- Status of the memory.
Memory Miscelaneous -- Other interesting functions.

This subsystem is responsable for accepting memory read and write requests,
managing memory for all processes: stealing and swapping pages as necesary.

Memory Interface

Name

Memory Interface -- MEM interface to the other subsystems.

Synopsis



void        (*page_ready_callback_t)        (gint pid,
                                             gint page);
void        mem_register_page_ready         (page_ready_callback_t func);
gboolean    mem_touch_page                  (proc_t *proc,
                                             gint page,
                                             gboolean write);

Description

This functions allow the other subsystems to interact, througth the messaging
service, with the Memory.

Details

page_ready_callback_t ()

void        (*page_ready_callback_t)        (gint pid,
                                             gint page);

Function pointer type for the callback used on mem_register_page_ready.

Function pointer type for the callback used on mem_register_page_ready.

           pid : the process involved.
          page : the process' page which has become ready.

mem_register_page_ready ()

void        mem_register_page_ready         (page_ready_callback_t func);

Registers func to be called whenever a processes page becomes available in
physical memory.

          func : function to be called.

mem_touch_page ()

gboolean    mem_touch_page                  (proc_t *proc,
                                             gint page,
                                             gboolean write);

Access the page number page of process proc. The access will be for writing if
write is TRUE.

          proc : process involved.
          page : page we pretend to use.
         write : are we writing to the specified page?
       Returns : TRUE if the page was available and FALSE if a page fault
                 ocurred and the process has to wait.

Memory Configuration

Name

Memory Configuration -- Internal configuration.

Synopsis



typedef     mem_config_t;
extern      const mem_config_t *MEM_config;
mem_config_t* get_MEM_config                (void);

Description

This is the way to find out Memory internal configuration.

Details

mem_config_t

typedef struct {
        gboolean stop_clock;    /* clock should be stoped when something
                                   interesting happens */
        gboolean disabled;      /* this subsystem is disabled */
} mem_config_t;

MEM_config

extern const mem_config_t *MEM_config;

This is a pointer to the configuration data, but should be used only for
reading.

get_MEM_config ()

mem_config_t* get_MEM_config                (void);

This is the right way to modify the configuration.

       Returns : a writable pointer to the configuration data.

Memory Algorithms

Name

Memory Algorithms -- Interface for Algorithms.

Synopsis



typedef     mem_algorithm_t;
mem_algorithm_t* get_MEM_current_algorithm  (void);
GSList*     init_MEM_algorithms             (void);
void        register_MEM_algorithm          (mem_algorithm_t *algorithm);

Description

Great effort has been devoted to making the addicion of new algorithms as easy
as posible, here is documented what there is to know to be able to write your
own algorithms.

Details

mem_algorithm_t

typedef struct {                                        /* This struct is all
                                                           that we know about
                                                           each algorithm */
        gchar * name;
        void (*select) (void);
        void (*unselect) (void);                        /* These two functions
                                                           will be called before
                                                           and after the use of
                                                           an algorithm to let
                                                           it keep a low memory
                                                           usage when not in
                                                           use.*/
        GtkWidget * properties;                         /* Each algorithm will
                                                           maintain it's own
                                                           properties widget.
                                                           NULL means "no
                                                           properties".  It
                                                           should be set to NULL
                                                           when destroyed. If
                                                           not destroyed in
                                                           "unselect" the system
                                                           will destroy it.*/
        void (*page_access) (gint pid, gint page);      /* lets the algorithm
                                                           keep track of page
                                                           accesses */
        gint (*select_frame) (void);                    /* it should return a
                                                           frame to be assigned
                                                           when out of memory */
} mem_algorithm_t;

get_MEM_current_algorithm ()

mem_algorithm_t* get_MEM_current_algorithm  (void);

Find out which is the current algorithm.

       Returns : the struct which descrives the current algorithm.

init_MEM_algorithms ()

GSList*     init_MEM_algorithms             (void);

Initializes the MEM algorithms code.

Mainly will call init functions for each algorithm.

       Returns : a pointer to the algorithm structs linked list.

register_MEM_algorithm ()

void        register_MEM_algorithm          (mem_algorithm_t *algorithm);

Each algorithm should call this function in it's initialization function to
register its algorithm struct.

     algorithm : algorithm struct to register.

Swap

Name

Swap -- Swapping system.

Synopsis



void        MEM_swap_init                   (void);
void        MEM_swapout_page                (gint pid,
                                             gint page);
void        MEM_swapin_page                 (gint pid,
                                             gint page,
                                             guint32 set_flags);

Description

This functions serve to get process pages in and out of the swap device.

Details

MEM_swap_init ()

void        MEM_swap_init                   (void);

Gets things ready to be able to swap memory in and out.

MEM_swapout_page ()

void        MEM_swapout_page                (gint pid,
                                             gint page);

Writes page from Proces' pid virtual memory address space from memory into a
free block in the swap device.

           pid : The Process Identification number.
          page : Which one of the process' pages we what back.

MEM_swapin_page ()

void        MEM_swapin_page                 (gint pid,
                                             gint page,
                                             guint32 set_flags);

Reads page from Proces' pid virtual memory address space into memory from the
swap device

If the page has never been swapped out we will suppose it is in the first free
swap block and request an IO access to it.

If the page is already swaping in then we will take note of set_flags and let
it be.

           pid : The Process Identification number
          page : Which one of the process' pages we what back
     set_flags : This flags will be set on the frame when when one is assigned

Memory Status

Name

Memory Status -- Status of the memory.

Synopsis



typedef     frame_info_t;
enum        mem_frame_flags_t;
#define     FRAME_LOCKED                    (frame)
#define     FRAME_REFERENCED                (frame)
#define     FRAME_MODIFIED                  (frame)
typedef     proc_pages_info_t;
#define     PAGE_VALID                      (proc_pages, page)
#define     NO_FRAME
#define     NO_PAGE
#define     NO_PROC
#define     NO_BLOCK
void        init_page_info                  (void);
frame_info_t* get_free_frame                (void);
void        put_free_frame                  (gint frame);
gboolean    have_free_frame                 (void);
frame_info_t* get_frame_info                (gint frame);
frame_info_t* get_frames_list               (void);
frame_info_t* mem_frames_next               (frame_info_t *frame);
proc_pages_info_t* get_proc_pages           (gint pid,
                                             gboolean creat);
proc_pages_info_t* get_proc_pages_list      (void);
proc_pages_info_t* proc_pages_next          (proc_pages_info_t *pages);
gint        virt_to_phys                    (gint pid,
                                             gint page);
void        mem_page_invalid                (gint pid,
                                             gint page);
gint        mem_assign_frame                (gint pid,
                                             gint page,
                                             gint frame);
void        mem_page_valid                  (gint pid,
                                             gint page);

Description

Here is descrived show to find out the status of memory, the frames available,
what process they belong to, valid and invalid pages...

Details

frame_info_t

typedef struct {                /* what there is to know about a frame */
        gint frame;             /* frame number */
        gint proc;              /* process it belongs to or NO_PROC */
        gint page;              /* page it belongs to of NO_PAGE */
        guint32 flags;          /* See mem_frame_flags_t */
        guint32 private_flags;  /* algorithm dependet flags */
}frame_info_t;

enum mem_frame_flags_t

typedef enum {                  /* bit indexes for frame flags */
        MEM_FRAME_LOCKED=0,     /* frame is locked and should not be
                                   stolen of assigned */
        MEM_FRAME_REFERENCED,   /* frame has been referenced recently */
        MEM_FRAME_MODIFIED      /* frame is modified and should be writen to
                                   swap if stolen */
} mem_frame_flags_t;

FRAME_LOCKED()

#define FRAME_LOCKED(frame) (test_bit(MEM_FRAME_LOCKED, &frame->flags))

Test whether frame is locked.

         frame : frame involved.

FRAME_REFERENCED()

#define FRAME_REFERENCED(frame) (test_bit(MEM_FRAME_REFERENCED, &frame->flags))

Test whether frame has been referenced.

         frame : frame involved.

FRAME_MODIFIED()

#define FRAME_MODIFIED(frame) (test_bit(MEM_FRAME_MODIFIED, &frame->flags))

Test whether frame has been modified.

         frame : frame involved.

proc_pages_info_t

typedef struct {                        /* memory related information for a
                                           process */
        gint pid;                       /* process id of the process */
        gint n_pages;                   /* number of pages its using */
        guint32 bitmap;                 /* bitmap of valid pages */
        frame_info_t *frame[MAX_PAGES]; /* frames where the pages are stored*/
        gint block[MAX_PAGES];          /* swap blocks assigned to pages */
        GSList *node;                   /* GSList link this struct is hanging
                                           from */
} proc_pages_info_t;

PAGE_VALID()

#define PAGE_VALID(proc_pages, page) (proc_pages->bitmap & (1<<page))

Test whether page is valid in proc_pages.

    proc_pages : process memory information.
          page : page involved.

NO_FRAME

#define NO_FRAME -1     /* frame number when there is no frame */

NO_PAGE

#define NO_PAGE -1      /* page number when there is no page */

NO_PROC

#define NO_PROC -1      /* process number when there is no process */

NO_BLOCK

#define NO_BLOCK -1     /* block number when there is no block */

init_page_info ()

void        init_page_info                  (void);

Initialize the code which keeps track of pages and frames.

get_free_frame ()

frame_info_t* get_free_frame                (void);

       Returns : a free frame if any, NULL otherwise.

put_free_frame ()

void        put_free_frame                  (gint frame);

Give back a frame to be returned by get_free_frame later.

         frame : frame to return.

have_free_frame ()

gboolean    have_free_frame                 (void);

       Returns : TRUE if we have free memory frames available.

get_frame_info ()

frame_info_t* get_frame_info                (gint frame);

         frame : frame involved.
       Returns : frame's information data.

get_frames_list ()

frame_info_t* get_frames_list               (void);

       Returns : the first element on the list of frame information structures.

mem_frames_next ()

frame_info_t* mem_frames_next               (frame_info_t *frame);

         frame : a frame information structure.
       Returns : the next frame information structure or NULL if frame is the
                 last element.

get_proc_pages ()

proc_pages_info_t* get_proc_pages           (gint pid,
                                             gboolean creat);

Retrives the memory related information for pid.

If there is no memory information for pid and creat is TRUE the information
will be created.

           pid : process involved.
         creat : it TRUE a process information structure will be created.
       Returns : memory information for pid if applyable of NULL otherwise.

get_proc_pages_list ()

proc_pages_info_t* get_proc_pages_list      (void);

       Returns : the first element of the memory infomation structures.

proc_pages_next ()

proc_pages_info_t* proc_pages_next          (proc_pages_info_t *pages);

         pages : a process' memory information structure.
       Returns : then next memory information structure or NULL if pages is the
                 last element.

virt_to_phys ()

gint        virt_to_phys                    (gint pid,
                                             gint page);

           pid : process involved.
          page : a page in pid's virtual memory.
       Returns : the frame number coresponding to page in pid's address space
                 or NO_FRAME if there is non assigned.

mem_page_invalid ()

void        mem_page_invalid                (gint pid,
                                             gint page);

Makes page of pid's address space invalid so pid will incure a page fault if it
tryes to use it.

           pid : process involved.
          page : invalid page.

mem_assign_frame ()

gint        mem_assign_frame                (gint pid,
                                             gint page,
                                             gint frame);

Assings frame to page in pid's address space.

           pid : process involved.
          page : a page in pid's address space.
         frame : a free frame.
       Returns : 0 if all went well -1 otherwise.

mem_page_valid ()

void        mem_page_valid                  (gint pid,
                                             gint page);

Makes page of pid's address space valid for pid to use.

           pid : process involved.
          page : valid page.

Memory Miscelaneous

Name

Memory Miscelaneous -- Other interesting functions.

Synopsis



#define     MAX_FRAMES
#define     MAX_PAGES
gint        mem_server_init                 (GladeXML *xml);
gint        mem_page_ready_server           (gint pid,
                                             gint page);
gint        mem_page_bitmap_update_server   (gint pid,
                                             guint32 new_page_bitmap);

Description

This functions wouldn't make a proper section, but I believe that they are
relevant enough to be mencioned.

Details

MAX_FRAMES

#define MAX_FRAMES 40   /* total number of frames available */

MAX_PAGES

#define MAX_PAGES 32    /* maximun number of pages per process */

mem_server_init ()

gint        mem_server_init                 (GladeXML *xml);

Called from the subsystem's code to initialize the interface code.

           xml : Glade interface object.
       Returns : nothing important.

mem_page_ready_server ()

gint        mem_page_ready_server           (gint pid,
                                             gint page);

Called from the subsystem's code to tell the client about a fulfilled page
fault.

           pid : process involved.
          page : ready page.
       Returns : nothing important.

mem_page_bitmap_update_server ()

gint        mem_page_bitmap_update_server   (gint pid,
                                             guint32 new_page_bitmap);

Called from the subsystem's code to update the valid page bitmap on the client.

            pid : process involved.
new_page_bitmap : valid page bitmap.
        Returns : nothing important.

-------------------------------------------------------------------------------

Clock

Table of Contents
Clock Interface -- CLOCK interface to the other subsystems.

This subsystem is responsable for generating a common time reference for all
other subsystems.

Clock Interface

Name

Clock Interface -- CLOCK interface to the other subsystems.

Synopsis



gint        (*tick_callback_t)              (gint time);
gint        clock_register_tick             (tick_callback_t func);
gint        get_time                        (void);
void        CLOCK_stop                      (void);

Description

This functions allow the other subsystems to interact, througth the messaging
service, with the CLOCK.

Details

tick_callback_t ()

gint        (*tick_callback_t)              (gint time);

function pointer to be used with clock_reguster_tick.

function pointer to be used with clock_reguster_tick.

          time : current time in "time units".
       Returns : nothing important.

clock_register_tick ()

gint        clock_register_tick             (tick_callback_t func);

Instructs the CLOCK subsystem to call func for every "time unit".

          func : function to be called as time goes by.
       Returns : nothing important.

get_time ()

gint        get_time                        (void);

       Returns : the current time in "time units".

CLOCK_stop ()

void        CLOCK_stop                      (void);

Tells the CLOCK to stop counting "time units".

-------------------------------------------------------------------------------

Requestor

This subsystem is not important for the general understanding of the program,
but is included here for completnes. It is there to allow the user to request I
/O data and Memory manualy acting as the client for those subsystems.