= Project architecture =

== 1. File system organization ==
The distribution is subdivided in several folders in order to efficiently
organize files and logically separate them into different sections.
Kaya is a layered OS, so each Phase has been confined in a sub-distribution
own hierarchy, in order to ease interchanges between different implementation
of the same layer and to underline that opportunity.
In addition to this, each Phase has the common unix-like directory organization:
 * `phase`''N''`/`
   * `src/`: Phase ''N'' source code and a test programs;
   * `obj/`: Phase ''N'' objects files;
   * `include/`: Phase ''N'' library headers;
 * `include/`: system common definitions: constants and macro (`const.h`),
   types and data structures (`types.h`);
 * `dev/`: uMPS virtual devices files;
 * `doc/`: documentation root containing various developers informations about 
   project internals and development process.

== 2. Source modules organization ==

=== 2.1. Phase 1 ===
Following the evident logical division between two entities that we had to 
instantiate - processes and semaphores -, we opted for a two-modules subdivision:
 * `pcb.c`: collects primitive functions for PCBs initialization/ allocation/
   deallocation, process queue/ tree maintenance;
 * `st.c`: collects primitive functions for SD tree initialization and PCB
   enqueueing to/dequeueing from semaphores.

=== 2.2. Phase 2 ===
Nucleus modular division reflects main objectives of the operating system:
hardware interface, process alternation, low-level synchronization primitives
and exception handling routines.
Let's see such division in detail:
 * `initial.c` implements `main()` and exports the nucleus’s global variables
   (e.g. process count, device descriptors, etc.);
 * `interrupts.c` implements the device interrupt exception handler. Processes
   all the device interrupts, including Interval Timer interrupts, converting
   device interrupts into V operations on the appropriate semaphores;
 * `exception.c` implements the TLB program trap and syscall/breakpoint
   exception handlers;
 * `dispatcher.c` implements Kaya’s process dispatcher and deadlock detector;
 * `scheduler.c` implements Kaya’s process configurable scheduler;
 * `tools.c` implements some kernel utilties and debugging tools.