From b69cb5a31058c0295f2d810c852cc5b52d77225c Mon Sep 17 00:00:00 2001 From: Uwe Hermann Date: Tue, 26 Oct 2010 22:46:43 +0000 Subject: [PATCH] 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 Acked-by: Uwe Hermann git-svn-id: svn://svn.coreboot.org/coreboot/trunk@5993 2b7e53f0-3cfb-0310-b3e9-8179ed1497e1 --- src/northbridge/amd/amdht/AsPsNb.c | 47 +- src/northbridge/intel/e7501/raminit.c | 470 ++++++++---------- src/northbridge/intel/e7520/raminit.c | 8 +- src/northbridge/intel/i3100/raminit_ep80579.c | 1 - src/northbridge/intel/i855/raminit.c | 96 ++-- src/southbridge/intel/i82801cx/i82801cx.h | 8 +- src/southbridge/intel/i82801cx/i82801cx_lpc.c | 17 +- src/southbridge/intel/i82870/p64h2_ioapic.c | 18 +- src/southbridge/sis/sis966/sis761.c | 30 +- src/southbridge/sis/sis966/sis966_lpc.c | 5 +- src/southbridge/sis/sis966/sis966_nic.c | 19 +- .../smsc/lpc47b272/lpc47b272_early_serial.c | 28 +- src/superio/smsc/lpc47b272/superio.c | 74 +-- .../smsc/lpc47m10x/lpc47m10x_early_serial.c | 28 +- src/superio/smsc/lpc47m10x/superio.c | 74 +-- .../smsc/lpc47n217/lpc47n217_early_serial.c | 70 +-- src/superio/smsc/lpc47n217/superio.c | 91 ++-- src/superio/smsc/lpc47n227/lpc47n227.h | 5 +- .../smsc/lpc47n227/lpc47n227_early_serial.c | 85 ++-- src/superio/smsc/lpc47n227/superio.c | 91 ++-- 20 files changed, 535 insertions(+), 730 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 #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 */ -/**********************************************************************************/ +/*----------------------------------------------------------------------------- +SDRAM configuration 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. -// +/** + * 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 */ -/**********************************************************************************/ +/*----------------------------------------------------------------------------- +DIMM-independant 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. -// +/** + * 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 */ -/**********************************************************************************/ +/* 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 (?) -// +/** + * 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 */ -/**********************************************************************************/ +/*----------------------------------------------------------------------------- +Public interface: +-----------------------------------------------------------------------------*/ -//---------------------------------------------------------------------------------- -// 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. -// +/** + * 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 @@ -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 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 #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 #include -/** - * @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 #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 #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 #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 #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); } -