2
0
mirror of https://github.com/xcat2/xNBA.git synced 2024-12-23 19:51:46 +00:00

Doxygenation

This commit is contained in:
Michael Brown 2005-05-19 15:35:47 +00:00
parent d0c9183903
commit f88c0d42d5

View File

@ -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 ) {