narenas
/
opengnsys_ipxe
mirror of https://github.com/ipxe/ipxe.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Doxygenation

pull/1/head
Michael Brown 2005-05-19 15:35:47 +00:00
parent d0c9183903
commit f88c0d42d5
1 changed files with 196 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

254
src/drivers/bus/isapnp.c
View File

@ -33,16 +33,18 @@
* *
***************************************************************************/ ***************************************************************************/
#include "string.h" /** @file
#include "timer.h" *
#include "io.h" * ISAPnP bus support
#include "console.h" *
#include "isapnp.h" * 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
* We can have only one ISAPnP bus in a system. Once the read port is * to the Linux ISAPnP code.
* known and all cards have been allocated CSNs, there's nothing to be *
* gained by re-scanning for cards. * 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(), * However, we shouldn't make scanning the ISAPnP bus an INIT_FN(),
* because even ISAPnP probing can still screw up other devices on the * because even ISAPnP probing can still screw up other devices on the
@ -50,18 +52,30 @@
* an ISAPnP device. * an ISAPnP device.
* *
* External code (e.g. the ISAPnP ROM prefix) may already know the * External code (e.g. the ISAPnP ROM prefix) may already know the
* read port address, in which case it can initialise this value. * read port address, in which case it can store it in @c
* Note that setting the read port address will prevent further * isapnp_read_port. Note that setting the read port address in this
* isolation from taking place; you should set the read port address * way will prevent further isolation from taking place; you should
* only if you know that devices have already been allocated CSNs. * 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; uint16_t isapnp_read_port;
/* /**
* Highest assigned CSN. * 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 * 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 * 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 * (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 ) ); + isapnp_read_byte ( address + 1 ) );
} }
/** Inform cards of a new read port address */
static inline void isapnp_set_read_port ( void ) { static inline void isapnp_set_read_port ( void ) {
isapnp_write_byte ( ISAPNP_READPORT, isapnp_read_port >> 2 ); 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 ) { static inline void isapnp_serialisolation ( void ) {
isapnp_write_address ( ISAPNP_SERIALISOLATION ); 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 ) { static inline void isapnp_wait_for_key ( void ) {
isapnp_write_byte ( ISAPNP_CONFIGCONTROL, ISAPNP_CONFIG_WAIT_FOR_KEY ); 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 ) { static inline void isapnp_reset_csn ( void ) {
isapnp_write_byte ( ISAPNP_CONFIGCONTROL, ISAPNP_CONFIG_RESET_CSN ); 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 ) { static inline void isapnp_wake ( uint8_t csn ) {
isapnp_write_byte ( ISAPNP_WAKE, 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 ); 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 ) { static inline void isapnp_write_csn ( uint8_t csn ) {
isapnp_write_byte ( ISAPNP_CARDSELECTNUMBER, csn ); isapnp_write_byte ( ISAPNP_CARDSELECTNUMBER, csn );
} }
@ -174,12 +235,20 @@ static void isapnp_delay ( void ) {
udelay ( 1000 ); udelay ( 1000 );
} }
/* /**
* The linear feedback shift register as described in Appendix B of * Linear feedback shift register.
* the PnP ISA spec. The hardware implementation uses eight D-type *
* latches and two XOR gates. I think this is probably the smallest * @v lfsr Current value of the LFSR
* possible implementation in software. Six instructions when input_bit * @v input_bit Current input bit to the LFSR
* is a constant 0 (for isapnp_send_key). :) * @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 ) { 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; 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 ) { 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 ) { static uint8_t isapnp_checksum ( struct isapnp_identifier *identifier ) {
@ -248,9 +324,16 @@ static inline uint8_t isapnp_peek_byte ( void ) {
return 0xff; return 0xff;
} }
/* /**
* Read n bytes of resource data from the current location. If buf is * Read resource data.
* NULL, discard 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 ) { 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 * Find a tag within the resource data.
* read its contents into a buffer.
* *
* It is the caller's responsibility to ensure that buf is large * @v wanted_tag The tag that we're looking for
* enough to contain a tag of the requested size. * @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 ) { 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; return 0;
} }
/* /**
* Try isolating ISAPnP cards at the current read port. Return the * Try isolating ISAPnP cards at the current read port.
* number of ISAPnP cards found. <0 indicates "try a new read port", *
* 0 indicates "definitely no cards". * @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 * The state diagram on page 18 (PDF page 24) of the PnP ISA spec
* gives the best overview of what happens here. * gives the best overview of what happens here.
@ -429,8 +522,8 @@ static int isapnp_try_isolate ( void ) {
return csn; 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 ) { 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. * Increment a @c bus_loc structure to the next possible ISAPnP
* Leave the structure zeroed and return 0 if there are no more valid * location.
* locations. *
* @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 ) { 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 ); 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, 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; return 1;
} }
/* /**
* Test whether or not a driver is capable of driving the device. * 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, static int isapnp_check_driver ( struct bus_dev *bus_dev,
struct device_driver *device_driver ) { struct device_driver *device_driver ) {
@ -598,8 +708,15 @@ static int isapnp_check_driver ( struct bus_dev *bus_dev,
return 0; 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 ) { 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; 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 ) { 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, .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 * This routine simply activates the device in its current
* configuration. It does not attempt any kind of resource * configuration, or deactivates the device. It does not attempt any
* arbitration. * kind of resource arbitration.
* *
*/ */
void isapnp_device_activation ( struct isapnp_device *isapnp, void isapnp_device_activation ( struct isapnp_device *isapnp,
@ -662,8 +791,17 @@ void isapnp_device_activation ( struct isapnp_device *isapnp,
isapnp->csn, isapnp->logdev ); 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 ) { void isapnp_fill_nic ( struct nic *nic, struct isapnp_device *isapnp ) {