summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorUwe Hermann <uwe@hermann-uwe.de>2010-10-26 22:46:43 +0000
committerUwe Hermann <uwe@hermann-uwe.de>2010-10-26 22:46:43 +0000
commitb69cb5a31058c0295f2d810c852cc5b52d77225c (patch)
tree9f462e829279fbc1a892a70898ac2ee9da4c79e1
parentb907d321a5d0957f5cbb03d8f9c8d0ff0c23523b (diff)
downloadcoreboot-b69cb5a31058c0295f2d810c852cc5b52d77225c.tar.xz
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
-rw-r--r--src/northbridge/amd/amdht/AsPsNb.c47
-rw-r--r--src/northbridge/intel/e7501/raminit.c478
-rw-r--r--src/northbridge/intel/e7520/raminit.c8
-rw-r--r--src/northbridge/intel/i3100/raminit_ep80579.c1
-rw-r--r--src/northbridge/intel/i855/raminit.c96
-rw-r--r--src/southbridge/intel/i82801cx/i82801cx.h8
-rw-r--r--src/southbridge/intel/i82801cx/i82801cx_lpc.c17
-rw-r--r--src/southbridge/intel/i82870/p64h2_ioapic.c18
-rw-r--r--src/southbridge/sis/sis966/sis761.c30
-rw-r--r--src/southbridge/sis/sis966/sis966_lpc.c5
-rw-r--r--src/southbridge/sis/sis966/sis966_nic.c19
-rw-r--r--src/superio/smsc/lpc47b272/lpc47b272_early_serial.c28
-rw-r--r--src/superio/smsc/lpc47b272/superio.c74
-rw-r--r--src/superio/smsc/lpc47m10x/lpc47m10x_early_serial.c28
-rw-r--r--src/superio/smsc/lpc47m10x/superio.c74
-rw-r--r--src/superio/smsc/lpc47n217/lpc47n217_early_serial.c70
-rw-r--r--src/superio/smsc/lpc47n217/superio.c91
-rw-r--r--src/superio/smsc/lpc47n227/lpc47n227.h5
-rw-r--r--src/superio/smsc/lpc47n227/lpc47n227_early_serial.c85
-rw-r--r--src/superio/smsc/lpc47n227/superio.c91
20 files changed, 539 insertions, 734 deletions
diff --git a/src/northbridge/amd/amdht/AsPsNb.c b/src/northbridge/amd/amdht/AsPsNb.c
index 52f8645e8d..7d7e463e0f 100644
--- a/src/northbridge/amd/amdht/AsPsNb.c
+++ b/src/northbridge/amd/amdht/AsPsNb.c
@@ -17,39 +17,23 @@
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
-
-/*
- *----------------------------------------------------------------------------
- * MODULES USED
- *
- *----------------------------------------------------------------------------
- */
#undef FILECODE
#define FILECODE 0xCCCC
+
#include "comlib.h"
#include "AsPsDefs.h"
#include "AsPsNb.h"
-
-/*----------------------------------------------------------------------------
- * PROTOTYPES OF LOCAL FUNCTIONS
- *
- *----------------------------------------------------------------------------
- */
u8 getNumOfNodeNb(void);
u8 translateNodeIdToDeviceIdNb(u8 nodeId);
-
-/*----------------------------------------------------------------------------
- * FUNCTION: getMinNbCOF
- * INPUT: None
- * OUTPUT: minNbCOF (in multiple of half of CLKIN, 100MHz)
- * DESCRIPTION:
- * This function returns the minimum possible NbCOF (in 100MHz)
- * for the system .
- * This function can be run on any core and is used by the HT & Memory init code
- * in Phase 1.
- * ----------------------------------------------------------------------------
+/**
+ * Return the minimum possible NbCOF (in 100MHz) for the system.
+ *
+ * This function can be run on any core and is used by the HT & Memory init
+ * code in Phase 1.
+ *
+ * @return minNbCOF (in multiple of half of CLKIN, 100MHz).
*/
u8 getMinNbCOF(void)
{
@@ -130,14 +114,13 @@ u8 getNumOfNodeNb(void)
return (u8)dtemp;
}
-/*----------------------------------------------------------------------------
- * FUNCTION: translateNodeIdToDeviceId
- * INPUT: u8 nodeId - node ID of the node
- * OUTPUT: u8 - PCI device ID of the node
- * DESCRIPTION:
- * This function return the PCI device ID for PCI access using node ID.
- * This function may need to chnage node ID to device ID in big MP systems.
- * ----------------------------------------------------------------------------
+/**
+ * Return the PCI device ID for PCI access using node ID.
+ *
+ * This function may need to change node ID to device ID in big MP systems.
+ *
+ * @param nodeId Node ID of the node.
+ * @return PCI device ID of the node.
*/
u8 translateNodeIdToDeviceIdNb(u8 nodeId)
{
diff --git a/src/northbridge/intel/e7501/raminit.c b/src/northbridge/intel/e7501/raminit.c
index ac3bd41866..c049d9e5b3 100644
--- a/src/northbridge/intel/e7501/raminit.c
+++ b/src/northbridge/intel/e7501/raminit.c
@@ -17,6 +17,10 @@
#include <stdlib.h>
#include "e7501.h"
+/*-----------------------------------------------------------------------------
+Definitions:
+-----------------------------------------------------------------------------*/
+
// Uncomment this to enable run-time checking of DIMM parameters
// for dual-channel operation
// Unfortunately the code seems to chew up several K of space.
@@ -47,10 +51,6 @@ struct dimm_size {
unsigned long side2;
};
-/*^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/
-/* DEFINITIONS */
-/**********************************************************************************/
-
static const uint32_t refresh_frequency[] = {
/* Relative frequency (array value) of each E7501 Refresh Mode Select
* (RMS) value (array index)
@@ -451,9 +451,10 @@ static const uint32_t maybe_pull_updown_offset_table[] = {
0x88888888, 0x88888888, 0x88888888, 0x88888888,
};
-/*^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/
-/* TABLES */
-/**********************************************************************************/
+/*-----------------------------------------------------------------------------
+Delay functions:
+-----------------------------------------------------------------------------*/
+
#define SLOW_DOWN_IO inb(0x80)
//#define SLOW_DOWN_IO udelay(40);
@@ -477,27 +478,26 @@ static void do_delay(void)
#define EXTRA_DELAY DO_DELAY
-/*^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/
-/* DELAY FUNCTIONS */
-/**********************************************************************************/
-
static void die_on_spd_error(int spd_return_value)
{
if (spd_return_value < 0)
die("Error reading SPD info\n");
}
-//----------------------------------------------------------------------------------
-// Function: sdram_spd_get_page_size
-// Parameters: dimm_socket_address - SMBus address of DIMM socket to interrogate
-// Return Value: struct dimm_size - log2(page size) for each side of the DIMM.
-// Description: Calculate the page size for each physical bank of the DIMM:
-// log2(page size) = (# columns) + log2(data width)
-//
-// NOTE: page size is the total number of data bits in a row.
-//
-static struct dimm_size sdram_spd_get_page_size(uint16_t
- dimm_socket_address)
+/*-----------------------------------------------------------------------------
+Serial presence detect (SPD) functions:
+-----------------------------------------------------------------------------*/
+
+/**
+ * Calculate the page size for each physical bank of the DIMM:
+ * log2(page size) = (# columns) + log2(data width)
+ *
+ * NOTE: Page size is the total number of data bits in a row.
+ *
+ * @param dimm_socket_address SMBus address of DIMM socket to interrogate.
+ * @return log2(page size) for each side of the DIMM.
+ */
+static struct dimm_size sdram_spd_get_page_size(uint16_t dimm_socket_address)
{
uint16_t module_data_width;
int value;
@@ -554,13 +554,12 @@ static struct dimm_size sdram_spd_get_page_size(uint16_t
return pgsz; // Never reached
}
-//----------------------------------------------------------------------------------
-// Function: sdram_spd_get_width
-// Parameters: dimm_socket_address - SMBus address of DIMM socket to interrogate
-// Return Value: dimm_size - width in bits of each DIMM side's DRAMs.
-// Description: Read the width in bits of each DIMM side's DRAMs via SPD.
-// (i.e. 4, 8, 16)
-//
+/**
+ * Read the width in bits of each DIMM side's DRAMs via SPD (i.e. 4, 8, 16).
+ *
+ * @param dimm_socket_address SMBus address of DIMM socket to interrogate.
+ * @return Width in bits of each DIMM side's DRAMs.
+ */
static struct dimm_size sdram_spd_get_width(uint16_t dimm_socket_address)
{
int value;
@@ -601,18 +600,19 @@ static struct dimm_size sdram_spd_get_width(uint16_t dimm_socket_address)
return width;
}
-//----------------------------------------------------------------------------------
-// Function: spd_get_dimm_size
-// Parameters: dimm_socket_address - SMBus address of DIMM socket to interrogate
-// Return Value: dimm_size - log2(number of bits) for each side of the DIMM
-// Description: Calculate the log base 2 size in bits of both DIMM sides.
-// log2(# bits) = (# columns) + log2(data width) +
-// (# rows) + log2(banks per SDRAM)
-//
-// Note that it might be easier to use SPD byte 31 here, it has the
-// DIMM size as a multiple of 4MB. The way we do it now we can size
-// both sides of an asymmetric dimm.
-//
+/**
+ * Calculate the log base 2 size in bits of both DIMM sides.
+ *
+ * log2(# bits) = (# columns) + log2(data width) +
+ * (# rows) + log2(banks per SDRAM)
+ *
+ * Note that it might be easier to use SPD byte 31 here, it has the DIMM size
+ * as a multiple of 4MB. The way we do it now we can size both sides of an
+ * asymmetric DIMM.
+ *
+ * @param dimm_socket_address SMBus address of DIMM socket to interrogate.
+ * @return log2(number of bits) for each side of the DIMM.
+ */
static struct dimm_size spd_get_dimm_size(unsigned dimm_socket_address)
{
int value;
@@ -651,20 +651,21 @@ static struct dimm_size spd_get_dimm_size(unsigned dimm_socket_address)
}
#ifdef VALIDATE_DIMM_COMPATIBILITY
-//----------------------------------------------------------------------------------
-// Function: are_spd_values_equal
-// Parameters: spd_byte_number -
-// dimmN_address - SMBus addresses of DIMM sockets to interrogate
-// Return Value: 1 if both DIMM sockets report the same value for the specified
-// SPD parameter; 0 if the values differed or an error occurred.
-// Description: Determine whether two DIMMs have the same value for a SPD parameter.
-//
+
+/**
+ * Determine whether two DIMMs have the same value for an SPD parameter.
+ *
+ * @param spd_byte_number The SPD byte number to compare in both DIMMs.
+ * @param dimm0_address SMBus address of the 1st DIMM socket to interrogate.
+ * @param dimm1_address SMBus address of the 2nd DIMM socket to interrogate.
+ * @return 1 if both DIMM sockets report the same value for the specified
+ * SPD parameter, 0 if the values differed or an error occurred.
+ */
static uint8_t are_spd_values_equal(uint8_t spd_byte_number,
uint16_t dimm0_address,
uint16_t dimm1_address)
{
uint8_t bEqual = 0;
-
int dimm0_value = spd_read_byte(dimm0_address, spd_byte_number);
int dimm1_value = spd_read_byte(dimm1_address, spd_byte_number);
@@ -676,23 +677,24 @@ static uint8_t are_spd_values_equal(uint8_t spd_byte_number,
}
#endif
-//----------------------------------------------------------------------------------
-// Function: spd_get_supported_dimms
-// Parameters: ctrl - PCI addresses of memory controller functions, and
-// SMBus addresses of DIMM slots on the mainboard
-// Return Value: uint8_t - a bitmask indicating which of the possible sockets
-// for each channel was found to contain a compatible DIMM.
-// Bit 0 corresponds to the closest socket for channel 0,
-// Bit 1 to the next socket for channel 0,
-// ...
-// Bit MAX_DIMM_SOCKETS_PER_CHANNEL-1 to the last socket for channel 0,
-// Bit MAX_DIMM_SOCKETS_PER_CHANNEL is the closest socket for channel 1,
-// ...
-// Bit 2*MAX_DIMM_SOCKETS_PER_CHANNEL-1 is the last socket for channel 1
-// Description: Scan for compatible DIMMs.
-// The code in this module only supports dual-channel operation,
-// so we test that compatible DIMMs are paired.
-//
+/**
+ * Scan for compatible DIMMs.
+ *
+ * The code in this module only supports dual-channel operation, so we test
+ * that compatible DIMMs are paired.
+ *
+ * @param ctrl PCI addresses of memory controller functions, and SMBus
+ * addresses of DIMM slots on the mainboard.
+ * @return A bitmask indicating which of the possible sockets for each channel
+ * was found to contain a compatible DIMM.
+ * Bit 0 corresponds to the closest socket for channel 0
+ * Bit 1 to the next socket for channel 0
+ * ...
+ * Bit MAX_DIMM_SOCKETS_PER_CHANNEL-1 to the last socket for channel 0
+ * Bit MAX_DIMM_SOCKETS_PER_CHANNEL is the closest socket for channel 1
+ * ...
+ * Bit 2*MAX_DIMM_SOCKETS_PER_CHANNEL-1 is the last socket for channel 1
+ */
static uint8_t spd_get_supported_dimms(const struct mem_controller *ctrl)
{
int i;
@@ -828,25 +830,17 @@ static uint8_t spd_get_supported_dimms(const struct mem_controller *ctrl)
return dimm_mask;
}
-/*^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/
-/* SPD (SERIAL PRESENCE DETECT) FUNCTIONS */
-/**********************************************************************************/
-
-//----------------------------------------------------------------------------------
-// Function: do_ram_command
-// Parameters:
-// command - specifies the command to be sent to the DIMMs:
-// RAM_COMMAND_NOP - No Operation
-// RAM_COMMAND_PRECHARGE - Precharge all banks
-// RAM_COMMAND_MRS - Load Mode Register
-// RAM_COMMAND_EMRS - Load Extended Mode Register
-// RAM_COMMAND_CBR - Auto Refresh ("CAS-before-RAS")
-// RAM_COMMAND_NORMAL - Normal operation
-// jedec_mode_bits - for mode register set & extended mode register set
-// commands, bits 0-12 contain the register value in JEDEC format.
-// Return Value: None
-// Description: Send the specified command to all DIMMs.
-//
+/*-----------------------------------------------------------------------------
+SDRAM configuration functions:
+-----------------------------------------------------------------------------*/
+
+/**
+ * Send the specified command to all DIMMs.
+ *
+ * @param command Specifies the command to be sent to the DIMMs.
+ * @param jedec_mode_bits For the MRS & EMRS commands, bits 0-12 contain the
+ * register value in JEDEC format.
+ */
static void do_ram_command(uint8_t command, uint16_t jedec_mode_bits)
{
int i;
@@ -916,14 +910,15 @@ static void do_ram_command(uint8_t command, uint16_t jedec_mode_bits)
}
}
-//----------------------------------------------------------------------------------
-// Function: set_ram_mode
-// Parameters: jedec_mode_bits - for mode register set & extended mode register set
-// commands, bits 0-12 contain the register value in JEDEC format.
-// Return Value: None
-// Description: Set the mode register of all DIMMs. The proper CAS# latency
-// setting is added to the mode bits specified by the caller.
-//
+/**
+ * Set the mode register of all DIMMs.
+ *
+ * The proper CAS# latency setting is added to the mode bits specified
+ * by the caller.
+ *
+ * @param jedec_mode_bits For the MRS & EMRS commands, bits 0-12 contain the
+ * register value in JEDEC format.
+ */
static void set_ram_mode(uint16_t jedec_mode_bits)
{
ASSERT(!(jedec_mode_bits & SDRAM_CAS_MASK));
@@ -948,22 +943,22 @@ static void set_ram_mode(uint16_t jedec_mode_bits)
do_ram_command(RAM_COMMAND_MRS, jedec_mode_bits);
}
-/*^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/
-/* SDRAM CONFIGURATION FUNCTIONS */
-/**********************************************************************************/
-
-//----------------------------------------------------------------------------------
-// Function: configure_dimm_row_boundaries
-// Parameters:
-// dimm_log2_num_bits - log2(number of bits) for each side of the DIMM
-// total_dram_64M_multiple - total DRAM in the system (as a
-// multiple of 64 MB) for DIMMs < dimm_index
-// dimm_index - which DIMM pair is being processed
-// (0..MAX_DIMM_SOCKETS_PER_CHANNEL)
-// Return Value: New multiple of 64 MB total DRAM in the system
-// Description: Configure the E7501's DRAM Row Boundary registers for the memory
-// present in the specified DIMM.
-//
+/*-----------------------------------------------------------------------------
+DIMM-independant configuration functions:
+-----------------------------------------------------------------------------*/
+
+/**
+ * Configure the E7501's DRAM Row Boundary (DRB) registers for the memory
+ * present in the specified DIMM.
+ *
+ * @param dimm_log2_num_bits Specifies log2(number of bits) for each side of
+ * the DIMM.
+ * @param total_dram_64M_multiple Total DRAM in the system (as a multiple of
+ * 64 MB) for DIMMs < dimm_index.
+ * @param dimm_index Which DIMM pair is being processed
+ * (0..MAX_DIMM_SOCKETS_PER_CHANNEL).
+ * @return New multiple of 64 MB total DRAM in the system.
+ */
static uint8_t configure_dimm_row_boundaries(struct dimm_size dimm_log2_num_bits, uint8_t total_dram_64M_multiple, unsigned dimm_index)
{
int i;
@@ -1017,18 +1012,16 @@ static uint8_t configure_dimm_row_boundaries(struct dimm_size dimm_log2_num_bits
return total_dram_64M_multiple;
}
-//----------------------------------------------------------------------------------
-// Function: configure_e7501_ram_addresses
-// Parameters: ctrl - PCI addresses of memory controller functions, and
-// SMBus addresses of DIMM slots on the mainboard
-// dimm_mask - bitmask of populated DIMMs on the board - see
-// spd_get_supported_dimms()
-// Return Value: None
-// Description: Program the E7501's DRAM row boundary addresses and its Top Of
-// Low Memory (TOLM). If necessary, set up a remap window so we
-// don't waste DRAM that ordinarily would lie behind addresses
-// reserved for memory-mapped I/O.
-//
+/**
+ * Set the E7501's DRAM row boundary addresses & its Top Of Low Memory (TOLM).
+ *
+ * If necessary, set up a remap window so we don't waste DRAM that ordinarily
+ * would lie behind addresses reserved for memory-mapped I/O.
+ *
+ * @param ctrl PCI addresses of memory controller functions, and SMBus
+ * addresses of DIMM slots on the mainboard.
+ * @param dimm_mask Bitmask of populated DIMMs, see spd_get_supported_dimms().
+ */
static void configure_e7501_ram_addresses(const struct mem_controller
*ctrl, uint8_t dimm_mask)
{
@@ -1130,13 +1123,10 @@ static void configure_e7501_ram_addresses(const struct mem_controller
}
}
-//----------------------------------------------------------------------------------
-// Function: initialize_ecc
-// Parameters: None
-// Return Value: None
-// Description: If we're configured to use ECC, initialize the SDRAM and
-// clear the E7501's ECC error flags.
-//
+/**
+ * If we're configured to use ECC, initialize the SDRAM and clear the E7501's
+ * ECC error flags.
+ */
static void initialize_ecc(void)
{
uint32_t dram_controller_mode;
@@ -1177,17 +1167,15 @@ static void initialize_ecc(void)
}
-//----------------------------------------------------------------------------------
-// Function: configure_e7501_dram_timing
-// Parameters: ctrl - PCI addresses of memory controller functions, and
-// SMBus addresses of DIMM slots on the mainboard
-// dimm_mask - bitmask of populated DIMMs on the board - see
-// spd_get_supported_dimms()
-// Return Value: None
-// Description: Program the DRAM Timing register of the E7501 (except for CAS#
-// latency, which is assumed to have been programmed already), based
-// on the parameters of the various installed DIMMs.
-//
+/**
+ * Program the DRAM Timing register (DRT) of the E7501 (except for CAS#
+ * latency, which is assumed to have been programmed already), based on the
+ * parameters of the various installed DIMMs.
+ *
+ * @param ctrl PCI addresses of memory controller functions, and SMBus
+ * addresses of DIMM slots on the mainboard.
+ * @param dimm_mask Bitmask of populated DIMMs, see spd_get_supported_dimms().
+ */
static void configure_e7501_dram_timing(const struct mem_controller *ctrl,
uint8_t dimm_mask)
{
@@ -1314,16 +1302,14 @@ static void configure_e7501_dram_timing(const struct mem_controller *ctrl,
die(SPD_ERROR);
}
-//----------------------------------------------------------------------------------
-// Function: configure_e7501_cas_latency
-// Parameters: ctrl - PCI addresses of memory controller functions, and
-// SMBus addresses of DIMM slots on the mainboard
-// dimm_mask - bitmask of populated DIMMs on the board - see
-// spd_get_supported_dimms()
-// Return Value: None
-// Description: Determine the shortest CAS# latency that the E7501 and all DIMMs
-// have in common, and program the E7501 to use it.
-//
+/**
+ * Determine the shortest CAS# latency that the E7501 and all DIMMs have in
+ * common, and program the E7501 to use it.
+ *
+ * @param ctrl PCI addresses of memory controller functions, and SMBus
+ * addresses of DIMM slots on the mainboard.
+ * @param dimm_mask Bitmask of populated DIMMs, spd_get_supported_dimms().
+ */
static void configure_e7501_cas_latency(const struct mem_controller *ctrl,
uint8_t dimm_mask)
{
@@ -1471,17 +1457,15 @@ static void configure_e7501_cas_latency(const struct mem_controller *ctrl,
die(SPD_ERROR);
}
-//----------------------------------------------------------------------------------
-// Function: configure_e7501_dram_controller_mode
-// Parameters: ctrl - PCI addresses of memory controller functions, and
-// SMBus addresses of DIMM slots on the mainboard
-// dimm_mask - bitmask of populated DIMMs on the board - see
-// spd_get_supported_dimms()
-// Return Value: None
-// Description: Configure the refresh interval so that we refresh no more often
-// than required by the "most needy" DIMM. Also disable ECC if any
-// of the DIMMs don't support it.
-//
+/**
+ * Configure the refresh interval so that we refresh no more often than
+ * required by the "most needy" DIMM. Also disable ECC if any of the DIMMs
+ * don't support it.
+ *
+ * @param ctrl PCI addresses of memory controller functions, and SMBus
+ * addresses of DIMM slots on the mainboard.
+ * @param dimm_mask Bitmask of populated DIMMs, spd_get_supported_dimms().
+ */
static void configure_e7501_dram_controller_mode(const struct
mem_controller *ctrl,
uint8_t dimm_mask)
@@ -1579,18 +1563,16 @@ static void configure_e7501_dram_controller_mode(const struct
pci_write_config32(PCI_DEV(0, 0, 0), DRC, controller_mode);
}
-//----------------------------------------------------------------------------------
-// Function: configure_e7501_row_attributes
-// Parameters: ctrl - PCI addresses of memory controller functions, and
-// SMBus addresses of DIMM slots on the mainboard
-// dimm_mask - bitmask of populated DIMMs on the board - see
-// spd_get_supported_dimms()
-// Return Value: None
-// Description: Configure the E7501's DRAM Row Attributes (DRA) registers
-// based on DIMM parameters read via SPD. This tells the controller
-// the width of the SDRAM chips on each DIMM side (x4 or x8) and
-// the page size of each DIMM side (4, 8, 16, or 32 KB).
-//
+/**
+ * Configure the E7501's DRAM Row Attributes (DRA) registers based on DIMM
+ * parameters read via SPD. This tells the controller the width of the SDRAM
+ * chips on each DIMM side (x4 or x8) and the page size of each DIMM side
+ * (4, 8, 16, or 32 KB).
+ *
+ * @param ctrl PCI addresses of memory controller functions, and SMBus
+ * addresses of DIMM slots on the mainboard.
+ * @param dimm_mask Bitmask of populated DIMMs, spd_get_supported_dimms().
+ */
static void configure_e7501_row_attributes(const struct mem_controller
*ctrl, uint8_t dimm_mask)
{
@@ -1634,14 +1616,12 @@ static void configure_e7501_row_attributes(const struct mem_controller
pci_write_config32(PCI_DEV(0, 0, 0), DRA, row_attributes);
}
-//----------------------------------------------------------------------------------
-// Function: enable_e7501_clocks
-// Parameters: dimm_mask - bitmask of populated DIMMs on the board - see
-// spd_get_supported_dimms()
-// Return Value: None
-// Description: Enable clock signals for populated DIMM sockets and disable them
-// for unpopulated sockets (to reduce EMI).
-//
+/*
+ * Enable clock signals for populated DIMM sockets and disable them for
+ * unpopulated sockets (to reduce EMI).
+ *
+ * @param dimm_mask Bitmask of populated DIMMs, see spd_get_supported_dimms().
+ */
static void enable_e7501_clocks(uint8_t dimm_mask)
{
int i;
@@ -1660,17 +1640,11 @@ static void enable_e7501_clocks(uint8_t dimm_mask)
pci_write_config8(PCI_DEV(0, 0, 0), CKDIS, clock_disable);
}
-/*^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/
-/* DIMM-DEDEPENDENT CONFIGURATION FUNCTIONS */
-/**********************************************************************************/
-
-//----------------------------------------------------------------------------------
-// Function: RAM_RESET_DDR_PTR
-// Parameters: ctrl - PCI addresses of memory controller functions, and
-// SMBus addresses of DIMM slots on the mainboard
-// Return Value: None
-// Description: DDR Receive FIFO RE-Sync (?)
-//
+/* DIMM-dedependent configuration functions */
+
+/**
+ * DDR Receive FIFO RE-Sync (?)
+ */
static void RAM_RESET_DDR_PTR(void)
{
uint8_t byte;
@@ -1683,17 +1657,15 @@ static void RAM_RESET_DDR_PTR(void)
pci_write_config8(PCI_DEV(0, 0, 0), 0x88, byte);
}
-//----------------------------------------------------------------------------------
-// Function: ram_set_d0f0_regs
-// Parameters: None
-// Return Value: None
-// Description: Set E7501 registers that are either independent of DIMM specifics,
-// or establish default settings that will be overridden when we
-// learn the specifics.
-// This sets PCI configuration registers to known good values based
-// on the table 'constant_register_values', which are a triple of
-// configuration register offset, mask, and bits to set.
-//
+/**
+ * Set E7501 registers that are either independent of DIMM specifics, or
+ * establish default settings that will be overridden when we learn the
+ * specifics.
+ *
+ * This sets PCI configuration registers to known good values based on the
+ * table 'constant_register_values', which are a triple of configuration
+ * register offset, mask, and bits to set.
+ */
static void ram_set_d0f0_regs(void)
{
int i;
@@ -1726,14 +1698,13 @@ static void ram_set_d0f0_regs(void)
}
}
-//----------------------------------------------------------------------------------
-// Function: write_8dwords
-// Parameters: src_addr
-// dst_addr
-// Return Value: None
-// Description: Copy 64 bytes from one location to another.
-//
-static void write_8dwords(const uint32_t * src_addr, uint32_t dst_addr)
+/**
+ * Copy 64 bytes from one location to another.
+ *
+ * @param src_addr TODO
+ * @param dst_addr TODO
+ */
+static void write_8dwords(const uint32_t *src_addr, uint32_t dst_addr)
{
int i;
for (i = 0; i < 8; i++) {
@@ -1743,17 +1714,16 @@ static void write_8dwords(const uint32_t * src_addr, uint32_t dst_addr)
}
}
-//----------------------------------------------------------------------------------
-// Function: ram_set_rcomp_regs
-// Parameters: None
-// Return Value: None
-// Description: Set the E7501's (undocumented) RCOMP registers.
-// Per the 855PM datasheet and IXP2800 HW Initialization Reference
-// Manual, RCOMP registers appear to affect drive strength,
-// pullup/pulldown offset, and slew rate of various signal groups.
-// Comments below are conjecture based on apparent similarity
-// between the E7501 and these two chips.
-//
+/**
+ * Set the E7501's (undocumented) RCOMP registers.
+ *
+ * Per the 855PM datasheet and IXP2800 HW Initialization Reference Manual,
+ * RCOMP registers appear to affect drive strength, pullup/pulldown offset,
+ * and slew rate of various signal groups.
+ *
+ * Comments below are conjecture based on apparent similarity between the
+ * E7501 and these two chips.
+ */
static void ram_set_rcomp_regs(void)
{
uint32_t dword;
@@ -1857,20 +1827,19 @@ static void ram_set_rcomp_regs(void)
}
-/*^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/
-/* DIMM-INDEPENDENT CONFIGURATION FUNCTIONS */
-/**********************************************************************************/
-
-//----------------------------------------------------------------------------------
-// Function: sdram_enable
-// Parameters: controllers - not used
-// ctrl - PCI addresses of memory controller functions, and
-// SMBus addresses of DIMM slots on the mainboard
-// Return Value: None
-// Description: Go through the JEDEC initialization sequence for all DIMMs,
-// then enable refresh and initialize ECC and memory to zero.
-// Upon exit, SDRAM is up and running.
-//
+/*-----------------------------------------------------------------------------
+Public interface:
+-----------------------------------------------------------------------------*/
+
+/**
+ * Go through the JEDEC initialization sequence for all DIMMs, then enable
+ * refresh and initialize ECC and memory to zero. Upon exit, SDRAM is up
+ * and running.
+ *
+ * @param controllers Not used.
+ * @param ctrl PCI addresses of memory controller functions, and SMBus
+ * addresses of DIMM slots on the mainboard.
+ */
static void sdram_enable(int controllers,
const struct mem_controller *ctrl)
{
@@ -1975,16 +1944,14 @@ static void sdram_enable(int controllers,
DUMPNORTH();
}
-//----------------------------------------------------------------------------------
-// Function: sdram_set_spd_registers
-// Parameters: ctrl - PCI addresses of memory controller functions, and
-// SMBus addresses of DIMM slots on the mainboard
-// Return Value: None
-// Description: Configure SDRAM controller parameters that depend on
-// characteristics of the DIMMs installed in the system. These
-// characteristics are read from the DIMMs via the standard Serial
-// Presence Detect (SPD) interface.
-//
+/**
+ * Configure SDRAM controller parameters that depend on characteristics of the
+ * DIMMs installed in the system. These characteristics are read from the
+ * DIMMs via the standard Serial Presence Detect (SPD) interface.
+ *
+ * @param ctrl PCI addresses of memory controller functions, and SMBus
+ * addresses of DIMM slots on the mainboard.
+ */
static void sdram_set_spd_registers(const struct mem_controller *ctrl)
{
uint8_t dimm_mask;
@@ -2023,14 +1990,13 @@ static void sdram_set_spd_registers(const struct mem_controller *ctrl)
pci_write_config16(PCI_DEV(0, 0, 0), SKPD, dimm_mask);
}
-//----------------------------------------------------------------------------------
-// Function: sdram_set_registers
-// Parameters: ctrl - PCI addresses of memory controller functions, and
-// SMBus addresses of DIMM slots on the mainboard
-// Return Value: None
-// Description: Do basic ram setup that does NOT depend on serial presence detect
-// information (i.e. independent of DIMM specifics).
-//
+/**
+ * Do basic RAM setup that does NOT depend on serial presence detect
+ * information (i.e. independent of DIMM specifics).
+ *
+ * @param ctrl PCI addresses of memory controller functions, and SMBus
+ * addresses of DIMM slots on the mainboard.
+ */
static void sdram_set_registers(const struct mem_controller *ctrl)
{
RAM_DEBUG_MESSAGE("Northbridge prior to SDRAM init:\n");
@@ -2039,7 +2005,3 @@ static void sdram_set_registers(const struct mem_controller *ctrl)
ram_set_rcomp_regs();
ram_set_d0f0_regs();
}
-
-/*^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/
-/* PUBLIC INTERFACE */
-/**********************************************************************************/
diff --git a/src/northbridge/intel/e7520/raminit.c b/src/northbridge/intel/e7520/raminit.c
index e9827c43b9..235ce44f2b 100644
--- a/src/northbridge/intel/e7520/raminit.c
+++ b/src/northbridge/intel/e7520/raminit.c
@@ -15,7 +15,6 @@
* 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., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
- *
*/
#include <cpu/x86/mtrr.h>
@@ -81,8 +80,6 @@ static void sdram_set_registers(const struct mem_controller *ctrl)
print_spew("done.\n");
}
-
-
struct dimm_size {
unsigned long side1;
unsigned long side2;
@@ -209,7 +206,6 @@ static long spd_set_ram_size(const struct mem_controller *ctrl, long dimm_mask)
return 0;
}
-
static unsigned int spd_detect_dimms(const struct mem_controller *ctrl)
{
unsigned dimm_mask;
@@ -236,7 +232,6 @@ static unsigned int spd_detect_dimms(const struct mem_controller *ctrl)
return dimm_mask;
}
-
static int spd_set_row_attributes(const struct mem_controller *ctrl,
long dimm_mask)
{
@@ -296,7 +291,6 @@ hw_err:
}
-
static int spd_set_drt_attributes(const struct mem_controller *ctrl,
long dimm_mask, uint32_t drc)
{
@@ -798,6 +792,7 @@ static void set_on_dimm_termination_enable(const struct mem_controller *ctrl)
}
}
}
+
static void set_receive_enable(const struct mem_controller *ctrl)
{
unsigned int i;
@@ -1030,7 +1025,6 @@ static void set_receive_enable(const struct mem_controller *ctrl)
write32(BAR+0x154, recenb);
}
-
static void sdram_enable(int controllers, const struct mem_controller *ctrl)
{
int i;
diff --git a/src/northbridge/intel/i3100/raminit_ep80579.c b/src/northbridge/intel/i3100/raminit_ep80579.c
index 7aeef29c84..8967594b53 100644
--- a/src/northbridge/intel/i3100/raminit_ep80579.c
+++ b/src/northbridge/intel/i3100/raminit_ep80579.c
@@ -16,7 +16,6 @@
* 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., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
- *
*/
#include <cpu/x86/mtrr.h>
diff --git a/src/northbridge/intel/i855/raminit.c b/src/northbridge/intel/i855/raminit.c
index 539d161640..1120853fe5 100644
--- a/src/northbridge/intel/i855/raminit.c
+++ b/src/northbridge/intel/i855/raminit.c
@@ -25,6 +25,10 @@
#include <delay.h>
#include "i855.h"
+/*-----------------------------------------------------------------------------
+Macros and definitions:
+-----------------------------------------------------------------------------*/
+
#define VALIDATE_DIMM_COMPATIBILITY
/* Debugging macros. */
@@ -65,10 +69,6 @@ struct dimm_size {
unsigned int side2;
};
-/*^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/
-/* DEFINITIONS */
-/**********************************************************************************/
-
static const uint32_t refresh_frequency[] = {
/* Relative frequency (array value) of each E7501 Refresh Mode Select
* (RMS) value (array index)
@@ -104,7 +104,7 @@ static const uint32_t refresh_rate_map[] = {
#define MAX_SPD_REFRESH_RATE ((sizeof(refresh_rate_map) / sizeof(uint32_t)) - 1)
/*-----------------------------------------------------------------------------
-SPD functions.
+SPD functions:
-----------------------------------------------------------------------------*/
static void die_on_spd_error(int spd_return_value)
@@ -117,15 +117,16 @@ static void die_on_spd_error(int spd_return_value)
*/
}
-//----------------------------------------------------------------------------------
-// Function: sdram_spd_get_page_size
-// Parameters: dimm_socket_address - SMBus address of DIMM socket to interrogate
-// Return Value: struct dimm_size - log2(page size) for each side of the DIMM.
-// Description: Calculate the page size for each physical bank of the DIMM:
-// log2(page size) = (# columns) + log2(data width)
-//
-// NOTE: page size is the total number of data bits in a row.
-//
+/**
+ * Calculate the page size for each physical bank of the DIMM:
+ *
+ * log2(page size) = (# columns) + log2(data width)
+ *
+ * NOTE: Page size is the total number of data bits in a row.
+ *
+ * @param dimm_socket_address SMBus address of DIMM socket to interrogate.
+ * @return log2(page size) for each side of the DIMM.
+ */
static struct dimm_size sdram_spd_get_page_size(uint16_t dimm_socket_address)
{
uint16_t module_data_width;
@@ -180,13 +181,12 @@ static struct dimm_size sdram_spd_get_page_size(uint16_t dimm_socket_address)
return pgsz;
}
-//----------------------------------------------------------------------------------
-// Function: sdram_spd_get_width
-// Parameters: dimm_socket_address - SMBus address of DIMM socket to interrogate
-// Return Value: dimm_size - width in bits of each DIMM side's DRAMs.
-// Description: Read the width in bits of each DIMM side's DRAMs via SPD.
-// (i.e. 4, 8, 16)
-//
+/**
+ * Read the width in bits of each DIMM side's DRAMs via SPD (i.e. 4, 8, 16).
+ *
+ * @param dimm_socket_address SMBus address of DIMM socket to interrogate.
+ * @return Width in bits of each DIMM side's DRAMs.
+ */
static struct dimm_size sdram_spd_get_width(uint16_t dimm_socket_address)
{
int value;
@@ -225,18 +225,19 @@ static struct dimm_size sdram_spd_get_width(uint16_t dimm_socket_address)
return width;
}
-//----------------------------------------------------------------------------------
-// Function: spd_get_dimm_size
-// Parameters: dimm_socket_address - SMBus address of DIMM socket to interrogate
-// Return Value: dimm_size - log2(number of bits) for each side of the DIMM
-// Description: Calculate the log base 2 size in bits of both DIMM sides.
-// log2(# bits) = (# columns) + log2(data width) +
-// (# rows) + log2(banks per SDRAM)
-//
-// Note that it might be easier to use SPD byte 31 here, it has the
-// DIMM size as a multiple of 4MB. The way we do it now we can size
-// both sides of an asymmetric dimm.
-//
+/**
+ * Calculate the log base 2 size in bits of both DIMM sides.
+ *
+ * log2(# bits) = (# columns) + log2(data width) +
+ * (# rows) + log2(banks per SDRAM)
+ *
+ * Note that it might be easier to use SPD byte 31 here, it has the DIMM size
+ * as a multiple of 4MB. The way we do it now we can size both sides of an
+ * asymmetric DIMM.
+ *
+ * @param dimm SMBus address of DIMM socket to interrogate.
+ * @return log2(number of bits) for each side of the DIMM.
+ */
static struct dimm_size spd_get_dimm_size(unsigned dimm)
{
int value;
@@ -270,13 +271,13 @@ static struct dimm_size spd_get_dimm_size(unsigned dimm)
return sz;
}
-//----------------------------------------------------------------------------------
-// Function: spd_get_supported_dimms
-// Parameters: ctrl - PCI addresses of memory controller functions, and
-// SMBus addresses of DIMM slots on the mainboard
-// Return Value: uint8_t - a bitmask indicating which sockets contain a compatible DIMM.
-// Description: Scan for compatible DIMMs.
-//
+/**
+ * Scan for compatible DIMMs.
+ *
+ * @param ctrl PCI addresses of memory controller functions, and SMBus
+ * addresses of DIMM slots on the mainboard.
+ * @return A bitmask indicating which sockets contain a compatible DIMM.
+ */
static uint8_t spd_get_supported_dimms(const struct mem_controller *ctrl)
{
int i;
@@ -356,8 +357,9 @@ static uint8_t spd_get_supported_dimms(const struct mem_controller *ctrl)
}
/*-----------------------------------------------------------------------------
-DIMM-initialization functions.
+SDRAM configuration functions:
-----------------------------------------------------------------------------*/
+
static void do_ram_command(uint8_t command, uint16_t jedec_mode_bits)
{
int i;
@@ -487,14 +489,16 @@ static void sdram_enable(int controllers, const struct mem_controller *ctrl)
}
/*-----------------------------------------------------------------------------
-DIMM-independant configuration functions.
+DIMM-independant configuration functions:
-----------------------------------------------------------------------------*/
/**
- * Set only what I need until it works, then make it figure things out on boot
- * assumes only one dimm is populated
- */
-
+ * Set only what I need until it works, then make it figure things out on boot
+ * assumes only one DIMM is populated.
+ *
+ * @param ctrl PCI addresses of memory controller functions, and SMBus
+ * addresses of DIMM slots on the mainboard.
+ */
static void sdram_set_registers(const struct mem_controller *ctrl)
{
/*
diff --git a/src/southbridge/intel/i82801cx/i82801cx.h b/src/southbridge/intel/i82801cx/i82801cx.h
index e0d377a9cd..da518a3660 100644
--- a/src/southbridge/intel/i82801cx/i82801cx.h
+++ b/src/southbridge/intel/i82801cx/i82801cx.h
@@ -32,9 +32,7 @@ void i82801cx_hard_reset(void);
#define RTC_POWER_FAILED (1<<1)
#define SLEEP_AFTER_POWER_FAIL (1<<0)
-/********************************************************************/
-/* IDE Controller */
-/********************************************************************/
+/* IDE controller: */
// PCI Configuration Space (D31:F1)
#define IDE_TIM_PRI 0x40 // IDE timings, primary
@@ -44,9 +42,7 @@ void i82801cx_hard_reset(void);
// IDE_TIM bits
#define IDE_DECODE_ENABLE (1<<15)
-/********************************************************************/
-/* SMBus */
-/********************************************************************/
+/* SMBus: */
// PCI Configuration Space (D31:F3)
#define SMB_BASE 0x20
diff --git a/src/southbridge/intel/i82801cx/i82801cx_lpc.c b/src/southbridge/intel/i82801cx/i82801cx_lpc.c
index 2f2c4600a2..a1ffb8f540 100644
--- a/src/southbridge/intel/i82801cx/i82801cx_lpc.c
+++ b/src/southbridge/intel/i82801cx/i82801cx_lpc.c
@@ -61,15 +61,14 @@ static void i82801cx_enable_serial_irqs( struct device *dev)
pci_write_config8(dev, SERIRQ_CNTL, (1 << 7)|(1 << 6)|((21 - 17) << 2)|(0<< 0));
}
-//----------------------------------------------------------------------------------
-// Function: i82801cx_lpc_route_dma
-// Parameters: dev
-// mask - identifies whether each channel should be used for PCI DMA
-// (bit = 0) or LPC DMA (bit = 1). The LSb controls channel 0.
-// Channel 4 is not used (reserved).
-// Return Value: None
-// Description: Route all DMA channels to either PCI or LPC.
-//
+/**
+ * Route all DMA channels to either PCI or LPC.
+ *
+ * @param dev TODO
+ * @param mask Identifies whether each channel should be used for PCI DMA
+ * (bit = 0) or LPC DMA (bit = 1). The LSb controls channel 0.
+ * Channel 4 is not used (reserved).
+ */
static void i82801cx_lpc_route_dma( struct device *dev, uint8_t mask)
{
uint16_t dmaConfig;
diff --git a/src/southbridge/intel/i82870/p64h2_ioapic.c b/src/southbridge/intel/i82870/p64h2_ioapic.c
index 0f998dda9e..8af57beed7 100644
--- a/src/southbridge/intel/i82870/p64h2_ioapic.c
+++ b/src/southbridge/intel/i82870/p64h2_ioapic.c
@@ -18,15 +18,15 @@ static void p64h2_ioapic_enable(device_t dev)
pci_write_config16(dev, PCI_COMMAND, command);
}
-//----------------------------------------------------------------------------------
-// Function: p64h2_ioapic_init
-// Parameters: dev - PCI bus/device/function of P64H2 IOAPIC
-// NOTE: There are two IOAPICs per P64H2, at D28:F0 and D30:F0
-// Return Value: None
-// Description: Configure one of the IOAPICs in a P64H2.
-// Note that a PCI bus scan will detect both IOAPICs, so this function
-// will be called twice for each P64H2 in the system.
-//
+/**
+ * Configure one of the IOAPICs in a P64H2.
+ *
+ * Note that a PCI bus scan will detect both IOAPICs, so this function
+ * will be called twice for each P64H2 in the system.
+ *
+ * @param dev PCI bus/device/function of P64H2 IOAPIC.
+ * NOTE: There are two IOAPICs per P64H2, at D28:F0 and D30:F0.
+ */
static void p64h2_ioapic_init(device_t dev)
{
uint32_t memoryBase;
diff --git a/src/southbridge/sis/sis966/sis761.c b/src/southbridge/sis/sis966/sis761.c
index f1d1fe26d8..3d7bc470d3 100644
--- a/src/southbridge/sis/sis966/sis761.c
+++ b/src/southbridge/sis/sis966/sis761.c
@@ -41,22 +41,6 @@
#include <cpu/amd/model_fxx_rev.h>
#include <arch/io.h>
-/**
- * @brief Read resources for AGP aperture
- *
- * @param
- *
- * There is only one AGP aperture resource needed. The resoruce is added to
- * the northbridge of BSP.
- *
- * The same trick can be used to augment legacy VGA resources which can
- * be detect by generic pci reousrce allocator for VGA devices.
- * BAD: it is more tricky than I think, the resource allocation code is
- * implemented in a way to NOT DOING legacy VGA resource allcation on
- * purpose :-(.
- */
-
-
typedef struct msr_struct
{
unsigned lo;
@@ -71,6 +55,20 @@ static inline msr_t rdmsr(unsigned index)
return result;
}
+/**
+ * Read resources for AGP aperture.
+ *
+ * There is only one AGP aperture resource needed. The resoruce is added to
+ * the northbridge of BSP.
+ *
+ * The same trick can be used to augment legacy VGA resources which can
+ * be detect by generic PCI resource allocator for VGA devices.
+ * BAD: it is more tricky than I think, the resource allocation code is
+ * implemented in a way to NOT DOING legacy VGA resource allcation on
+ * purpose :-(.
+ *
+ * @param dev TODO
+ */
static void sis761_read_resources(device_t dev)
{
/* Read the generic PCI resources */
diff --git a/src/southbridge/sis/sis966/sis966_lpc.c b/src/southbridge/sis/sis966/sis966_lpc.c
index c6a1fce20d..26f60dd3af 100644
--- a/src/southbridge/sis/sis966/sis966_lpc.c
+++ b/src/southbridge/sis/sis966/sis966_lpc.c
@@ -184,10 +184,9 @@ static void sis966_lpc_read_resources(device_t dev)
}
/**
- * @brief Enable resources for children devices
- *
- * @param dev the device whos children's resources are to be enabled
+ * Enable resources for children devices.
*
+ * @param dev The device whos children's resources are to be enabled.
*/
static void sis966_lpc_enable_childrens_resources(device_t dev)
{
diff --git a/src/southbridge/sis/sis966/sis966_nic.c b/src/southbridge/sis/sis966/sis966_nic.c
index 7b1a856c8d..a7aeec37ed 100644
--- a/src/southbridge/sis/sis966/sis966_nic.c
+++ b/src/southbridge/sis/sis966/sis966_nic.c
@@ -124,17 +124,14 @@ static void set_apc(struct device *dev)
pci_write_config8(dev, 0x73, bTmp);
}
-//-----------------------------------------------------------------------------
-// Procedure: ReadEEprom
-//
-// Description: This routine serially reads one word out of the EEPROM.
-//
-// Arguments:
-// Reg - EEPROM word to read.
-//
-// Returns:
-// Contents of EEPROM word (Reg).
-//-----------------------------------------------------------------------------
+/**
+ * Read one word out of the serial EEPROM.
+ *
+ * @param dev TODO
+ * @param base TODO
+ * @param Reg EEPROM word to read.
+ * @return Contents of EEPROM word (Reg).
+ */
#define LoopNum 200
static unsigned long ReadEEprom( struct device *dev, u32 base, u32 Reg)
{
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);
}
-