Generic hardware access library
|
The implementation of the hardwareDeviceInterface. More...
#include <HardwareDevice.hh>
Public Member Functions | |
HardwareDevice (AddressTableInterface &AddressTable) | |
The constructor needs a reference to the AddressTable for the hardware Device. | |
virtual | ~HardwareDevice () |
void | unmaskedWrite (std::string item, uint32_t data, HalVerifyOption verifyFlag=HAL_NO_VERIFY, uint32_t offset=0) const throw (NoSuchItemException, IllegalOperationException, BusAdapterException, VerifyException, AddressOutOfLimitsException) |
Write a data word without applying the mask for the item. | |
void | write (std::string item, uint32_t data, HalVerifyOption verifyFlag=HAL_NO_VERIFY, uint32_t offset=0) const throw (NoSuchItemException, BusAdapterException, IllegalOperationException, VerifyException, MaskBoundaryException, AddressOutOfLimitsException) |
Write a new value for an item into the hardware device. | |
void | writePulse (std::string item, uint32_t offset=0) const throw (NoSuchItemException, BusAdapterException, IllegalOperationException, AddressOutOfLimitsException) |
Perform a write access in order to trigger side effects. | |
void | readPulse (std::string item, uint32_t offset=0) const throw (NoSuchItemException, BusAdapterException, IllegalOperationException, AddressOutOfLimitsException) |
Perform a read access in order to trigger side effects. | |
void | unmaskedRead (std::string item, uint32_t *result, uint32_t offset=0) const throw (NoSuchItemException, BusAdapterException, IllegalOperationException, AddressOutOfLimitsException) |
Read a data word without applying the items mask. | |
void | read (std::string item, uint32_t *result, uint32_t offset=0) const throw (NoSuchItemException, BusAdapterException, IllegalOperationException, MaskBoundaryException, AddressOutOfLimitsException ) |
Read an item from the hardware device. | |
bool | check (std::string item, uint32_t expected, std::string faultMessage="", uint32_t offset=0, std::ostream &os=std::cout) const throw ( NoSuchItemException, IllegalOperationException, BusAdapterException, AddressOutOfLimitsException) |
Read an item from the hardware and check the result. | |
void | setBit (std::string item, HalVerifyOption verifyFlag=HAL_NO_VERIFY, uint32_t offset=0) const throw (NoSuchItemException, IllegalOperationException, BusAdapterException, VerifyException, AddressOutOfLimitsException) |
Set a single bit. | |
void | resetBit (std::string item, HalVerifyOption verifyFlag=HAL_NO_VERIFY, uint32_t offset=0) const throw (NoSuchItemException, IllegalOperationException, BusAdapterException, VerifyException, AddressOutOfLimitsException) |
Reset a single bit. | |
bool | isSet (std::string item, uint32_t offset=0) const throw (NoSuchItemException, BusAdapterException, IllegalOperationException, AddressOutOfLimitsException) |
Test the value of a single bit. | |
void | writeBlock (std::string startItem, uint32_t length, char *buffer, HalVerifyOption verifyFlag=HAL_NO_VERIFY, HalAddressIncrement addressBehaviour=HAL_DO_INCREMENT, uint32_t offset=0) const throw ( NoSuchItemException, IllegalValueException, UnsupportedException, VerifyException, BusAdapterException, IllegalOperationException, AddressOutOfLimitsException ) |
A function to read a block of data into the host memory. | |
void | readBlock (std::string startItem, uint32_t length, char *buffer, HalAddressIncrement addressBehaviour=HAL_DO_INCREMENT, uint32_t offset=0) const throw ( NoSuchItemException, IllegalValueException, UnsupportedException, BusAdapterException, IllegalOperationException, AddressOutOfLimitsException ) |
A function to a block write of data into the hardware device. | |
void | pollItem (std::string item, uint32_t referenceValue, uint32_t timeout, uint32_t *result, HalPollMethod pollMethod=HAL_POLL_UNTIL_EQUAL, uint32_t offset=0) const throw ( NoSuchItemException, IllegalOperationException, BusAdapterException, MaskBoundaryException, TimeoutException, AddressOutOfLimitsException ) |
This function polls an item and does not return until the polling condition is matched. | |
const AddressTableInterface & | getAddressTableInterface () const |
Retrieve a handle to the AddressTableInterface. | |
void | printAddressTable () const |
Print out the AddressTable of the hardware device This prints out the AddressTable which is used by the HardwareDevice to resolve the addresses of the various items. | |
virtual void | hardwareRead (const GeneralHardwareAddress &address, uint32_t *result, uint32_t offset=0) const =0 throw (IllegalValueException, BusAdapterException) |
Abstraction of the hardware read access. | |
virtual void | hardwareWrite (const GeneralHardwareAddress &address, uint32_t data, uint32_t offset=0) const =0 throw (IllegalValueException, BusAdapterException) |
Abstraction of the hardware write access. | |
virtual void | hardwareReadBlock (const GeneralHardwareAddress &address, uint32_t length, char *buffer, HalAddressIncrement addressBehaviour=HAL_DO_INCREMENT, uint32_t offset=0) const =0 throw (IllegalValueException, UnsupportedException, IllegalOperationException, BusAdapterException) |
Abstraction of the hardware block-read access. | |
virtual void | hardwareWriteBlock (const GeneralHardwareAddress &address, uint32_t length, char *buffer, HalAddressIncrement addressBehaviour=HAL_DO_INCREMENT, uint32_t offset=0) const =0 throw (IllegalValueException, UnsupportedException, IllegalOperationException, BusAdapterException) |
Abstraction of the hardware block-write access. | |
Private Member Functions | |
void | verify (uint32_t readBack, uint32_t data, std::string methodName) const throw ( VerifyException ) |
void | writeAddressItem (const AddressTableItem &addressItem, uint32_t data, uint32_t offset, HalVerifyOption verify) const throw ( MaskBoundaryException, IllegalValueException, BusAdapterException, VerifyException, AddressOutOfLimitsException ) |
Private Attributes | |
AddressTableInterface & | addressTable |
The implementation of the hardwareDeviceInterface.
This class implements the HardwareDeviceInterface. The public methods are documented there.
Note that this class is still abstract since it defines an interface to routines which do the actual hardware access. The implementation of these routines is technology dependent and therefore cannot be implemented in this class. In addition the methods readBlock and writeBlock are not implemented in this class since this is an technology dependent issue (there are fundamental differences for VME and PCI).
Definition at line 46 of file HardwareDevice.hh.
HAL::HardwareDevice::HardwareDevice | ( | HAL::AddressTableInterface & | addressTable | ) |
The constructor needs a reference to the AddressTable for the hardware Device.
The AddressTable MUST exist as long as the HardwareDevice since only a reference is passed to the HardwareDevice (this enables to share an addressTable among many HardwareDevices: imagine a crate full of ADC cards.)
Definition at line 7 of file HardwareDevice.cc.
HAL::HardwareDevice::~HardwareDevice | ( | ) | [virtual] |
Definition at line 10 of file HardwareDevice.cc.
bool HAL::HardwareDevice::check | ( | std::string | item, |
uint32_t | expectation, | ||
std::string | faultMessage = "" , |
||
uint32_t | offset = 0 , |
||
std::ostream & | os = std::cout |
||
) | const throw ( NoSuchItemException, IllegalOperationException, BusAdapterException, AddressOutOfLimitsException) [virtual] |
Read an item from the hardware and check the result.
For debugging and automated tests this function reads a value from the hardware and checks it against an expected value. In case the function finds a descrepancy between the expected and the read value a message is printed to the standard output containing the item name, the read value and the expected value.
expectation | is the value which is expected to be read from item. |
faultMessage | might contain additional information to be printed in case of a non successful test. |
Implements HAL::HardwareDeviceInterface.
Definition at line 203 of file HardwareDevice.cc.
const HAL::AddressTableInterface & HAL::HardwareDevice::getAddressTableInterface | ( | ) | const [virtual] |
Retrieve a handle to the AddressTableInterface.
In some cases it might be desirable to get the AddressMap of the hardware device (for example to get addresses subsequently used in unmasked read/write commands for time critical parts of the program). Therefore a method is provided which returns the Memory Map.
Implements HAL::HardwareDeviceInterface.
Definition at line 309 of file HardwareDevice.cc.
virtual void HAL::HardwareDevice::hardwareRead | ( | const GeneralHardwareAddress & | address, |
uint32_t * | result, | ||
uint32_t | offset = 0 |
||
) | const throw (IllegalValueException, BusAdapterException) [pure virtual] |
Abstraction of the hardware read access.
This interface is called by the implementation of the HardwareDeviceInterface. Since the implementation depends on the technology of the hardware device (VME or PCI) they are implemented in the classes inheriting from this interface (PCIDevice and VMEDevice).
address | is a generalized address from which the program should read. It's precise content depend on the device technology. |
Implemented in HAL::PCIDevice, HAL::VMEDevice, HAL::VMEConfigurationSpaceDevice, and HAL::VME64xDevice.
virtual void HAL::HardwareDevice::hardwareReadBlock | ( | const GeneralHardwareAddress & | address, |
uint32_t | length, | ||
char * | buffer, | ||
HalAddressIncrement | addressBehaviour = HAL_DO_INCREMENT , |
||
uint32_t | offset = 0 |
||
) | const throw (IllegalValueException, UnsupportedException, IllegalOperationException, BusAdapterException) [pure virtual] |
Abstraction of the hardware block-read access.
This interface is called by the readBlock implementation of the HardwareDeviceInterface. Since the implementation depends on the technology of the hardware device (VME or PCI) they are implemented in the classes inheriting from this interface (PCIDevice and VMEDevice).
address | is a generalized address from which the program should read. It's precise content depend on the device technology. |
Implemented in HAL::PCIDevice, HAL::VMEDevice, and HAL::VMEConfigurationSpaceDevice.
virtual void HAL::HardwareDevice::hardwareWrite | ( | const GeneralHardwareAddress & | address, |
uint32_t | data, | ||
uint32_t | offset = 0 |
||
) | const throw (IllegalValueException, BusAdapterException) [pure virtual] |
Abstraction of the hardware write access.
This interface is called by the above implementation of the HardwareDeviceInterface. Since the implementation depends on the technology of the hardware device (VME or PCI) they are implemented in the classes inheriting from this interface (PCIDevice and VMEDevice).
address | is a generalized address to which the program should write. It's precise content depend on the device technology. |
Implemented in HAL::PCIDevice, HAL::VMEDevice, HAL::VMEConfigurationSpaceDevice, and HAL::VME64xDevice.
virtual void HAL::HardwareDevice::hardwareWriteBlock | ( | const GeneralHardwareAddress & | address, |
uint32_t | length, | ||
char * | buffer, | ||
HalAddressIncrement | addressBehaviour = HAL_DO_INCREMENT , |
||
uint32_t | offset = 0 |
||
) | const throw (IllegalValueException, UnsupportedException, IllegalOperationException, BusAdapterException) [pure virtual] |
Abstraction of the hardware block-write access.
This interface is called by the writeBlock implementation of the HardwareDeviceInterface. Since the implementation depends on the technology of the hardware device (VME or PCI) they are implemented in the classes inheriting from this interface (PCIDevice and VMEDevice).
address | is a generalized address from which the program should read. It's precise content depend on the device technology. |
Implemented in HAL::PCIDevice, HAL::VMEDevice, and HAL::VMEConfigurationSpaceDevice.
bool HAL::HardwareDevice::isSet | ( | std::string | item, |
uint32_t | offset = 0 |
||
) | const throw (NoSuchItemException, BusAdapterException, IllegalOperationException, AddressOutOfLimitsException) [virtual] |
Test the value of a single bit.
This function can be used if the item describes a flag (i.e. exactly one bit is set to '1' in the item's bit mask.)
Implements HAL::HardwareDeviceInterface.
Definition at line 184 of file HardwareDevice.cc.
void HAL::HardwareDevice::pollItem | ( | std::string | item, |
uint32_t | referenceValue, | ||
uint32_t | timeout, | ||
uint32_t * | result, | ||
HalPollMethod | pollMethod = HAL_POLL_UNTIL_EQUAL , |
||
uint32_t | offset = 0 |
||
) | const throw ( NoSuchItemException, IllegalOperationException, BusAdapterException, MaskBoundaryException, TimeoutException, AddressOutOfLimitsException ) [virtual] |
This function polls an item and does not return until the polling condition is matched.
The function allows to poll until a reference value is read back from the hardware or until the value read from the hardware is different from the reference value. The user must give a timeout value in ms. If the call to this function takes longer than the timeout a TimeoutException is thrown.
referenceValue | is the value against the polled item is checked. The value of the pollMethod parameter defines its meaning (see below). |
timeout | determines the time in milliseconds after which a TimeoutException will be thrown if the poll condition has not been encountered before. This parameter is necessary in order to avoid that faulty hardware or buggy programs make this function to block forever. The timeout value must be given in milliseconds. It is only garanteed that the exception is not thrown before the timout-period has passed. It might though pass a significant longer time before the exception is thrown (this depends on the implementation of the routine). |
*result | points to a variable which will contain the value of the last read access performed during polling. If the call to pollItem has been terminated by an exception there is no meaningful value in this variable. |
pollMethod | can take the value HAL_POLL_UNTIL_EQUAL or HAL_POLL_UNTIL_DIFFERENT. If the first value (which is the default) is given, the call blocks until the value read back from the item is equal to the referenceValue. If the second value is given, the call blocks until the value read back from the item is not equal to the referenceValue. |
Implements HAL::HardwareDeviceInterface.
Definition at line 104 of file HardwareDevice.cc.
void HAL::HardwareDevice::printAddressTable | ( | ) | const [virtual] |
Print out the AddressTable of the hardware device This prints out the AddressTable which is used by the HardwareDevice to resolve the addresses of the various items.
Implements HAL::HardwareDeviceInterface.
Definition at line 313 of file HardwareDevice.cc.
void HAL::HardwareDevice::read | ( | std::string | item, |
uint32_t * | result, | ||
uint32_t | offset = 0 |
||
) | const throw (NoSuchItemException, BusAdapterException, IllegalOperationException, MaskBoundaryException, AddressOutOfLimitsException ) [virtual] |
Read an item from the hardware device.
This is the function to be normally used in order to read data from the hardware. The items bit mask in used to shift the result that the items least significant bit becomes bit 0 of the result.
Implements HAL::HardwareDeviceInterface.
Definition at line 85 of file HardwareDevice.cc.
void HAL::HardwareDevice::readBlock | ( | std::string | startItem, |
uint32_t | length, | ||
char * | buffer, | ||
HalAddressIncrement | addressBehaviour = HAL_DO_INCREMENT , |
||
uint32_t | offset = 0 |
||
) | const throw ( NoSuchItemException, IllegalValueException, UnsupportedException, BusAdapterException, IllegalOperationException, AddressOutOfLimitsException ) [virtual] |
A function to a block write of data into the hardware device.
The data to be written is contained in a buffer of the host. The user has to make sure that this buffer is at least as large as indicated by the length argument. For this function you must read the documentation in the technology dependent classes VMEDevice or PCIDevice.
startItem | is a item in the AddressTable which defines the startaddress of the block in the hardware device. Note that the addressModifier of this item determines how the transfer will be performed. Blocktransfers are only initiated if the correct addressmodifier is associated with this item (and of course, if the used BusAdapter is supporting BlockTransfers). |
length | is the number of bytes the user wants to transfer. Note that the length must be a multiple of the dataWidth specified for the item (in the AddressTable), otherwise an exception is thrown. |
buffer | points to the data in the host computer from where to transfer the data. It is the responsibility of the user to make sure that this buffer is at least as large as indicated by the length paramenter! This library cannot prevent core-dumps and segmentation faults here! (It starts to become less user-friendly here, but if you want performance, that's life !!!!) On purpose this buffer has been specified to be of the type (char) since this makes sure that it is just an array of bytes. |
addressBehaviour | determines if the address at in the hardware device is incremented for every dataword to be transfered or if it stays constant (in order to read out some Fifo-like memory). NOTE THAT YOU CANNOT ALWAYS GUARANTEE THAT YOUR SYSTEMS BEHAVES ACCORDING TO THE SETTING OF THIS FLAG. The reason for this is explained in the documentation of this function in the VMEDevice. (Instead for PCIDevices the funtion behaves as you expect.) |
offset | is optional and is the an offset in number of bytes which in present is added to the address correspondig to 'item'. The resulting address must be aligned with respect to the dataWidth of 'item'. |
IllegalValueException | is thrown if the length is not a multiple of the dataWidth defined for the item. |
UnsupportedException | if the desired addressBehaviour is not implemented by the attached BusAdapter. |
Implements HAL::HardwareDeviceInterface.
Definition at line 279 of file HardwareDevice.cc.
void HAL::HardwareDevice::readPulse | ( | std::string | item, |
uint32_t | offset = 0 |
||
) | const throw (NoSuchItemException, BusAdapterException, IllegalOperationException, AddressOutOfLimitsException) [virtual] |
Perform a read access in order to trigger side effects.
This function is performing a read access to trigger some hardware specific activity (side effect). No data is actually returned to the user.
Implements HAL::HardwareDeviceInterface.
Definition at line 60 of file HardwareDevice.cc.
void HAL::HardwareDevice::resetBit | ( | std::string | item, |
HalVerifyOption | verifyFlag = HAL_NO_VERIFY , |
||
uint32_t | offset = 0 |
||
) | const throw (NoSuchItemException, IllegalOperationException, BusAdapterException, VerifyException, AddressOutOfLimitsException) [virtual] |
Reset a single bit.
This function can be used if the item describes a flag (i.e. exactly one bit is set to '1' in the item's bit mask.). If the flag needs to be reset according to a value contained in a variable the write command should be used.
verifyFlag | allows automatic verification of the written data if set to "HAL_DO_VERIFY". If the item is readable it is read back and compared to the originally written value. The VerifyException is thrown if no coincidenc is found. |
Implements HAL::HardwareDeviceInterface.
Definition at line 170 of file HardwareDevice.cc.
void HAL::HardwareDevice::setBit | ( | std::string | item, |
HalVerifyOption | verifyFlag = HAL_NO_VERIFY , |
||
uint32_t | offset = 0 |
||
) | const throw (NoSuchItemException, IllegalOperationException, BusAdapterException, VerifyException, AddressOutOfLimitsException) [virtual] |
Set a single bit.
This function can be used if the item describes a flag (i.e. exactly one bit is set to '1' in the item's bit mask.). If the flag needs to be set according to a value contained in a variable the write command should be used.
verifyFlag | allows automatic verification of the written data if set to "HAL_DO_VERIFY". If the item is readable it is read back and compared to the originally written value. The VerifyException is thrown if no coincidenc is found. |
Implements HAL::HardwareDeviceInterface.
Definition at line 156 of file HardwareDevice.cc.
void HAL::HardwareDevice::unmaskedRead | ( | std::string | item, |
uint32_t * | result, | ||
uint32_t | offset = 0 |
||
) | const throw (NoSuchItemException, BusAdapterException, IllegalOperationException, AddressOutOfLimitsException) [virtual] |
Read a data word without applying the items mask.
Implements HAL::HardwareDeviceInterface.
Definition at line 73 of file HardwareDevice.cc.
void HAL::HardwareDevice::unmaskedWrite | ( | std::string | item, |
uint32_t | data, | ||
HalVerifyOption | verifyFlag = HAL_NO_VERIFY , |
||
uint32_t | offset = 0 |
||
) | const throw (NoSuchItemException, IllegalOperationException, BusAdapterException, VerifyException, AddressOutOfLimitsException) [virtual] |
Write a data word without applying the mask for the item.
verifyFlag | allows automatic verification of the written data if set to "HAL_DO_VERIFY". If the item is readable it is read back and compared to the originally written value. The VerifyException is thrown if no coincidenc is found. |
Implements HAL::HardwareDeviceInterface.
Definition at line 12 of file HardwareDevice.cc.
void HAL::HardwareDevice::verify | ( | uint32_t | readBack, |
uint32_t | data, | ||
std::string | methodName | ||
) | const throw ( VerifyException ) [private] |
Definition at line 317 of file HardwareDevice.cc.
void HAL::HardwareDevice::write | ( | std::string | item, |
uint32_t | data, | ||
HalVerifyOption | verifyFlag = HAL_NO_VERIFY , |
||
uint32_t | offset = 0 |
||
) | const throw (NoSuchItemException, BusAdapterException, IllegalOperationException, VerifyException, MaskBoundaryException, AddressOutOfLimitsException) [virtual] |
Write a new value for an item into the hardware device.
This is the function which is usually used in order to write data to the hardware. It is important to understand some details of what is happening when invoking the method:
The aim of the procedure is that new values can be written to bitfields without destroying the value contained in bits not belonging to the item. This of course is only possible if the item is also readable.
verifyFlag | allows automatic verification of the written data if set to "HAL_DO_VERIFY". If the item is readable it is read back and compared to the originally written value. The VerifyException is thrown if no coincidenc is found. |
Implements HAL::HardwareDeviceInterface.
Definition at line 32 of file HardwareDevice.cc.
void HAL::HardwareDevice::writeAddressItem | ( | const AddressTableItem & | addressItem, |
uint32_t | data, | ||
uint32_t | offset, | ||
HalVerifyOption | verify | ||
) | const throw ( MaskBoundaryException, IllegalValueException, BusAdapterException, VerifyException, AddressOutOfLimitsException ) [private] |
Definition at line 331 of file HardwareDevice.cc.
void HAL::HardwareDevice::writeBlock | ( | std::string | startItem, |
uint32_t | length, | ||
char * | buffer, | ||
HalVerifyOption | verifyFlag = HAL_NO_VERIFY , |
||
HalAddressIncrement | addressBehaviour = HAL_DO_INCREMENT , |
||
uint32_t | offset = 0 |
||
) | const throw ( NoSuchItemException, IllegalValueException, UnsupportedException, VerifyException, BusAdapterException, IllegalOperationException, AddressOutOfLimitsException ) [virtual] |
A function to read a block of data into the host memory.
The buffer to be filled consists of an allocated space of bytes. The user has to make sure that this buffer is large enough to receive all data to be read. For this function you must read the documentation in the technology dependent classes VMEDevice or PCIDevice.
startItem | is a item in the AddressTable which defines the startaddress of the block in the hardware device. Note that the addressModifier of this item determines how the transfer will be performed. Blocktransfers are only initiated if the correct addressmodifier is associated with this item (and of course, if the used BusAdapter is supporting BlockTransfers). |
length | is the number of bytes the user wants to transfer. Note that the length must be a multiple of the dataWidth specified for the item (in the AddressTable), otherwise an exception is thrown. |
buffer | points to the destination in the host computer where to transfer the data to. It is the responsibility of the user to provide a data buxffer with sufficient space! This library cannot prevent core-dumps and segmentation faults here. (It starts to become less user-friendly here, but if you want performance, that's life !!!!) On purpose this buffer has been specified to be of the type (char) since this makes sure that it is just an array of bytes. |
verifyFlag | allows automatic verification of the written data if set to "HAL_DO_VERIFY". If the startItem is readable the data block is read back with the readBlock function and the read block is compared to the orgiginal block written. The VerifyException is thrown if no coincidence is found. |
addressBehaviour | determines if the address in the hardware device is incremented for every dataword to be transfered or if it stays constant (in order to read out some Fifo-like memory). NOTE THAT YOU CANNOT ALWAYS GUARANTEE THAT YOUR SYSTEMS BEHAVES ACCORDING TO THE SETTING OF THIS FLAG. The reason for this is explained in the documentation of this function in the VMEDevice. (Instead for PCIDevices the funtion behaves as you expect.) |
offset | is optional and is the an offset in number of bytes which in present is added to the address correspondig to 'item'. The resulting address must be aligned with respect to the dataWidth of 'item'. |
IllegalValueException | is thrown if the length is not a multiple of the dataWidth defined for the item. |
UnsupportedException | if the desired addressBehaviour is not implemented by the attached BusAdapter. |
Implements HAL::HardwareDeviceInterface.
Definition at line 235 of file HardwareDevice.cc.
void HAL::HardwareDevice::writePulse | ( | std::string | item, |
uint32_t | offset = 0 |
||
) | const throw (NoSuchItemException, BusAdapterException, IllegalOperationException, AddressOutOfLimitsException) [virtual] |
Perform a write access in order to trigger side effects.
Often in hardware modules certain functionality or action is triggered by a write-access to a specific address, where the data value transfered does not matter but only the so called side-effects of the write operation are exploited. (For example to invoke some reset function.) This function should be used in these cases. Using it consequently in these cases makes the code readable. The function is as efficient as the unmasked write function. The function actually writes a 0 into the hardware.
Implements HAL::HardwareDeviceInterface.
Definition at line 48 of file HardwareDevice.cc.
Definition at line 287 of file HardwareDevice.hh.