[Kos-cvs] kos/modules/debug bochs.c,1.13,1.14

[thomas at kos.enix.org]

Update of /home/kos/cvs/kos/modules/debug
In directory the-doors:/tmp/cvs-serv27084/modules/debug

Modified Files:
	bochs.c 
Log Message:
2005-01-16  Thomas Petazzoni  <thomas at crazy.kos.nx>

	* modules/i8042/i8042.c: Correct the name of init_module_level0 to
	init_module_level4, as reported by David Mentré.

	* modules/console/console.c: GPL header + doxygen documentation.

	* modules/console/console.h: GPL header + doxygen documentation.

	* modules/console/_console.h: GPL header + doxygen documentation.

	* modules/console/_console.c: GPL header + doxygen documentation.

	* modules/doc.cfg (PROJECT_NUMBER): Increment KOS version ;-)

	* doc/Makefile (SRCS): Add the helloworld documentation to the
	list of documentation automatically generated.

	* modules/debug/bochs.c: Some doxygen documentation.



Index: bochs.c
===================================================================
RCS file: /home/kos/cvs/kos/modules/debug/bochs.c,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -d -r1.13 -r1.14
--- bochs.c	18 Aug 2003 17:05:26 -0000	1.13
+++ bochs.c	16 Jan 2005 11:42:14 -0000	1.14
@@ -1,12 +1,42 @@
 /*
- * Copyright (C) 2000, Thomas PETAZZONI
- * http://kos.enix.org
+ * Copyright (C) 2000-2005
+ * David Decotigny, Julien Munier, Thomas Petazzoni
  *
- * Debug functions on bochs ports (e8 + e9)
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
+ * USA.
  *
  * @(#) $Id$
  */
 
+/**@file
+ * Debugging facilities usable with PC emulators.
+ *
+ * This file implements debugging facilities usable with the Bochs
+ * emulator (http://bochs.sf.net), or with the Qemu emulator
+ * (http://bellard.org/qemu/). As of January, 15th, the Qemu emulator
+ * has to be patched by the port-e9-hack patch to allow these
+ * debugging facilities to work.
+ *
+ * The 0xE9 port hack is a facility imagined by Emmanuel Marty. 0xE9
+ * is an I/O port unused on regular PC computers, so it can be used
+ * safely. The idea is that any character printed to this I/O port
+ * will be printed to the terminal which is running the emulator. It
+ * allows the guest OS to output lots of debugging information without
+ * having to implement a powerful console driver.
+ */
+
 #include "bochs.h"
 
 #include <loader/mod.h>
@@ -16,28 +46,58 @@
 
 SPINLOCK(bochs_output_spinlock);
 
-void bochs_putchar(int c) 
+/**
+ * Print a character through the 0xE9 hack.
+ *
+ * @param c The character to be printed to the 0xE9 port.
+ */
+void bochs_putchar(int c)
 {
   outb(c, 0xE9);
 }
 
+/**
+ * We use a static global buffer to format the output. As this is a
+ * global buffer, it is shared by all threads running is the system,
+ * so it is protected with the bochs_output_spinlock.
+ */
 static char bochs_printk_buf[1024];
 
+/**
+ * Print a string to the 0xE9 port without taking care of locking
+ * consideration. It is an internal function, used only by
+ * bochs_printk.
+ *
+ * @param str The string to be printed to the 0xE9 port. The string is
+ * printed without any formatting process (no %d, %s, %x...).
+ *
+ * @return The number of character printed.
+ */
 static int bochs_prints_unsafe(const char *str)
 {
   const char *c;
 
   for (c = str; *c != '\0'; c++)
    bochs_putchar(*c);
-  
+
   return (int) (c-str);
 }
 
+/**
+ * Print an already-formatted string to the 0xE9 port. This function
+ * is publicly available, so it takes care of taking the
+ * bochs_output_spinlock.
+ *
+ * @param str The string to be printed to the 0xE9 port. The string is
+ * printed without any formatting process (no %d, %s, %x...).
+ *
+ * @return The number of character printed.
+ */
 int bochs_prints(const char *str)
 {
   k_ui32_t flags;
   int ret;
-  
+
   write_spin_lock(bochs_output_spinlock, flags);
   ret = bochs_prints_unsafe(str);
   write_spin_unlock(bochs_output_spinlock, flags);
@@ -45,7 +105,16 @@
   return ret;
 }
 
-int bochs_printk(const char *format, ...) 
+/**
+ * Format and print a string to the 0xE9 port. This function has a
+ * printf() style and so can use all formatting facilities such as %d,
+ * %x, %s, %d, etc.
+ *
+ * @param format The format string
+ *
+ * @return The number of character printed.
+ */
+int bochs_printk(const char *format, ...)
 {
   k_ui32_t flags;
   va_list args;
@@ -54,17 +123,13 @@
   va_start(args, format);
 
   write_spin_lock(bochs_output_spinlock, flags);
-  len = vsnprintf(bochs_printk_buf,sizeof(bochs_printk_buf),format,args);  
+  len = vsnprintf(bochs_printk_buf,sizeof(bochs_printk_buf),format,args);
   ret = bochs_prints_unsafe(bochs_printk_buf);
   write_spin_unlock(bochs_output_spinlock, flags);
 
   return ret;
 }
 
-
-
 EXPORT_FUNCTION(bochs_putchar);
 EXPORT_FUNCTION(bochs_printk);
 EXPORT_FUNCTION(bochs_prints);
-
-