[Kos-cvs] kos/doc testingfr.tex,1.14,1.15

[thomas at kos.enix.org]

Update of /var/cvs/kos/kos/doc
In directory the-doors:/tmp/cvs-serv10813/doc

Modified Files:
	testingfr.tex 
Log Message:
2004-12-28  Thomas Petazzoni  <thomas at crazy.kos.nx>

	* modules/x86/task/task.c: Try to restrict access to exported
	symbol.

	* modules/x86/task/_thread_cpu_context.c: Move to the new PMM
	system.

	* modules/x86/task/Makefile (all): arch_task.ro instead of
	arch-task.ro.

	* modules/x86/mm/_team_mm_context.c: More informations.

	* modules/x86/mm/_mm.h, modules/x86/mm/mm.c, modules/x86/mm/_rmap.c,
	modules/x86/mm/_vmap.c: The new VMAP/RMAP system. We also make
	sure access to all exported function is restricted to the VMM
	module. 

	* modules/x86/mm/Makefile (all): arch_mm.ro instead of
	arch-mm.ro. 

	* modules/x86/lib/Makefile (all): Rename to arch_lib.ro instead of
	arch-lib.ro. 

	* modules/x86/internals.h: More definitions on the address space
	configuration. 

	* modules/vmm/vmm.h (struct address_space): Add a mutex and a
	spinlock to protect address space.

	* modules/vmm/vmm.c: Restrict access to some exported
	functions. More work has to be done in this area.

	* modules/vmm/_vmm_map.c: Part of the new vmap system.

	* modules/vmm/_vmm_as.c: Make the appropriate lock/unlock on the
	address space mutex. It's just a first try. More reflexion has to
	be made.

	* modules/task/task.h: Make sure DOXYGEN doesn't try to analyze
	the #if stuff, because it doesn't like it.

	* modules/task/_task_utils.c (show_all_thread_info): If team is
	NULL, it means that we want to display the threads of all teams.

	* modules/scheduler/synchq.h: Avoid inclusion of task.h.

	* modules/pmm/pmm.c: New PMM system.

	* modules/pmm/_pmm_put_page.c: New PMM system.

	* modules/pmm/_pmm_init.c: New PMM system.

	* modules/pmm/_pmm_get_page.c: New PMM system.

	* modules/pmm/_pmm_get_at_addr.c: New PMM system.

	* modules/pmm/_pmm.h: struct gpfme is now private.

	* modules/pmm/pmm.h: struct gpfme is now private (migrated to
	_pmm.h). 

	* modules/pmm/Makefile (OBJS): New PMM system, with fewer
	functionnalities. 

	* modules/kos/spinlock.h: New type spinlock_flags_t, that should
	be used instead of k_ui32_t for spinlock flags.

	* modules/kmem/_kvmem_utils.c: Migration to the new PMM
	system and various cleanups.

	* modules/kmem/_kvmem_init.c: Migration to the new PMM
	system and various cleanups.

	* modules/kmem/_kslab_cache_grow.c: Migration to the new PMM
	system and various cleanups.

	* modules/kmem/_kslab_cache_free.c: Migration to the new PMM
	system, and various cleanups.

	* modules/kitc/_kmutex.c: DEBUG_PRINT3 calls to show mutex
	lock/unlock/trylock.

	* modules/init/_init_modules.c (init_modules): A message is
	displayed when initializating modules.

	* modules/ide/_ide.c: Various cleanups.

	* modules/fs/fat/_fat.c: Various cleanups.

	* modules/fs/devfs/devfs.c: Various cleanups, including whitespace
	cleanification.

	* modules/debug/debug.h: Add the DEBUG_PRINT1, DEBUG_PRINT2,
	DEBUG_PRINT3 macros. Maybe there's a cleaner way to do it. David ?

	* modules/debug/debug.c (init_module_level0): Init the
	backtracking stuff a little later so that we have debugging
	messages during this initialization.

	* modules/debug/bt.c (_init_backtracing_stuff): bt_next is not
	anymore a valid candidate to determine if fomit-frame-pointer was
	selected or not, because of gcc optimizations. We use bt_init
	instead.

	* modules/Makefile (doc): Add a target that generates the doxygen
	documentation. 

	* loader/mod.h (EXPORT_FUNCTION_RESTRICTED): Change the symbol
	names generated by the macros, so that they include the name of
	the target module (the one allowed to import the exported
	symbol). This is needed in order to export the same symbol to
	multiple modules. Previously, the RESTRICTED system generated
	symbols that were identical for a given symbol exported to
	multiple modules.

	* doc/testingfr.tex: A big update to this documentation. Not
	finished. The english version should also be updated.

	* TODO: Some new things to do.

	* MkVars (CFLAGS): Pass the DEBUG_LEVEL Makefile variable to the C
	files. In each modules/.../Makefile, we can set a
	DEBUG_LEVEL=value that will set the level of verbosity of the
	module. Macros named DEBUG_PRINT1, DEBUG_PRINT2, DEBUG_PRINT3 have
	been added.
	(MODULES): Change all '-' to '_', because of the new
	EXPORT_FUNCTION_RESTRICTED system. This system creates symbol that
	contains the name of a module (the one allowed to import the
	exported symbol). But the '-' character is not allowed inside C
	identifiers. So, we use '_' instead.

	* CREDITS: Add Fabrice Bellard to the CREDITS, for his Qemu
	emulator.



Index: testingfr.tex
===================================================================
RCS file: /var/cvs/kos/kos/doc/testingfr.tex,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -d -r1.14 -r1.15
--- testingfr.tex	3 Jan 2004 16:57:08 -0000	1.14
+++ testingfr.tex	28 Dec 2004 18:44:11 -0000	1.15
@@ -15,47 +15,39 @@
 \usepackage{graphics}
 \usepackage{graphicx}
 \usepackage{url}
+\usepackage{a4wide}
+\usepackage{palatino}
 
 \newcommand{\ol}{\em}
-\newcommand{\kos}{{\ol KOS\ }}
+\newcommand{\kos}{{\sc Kos\ }}
 
-\title{Tester et débugger \kos}
+\title{Compiler, tester et débugger \kos}
 \author{Thomas Petazzoni}
+\date{28 décembre 2004}
 
 \begin{document}
 \maketitle
 
 \section*{Introduction}
 
-La partie codage en elle même ne représente qu'une fraction de la
-programmation de \kos : les tests et le debugging sont aussi
-extrêmement importants. Pour une application ``normale'', les
-débuggeurs classiques (\emph{gdb}) peuvent être utilisés, mais pour un
-OS, il convient de se créer ses propres moyens de test et de
-debugging.
+La compilation, le test et le débuggage d'un système d'exploitation
+n'est jamais une tâche aisée. Dans l'objectif de rendre celle-ci plus
+simple pour de nouveaux développeurs ou testeurs, cette documentation
+a été rédigée. Elle détaille étape par étape comment compiler \kos,
+puis comment le tester, et enfin quels sont les outils de débuggage
+disponibles.
 
-Il est très important pour nous de recevoir divers reports de
-problèmes ou de bugs concernant \kos, car nous ne pouvons pas le
-tester sur un grand nombre de machines avec du matériel
-différent. 
+\bigskip
 
 Pour contacter l'équipe de développement, visitez le site
-Web \url{http://kos.enix.org} ou écrivez à :
+Web\footnote{\url{http://kos.enix.org}} ou écrivez à :
 
 \begin{itemize}
-\item David Decotigny~: \emph{david.decotigny at irisa.fr}
-\item Julien Munier~: \emph{munier at wanadoo.fr}
-\item Thomas Petazzoni~: \emph{thomas.petazzoni at meridon.com}
+\item David Decotigny~: \emph{d2 at enix.org}
+\item Julien Munier~: \emph{mejj at enix.org}
+\item Thomas Petazzoni~: \emph{thomas.petazzoni at enix.org}
 \end{itemize}
 
-Une mailing list \emph{kos-bug} sera prochainement mise en place.
-
-Ce document explique donc pas à pas comment télécharger \kos, le
-compiler, le tester, trouver l'origine d'éventuels bugs, et les
-reporter.
-
-Merci !
-
 \newpage
 \tableofcontents
 
@@ -135,7 +127,13 @@
 configurés. Ils sont en général disponibles en standard dans toute
 bonne distribution d'Unix libre, mais la section \ref{utils:urls} de
 ce document donnera une liste d'adresses Internet indiquant où l'on
-peut les télécharger.
+peut les télécharger. En particulier, {\em make}, {\em gcc}, et {\em
+  binutils} sont généralement installés par défaut dans toute
+distribution GNU/Linux. Les autres outils sont disponibles sous forme
+de paquetage. Ainsi, dans la distribution
+Debian\footnote{\url{http://www.debian.org}}, il faut installer
+les paquets {\tt mtools}, {\tt grub}, {\tt libxml2-dev} et {\tt
+  console-tools}.
 
 Pour le moment, nous n'avons essayé de compiler \kos que sur les
 architectures suivantes :
@@ -172,86 +170,6 @@
 L'image de disque dur produite est dans le module {\tt kos-sys}, sous
 le nom {\tt hd10M.img}.
 
-\section{Compilation sous Windows}
-
-A noter que la compilation sous Windows n'a pas été testée depuis un
-long moment. Nous utilisons de nombreux programmes annexes comme Grub,
-Mtools, Libxml2 ou Loadkeys qui rendent délicate la compilation sous
-ce système. Cependant, si vous essayez la compilation, n'hésitez pas à
-nous faire part des problèmes rencontrés.
-
-\subsection{Prérequis}
-
-Il est théoriquement possible de compiler \kos sous Windows, mais pour
-celà vous devez disposer de programmes non disponibles en standard :
-
-\begin{enumerate}
-\item Cygwin32, version 1.1.1 ou plus récente
-\item Rawrite (DOS)
-\item Un compilateur générant des fichiers ELF reposant sur Binutils
-2.9.1.0.23 ou plus récent, par exemple celui de RTEMS.
-\item Libxml2
-\item Une version recompilée pour Windows du programme {\tt
-  loadkeys}.
-\end{enumerate}
-
-Tout d'abord, installez Cygwin, en suivant les instructions
-disponibles dans le README sur serveur FTP de Cygwin. Ensuite, lancez
-Cygwin, en utilisant le fichier {\tt cygnus.bat} suivant :
-
-\begin{verbatim}
- at echo off
-set make_mode=unix
-set path=c:\windows\cygnus\cygwin-1.1\bin;%PATH%
-bash
-\end{verbatim}
-
-Ensuite, installez le compilateur ELF via la commande suivante,
-exécutée à la racine du système Cygwin ({\tt cd /})~:
-
-\begin{verbatim}
-tar xvzf cygwin-elf.tar.gz
-\end{verbatim}
-
-{\bf Remarque :} sous Cygwin, la racine (``/'') correspond à
-l'endroit où vous avez installé Cygwin. Pour accéder aux lecteurs
-``normaux'' de Windows, il suffit de faire ``cd //c'' pour accéder à
-C:. Ce comportement peut être modifié en utilisant la commande
-{\tt mount} ou en éditant la base de registre.
-
-\subsection{Compilation}
-
-La méthode pour compiler \kos sous Windows est assez semblable à la méthode
-pour compiler \kos sous Unix.
-
-Il faudra d'abord compiler le chargeur et les modules, via {\tt make
-clean all}.
-
-Ensuite, on pourra créer une image de disquette Grub en copiant les
-modules et le chargeur sur une disquette avec un Grub préinstallé. En
-effet, Grub n'est pas utilisable sous Windows, il faut alors ruser.
-
-La solution la plus simple pour crééer une image de disquette sous
-Windows, est de télécharger depuis le site de \kos une image de
-disquette, que l'on copiera sur une disquette à l'aide de {\tt
-rawrite}, ou a laquelle on accedera en utilisant les mtools (URL en annexe),
-disponibles sous Windows.
-
-Il suffira alors de copier les modules et le loader fraîchement
-compilés sur la disquette directement avec Windows, ou sur l'image de
-disquette en utilisant les mtools, à l'emplacement prévu à cet
-effet. Vous pourrez aussi personnaliser le fichier {\tt menu.lst} de
-la disquette pour ne charger que certains modules, ou pour ajouter vos
-modules.
-
-Vous devrez également créer un répertoire {\tt C:/bin/}
-(partition FAT) et y placer {\em kos-sys/src/console\/}.
-
-Si vous avez utilisé une disquette, celle-ci est prête à être testée
-sur une machine réelle. Si vous avez utilisé l'image de disquette,
-alors celle-ci est prête pour être bootée dans un émulateur, Bochs ou
-VMWare par exemple.
-
 \section{Tester sur une machine réelle}
 
 \kos est un système d'exploitation complet, on peut donc le tester sur
@@ -259,7 +177,7 @@
 l'instant pas très souple : les applications utilisateur de test
 doivent obligatoirement être à la racine de la première partition du
 premier disque. Nous recommandons donc de tester \kos dans Bochs ou
-dans un autre émulateur.
+dans un autre émulateur, voir \ref{emu}.
 
 \subsection{Avec une disquette}
 
@@ -274,12 +192,8 @@
 dd if=kos/grub/fd.img of=/dev/fd0 bs=18k conv=sync
 \end{verbatim}
 
-En ce qui concerne le chargement des applications utilisateur de tests
-du module {\tt kos-sys}, le système \textsc{Kos} va chercher
-automatiquement à monter la première partition du premier disque, qui
-doit être au format FAT. Elle sera montée dans le répertoire {\tt
-  /file}, et \textsc{Kos} s'attend à trouver les applications de test
-directement à la racine. Pour l'instant, ce n'est pas très flexible.
+Il suffit ensuite de rédémarrer la machine et de la faire booter sur
+la disquette.
 
 \subsection{Par réseau}
 
@@ -465,18 +379,30 @@
 (surtout quand il est open source) est vraiment très pratique pour le
 debugging.
 
-Nous utilisons l'émulateur Bochs, que nous préférons à Plex86. Bochs
-est bien sûr téléchargeable sur Internet, des versions binaires
-existent pour Linux et Windows, et les sources sont disponibles car
-c'est un projet sous licence GPL. Vous pouvez aussi utiliser VMWare,
-disponible sous Windows et Linux à l'adresse
-\url{http://www.vmware.com}.\footnote{Attention : contrairement à
-Bochs, VMWare n'est pas un logiciel libre !}
+Nous utilisons principalement {\em Bochs} (voir \ref{emu:bochs}) et
+{\em Qemu} (voir \ref{emu:qemu}). Il est
+également possible d'utiliser {\em VMWare} (voir \ref{emu:vmware}),
+mais ce n'est pas un Logiciel Libre !
 
-\subsection{Compilation et installation de Bochs}
+\subsection{Bochs}
 
-Si vous avez téléchargé une version binaire, vous pouvez passer cette
-section qui concerne la compilation et l'installation.
+\label{emu:bochs}
+
+{\em Bochs} est un émulateur d'architecture x86 plateforme PC
+standard. Il permet d'émuler des lecteurs de disquette, de disques
+durs, de CD-ROM, le PCI, une carte son et le réseau. Le site officiel
+de Bochs est \url{http://bochs.sourceforge.net}.
+
+{\em Bochs} est disponible en version binaire pour Windows ou Unix sur
+le site Web. Les sources sont également disponibles sous forme
+d'archives, ou via CVS. Certaines distributions GNU/Linux, dont {\em
+Debian} proposent des paquets précompilés pour {\em Bochs}.
+
+\subsubsection{Compilation et installation de Bochs}
+
+Si vous avez téléchargé une version binaire ou une version précompilée
+pour votre distribution GNU/Linux, vous pouvez passer cette section
+qui concerne la compilation et l'installation.
 
 Pour compiler Bochs, c'est assez simple :
 
@@ -510,9 +436,9 @@
 ln -s bochs /usr/bin/bochs
 \end{verbatim}
 
-\subsection{Configuration de Bochs}
+\subsubsection{Configuration de Bochs}
 
-\subsubsection{Configuration de base}
+\paragraph{Configuration de base}
 
 Bochs dispose maintenant d'une interface en mode texte permettant de
 configurer la plupart des paramètres importants. Toutefois, je vais
@@ -532,7 +458,7 @@
 Evidemment n'oubliez pas de personnaliser ces lignes pour qu'elles
 correspondent à votre configuration.
 
-\subsubsection{Fabrication de votre propre image de disque dur}
+\paragraph{Fabrication de votre propre image de disque dur}
 
 Avec Bochs, il est possible d'émuler le controleur IDE, et donc
 d'avoir dans le système qui tourne dans l'émulateur des disques
@@ -583,7 +509,7 @@
 Le driver IDE de KOS devrait normalement reconnaître la présence d'un
 disque dur en {\em Primary Master}.
 
-\subsection{Utilisation de Bochs}
+\subsubsection{Utilisation de Bochs}
 
 Pour utiliser Bochs à partir des sources de \kos, utilisez simplement
 la commande :
@@ -604,7 +530,16 @@
 bochs
 \end{verbatim}
 
-\subsection{Installation et utilisation de VMWare}
+\subsection{Qemu}
+
+\label{emu:qemu}
+
+{\em Qemu} est un émulateur écrit par Fabrice Bellard, et disponible
+sur le site ????. FIXME.
+
+\subsection{VMWare}
+
+\label{emu:vmware}
 
 Nous ne détaillerons pas la procédure d'installation de VMWare, elle
 st complètement automatisée par le script \texttt{vmware-install.pl}
@@ -617,14 +552,17 @@
 
 \section{Débugger dans un émulateur}
 
-\subsection{Le port-e9-hack de Bochs}
+\subsection{Le port-e9-hack}
 
-L'option \tt --enable-port-e9-hack \rm permet d'avoir les messages de
-debug dans le terminal qui a lancé Bochs. 
+\subsubsection{Dans Bochs}
+
+Dans {\em Bochs}, le {\em port-e9-hack} est intégré en standard dans
+les sources, et est activé dès lors qu'il a été compilé avec l'option
+de configure {\tt --enable-port-e9-hack}.
 
 Pour activer l'envoi des messages de debugging pour le loader, éditez
 le fichier {\tt loader/config.h} et vérifiez que la constante {\em
-DEBUG\_ON\_BOCHS\/} est bien définie. 
+DEBUG\_ON\_BOCHS\/} est bien définie.
 
 Pour activer l'envoi des messages de debugging pour les modules (le
 noyau), faites de même pour le fichier {\tt modules/config.h}.
@@ -638,12 +576,18 @@
 conservant de nombreuses lignes d'historique, comme c'était le cas
 pour le debugging via ligne série.
 
+\subsubsection{Dans Qemu}
+
+Dans {\em Qemu}, le {\em port-e9-hack} n'est pas disponible en
+standard, mais nous proposons un patch pour Qemu permettant de
+l'intégrer. Celui-ci sera prochainement disponible.
+
 \subsection{Les sources de Bochs}
 
 Bochs étant sous licence GPL, ses sources sont disponibles et surtout
 modifiables. On peut donc modifier le comportement de la machine
 virtuelle, et obtenir de nombreuses informations sur ce qui se déroule
-en interne du processeur. 
+en interne du processeur.
 
 \subsection{Le debugger de Bochs}
 
@@ -690,7 +634,7 @@
 propres patchs corrigeant les éventuels bugs que vous auriez pu
 trouver.
 
-\section{Diverses URLs}
+\section{Références}
 \label{utils:urls}
 
 \begin{enumerate}
@@ -716,4 +660,106 @@
 \item \url{http://www.vmware.com}~: Le site officiel de VMWare
 \end{enumerate}
 
+\appendix
+\section{Compilation sous Windows}
+
+La compilation sous Windows n'a pas été testée depuis un long
+moment. Nous utilisons de nombreux programmes annexes comme Grub,
+Mtools, Libxml2 ou Loadkeys qui rendent délicate la compilation sous
+ce système. Cependant, si vous essayez la compilation, n'hésitez pas à
+nous faire part des problèmes rencontrés.
+
+\subsection{Prérequis}
+
+Il est théoriquement possible de compiler \kos sous Windows, mais pour
+celà vous devez disposer de programmes non disponibles en standard :
+
+\begin{enumerate}
+\item Cygwin32, version 1.1.1 ou plus récente
+\item Rawrite (DOS)
+\item Un compilateur générant des fichiers ELF reposant sur Binutils
+2.9.1.0.23 ou plus récent
+\item Libxml2
+\item Une version recompilée pour Windows du programme {\tt
+  loadkeys}.
+\end{enumerate}
+
+Tout d'abord, installez Cygwin, en suivant les instructions
+disponibles dans le README sur serveur FTP de Cygwin. Ensuite, lancez
+Cygwin, en utilisant le fichier {\tt cygnus.bat} suivant :
+
+\begin{verbatim}
+ at echo off
+set make_mode=unix
+set path=c:\windows\cygnus\cygwin-1.1\bin;%PATH%
+bash
+\end{verbatim}
+
+Le problème est que le compilateur {\em gcc} de Cygwin génère des
+éxécutables au format {\em PE}, le format binaire de Microsoft
+Windows. Or \kos doit être compilé dans le format binaire {\em
+  ELF}. C'est la raison pour laquelle vous avez besoin de deux
+compilateurs :
+
+\begin{itemize}
+
+ \item Le {\em gcc} de Cygwin, fournit par défaut et qui génère des
+ fichiers au format {\em PE}. Celui-ci permettra de compiler les
+ programmes devant tourner sur la machine (vérificateurs, générateurs
+ de fichiers),
+
+ \item Un {\em gcc} générant des binaires au format {\em ELF}. Ce
+ dernier n'est pas fourni en standard dans Cygwin. Il faudra donc soit
+ le compiler\footnote{Il faudra alors procéder par cross-compilation,
+ voir
+ \url{http://www.mega-tokyo.com/osfaq2/index.php/GCC\%20Cross-Compiler}},
+ soit en récupérer une version précompilée.
+
+\end{itemize}
+
+{\bf Remarque :} sous Cygwin, la racine (``/'') correspond à
+l'endroit où vous avez installé Cygwin. Pour accéder aux lecteurs
+``normaux'' de Windows, il suffit de faire ``cd //c'' pour accéder à
+C:. Ce comportement peut être modifié en utilisant la commande
+{\tt mount} ou en éditant la base de registre.
+
+\subsection{Compilation}
+
+La méthode pour compiler \kos sous Windows est assez semblable à la méthode
+pour compiler \kos sous Unix.
+
+Il faudra d'abord compiler le chargeur et les modules, via {\tt make
+clean all}.
+
+Ensuite, on pourra créer une image de disquette Grub en copiant les
+modules et le chargeur sur une disquette avec un Grub préinstallé. En
+effet, Grub n'est pas utilisable sous Windows, il faut alors ruser.
+
+La solution la plus simple pour crééer une image de disquette sous
+Windows, est de télécharger depuis le site de \kos une image de
+disquette, que l'on copiera sur une disquette à l'aide de {\tt
+rawrite}, ou a laquelle on accedera en utilisant les mtools (URL en annexe),
+disponibles sous Windows.
+
+Il suffira alors de copier les modules et le loader fraîchement
+compilés sur la disquette directement avec Windows, ou sur l'image de
+disquette en utilisant les mtools, à l'emplacement prévu à cet
+effet. Vous pourrez aussi personnaliser le fichier {\tt menu.lst} de
+la disquette pour ne charger que certains modules, ou pour ajouter vos
+modules.
+
+Vous devrez également créer un répertoire {\tt C:/bin/}
+(partition FAT) et y placer {\em kos-sys/src/console\/}.
+
+Si vous avez utilisé une disquette, celle-ci est prête à être testée
+sur une machine réelle. Si vous avez utilisé l'image de disquette,
+alors celle-ci est prête pour être bootée dans un émulateur, Bochs ou
+VMWare par exemple.
+
+{\bf Attention:} À l'heure actuelle, \kos ne compile pas avec Cygwin,
+en raison d'un conflit sur la définition du type {\tt addr\_t}. Un
+patch a été écrit pour résoudre ce problème, mais n'est pas encore
+intégré au CVS. N'hésitez pas à demander des renseignements
+complémentaires.
+
 \end{document}