mirror of
https://github.com/xcat2/xNBA.git
synced 2024-12-24 12:11:33 +00:00
Doxygenation
This commit is contained in:
Michael Brown
parent
d0c9183903
commit
f88c0d42d5
@ -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 ) {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user