From f88c0d42d586eed1ce3fbe3432d33b80e995d2ed Mon Sep 17 00:00:00 2001 From: Michael Brown Date: Thu, 19 May 2005 15:35:47 +0000 Subject: [PATCH] Doxygenation --- src/drivers/bus/isapnp.c | 254 ++++++++++++++++++++++++++++++--------- 1 file changed, 196 insertions(+), 58 deletions(-) diff --git a/src/drivers/bus/isapnp.c b/src/drivers/bus/isapnp.c index 6b7c79e4..4888c611 100644 --- a/src/drivers/bus/isapnp.c +++ b/src/drivers/bus/isapnp.c @@ -33,16 +33,18 @@ * ***************************************************************************/ -#include "string.h" -#include "timer.h" -#include "io.h" -#include "console.h" -#include "isapnp.h" - -/* - * We can have only one ISAPnP bus in a system. Once the read port is - * known and all cards have been allocated CSNs, there's nothing to be - * gained by re-scanning for cards. +/** @file + * + * ISAPnP bus support + * + * Etherboot orignally gained ISAPnP support in a very limited way for + * the 3c515 NIC. The current implementation is almost a complete + * rewrite based on the ISAPnP specification, with passing reference + * to the Linux ISAPnP code. + * + * There can be only one ISAPnP bus in a system. Once the read port + * is known and all cards have been allocated CSNs, there's nothing to + * be gained by re-scanning for cards. * * However, we shouldn't make scanning the ISAPnP bus an INIT_FN(), * because even ISAPnP probing can still screw up other devices on the @@ -50,18 +52,30 @@ * an ISAPnP device. * * External code (e.g. the ISAPnP ROM prefix) may already know the - * read port address, in which case it can initialise this value. - * Note that setting the read port address will prevent further - * isolation from taking place; you should set the read port address - * only if you know that devices have already been allocated CSNs. + * read port address, in which case it can store it in @c + * isapnp_read_port. Note that setting the read port address in this + * way will prevent further isolation from taking place; you should + * set the read port address only if you know that devices have + * already been allocated CSNs. + * + */ + +#include "string.h" +#include "timer.h" +#include "io.h" +#include "console.h" +#include "isapnp.h" + +/** + * ISAPnP Read Port address. * */ uint16_t isapnp_read_port; -/* +/** * Highest assigned CSN. * - * Note that *we* do not necessarily assign CSNs; it could be done by + * Note that @b we do not necessarily assign CSNs; it could be done by * the PnP BIOS instead. We therefore set this only when we first try * to Wake[CSN] a device and find that there's nothing there. Page 16 * (PDF page 22) of the ISAPnP spec states that "Valid Card Select @@ -116,22 +130,56 @@ static inline uint16_t isapnp_read_word ( uint8_t address ) { + isapnp_read_byte ( address + 1 ) ); } +/** Inform cards of a new read port address */ static inline void isapnp_set_read_port ( void ) { isapnp_write_byte ( ISAPNP_READPORT, isapnp_read_port >> 2 ); } +/** + * Enter the Isolation state. + * + * Only cards currently in the Sleep state will respond to this + * command. + * + */ static inline void isapnp_serialisolation ( void ) { isapnp_write_address ( ISAPNP_SERIALISOLATION ); } +/** + * Enter the Wait for Key state. + * + * All cards will respond to this command, regardless of their current + * state. + * + */ static inline void isapnp_wait_for_key ( void ) { isapnp_write_byte ( ISAPNP_CONFIGCONTROL, ISAPNP_CONFIG_WAIT_FOR_KEY ); } +/** + * Reset (i.e. remove) Card Select Number. + * + * Only cards currently in the Sleep state will respond to this + * command. + * + */ static inline void isapnp_reset_csn ( void ) { isapnp_write_byte ( ISAPNP_CONFIGCONTROL, ISAPNP_CONFIG_RESET_CSN ); } +/** + * Place a specified card into the Config state. + * + * @v csn Card Select Number + * @ret None + * @err None + * + * Only cards currently in the Sleep, Isolation, or Config states will + * respond to this command. The card that has the specified CSN will + * enter the Config state, all other cards will enter the Sleep state. + * + */ static inline void isapnp_wake ( uint8_t csn ) { isapnp_write_byte ( ISAPNP_WAKE, csn ); } @@ -144,6 +192,19 @@ static inline uint8_t isapnp_read_status ( void ) { return isapnp_read_byte ( ISAPNP_STATUS ); } +/** + * Assign a Card Select Number to a card, and enter the Config state. + * + * @v csn Card Select Number + * @ret None + * @err None + * + * Only cards in the Isolation state will respond to this command. + * The isolation protocol is designed so that only one card will + * remain in the Isolation state by the time the isolation protocol + * completes. + * + */ static inline void isapnp_write_csn ( uint8_t csn ) { isapnp_write_byte ( ISAPNP_CARDSELECTNUMBER, csn ); } @@ -174,12 +235,20 @@ static void isapnp_delay ( void ) { udelay ( 1000 ); } -/* - * The linear feedback shift register as described in Appendix B of - * the PnP ISA spec. The hardware implementation uses eight D-type - * latches and two XOR gates. I think this is probably the smallest - * possible implementation in software. Six instructions when input_bit - * is a constant 0 (for isapnp_send_key). :) +/** + * Linear feedback shift register. + * + * @v lfsr Current value of the LFSR + * @v input_bit Current input bit to the LFSR + * @ret lfsr Next value of the LFSR + * @err None + * + * This routine implements the linear feedback shift register as + * described in Appendix B of the PnP ISA spec. The hardware + * implementation uses eight D-type latches and two XOR gates. I + * think this is probably the smallest possible implementation in + * software. Six instructions when input_bit is a constant 0 (for + * isapnp_send_key). :) * */ static inline uint8_t isapnp_lfsr_next ( uint8_t lfsr, int input_bit ) { @@ -190,8 +259,11 @@ static inline uint8_t isapnp_lfsr_next ( uint8_t lfsr, int input_bit ) { return lfsr_next; } -/* - * Send the ISAPnP initiation key +/** + * Send the ISAPnP initiation key. + * + * Sending the key causes all ISAPnP cards that are currently in the + * Wait for Key state to transition into the Sleep state. * */ static void isapnp_send_key ( void ) { @@ -209,8 +281,12 @@ static void isapnp_send_key ( void ) { } } -/* - * Compute ISAPnP identifier checksum +/** + * Compute ISAPnP identifier checksum + * + * @v identifier ISAPnP identifier + * @ret checksum Expected checksum value + * @err None * */ static uint8_t isapnp_checksum ( struct isapnp_identifier *identifier ) { @@ -248,9 +324,16 @@ static inline uint8_t isapnp_peek_byte ( void ) { return 0xff; } -/* - * Read n bytes of resource data from the current location. If buf is - * NULL, discard data. +/** + * Read resource data. + * + * @v buf Buffer in which to store data, or NULL + * @v bytes Number of bytes to read + * @ret None + * @err None + * + * Resource data is read from the current location. If @c buf is NULL, + * the data is discarded. * */ static void isapnp_peek ( uint8_t *buf, size_t bytes ) { @@ -265,12 +348,19 @@ static void isapnp_peek ( uint8_t *buf, size_t bytes ) { } } -/* - * Scan through the resource data until we find a particular tag, and - * read its contents into a buffer. +/** + * Find a tag within the resource data. * - * It is the caller's responsibility to ensure that buf is large - * enough to contain a tag of the requested size. + * @v wanted_tag The tag that we're looking for + * @v buf Buffer in which to store the tag's contents + * @ret True Tag was found + * @ret False Tag was not found + * @err None + * + * Scan through the resource data until we find a particular tag, and + * read its contents into a buffer. It is the caller's responsibility + * to ensure that @c buf is large enough to contain a tag of the + * requested size. * */ static int isapnp_find_tag ( uint8_t wanted_tag, uint8_t *buf ) { @@ -300,10 +390,13 @@ static int isapnp_find_tag ( uint8_t wanted_tag, uint8_t *buf ) { return 0; } -/* - * Try isolating ISAPnP cards at the current read port. Return the - * number of ISAPnP cards found. <0 indicates "try a new read port", - * 0 indicates "definitely no cards". +/** + * Try isolating ISAPnP cards at the current read port. + * + * @ret \>0 Number of ISAPnP cards found + * @ret 0 There are no ISAPnP cards in the system + * @ret \<0 A conflict was detected; try a new read port + * @err None * * The state diagram on page 18 (PDF page 24) of the PnP ISA spec * gives the best overview of what happens here. @@ -429,8 +522,8 @@ static int isapnp_try_isolate ( void ) { return csn; } -/* - * Isolate all ISAPnP cards, locating a valid read port in the process. +/** + * Find a valid read port and isolate all ISAPnP cards. * */ static void isapnp_isolate ( void ) { @@ -450,10 +543,17 @@ static void isapnp_isolate ( void ) { } } -/* - * Increment a bus_loc structure to the next possible ISAPnP location. - * Leave the structure zeroed and return 0 if there are no more valid - * locations. +/** + * Increment a @c bus_loc structure to the next possible ISAPnP + * location. + * + * @v bus_loc Bus location + * @ret True @c bus_loc contains a valid ISAPnP location + * @ret False There are no more valid ISAPnP locations + * @err None + * + * If there are no more valid locations, the @c bus_loc structure will + * be zeroed. * */ static int isapnp_next_location ( struct bus_loc *bus_loc ) { @@ -471,10 +571,14 @@ static int isapnp_next_location ( struct bus_loc *bus_loc ) { return ( ++isapnp_loc->logdev ? 1 : ++isapnp_loc->csn ); } -/* - * Fill in parameters for an ISAPnP device based on CSN +/** + * Fill in parameters for an ISAPnP device based on CSN. * - * Return 1 if device present, 0 otherwise + * @v bus_dev Bus device to be filled in + * @v bus_loc Bus location as filled in by isapnp_next_location() + * @ret True A device is present at this location + * @ret False No device is present at this location + * @err None * */ static int isapnp_fill_device ( struct bus_dev *bus_dev, @@ -566,9 +670,15 @@ static int isapnp_fill_device ( struct bus_dev *bus_dev, return 1; } -/* +/** * Test whether or not a driver is capable of driving the device. * + * @v bus_dev Bus device as filled in by isapnp_fill_device() + * @v device_driver Device driver + * @ret True Driver is capable of driving this device + * @ret False Driver is not capable of driving this device + * @err None + * */ static int isapnp_check_driver ( struct bus_dev *bus_dev, struct device_driver *device_driver ) { @@ -598,8 +708,15 @@ static int isapnp_check_driver ( struct bus_dev *bus_dev, return 0; } -/* - * Describe an ISAPnP device +/** + * Describe an ISAPnP device. + * + * @v bus_dev Bus device as filled in by isapnp_fill_device() + * @ret string Printable string describing the device + * @err None + * + * The string returned by isapnp_describe_device() is valid only until + * the next call to isapnp_describe_device(). * */ static char * isapnp_describe_device ( struct bus_dev *bus_dev ) { @@ -611,8 +728,15 @@ static char * isapnp_describe_device ( struct bus_dev *bus_dev ) { return isapnp_description; } -/* - * Name an ISAPnP device +/** + * Name an ISAPnP device. + * + * @v bus_dev Bus device as filled in by isapnp_fill_device() + * @ret string Printable string naming the device + * @err None + * + * The string returned by isapnp_name_device() is valid only until the + * next call to isapnp_name_device(). * */ static const char * isapnp_name_device ( struct bus_dev *bus_dev ) { @@ -634,12 +758,17 @@ struct bus_driver isapnp_driver __bus_driver = { .name_device = isapnp_name_device, }; -/* - * Activate or deactivate an ISAPnP device +/** + * Activate or deactivate an ISAPnP device. + * + * @v isapnp ISAPnP device + * @v activation True to enable, False to disable the device + * @ret None + * @err None * * This routine simply activates the device in its current - * configuration. It does not attempt any kind of resource - * arbitration. + * configuration, or deactivates the device. It does not attempt any + * kind of resource arbitration. * */ void isapnp_device_activation ( struct isapnp_device *isapnp, @@ -662,8 +791,17 @@ void isapnp_device_activation ( struct isapnp_device *isapnp, isapnp->csn, isapnp->logdev ); } -/* - * Fill in a nic structure +/** + * Fill in a nic structure. + * + * @v nic NIC structure to be filled in + * @v isapnp ISAPnP device + * @ret None + * @err None + * + * This fills in generic NIC parameters (e.g. I/O address and IRQ + * number) that can be determined directly from the ISAPnP device, + * without any driver-specific knowledge. * */ void isapnp_fill_nic ( struct nic *nic, struct isapnp_device *isapnp ) {