Add documentation files.

3 files changed, 222 insertions, 0 deletions

diff --git a/doc/filesystem.md b/doc/filesystem.md
new file mode 100644
index 0000000..99f58a9
--- /dev/null
+++ b/doc/filesystem.md
@@ -0,0 +1,119 @@
+(sorry, in french for the moment)
+
+# Idée de layout pour les fichiers dans une installation classique :
+
+Le layout tel que peut le constater l'utilisateur :
+
+- `io:/` : périphériques système et accès aux ressources contrôlées
+  par le processus parent, peut changer quand on entre dans une "boîte".
+  Lecture seule, contôlé par l'init et le desktop manager (ou n'importe quel processus qui crée une "boîte")
+  - `io:/keyboard`, `io:/mouse`, `io:/display`, `io:/sound` : interfaces spécialisées
+    sur chacun, accessibles via une API fournie dans `libkogata`
+
+- `root:/` : partition système. Contenu géré par l'administrateur du système.
+  - `root:/boot/kernel-2.bin` : le noyau (V2)
+  - `root:/boot/init-4.bin` : l'init et gestionnaire de paquets système (V4)
+  - `root:/pkg/` : les paquets du système, montés en overlay sur `sys:` et sur `cmd:`
+      - `root:/pkg/kogata` : paquets essentiels du système
+          - `root:/pkg/kogata/kogata-r2.pkg` : release 2 du système kogata de base (contenu à choisir précisément)
+          - `root:/pkg/kogata/kogata-compat-r2.pkg` : librairies compatibles avec les anciennes API mais fonctionnant avec le système R2 actuel
+          - `root:/pkg/kogata/kogata-dev-r2.pkg` : binaires ligne de commande et en-têtes de dév pour la release 2
+          - `root:/pkg/kogata/kogata-extras-r2.pkg` : ressources, bibliothèques et utilitaires supplémentaires
+          - `root:/pkg/kogata/kogata-langpack-ja-r2.pkg` : fichiers nécessaires pour utiliser le système en japonais (au pif !)
+      - `root:/pkg/themes/` : fichiers de personnalisation de l'interface : polices, icônes, fonds d'écran
+      - `root:/pkg/filetypes/` : extensions à libfiles pour la gestion de types de fichiers nouveaux
+  - `root:/apps/` : applications et utilitaires supplémentaires, ne peuvent pas dépendre de
+    bibliothèques non inclues  dans `kogata-rx.pkg` ou `kogata-extras-rx.pkg`
+	et doivent inclure elle-même les fichiers `.so` correspondant
+  - `root:/services/` : applications du serveur
+  - `root:/config/` : configurations du système (plusieurs sous-dossiers pour plusieurs configurations)
+  - `root:/users/` : à défaut d'utiliser une partition séparée, dossiers des utilisateurs
+  - `root:/services/` : données des serveurs
+
+- `config:/` : bind-mount de `root:/config/config-en-cours`, contient les fichiers de configuration du système
+
+- `sys:/` : librairies, binaires et ressources du système, c'est un overlayfs constitué à partir d'images pré-préparées contenues dans `root:/pkg/`. Tout ce qui est dans `sys:` est considéré de source sûre.
+  - `sys:/lib` : librairies
+      - `sys:/lib/libkogata/libkogata-1.so` : `libkogata` avec compatibilité API V1
+      - `sys:/lib/libkogata/libkogata-dev.so` : `libkogata` sans compatibilité (version de développement)
+      - `sys:/lib/libkogata/libkogata-sys.so` : `libkogata` avec compatibilité API avec les binaires du système
+      - `sys:/lib/libc/libc-1.so`
+      - `sys:/lib/libalgo/libalgo-1.so`
+      - `sys:/lib/libgui` : bibliothèque de dessin à l'écran, rendu des polices, toolkit graphique
+      - `sys:/lib/libfiles` : bibliothèque pour la manipulation de fichiers de différents formats ; extensible
+  - `sys:/filetypes` : extensions à `libfiles` pour gérer des fichiers
+      - `sys:/filetypes/jpeg-1.so` : plugin pour charger des JPEG
+      - `sys:/filetypes/mp3-1.so` : plugin pour charger des MP3
+  - `sys:/fonts` : extensions à `libgui`, polices d'écriture
+  - `sys:/input` : extensions à `libgui`, méthodes d'entrée et keymaps
+      - `sys:/input/keymaps` : keymaps
+  - `sys:/icons` : extensions à `libgui`, thèmes d'icônes
+      - `sys:/icons/default` : icônes par défaut
+  - `sys:/wallpapers` : fonds d'écran
+  - `sys:/bin` : binaires du système
+      - `sys:/bin/login.bin` : login manager
+      - `sys:/bin/desktop.bin` : le gestionnaire de bureau (wm-compositor, multiplexage des périphériques, boxing, IPC-master & gestionnaire d'autorisations)
+      - `sys:/bin/config.bin` : éditeur de configuration utilisateur
+      - `sys:/bin/admin.bin` : éditeur de configuration système et autres outils d'admin
+  - `sys:/cmd` : binaires utilisables en ligne de commande, essentiellement pour le dév ; hiérarchie type unix
+      - `sys:/cmd/bin/`
+      - `sys:/cmd/lib/`
+      - `sys:/cmd/include/`
+      - `sys:/cmd/share/`
+
+- `apps:/` : dossier contenant les paquets d'application pour les applications utilisateurs, c'est un bind-mount de `root:/apps` essentiellement
+- `services:/` : dossier contenant les paquets d'application pour les services du système, bind-mount de `root:/services`
+- `user:/` : bind-mount de `root:/users/utilisateur-actuel`, lecture-écriture, géré à la discrétion de l'utilisateur
+  - `user:/apps` : paquets d'application
+  - `user:/data` : configuration et données des applications
+
+Ligne d'init typique :
+
+    kernel /boot/kernel-12.bin root=io:/disk/ata0p0 init=root:/boot/init-12.bin config=test-config
+
+Hiérarchie telle que la voit une application qui tourne dans une boîte (c'est-à-dire n'importe quelle application de `apps:/` ou `home:/apps`) :
+
+- `io:/` : accès contrôlé aux ressources du système et à l'extérieur
+  - `io:/display`, `io:/mouse`, ... accessible via une inter-couche dans `desktop.bin` qui gère les autorisations
+  - `io:/desktop` : communication contrôlée avec les autres processus (notifications, demandes d'accès, ...)
+- `sys:/` : accès en lecture seule permettant d'utiliser les libs du système
+- `app:/` : dossier application (lecture-seule, correspond à `apps:/nom-appli.pkg` ou `user:/apps/nom-appli.pkg`)
+- `data:/` : dossier de données de l'application pour l'utilisateur (lecture-écriture, correspond à `user:/data/nom-appli`)
+- `user:/` : sous-portion séléctivement autorisée en lecture seule et en lecture-écriture du dossier `user:/`
+
+Hiérarchie telle que la voit un service du système qui tourne dans une boîte (c'est-à-dire n'importe quel serveur)
+
+- `sys:/` : accès en lecture seule permettant d'utiliser les libs du système
+- `app:/` : dossier du service, correspond à `services:/nom-service.pkg`
+- `data:/` : bind-mount de `root:/services/nom-service`
+
+Du coup ce qu'il faut en termes de systèmes de fichiers :
+
+- il faut que seul le processus qui a créé un FS puisse l'adminsitrer (ie faire des add-source)
+- `pkgfs` : capable de prendre un nombre arbitraire de fichiers `.pkg` et de faire apparaître leur contenu comme un dossier
+  - il faut que les fichiers `.pkg` puissent facilement contenir des métadonnées
+  - au moment du mount, soit copier en RAM (typiquement pour les paquets système ou pour les applis utilisateurs dans certains cas), soit lire à la demande à partir du support sous-jaccent
+  - toujours read-only
+  - charger un `.pkg` correspond à un add-source
+- Nativement dans la couche VFS inclure une fonctionnalité `fs_subfs` qui permet de :
+  - prendre un sous-dossier comme racine
+  - restreindre les droits (ie enlver tous droits d'écriture, typiquement)
+  - dans un premier temps, cette seconde fonctionnalité peut suffire, on n'utilise simplement pas encore de fichiers `.pkg` mais par exemple un cdrom avec un dossier `sys` que l'on binde comme `sys:/` par exemple.
+
+Rôle des différents binaires du système :
+
+- `init.bin` : fait le setup de `config:/` puis de `sys:/`, `apps:/` et
+  `services:/`, lance `sys:/bin/login.bin` avec tous les droits (pour les
+  services on verra plus tard mais il y aura sans doute un
+  `sys:/bin/svcmgr.bin`)
+- `login.bin` : authentification, fait le setup de `user:/`, puis lance
+  `sys:/bin/desktop.bin` avec les droits associés à l'utilisateur (`sys` et
+  `config` en RO, éventuellement déjà un partage des périphériques pour prévoir
+  plusieurs sessions simultanées - un `login.bin` primitif ne fait rien de tout
+  ça évidemment)
+- alternativement `login.bin` peut lancer `admin.bin` (console
+  d'administration) avec tous les droits, sur authentification appropriée
+- `desktop.bin` : gère les périphériques au niveau utilisateur, crée des boîtes
+  pour lancer les applications utilisateur
+
+
diff --git a/doc/gui-stack-design.md b/doc/gui-stack-design.md
new file mode 100644
index 0000000..b545520
--- /dev/null
+++ b/doc/gui-stack-design.md
@@ -0,0 +1,65 @@
+(sorry, in french for the moment)
+
+# Design de la pile GUI
+
+Deux protocoles :
+
+- GIP (Graphics Initiation Protocol) : un buffer graphique, un clavier, une
+  souris. Redimensionnement. Création du buffer partagé. Opération de reset.
+  Extension possible de GIP pour le son.
+- WMP (Window Management Protocol) : création de fenêtres et d'un canal GIP pour
+  chaque fenêtre. Déplacement, barres de titre, icônes, propriétés quelconques,
+  messages, notifications, ... Gère une hiérarchie de canaux WMP : dans un canal
+  WMP on peut demander la création d'un nouveau canal WMP qui sera créé comme
+  fils du canal actuel.
+
+Pile graphique :
+
+- Serveur graphique racine : parle au matériel, fournit un canal GIP (root GIP).
+- Login manager : parle au root GIP, a sa propre UI pour lancer des sessions et
+  compagnie, crée pour chaque sous-session un canal GIP particulier (session
+  GIP).
+- Session manager : parle au login manager, a accès au session GIP, gère les
+  fenêtres et propose des canaux WMP pour les applications de la session (ce qui
+  engendre la création de canaux window GIP pour chaque fenêtre)
+- Bibliothèque "libtk" : sur une session GIP donner une interface facile pour
+  créer des widgets, gérer des layouts de widgets, gérer les interactions
+  (transformation des keycodes en lettres, etc.)
+
+Applications système :
+
+- Desktop manager : lancé par le session manager, affiche l'interface
+  utilisateur de base. C'est le client du WMP racine pour la session. Inclut la
+  portion "gestionnaire de fichier" de l'UI.
+- Terminal : application qui peut tourner sur un simple GIP, en particulier en
+  plein écran dans une session administrateur (ou directement sur le serveur
+  racine tant qu'on n'aura pas écrit le login manager). Crée un canal
+  pur-textuel (type VT100) pour les applications console à l'intérieur.
+
+Deux types d'application :
+
+- Des applications WMP qui désirent utiliser plusieurs fenêtres (la majorité des
+  cas). S'attendent à être lancées avec comme file descriptor 0 un canal WMP.
+- Des applications GIP qui utilisent une seule fenêtre (typiquement, les jeux).
+  S'attendent à être lancées avec comme FD0 un canal GIP.
+
+Le desktop manager, lorsqu'il lance une application, doit demander la création
+d'un nouveau canal WMP pour cette application. De plus si l'application indique
+que c'est une simple application GIP alors le desktop manager s'occupe du
+dialogue sur ce canal WMP particulier pour la création d'une fenêtre et du
+lancement du GIP correspondant pour l'application. Il peut ainsi binder le bon
+FD0 sur le process de l'application lancée.
+
+Hiérarchie de raccourcis claviers et d'interceptions :
+
+- Quand on est dans une session utilisateur, le login manager agit comme un
+  proxy GIP. Il intercepte simplement le raccourci Ctrl+Alt+Del, qui renvoie sur
+  l'interface du gestionnaire de session (changer d'utilisateur, ou bien tuer
+  des sessions ou lancer les outils d'administration)
+- Quand on est dans une session utilisateur, le window manager (session manager)
+  intercepte tous les raccourcis avec la touche "super". La plupart sont
+  directement liés au window-management, mais on peut imaginer un raccourci qui
+  lance une interface qui liste la hiérarchie de toutes les sessions WMP actives
+  et permette de les tuer sélectivement, neutralisant ainsi les applications qui
+  spamment l'interface de messages débiles.
+
diff --git a/doc/roadmap.md b/doc/roadmap.md
new file mode 100644
index 0000000..fb5b8b2
--- /dev/null
+++ b/doc/roadmap.md
@@ -0,0 +1,38 @@
+# Roadmap
+
+## Plans for soon
+
+* Write device drivers : keyboard, FAT (or EXT2 ?)
+* Work on userland : init, terminal emulator, shell
+* GUI server with help from kernel for framebuffer management
+
+## Things to design
+
+* Reclaiming physical memory :
+  - Freeing some cached stuff, ie swapping pages from mmap regions
+  - Swapping pages from processes non-mmap regions (ie real data regions)
+* Better handling of errors (rather than panicing) ; userspace apps should not
+  have the possibility of crashing the system
+* How does a process transmit information (such as environment, arguments, file
+  descriptors) to its children ?
+* How do we do stream-like IO on files ? (ie how do we implement the append
+* access mode
+  and non-position-dependant read/write calls & seek call)
+* Better error reporting for system calls that fail
+
+## Things not sure
+
+* VFS thread safety : is the design correct ? (probably)
+* Cache architecture (called *pager*, after 4.4BSD terminology)
+* Not enough tests!
+
+## Plans for the later future
+
+* Define a format for "packages", i.e. read-only filesystem images used for
+* adding system
+  components or apps to the OS ; make sure to implement it in a way that does
+  not waste memory
+* Module system for extending the kernel In userspace, simple Scheme-like
+* scripting language POSIX compatibility layer, self-hosting OS The obvious
+* stuff ;-)
+