Implementation of a PCI Hardware device. More...

#include <PCIDevice.hh>

Inheritance diagram for HAL::PCIDevice:

Classes
struct	PCILocationIdentifier_s
Public Types
typedef struct HAL::PCIDevice::PCILocationIdentifier_s	PCILocationIdentifier
Public Member Functions
	PCIDevice (PCIAddressTable &addressTable, PCIBusAdapterInterface &pciBusAdapter, uint32_t vendorID, uint32_t deviceID, uint32_t index, bool swapFlag=false)
	The Constructor of a PCI device if the vendorID and deviceID are given.
	PCIDevice (PCIAddressTable &addressTable, PCIBusAdapterInterface &pciBusAdapter, uint32_t vendorID, uint32_t deviceID, uint32_t index, std::vector< uint32_t > &baseAddresses, uint32_t command)
	VxWorks which is supported by this library is not plug and play.
	PCIDevice (PCIAddressTable &addressTable, PCIBusAdapterInterface &pciBusAdapter, const PCILocationIdentifier &location, bool swapFlag)
	The Constructor of a PCI device if the BusID, slotID and functionID of the device are given.
virtual	~PCIDevice ()
void	hardwareWrite (const GeneralHardwareAddress &pciAddress, uint32_t data, uint32_t offset=0) const throw (IllegalValueException, BusAdapterException)
	Implementation of the abstract function in HardwareDevice.
void	hardwareRead (const GeneralHardwareAddress &pciAddress, uint32_t *result, uint32_t offset=0) const throw (IllegalValueException, BusAdapterException)
	Implementation of the abstract function in HardwareDevice.
void	memoryWrite (uint32_t address, uint32_t barId, uint32_t data) const throw (IllegalValueException, BusAdapterException)
	A function to perform a PCI memory-write.
void	memoryRead (uint32_t address, uint32_t barId, uint32_t *result) const throw (IllegalValueException, BusAdapterException)
	A function to perform a PCI memory-read.
void	configWrite (uint32_t address, uint32_t data) const throw (BusAdapterException)
	A function to perform a PCI config-write.
void	configRead (uint32_t address, uint32_t *result) const throw (BusAdapterException)
	A function to perform a PCI config-read.
void	hardwareReadBlock (const GeneralHardwareAddress &pciAddress, uint32_t length, char *buffer, HalAddressIncrement addressBehaviour=HAL_DO_INCREMENT, uint32_t offset=0) const throw (IllegalValueException, UnsupportedException, IllegalOperationException, BusAdapterException)
	Implementation of the abstract function in HardwareDevice.
void	hardwareWriteBlock (const GeneralHardwareAddress &pciAddress, uint32_t length, char *buffer, HalAddressIncrement addressBehaviour=HAL_DO_INCREMENT, uint32_t offset=0) const throw (IllegalValueException, UnsupportedException, IllegalOperationException, BusAdapterException)
	Implementation of the abstract function in HardwareDevice.
uint32_t	getItemAddress (std::string) const throw ( NoSuchItemException, IllegalOperationException )
	undocumented feature...do not use: might dissapear in future, makes your application BusAdapter - dependent.
uint32_t	getPCIBusAddress (uint32_t iBar) throw (BusAdapterException)
	Retrieves the PCI Bus-Address for a BAR to the user This function is useful if the user has to set up DMA engines which transfer data to or from this device.
Private Attributes
PCIAddressTable &	pciAddressTable
PCIBusAdapterInterface &	pciBusAdapter
PCIDeviceIdentifier *	deviceIdentifierPtr
std::vector< uint32_t >	baseRegisters

Detailed Description

Implementation of a PCI Hardware device.

This class is the first technology dependent class in the class hierachy. (But it does not depend on the specific hardware to use the technology: It is PCI specific but does not depend on the implementation of the PCI-interface.)

The PCIDevice implements the interface to access the hardware defined in the HardwareDevice class for the PCI technology.

See also:: HardwareDeviceInterface, HardwareDevice

Author:: Christoph Schwick

Revision:: 1.1

Date:: 2007/03/05 18:02:10

Definition at line 38 of file PCIDevice.hh.

Member Typedef Documentation

typedef struct HAL::PCIDevice::PCILocationIdentifier_s HAL::PCIDevice::PCILocationIdentifier

Constructor & Destructor Documentation

HAL::PCIDevice::PCIDevice	(	HAL::PCIAddressTable &	addressTable,
		HAL::PCIBusAdapterInterface &	pciBusAdapter,
		uint32_t	vendorID,
		uint32_t	deviceID,
		uint32_t	index,
		bool	swapFlag = `false`
	)

The Constructor of a PCI device if the vendorID and deviceID are given.

The constructor needs all parameters which unambiguously define the device and the methods how to access it in the specific hardware implementation. The user must make sure that the addressTable exists as long as the PCIDevice (only a reference is passed to the PCIDevice so that a single table can be shared among several PCIDevices.) The same is valid for the busAdapter.

Parameters:

addressTable	defines all accessable items of the device.
pciBusAdapter	actually transfers data between the device and the software. It depends on the specific hardware implementation of the PCI interface and on the operating system.
vendorID	is the corresponding value in the configuration space of the device.
deviceID	is the corresponding value in the configuration space of the device.
index	identifies the device unambigiously in the system (there could be more than one module of the same kind plugged into the same PCI bus).
swapFlag	can be set in order to use big-endian devices with the HAL library. (Usually PCI peripherals are little endian, but there are exotic cards like the Myrinet NICs with the LANAI9 processor which are big endian.

Definition at line 5 of file PCIDevice.cc.

HAL::PCIDevice::PCIDevice	(	HAL::PCIAddressTable &	addressTable,
		HAL::PCIBusAdapterInterface &	pciBusAdapter,
		uint32_t	vendorID,
		uint32_t	deviceID,
		uint32_t	index,
		std::vector< uint32_t > &	baseAddresses,
		uint32_t	command
	)

VxWorks which is supported by this library is not plug and play.

This means that the BaseAddresses are not determined automatically by the operating system, but the user has to give them to the system by hand. For this case there exists the following constructor.

Parameters:

baseAddresses	is assumed to contain the desired BARs for the module. When the device is opened (in a VxWorks specific BusAdapter) the busAdapter performs configuration space write cycles in order to set the baseAddresses and the command register in configurationspace of the device.
command	contains the 10 bits of the equally named bitfield in the PCI space to define the access modes of the module.

Definition at line 19 of file PCIDevice.cc.

HAL::PCIDevice::PCIDevice	(	HAL::PCIAddressTable &	addressTable,
		HAL::PCIBusAdapterInterface &	pciBusAdapter,
		const PCILocationIdentifier &	location,
		bool	swapFlag
	)

The Constructor of a PCI device if the BusID, slotID and functionID of the device are given.

The constructor needs all parameters which unambiguously define the device and the methods how to access it in the specific hardware implementation. The user must make sure that the addressTable exists as long as the PCIDevice (only a reference is passed to the PCIDevice so that a single table can be shared among several PCIDevices.) The same is valid for the busAdapter.

Parameters:

addressTable	defines all accessable items of the device.
pciBusAdapter	actually transfers data between the device and the software. It depends on the specific hardware implementation of the PCI interface and on the operating system.
location	identifies the position in which the hardware module is plugged and the function of the module which should be addressed with this PCIDevie.
swapFlag	can be set in order to use big-endian devices with the HAL library. (Usually PCI peripherals are little endian, but there are exotic cards like the Myrinet NICs with the LANAI9 processor which are big endian.

Definition at line 38 of file PCIDevice.cc.

HAL::PCIDevice::~PCIDevice ( ) [virtual]

Definition at line 50 of file PCIDevice.cc.

Member Function Documentation

void HAL::PCIDevice::configRead	(	uint32_t	address,
		uint32_t *	result
	)		const throw (BusAdapterException)

A function to perform a PCI config-read.

This method is provided so that time critical applications which cannot afford the overhead in the HardwareDeviceInterface functions can call this method directly. It is strongly recommended to use this function only if ABSOLUTELY necessary (in fact using this function bypasses almost all services and "sanity" checks of the HAL.)

This function was introduced to accelerate the JAL of Hannes Sakulin.

Parameters:

address is the the plain address with respect to the BAR.

Definition at line 267 of file PCIDevice.cc.

void HAL::PCIDevice::configWrite	(	uint32_t	address,
		uint32_t	data
	)		const throw (BusAdapterException)

A function to perform a PCI config-write.

This method is provided so that time critical applications which cannot afford the overhead in the HardwareDeviceInterface functions can call this method directly. It is strongly recommended to use this function only if ABSOLUTELY necessary (in fact using this function bypasses almost all services and "sanity" checks of the HAL.)

This function was introduced to accelerate the JAL of Hannes Sakulin.

Parameters:

address is the the plain address with respect to the BAR.

Definition at line 260 of file PCIDevice.cc.

uint32_t HAL::PCIDevice::getItemAddress ( std::string item ) const throw ( NoSuchItemException, IllegalOperationException )

undocumented feature...do not use: might dissapear in future, makes your application BusAdapter - dependent.

Definition at line 54 of file PCIDevice.cc.

uint32_t HAL::PCIDevice::getPCIBusAddress ( uint32_t iBar ) throw (BusAdapterException)

Retrieves the PCI Bus-Address for a BAR to the user This function is useful if the user has to set up DMA engines which transfer data to or from this device.

Definition at line 253 of file PCIDevice.cc.

void HAL::PCIDevice::hardwareRead	(	const GeneralHardwareAddress &	pciAddress,
		uint32_t *	result,
		uint32_t	offset = `0`
	)		const throw (IllegalValueException, BusAdapterException) `[virtual]`

Implementation of the abstract function in HardwareDevice.

Accesses to the configuration space are excecuted directly here. Accesses to the memory space are delegated to the memoryRead function. (The reason for this is explained in the memoryWrite documentation.)

Implements HAL::HardwareDevice.

Definition at line 82 of file PCIDevice.cc.

void HAL::PCIDevice::hardwareReadBlock	(	const GeneralHardwareAddress &	pciAddress,
		uint32_t	length,
		char *	buffer,
		HalAddressIncrement	addressBehaviour = `HAL_DO_INCREMENT`,
		uint32_t	offset = `0`
	)		const throw (IllegalValueException, UnsupportedException, IllegalOperationException, BusAdapterException) `[virtual]`

Implementation of the abstract function in HardwareDevice.

Here you will only find PCI specific (BUT IMPORTANT) issues of this function. Refer to the HardwareDeviceInterface for general documentation.

IMPORTANT NOTE: If you read out a Fifo, you have to be sure that possible retry cylces on the PCI bus do not corrupt the data of your Fifo (that means it is not always clear that a PCI interface can be programmed not to repeat a local access to a Fifo in this case. This means that one data word of the Fifo (the one corresponding to the aborted cycle) is lost. This is a known problem in PCI technology but there are of course implementations which handle these cases correctly. This remark has only been added here in order to put you in an alert state if you deal with Fifos on PCI busses.

Parameters:

addressBehaviour determines if the address in the hardware device is incremented during the data transfer or not. (The latter you need if you read out a Fifo.) BusAdapters for hardware which contain DMA machines have to program the DMA engines accordingly.

Exceptions:

IllegalOperationException is thrown if the function is called on an item other than a memory space item.

Implements HAL::HardwareDevice.

Definition at line 152 of file PCIDevice.cc.

void HAL::PCIDevice::hardwareWrite	(	const GeneralHardwareAddress &	pciAddress,
		uint32_t	data,
		uint32_t	offset = `0`
	)		const throw (IllegalValueException, BusAdapterException) `[virtual]`

Implementation of the abstract function in HardwareDevice.

Accesses to the configuration space are excecuted directly here. Accesses to the memory space are delegated to the memoryWrite function. (The reason for this is explained in the memoryWrite documentation.)

Implements HAL::HardwareDevice.

Definition at line 68 of file PCIDevice.cc.

void HAL::PCIDevice::hardwareWriteBlock	(	const GeneralHardwareAddress &	pciAddress,
		uint32_t	length,
		char *	buffer,
		HalAddressIncrement	addressBehaviour = `HAL_DO_INCREMENT`,
		uint32_t	offset = `0`
	)		const throw (IllegalValueException, UnsupportedException, IllegalOperationException, BusAdapterException) `[virtual]`

Implementation of the abstract function in HardwareDevice.

Here you will only find PCI specific (BUT IMPORTANT) issues of this function. Refer to the HardwareDeviceInterface for general documentation.

IMPORTANT NOTE: If you read out a Fifo, you have to be sure that possible retry cylces on the PCI bus do not corrupt the data of your Fifo (that means it is not always clear that a PCI interface can be programmed not to repeat a local access to a Fifo in this case. This means that one data word of the Fifo (the one corresponding to the aborted cycle) is lost. This is a known problem in PCI technology but there are of course implementations which handle these cases correctly. This remark has only been added here in order to put you in an alert state if you deal with Fifos on PCI busses.

Parameters:

addressBehaviour determines if the address in the hardware device is incremented during the data transfer or not. (The latter you need if you read out a Fifo.) BusAdapters for hardware which contain DMA machines have to program the DMA engines accordingly.

Exceptions:

IllegalOperationException is thrown if the function is called on an item other than a memory space item.

Implements HAL::HardwareDevice.

Definition at line 97 of file PCIDevice.cc.

void HAL::PCIDevice::memoryRead	(	uint32_t	address,
		uint32_t	barId,
		uint32_t *	result
	)		const throw (IllegalValueException, BusAdapterException)

A function to perform a PCI memory-read.

This function is used by the hardwareREAD function. It has been made public so that time critical applications which cannot afford the overhead in the HardwareDeviceInterface functions can call this method directly. The only overhead of this function is to check the barID for validity (i.e. that it is in the range from 0...5). It is strongly recommended to use this function only if ABSOLUTELY necessary (in fact using this function bypasses almost all services and "sanity" checks of the HAL.)

Parameters:

address	is the the plain address with respect to the BAR.
barId	chooses one out of the six PCI BARS (0...5)

Definition at line 230 of file PCIDevice.cc.

void HAL::PCIDevice::memoryWrite	(	uint32_t	address,
		uint32_t	barId,
		uint32_t	data
	)		const throw (IllegalValueException, BusAdapterException)

A function to perform a PCI memory-write.

This function is used by the hardwareWrite function. It has been made public so that time critical applications which cannot afford the overhead in the HardwareDeviceInterface functions can call this method directly. The only overhead of this function is to check the barID for validity (i.e. that it is in the range from 0...5). It is strongly recommended to use this function only if ABSOLUTELY necessary (in fact using this function bypasses almost all services and "sanity" checks of the HAL.)

Parameters:

address	is the the plain address with respect to the BAR.
barId	chooses one out of the six PCI BARS (0...5)

Definition at line 207 of file PCIDevice.cc.

Member Data Documentation

std::vector<uint32_t> HAL::PCIDevice::baseRegisters [private]

Definition at line 331 of file PCIDevice.hh.

PCIDeviceIdentifier* HAL::PCIDevice::deviceIdentifierPtr [private]

Definition at line 330 of file PCIDevice.hh.

PCIAddressTable& HAL::PCIDevice::pciAddressTable [private]

Definition at line 328 of file PCIDevice.hh.

PCIBusAdapterInterface& HAL::PCIDevice::pciBusAdapter [private]

Definition at line 329 of file PCIDevice.hh.

The documentation for this class was generated from the following files:

/home/cschwick/hal/generic/include/hal/PCIDevice.hh
/home/cschwick/hal/generic/src/common/PCIDevice.cc

Classes

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation