Convert some comments to proper Doxygen syntax.

Also, make them all fit in 80chars/column, fix some whitespace issues
and also some typos I noticed.

Signed-off-by: Uwe Hermann <uwe@hermann-uwe.de>
Acked-by: Uwe Hermann <uwe@hermann-uwe.de>



git-svn-id: svn://svn.coreboot.org/coreboot/trunk@5993 2b7e53f0-3cfb-0310-b3e9-8179ed1497e1

9 files changed, 210 insertions, 336 deletions

diff --git a/src/superio/smsc/lpc47b272/lpc47b272_early_serial.c b/src/superio/smsc/lpc47b272/lpc47b272_early_serial.c
index c1f15bf25e..0c31b3a935 100644
--- a/src/superio/smsc/lpc47b272/lpc47b272_early_serial.c
+++ b/src/superio/smsc/lpc47b272/lpc47b272_early_serial.c
@@ -23,38 +23,26 @@
 #include <arch/romcc_io.h>
 #include "lpc47b272.h"
 
-/*
- * Function:    	pnp_enter_conf_state
- * Parameters:  	dev - high 8 bits = Super I/O port
- * Return Value:	None
- * Description: 	Enable access to the LPC47B272's configuration registers.
- */
+/** Enable access to the LPC47B272's configuration registers. */
 static inline void pnp_enter_conf_state(device_t dev)
 {
 	unsigned port = dev>>8;
 	outb(0x55, port);
 }
 
-/*
- * Function:    	pnp_exit_conf_state
- * Parameters:  	dev - high 8 bits = Super I/O port
- * Return Value:	None
- * Description: 	Disable access to the LPC47B272's configuration registers.
- */
+/** Disable access to the LPC47B272's configuration registers. */
 static void pnp_exit_conf_state(device_t dev)
 {
 	unsigned port = dev>>8;
 	outb(0xaa, port);
 }
 
-/*
- * Function:    	lpc47b272_enable_serial
- * Parameters:  	dev - high 8 bits = Super I/O port,
- *			      low 8 bits = logical device number (per lpc47b272.h)
- *			iobase - processor I/O port address to assign to this serial device
- * Return Value:	bool
- * Description: 	Configure the base I/O port of the specified serial device
- *			and enable the serial device.
+/**
+ * Configure the base I/O port of the specified serial device and enable the
+ * serial device.
+ *
+ * @param dev High 8 bits = Super I/O port, low 8 bits = logical device number.
+ * @param iobase Processor I/O port address to assign to this serial device.
  */
 static void lpc47b272_enable_serial(device_t dev, unsigned iobase)
 {
diff --git a/src/superio/smsc/lpc47b272/superio.c b/src/superio/smsc/lpc47b272/superio.c
index 6222a3d3fb..77fadd8a85 100644
--- a/src/superio/smsc/lpc47b272/superio.c
+++ b/src/superio/smsc/lpc47b272/superio.c
@@ -69,30 +69,23 @@ static struct pnp_info pnp_dev_info[] = {
 	{ &ops, LPC47B272_RT,   PNP_IO0, { 0x780, 0 }, },
 };
 
-/**********************************************************************************/
-/*              		PUBLIC INTERFACE				  */
-/**********************************************************************************/
-
-/*
- * Function:    	enable_dev
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Create device structures and allocate resources to devices
- *			specified in the pnp_dev_info array (above).
+/**
+ * Create device structures and allocate resources to devices specified in the
+ * pnp_dev_info array (above).
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
  */
 static void enable_dev(device_t dev)
 {
-	pnp_enable_devices(dev, &pnp_ops,
-			   ARRAY_SIZE(pnp_dev_info),
+	pnp_enable_devices(dev, &pnp_ops, ARRAY_SIZE(pnp_dev_info),
 			   pnp_dev_info);
 }
 
-/*
- * Function:    	lpc47b272_pnp_set_resources
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Configure the specified Super I/O device with the resources
- *			(I/O space, etc.) that have been allocated for it.
+/**
+ * Configure the specified Super I/O device with the resources (I/O space,
+ * etc.) that have been allocated for it.
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
  */
 static void lpc47b272_pnp_set_resources(device_t dev)
 {
@@ -122,13 +115,13 @@ static void lpc47b272_pnp_enable(device_t dev)
 	pnp_exit_conf_state(dev);
 }
 
-/*
- * Function:    	lpc47b272_init
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Initialize the specified Super I/O device.
- *			Devices other than COM ports and the keyboard controller are
- *			ignored. For COM ports, we configure the baud rate.
+/**
+ * Initialize the specified Super I/O device.
+ *
+ * Devices other than COM ports and the keyboard controller are ignored.
+ * For COM ports, we configure the baud rate.
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
  */
 static void lpc47b272_init(device_t dev)
 {
@@ -157,40 +150,25 @@ static void lpc47b272_init(device_t dev)
 	}
 }
 
-/**********************************************************************************/
-/*                      	PRIVATE FUNCTIONS				  */
-/**********************************************************************************/
-
-/*
- * Function:    	pnp_enter_conf_state
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Enable access to the LPC47B272's configuration registers.
- */
+/** Enable access to the LPC47B272's configuration registers. */
 static void pnp_enter_conf_state(device_t dev)
 {
 	outb(0x55, dev->path.pnp.port);
 }
 
-/*
- * Function:    	pnp_exit_conf_state
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Disable access to the LPC47B272's configuration registers.
- */
+/** Disable access to the LPC47B272's configuration registers. */
 static void pnp_exit_conf_state(device_t dev)
 {
 	outb(0xaa, dev->path.pnp.port);
 }
 
 #if 0
-/*
- * Function:    	dump_pnp_device
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Print the values of all of the LPC47B272's configuration registers.
- *			NOTE: The LPC47B272 must be in configuration mode when this
- *			function is called.
+/**
+ * Print the values of all of the LPC47B272's configuration registers.
+ *
+ * NOTE: The LPC47B272 must be in config mode when this function is called.
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
  */
 static void dump_pnp_device(device_t dev)
 {
diff --git a/src/superio/smsc/lpc47m10x/lpc47m10x_early_serial.c b/src/superio/smsc/lpc47m10x/lpc47m10x_early_serial.c
index 048a8d314d..e2aa63ab94 100644
--- a/src/superio/smsc/lpc47m10x/lpc47m10x_early_serial.c
+++ b/src/superio/smsc/lpc47m10x/lpc47m10x_early_serial.c
@@ -22,38 +22,26 @@
 #include <arch/romcc_io.h>
 #include "lpc47m10x.h"
 
-/*
- * Function:    	pnp_enter_conf_state
- * Parameters:  	dev - high 8 bits = Super I/O port
- * Return Value:	None
- * Description: 	Enable access to the LPC47M10X2's configuration registers.
- */
+/** Enable access to the LPC47M10X2's configuration registers. */
 static inline void pnp_enter_conf_state(device_t dev)
 {
 	unsigned port = dev>>8;
 	outb(0x55, port);
 }
 
-/*
- * Function:    	pnp_exit_conf_state
- * Parameters:  	dev - high 8 bits = Super I/O port
- * Return Value:	None
- * Description: 	Disable access to the LPC47M10X2's configuration registers.
- */
+/** Disable access to the LPC47M10X2's configuration registers. */
 static void pnp_exit_conf_state(device_t dev)
 {
 	unsigned port = dev>>8;
 	outb(0xaa, port);
 }
 
-/*
- * Function:    	lpc47m10x_enable_serial
- * Parameters:  	dev - high 8 bits = Super I/O port,
- *			      low 8 bits = logical device number (per lpc47m10x.h)
- *			iobase - processor I/O port address to assign to this serial device
- * Return Value:	bool
- * Description: 	Configure the base I/O port of the specified serial device
- *			and enable the serial device.
+/**
+ * Configure the base I/O port of the specified serial device and enable the
+ * serial device.
+ *
+ * @param dev High 8 bits = Super I/O port, low 8 bits = logical device number.
+ * @param iobase Processor I/O port address to assign to this serial device.
  */
 static void lpc47m10x_enable_serial(device_t dev, unsigned iobase)
 {
diff --git a/src/superio/smsc/lpc47m10x/superio.c b/src/superio/smsc/lpc47m10x/superio.c
index ea8cdc1f7d..2288ec9d15 100644
--- a/src/superio/smsc/lpc47m10x/superio.c
+++ b/src/superio/smsc/lpc47m10x/superio.c
@@ -67,30 +67,23 @@ static struct pnp_info pnp_dev_info[] = {
 	{ &ops, LPC47M10X2_KBC,  PNP_IO0 | PNP_IO1 | PNP_IRQ0 | PNP_IRQ1, { 0x7ff, 0 }, { 0x7ff, 0x4}, },
 };
 
-/**********************************************************************************/
-/*              		PUBLIC INTERFACE				  */
-/**********************************************************************************/
-
-/*
- * Function:    	enable_dev
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Create device structures and allocate resources to devices
- *			specified in the pnp_dev_info array (above).
+/**
+ * Create device structures and allocate resources to devices specified in the
+ * pnp_dev_info array (above).
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
  */
 static void enable_dev(device_t dev)
 {
-	pnp_enable_devices(dev, &pnp_ops,
-			   ARRAY_SIZE(pnp_dev_info),
+	pnp_enable_devices(dev, &pnp_ops, ARRAY_SIZE(pnp_dev_info),
 			   pnp_dev_info);
 }
 
-/*
- * Function:    	lpc47m10x_pnp_set_resources
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Configure the specified Super I/O device with the resources
- *			(I/O space, etc.) that have been allocated for it.
+/**
+ * Configure the specified Super I/O device with the resources (I/O space,
+ * etc.) that have been allocated for it.
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
  */
 static void lpc47m10x_pnp_set_resources(device_t dev)
 {
@@ -120,13 +113,13 @@ static void lpc47m10x_pnp_enable(device_t dev)
 	pnp_exit_conf_state(dev);
 }
 
-/*
- * Function:    	lpc47m10x_init
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Initialize the specified Super I/O device.
- *			Devices other than COM ports and the keyboard controller are
- *			ignored. For COM ports, we configure the baud rate.
+/**
+ * Initialize the specified Super I/O device.
+ *
+ * Devices other than COM ports and the keyboard controller are ignored.
+ * For COM ports, we configure the baud rate.
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
  */
 static void lpc47m10x_init(device_t dev)
 {
@@ -155,40 +148,25 @@ static void lpc47m10x_init(device_t dev)
 	}
 }
 
-/**********************************************************************************/
-/*      			PRIVATE FUNCTIONS				  */
-/**********************************************************************************/
-
-/*
- * Function:    	pnp_enter_conf_state
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Enable access to the LPC47M10X2's configuration registers.
- */
+/** Enable access to the LPC47M10X2's configuration registers. */
 static void pnp_enter_conf_state(device_t dev)
 {
 	outb(0x55, dev->path.pnp.port);
 }
 
-/*
- * Function:    	pnp_exit_conf_state
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Disable access to the LPC47M10X2's configuration registers.
- */
+/** Disable access to the LPC47M10X2's configuration registers. */
 static void pnp_exit_conf_state(device_t dev)
 {
 	outb(0xaa, dev->path.pnp.port);
 }
 
 #if 0
-/*
- * Function:    	dump_pnp_device
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Print the values of all of the LPC47M10X2's configuration registers.
- *			NOTE: The LPC47M10X2 must be in configuration mode when this
- *			function is called.
+/**
+ * Print the values of all of the LPC47M10X2's configuration registers.
+ *
+ * NOTE: The LPC47M10X2 must be in config mode when this function is called.
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
  */
 static void dump_pnp_device(device_t dev)
 {
diff --git a/src/superio/smsc/lpc47n217/lpc47n217_early_serial.c b/src/superio/smsc/lpc47n217/lpc47n217_early_serial.c
index 2b0c634bcf..34f2c4512b 100644
--- a/src/superio/smsc/lpc47n217/lpc47n217_early_serial.c
+++ b/src/superio/smsc/lpc47n217/lpc47n217_early_serial.c
@@ -24,38 +24,25 @@
 #include <assert.h>
 #include "lpc47n217.h"
 
-/*
- * Function:    	pnp_enter_conf_state
- * Parameters:  	dev - high 8 bits = Super I/O port
- * Return Value:	None
- * Description:		Enable access to the LPC47N217's configuration registers.
- */
+/** Enable access to the LPC47N217's configuration registers. */
 static inline void pnp_enter_conf_state(device_t dev)
 {
 	unsigned port = dev>>8;
 	outb(0x55, port);
 }
 
-/*
- * Function:		pnp_exit_conf_state
- * Parameters:		dev - high 8 bits = Super I/O port
- * Return Value:	None
- * Description:		Disable access to the LPC47N217's configuration registers.
- */
+/** Disable access to the LPC47N217's configuration registers. */
 static void pnp_exit_conf_state(device_t dev)
 {
 	unsigned port = dev>>8;
 	outb(0xaa, port);
 }
 
-/*
- * Function:	lpc47n217_pnp_set_iobase
- * Parameters:	dev - high 8 bits = Super I/O port,
- *		      low 8 bits = logical device number (per lpc47n217.h)
- *		iobase - base I/O port for the logical device
- * Return Value:None
- * Description:	Program the base I/O port for the specified logical device.
+/**
+ * Program the base I/O port for the specified logical device.
  *
+ * @param dev High 8 bits = Super I/O port, low 8 bits = logical device number.
+ * @param iobase Base I/O port for the logical device.
  */
 void lpc47n217_pnp_set_iobase(device_t dev, unsigned iobase)
 {
@@ -80,19 +67,17 @@ void lpc47n217_pnp_set_iobase(device_t dev, unsigned iobase)
 	}
 }
 
-/*
- * Function:	lpc47n217_pnp_set_enable
- * Parameters:	dev - high 8 bits = Super I/O port,
- *		      low 8 bits = logical device number (per lpc47n217.h)
- *		enable - 0 to disable, anythig else to enable
- * Return Value:None
- * Description:	Enable or disable the specified logical device.
- *		Technically, a full disable requires setting the device's base
- *		I/O port below 0x100. We don't do that here, because we don't
- *		have access to a data structure that specifies what the 'real'
- *		base port is (when asked to enable the device). Also the function
- *		is used only to disable the device while its true base port is
- *		programmed (see lpc47n217_enable_serial() below).
+/**
+ * Enable or disable the specified logical device.
+ *
+ * Technically, a full disable requires setting the device's base I/O port
+ * below 0x100. We don't do that here, because we don't have access to a data
+ * structure that specifies what the 'real' base port is (when asked to enable
+ * the device). Also the function is used only to disable the device while its
+ * true base port is programmed (see lpc47n217_enable_serial() below).
+ *
+ * @param dev High 8 bits = Super I/O port, low 8 bits = logical device number.
+ * @param enable 0 to disable, anythig else to enable.
  */
 void lpc47n217_pnp_set_enable(device_t dev, int enable)
 {
@@ -130,20 +115,19 @@ void lpc47n217_pnp_set_enable(device_t dev, int enable)
 	pnp_write_config(dev, power_register, new_power);
 }
 
-/*
- * Function:	lpc47n217_enable_serial
- * Parameters:	dev - high 8 bits = Super I/O port,
- *		      low 8 bits = logical device number (per lpc47n217.h)
- *		iobase - processor I/O port address to assign to this serial device
- * Return Value:bool
- * Description:	Configure the base I/O port of the specified serial device
- *		and enable the serial device.
+/**
+ * Configure the base I/O port of the specified serial device and enable the
+ * serial device.
+ *
+ * @param dev High 8 bits = Super I/O port, low 8 bits = logical device number.
+ * @param iobase Processor I/O port address to assign to this serial device.
  */
 static void lpc47n217_enable_serial(device_t dev, unsigned iobase)
 {
-	/* NOTE: Cannot use pnp_set_XXX() here because they assume chip
-	 * support for logical devices, which the LPC47N217 doesn't have*/
-
+	/*
+	 * NOTE: Cannot use pnp_set_XXX() here because they assume chip
+	 * support for logical devices, which the LPC47N217 doesn't have.
+	 */
 	pnp_enter_conf_state(dev);
 	lpc47n217_pnp_set_enable(dev, 0);
 	lpc47n217_pnp_set_iobase(dev, iobase);
diff --git a/src/superio/smsc/lpc47n217/superio.c b/src/superio/smsc/lpc47n217/superio.c
index 085331eaa7..95277cd42c 100644
--- a/src/superio/smsc/lpc47n217/superio.c
+++ b/src/superio/smsc/lpc47n217/superio.c
@@ -72,30 +72,23 @@ static struct pnp_info pnp_dev_info[] = {
 	{ &ops, LPC47N217_SP2,  PNP_IO0 | PNP_IRQ0, { 0x7f8, 0 }, }
 };
 
-/**********************************************************************************/
-/*			PUBLIC INTERFACE					  */
-/**********************************************************************************/
-
-/*
- * Function:    	enable_dev
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Create device structures and allocate resources to devices
- *			specified in the pnp_dev_info array (above).
+/**
+ * Create device structures and allocate resources to devices specified in the
+ * pnp_dev_info array (above).
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
  */
 static void enable_dev(device_t dev)
 {
-	pnp_enable_devices(dev, &pnp_ops,
-			   ARRAY_SIZE(pnp_dev_info),
+	pnp_enable_devices(dev, &pnp_ops, ARRAY_SIZE(pnp_dev_info),
 			   pnp_dev_info);
 }
 
-/*
- * Function:    	lpc47n217_pnp_set_resources
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Configure the specified Super I/O device with the resources
- *			(I/O space, etc.) that have been allocate for it.
+/**
+ * Configure the specified Super I/O device with the resources (I/O space,
+ * etc.) that have been allocate for it.
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
  */
 static void lpc47n217_pnp_set_resources(device_t dev)
 {
@@ -118,8 +111,9 @@ static void lpc47n217_pnp_enable_resources(device_t dev)
 {
 	pnp_enter_conf_state(dev);
 
-	/* NOTE: Cannot use pnp_enable_resources() here because it assumes chip
-	 * support for logical devices, which the LPC47N217 doesn't have
+	/*
+	 * NOTE: Cannot use pnp_enable_resources() here because it assumes chip
+	 * support for logical devices, which the LPC47N217 doesn't have.
 	 */
 	lpc47n217_pnp_set_enable(dev, 1);
 
@@ -130,10 +124,10 @@ static void lpc47n217_pnp_enable(device_t dev)
 {
 	pnp_enter_conf_state(dev);
 
-	/* NOTE: Cannot use pnp_set_enable() here because it assumes chip
-	 * support for logical devices, which the LPC47N217 doesn't have
+	/*
+	 * NOTE: Cannot use pnp_set_enable() here because it assumes chip
+	 * support for logical devices, which the LPC47N217 doesn't have.
 	 */
-
 	if(dev->enabled) {
 		lpc47n217_pnp_set_enable(dev, 1);
 	}
@@ -144,13 +138,13 @@ static void lpc47n217_pnp_enable(device_t dev)
 	pnp_exit_conf_state(dev);
 }
 
-/*
- * Function:    	lpc47n217_init
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Initialize the specified Super I/O device.
- *			Devices other than COM ports are ignored.
- *			For COM ports, we configure the baud rate.
+/**
+ * Initialize the specified Super I/O device.
+ *
+ * Devices other than COM ports are ignored. For COM ports, we configure the
+ * baud rate.
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
  */
 static void lpc47n217_init(device_t dev)
 {
@@ -173,10 +167,6 @@ static void lpc47n217_init(device_t dev)
 	}
 }
 
-/**********************************************************************************/
-/*      			PRIVATE FUNCTIONS				  */
-/**********************************************************************************/
-
 static void lpc47n217_pnp_set_resource(device_t dev, struct resource *resource)
 {
 	if (!(resource->flags & IORESOURCE_ASSIGNED)) {
@@ -186,10 +176,10 @@ static void lpc47n217_pnp_set_resource(device_t dev, struct resource *resource)
 	}
 
 	/* Now store the resource */
-	/* NOTE: Cannot use pnp_set_XXX() here because they assume chip
-	 * support for logical devices, which the LPC47N217 doesn't have
+	/*
+	 * NOTE: Cannot use pnp_set_XXX() here because they assume chip
+	 * support for logical devices, which the LPC47N217 doesn't have.
 	 */
-
 	if (resource->flags & IORESOURCE_IO) {
 		lpc47n217_pnp_set_iobase(dev, resource->base);
 	}
@@ -327,36 +317,25 @@ static void lpc47n217_pnp_set_enable(device_t dev, int enable)
 	pnp_write_config(dev, power_register, new_power);
 }
 
-/*
- * Function:    	pnp_enter_conf_state
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Enable access to the LPC47N217's configuration registers.
- */
+/** Enable access to the LPC47N217's configuration registers. */
 static void pnp_enter_conf_state(device_t dev)
 {
 	outb(0x55, dev->path.pnp.port);
 }
 
-/*
- * Function:    	pnp_exit_conf_state
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Disable access to the LPC47N217's configuration registers.
- */
+/** Disable access to the LPC47N217's configuration registers. */
 static void pnp_exit_conf_state(device_t dev)
 {
 	outb(0xaa, dev->path.pnp.port);
 }
 
 #if 0
-/*
- * Function:    	dump_pnp_device
- * Parameters:  	dev - pointer to structure describing a Super I/O device
- * Return Value:	None
- * Description: 	Print the values of all of the LPC47N217's configuration registers.
- *			NOTE: The LPC47N217 must be in configuration mode when this
- *			function is called.
+/**
+ * Print the values of all of the LPC47N217's configuration registers.
+ *
+ * NOTE: The LPC47N217 must be in config mode when this function is called.
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
  */
 static void dump_pnp_device(device_t dev)
 {
diff --git a/src/superio/smsc/lpc47n227/lpc47n227.h b/src/superio/smsc/lpc47n227/lpc47n227.h
index 10b47736b1..769b5beadb 100644
--- a/src/superio/smsc/lpc47n227/lpc47n227.h
+++ b/src/superio/smsc/lpc47n227/lpc47n227.h
@@ -17,9 +17,10 @@
  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  */
 
-/* Since the LPC47N227 does not have logical devices but a flat configuration
+/*
+ * Since the LPC47N227 does not have logical devices but a flat configuration
  * space, these are arbitrary, but must match declarations in the mainboard
- * devicetree.cb
+ * devicetree.cb.
  */
 #define LPC47N227_PP               1	/* Parallel Port */
 #define LPC47N227_SP1              2	/* COM1 */
diff --git a/src/superio/smsc/lpc47n227/lpc47n227_early_serial.c b/src/superio/smsc/lpc47n227/lpc47n227_early_serial.c
index c6527d1ba6..318f0f3541 100644
--- a/src/superio/smsc/lpc47n227/lpc47n227_early_serial.c
+++ b/src/superio/smsc/lpc47n227/lpc47n227_early_serial.c
@@ -23,38 +23,34 @@
 #include <arch/romcc_io.h>
 #include "lpc47n227.h"
 
-//----------------------------------------------------------------------------------
-// Function:            pnp_enter_conf_state
-// Parameters:          dev - high 8 bits = Super I/O port
-// Return Value:        None
-// Description:         Enable access to the LPC47N227's configuration registers.
-//
+/**
+ * Enable access to the LPC47N227's configuration registers.
+ *
+ * @param dev High 8 bits = Super I/O port.
+ */
 static inline void pnp_enter_conf_state(device_t dev)
 {
 	unsigned port = dev >> 8;
 	outb(0x55, port);
 }
 
-//----------------------------------------------------------------------------------
-// Function:            pnp_exit_conf_state
-// Parameters:          dev - high 8 bits = Super I/O port
-// Return Value:        None
-// Description:         Disable access to the LPC47N227's configuration registers.
-//
+/**
+ * Disable access to the LPC47N227's configuration registers.
+ *
+ * @param dev High 8 bits = Super I/O port.
+ */
 static void pnp_exit_conf_state(device_t dev)
 {
 	unsigned port = dev >> 8;
 	outb(0xaa, port);
 }
 
-//----------------------------------------------------------------------------------
-// Function:            lpc47n227_pnp_set_iobase
-// Parameters:          dev - high 8 bits = Super I/O port,
-//                            low 8 bits = logical device number (per lpc47n227.h)
-//                      iobase - base I/O port for the logical device
-// Return Value:        None
-// Description:         Program the base I/O port for the specified logical device.
-//
+/**
+ * Program the base I/O port for the specified logical device.
+ *
+ * @param dev High 8 bits = Super I/O port, low 8 bits = logical device number.
+ * @param iobase Base I/O port for the logical device.
+ */
 void lpc47n227_pnp_set_iobase(device_t dev, unsigned iobase)
 {
 	// LPC47N227 requires base ports to be a multiple of 4
@@ -78,20 +74,18 @@ void lpc47n227_pnp_set_iobase(device_t dev, unsigned iobase)
 	}
 }
 
-//----------------------------------------------------------------------------------
-// Function:            lpc47n227_pnp_set_enable
-// Parameters:          dev - high 8 bits = Super I/O port,
-//                      low 8 bits = logical device number (per lpc47n227.h)
-//                      enable - 0 to disable, anythig else to enable
-// Return Value:        None
-// Description:         Enable or disable the specified logical device.
-//                      Technically, a full disable requires setting the device's base
-//                      I/O port below 0x100. We don't do that here, because we don't
-//                      have access to a data structure that specifies what the 'real'
-//                      base port is (when asked to enable the device). Also the function
-//                      is used only to disable the device while its true base port is
-//                      programmed (see lpc47n227_enable_serial() below).
-//
+/**
+ * Enable or disable the specified logical device.
+ *
+ * Technically, a full disable requires setting the device's base I/O port
+ * below 0x100. We don't do that here, because we don't have access to a data
+ * structure that specifies what the 'real' base port is (when asked to enable
+ * the device). Also the function is used only to disable the device while its
+ * true base port is programmed (see lpc47n227_enable_serial() below).
+ *
+ * @param dev High 8 bits = Super I/O port, low 8 bits = logical device number.
+ * @param enable 0 to disable, anythig else to enable.
+ */
 void lpc47n227_pnp_set_enable(device_t dev, int enable)
 {
 	uint8_t power_register = 0;
@@ -128,20 +122,19 @@ void lpc47n227_pnp_set_enable(device_t dev, int enable)
 	pnp_write_config(dev, power_register, new_power);
 }
 
-//----------------------------------------------------------------------------------
-// Function:            lpc47n227_enable_serial
-// Parameters:          dev - high 8 bits = Super I/O port,
-//                            low 8 bits = logical device number (per lpc47n227.h)
-//                      iobase - processor I/O port address to assign to this serial device
-// Return Value:        bool
-// Description:         Configure the base I/O port of the specified serial device
-//                      and enable the serial device.
-//
+/**
+ * Configure the base I/O port of the specified serial device and enable the
+ * serial device.
+ *
+ * @param dev High 8 bits = Super I/O port, low 8 bits = logical device number.
+ * @param iobase Processor I/O port address to assign to this serial device.
+ */
 static void lpc47n227_enable_serial(device_t dev, unsigned iobase)
 {
-	// NOTE: Cannot use pnp_set_XXX() here because they assume chip
-	// support for logical devices, which the LPC47N227 doesn't have
-
+	/*
+	 * NOTE: Cannot use pnp_set_XXX() here because they assume chip
+	 * support for logical devices, which the LPC47N227 doesn't have.
+	 */
 	pnp_enter_conf_state(dev);
 	lpc47n227_pnp_set_enable(dev, 0);
 	lpc47n227_pnp_set_iobase(dev, iobase);
diff --git a/src/superio/smsc/lpc47n227/superio.c b/src/superio/smsc/lpc47n227/superio.c
index f921ed85f3..5a994f7ca3 100644
--- a/src/superio/smsc/lpc47n227/superio.c
+++ b/src/superio/smsc/lpc47n227/superio.c
@@ -70,38 +70,34 @@ static struct pnp_info pnp_dev_info[] = {
 	 {0x7f8, 0x4},}
 };
 
-/**********************************************************************************/
-/*                             PUBLIC INTERFACE	                                  */
-/**********************************************************************************/
-
-//----------------------------------------------------------------------------------
-// Function:            enable_dev
-// Parameters:          dev - pointer to structure describing a Super I/O device
-// Return Value:        None
-// Description:         Create device structures and allocate resources to devices
-//                      specified in the pnp_dev_info array (above).
-//
+/**
+ * Create device structures and allocate resources to devices specified in the
+ * pnp_dev_info array (above).
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
+ */
 static void enable_dev(device_t dev)
 {
 	pnp_enable_devices(dev, &pnp_ops,
 			   ARRAY_SIZE(pnp_dev_info), pnp_dev_info);
 }
 
-//----------------------------------------------------------------------------------
-// Function:            lpc47n227_pnp_set_resources
-// Parameters:          dev - pointer to structure describing a Super I/O device
-// Return Value:        None
-// Description:         Configure the specified Super I/O device with the resources
-//                      (I/O space, etc.) that have been allocate for it.
-//
+/**
+ * Configure the specified Super I/O device with the resources (I/O space,
+ * etc.) that have been allocate for it.
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
+ */
 void lpc47n227_pnp_set_resources(device_t dev)
 {
 	struct resource *res;
 
 	pnp_enter_conf_state(dev);
 
-	// NOTE: Cannot use pnp_set_resources() here because it assumes chip
-	// support for logical devices, which the LPC47N227 doesn't have
+	/*
+	 * NOTE: Cannot use pnp_set_resources() here because it assumes chip
+	 * support for logical devices, which the LPC47N227 doesn't have.
+	 */
 	for (res = dev->resource_list; res; res = res->next)
 		lpc47n227_pnp_set_resource(dev, res);
 
@@ -112,8 +108,10 @@ void lpc47n227_pnp_enable_resources(device_t dev)
 {
 	pnp_enter_conf_state(dev);
 
-	// NOTE: Cannot use pnp_enable_resources() here because it assumes chip
-	// support for logical devices, which the LPC47N227 doesn't have
+	/*
+	 * NOTE: Cannot use pnp_enable_resources() here because it assumes chip
+	 * support for logical devices, which the LPC47N227 doesn't have.
+	 */
 	lpc47n227_pnp_set_enable(dev, 1);
 
 	pnp_exit_conf_state(dev);
@@ -123,9 +121,10 @@ void lpc47n227_pnp_enable(device_t dev)
 {
 	pnp_enter_conf_state(dev);
 
-	// NOTE: Cannot use pnp_set_enable() here because it assumes chip
-	// support for logical devices, which the LPC47N227 doesn't have
-
+	/*
+	 * NOTE: Cannot use pnp_set_enable() here because it assumes chip
+	 * support for logical devices, which the LPC47N227 doesn't have.
+	 */
 	if (dev->enabled) {
 		lpc47n227_pnp_set_enable(dev, 1);
 	} else {
@@ -135,14 +134,14 @@ void lpc47n227_pnp_enable(device_t dev)
 	pnp_exit_conf_state(dev);
 }
 
-//----------------------------------------------------------------------------------
-// Function:            lpc47n227_init
-// Parameters:          dev - pointer to structure describing a Super I/O device
-// Return Value:        None
-// Description:         Initialize the specified Super I/O device.
-//                      Devices other than COM ports and keyboard controller are ignored.
-//                      For COM ports, we configure the baud rate.
-//
+/**
+ * Initialize the specified Super I/O device.
+ *
+ * Devices other than COM ports and keyboard controller are ignored.
+ * For COM ports, we configure the baud rate.
+ *
+ * @param dev Pointer to structure describing a Super I/O device.
+ */
 static void lpc47n227_init(device_t dev)
 {
 	struct superio_smsc_lpc47n227_config *conf = dev->chip_info;
@@ -169,10 +168,6 @@ static void lpc47n227_init(device_t dev)
 	}
 }
 
-/**********************************************************************************/
-/*                              PRIVATE FUNCTIONS                                 */
-/**********************************************************************************/
-
 static void lpc47n227_pnp_set_resource(device_t dev, struct resource *resource)
 {
 	if (!(resource->flags & IORESOURCE_ASSIGNED)) {
@@ -182,9 +177,10 @@ static void lpc47n227_pnp_set_resource(device_t dev, struct resource *resource)
 	}
 
 	/* Now store the resource */
-	// NOTE: Cannot use pnp_set_XXX() here because they assume chip
-	// support for logical devices, which the LPC47N227 doesn't have
-
+	/*
+	 * NOTE: Cannot use pnp_set_XXX() here because they assume chip
+	 * support for logical devices, which the LPC47N227 doesn't have.
+	 */
 	if (resource->flags & IORESOURCE_IO) {
 		lpc47n227_pnp_set_iobase(dev, resource->base);
 	} else if (resource->flags & IORESOURCE_DRQ) {
@@ -328,25 +324,14 @@ void lpc47n227_pnp_set_enable(device_t dev, int enable)
 	pnp_write_config(dev, power_register, new_power);
 }
 
-//----------------------------------------------------------------------------------
-// Function:            pnp_enter_conf_state
-// Parameters:          dev - pointer to structure describing a Super I/O device
-// Return Value:        None
-// Description:         Enable access to the LPC47N227's configuration registers.
-//
+/** Enable access to the LPC47N227's configuration registers. */
 static void pnp_enter_conf_state(device_t dev)
 {
 	outb(0x55, dev->path.pnp.port);
 }
 
-//----------------------------------------------------------------------------------
-// Function:            pnp_exit_conf_state
-// Parameters:          dev - pointer to structure describing a Super I/O device
-// Return Value:        None
-// Description:         Disable access to the LPC47N227's configuration registers.
-//
+/** Disable access to the LPC47N227's configuration registers. */
 static void pnp_exit_conf_state(device_t dev)
 {
 	outb(0xaa, dev->path.pnp.port);
 }
-