= 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 classic structure

 * `phase`''N''`/`
   * `src/`: sources folder containing Phase ''N'' source code and a test programs;
   * `obj/`: Phase ''N'' objects files;
   * `include/`: library headers of Phase ''N'';
 * `include/`: system common headers: constants and macro definitions
   (`const.h`), types and data structures definitions (`types.h`);
 * `dev/`: uMPS virtual devices;
 * `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 details:
 * `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.