API for accessing hardware devices, mosty over VMEbus. More...

#include "dbDefs.h"
#include "osdVME.h"
#include "errMdef.h"
#include "libComAPI.h"
#include "devLib.h"
#include "devLibVMEImpl.h"

Include dependency graph for devLibVME.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	epicsAddressType { atVMEA16, atVMEA24, atVMEA32, atISA, atVMECSR, atLast }
	The available bus address types. More...

Functions
LIBCOM_API long	devAddressMap (void)
	Print a map of registered bus addresses. More...

LIBCOM_API long	devBusToLocalAddr (epicsAddressType addrType, size_t busAddr, volatile void **ppLocalAddr)
	Translate a bus address to a pointer the CPU can use. More...

LIBCOM_API long	devReadProbe (unsigned wordSize, volatile const void ptr, void pValueRead)
	Probe the bus for reading from a specific address. More...

LIBCOM_API long	devNoResponseProbe (epicsAddressType addrType, size_t base, size_t size)
	Read-probe a range of bus addresses, looking for empty space. More...

LIBCOM_API long	devWriteProbe (unsigned wordSize, volatile void ptr, const void pValueWritten)
	Probe the bus for writing to a specific address. More...

LIBCOM_API long	devRegisterAddress (const char pOwnerName, epicsAddressType addrType, size_t logicalBaseAddress, size_t size, volatile void *pPhysicalAddress)
	Register a bus address range with a name. More...

LIBCOM_API long	devUnregisterAddress (epicsAddressType addrType, size_t logicalBaseAddress, const char *pOwnerName)
	Release a bus address range previously registered. More...

LIBCOM_API long	devAllocAddress (const char pOwnerName, epicsAddressType addrType, size_t size, unsigned alignment, volatile void *pLocalAddress)
	Allocate and register an unoccupied address block. More...

VME Interrupt Management
Routines to manage VME interrupts.
LIBCOM_API long	devConnectInterruptVME (unsigned vectorNumber, void(pFunction)(void ), void *parameter)
	Connect an ISR up to a VME interrupt vector. More...

LIBCOM_API long	devDisconnectInterruptVME (unsigned vectorNumber, void(pFunction)(void ))
	Disconnect an ISR from its VME interrupt vector. More...

LIBCOM_API int	devInterruptInUseVME (unsigned vectorNumber)
	Determine if a VME interrupt vector is in use. More...

LIBCOM_API long	devEnableInterruptLevelVME (unsigned level)
	Enable a VME interrupt level onto the CPU. More...

LIBCOM_API long	devDisableInterruptLevelVME (unsigned level)
	Disable a VME interrupt level. More...

Memory for VME DMA Operations
These routines manage memory that can be directly accessed from the VMEbus in the A24 address space by another bus master such as a DMA controller.
LIBCOM_API void *	devLibA24Malloc (size_t size)
	malloc() for VME drivers that support DMA. More...

LIBCOM_API void *	devLibA24Calloc (size_t size)
	calloc() for VME drivers that support DMA. More...

LIBCOM_API void	devLibA24Free (void *pBlock)
	free() for VME drivers that support DMA. More...

ISA Interrupt Management
Routines to manage ISAbus interrupts. Note These routines may not have been used for a very long time; some appear to have never been implemented at all. They may vanish with no notice from future versions of EPICS Base. Nobody is using the PC's ISA-bus any more are they?
LIBCOM_API long	devConnectInterruptISA (unsigned interruptLevel, void(pFunction)(void ), void *parameter)

LIBCOM_API long	devDisconnectInterruptISA (unsigned interruptLevel, void(pFunction)(void ))

LIBCOM_API int	devInterruptLevelInUseISA (unsigned interruptLevel)

LIBCOM_API long	devEnableInterruptLevelISA (unsigned level)

LIBCOM_API long	devDisableInterruptLevelISA (unsigned level)

Variables
LIBCOM_API const char *	epicsAddressTypeName []
	A string representation of each of the bus address types.

Deprecated Interfaces
enum	epicsInterruptType { intVME, intVXI, intISA }

LIBCOM_API long	devConnectInterrupt (epicsInterruptType intType, unsigned vectorNumber, void(pFunction)(void ), void *parameter)

LIBCOM_API long	devDisconnectInterrupt (epicsInterruptType intType, unsigned vectorNumber, void(pFunction)(void ))

LIBCOM_API long	devEnableInterruptLevel (epicsInterruptType intType, unsigned level)

LIBCOM_API long	devDisableInterruptLevel (epicsInterruptType intType, unsigned level)

LIBCOM_API long	locationProbe (epicsAddressType addrType, char *pLocation)

Detailed Description

Author: Marty Kraimer, Jeff Hill API for accessing hardware devices. The original APIs here were for written for use with VMEbus but additional routines were added for ISA-bus (but not fully implemented inside EPICS Base and may never have been actually used).

If all VMEbus drivers register with these routines then addressing conflicts caused by multiple device/drivers trying to use the same VME addresses will be detected. This API also makes it easy for a single driver to be written that works on both VxWorks and RTEMS.

Definition in file devLibVME.h.

Enumeration Type Documentation

enum epicsAddressType

Enumerator
atVMEA16	VME short I/O.
atVMEA24	VME standard I/O.
atVMEA32	VME extended I/O.
atISA	Memory mapped ISA access.
atVMECSR	VME-64 CR/CSR address space.
atLast	Invalid, must be the last entry.

Definition at line 41 of file devLibVME.h.

Function Documentation

LIBCOM_API long devAddressMap ( void )

Display a table of registered bus address ranges, including the owner of each registered address.

Returns: 0, or an error status value

LIBCOM_API long devBusToLocalAddr	(	epicsAddressType	addrType,
		size_t	busAddr,
		volatile void **	ppLocalAddr
	)

Given a bus address, returns a pointer to that location in the CPU's memory map, or an error if direct access isn't currently possible.

Parameters

addrType	The bus address type.
busAddr	Bus address to be translated.
*ppLocalAddr	Where to put the CPU pointer.

Returns: 0, or an error status value.

LIBCOM_API long devReadProbe	(	unsigned	wordSize,
		volatile const void *	ptr,
		void *	pValueRead
	)

Performs a bus-error-safe wordSize atomic read from a specific address and returns an error if this caused a bus error.

Parameters

wordSize	The word size to read: 1, 2, 4 or 8 bytes.
ptr	Pointer to the location in the CPU's memory map to read.
pValueRead	Where to put the value read.

Returns: 0, or an error status value if the location could not be accessed or the read caused a bus error.

LIBCOM_API long devNoResponseProbe	(	epicsAddressType	addrType,
		size_t	base,
		size_t	size
	)

Verifies that no device responds at any naturally aligned addresses within the given range. Tries to read every aligned address at every word size between char and long over the entire range, returning success only if none of the reads succeed.

Warning: This routine may be slow and have a very bad effect on a busy VMEbus. Every read probe of an unused address will hold onto the VMEbus for the global bus timeout period.

Parameters

addrType	The bus address type.
base	First address base to probe.
size	Range of bus addresses to test, in bytes.

Returns: 0 if no devices respond, or an error status value.

LIBCOM_API long devWriteProbe	(	unsigned	wordSize,
		volatile void *	ptr,
		const void *	pValueWritten
	)

Performs a bus-error-safe wordSize atomic write to a specific address and returns an error if this caused a bus error.

Parameters

wordSize	The word size to write: 1, 2, 4 or 8 bytes.
ptr	Pointer to the location in the CPU's memory map to write to.
pValueWritten	The value to write.

Returns: 0, or an error status value if the location could not be accessed or the write caused a bus error.

LIBCOM_API long devRegisterAddress	(	const char *	pOwnerName,
		epicsAddressType	addrType,
		size_t	logicalBaseAddress,
		size_t	size,
		volatile void **	pPhysicalAddress
	)

The devLib code keeps a list of all bus address ranges registered with this routine and returns an error if a later call attempts to register any addresses that overlap with a range already registered. The call to registering a range also converts the given base address into a pointer in the CPU address space for the driver to use (see devBusToLocalAddr()).

Parameters

pOwnerName	Name of a driver that will own this range.
addrType	The bus address type.
logicalBaseAddress	The bus start address.
size	Number of bytes to reserve.
pPhysicalAddress	Where to put the converted CPU pointer.

Returns: 0, or an error status.

LIBCOM_API long devUnregisterAddress	(	epicsAddressType	addrType,
		size_t	logicalBaseAddress,
		const char *	pOwnerName
	)

Release an address range that was previously registered by a call to devRegisterAddress() or devAllocAddress().

Parameters

addrType	The bus address type.
logicalBaseAddress	The bus start address.
pOwnerName	The name of the driver that owns this range.

Returns: 0, or an error status.

LIBCOM_API long devAllocAddress	(	const char *	pOwnerName,
		epicsAddressType	addrType,
		size_t	size,
		unsigned	alignment,
		volatile void **	pLocalAddress
	)

Asks devLib to allocate an address block of a particular address type. This is useful for devices that appear in more than one address space and can program the base address of one window using registers found in another window. As with devRegisterAddress() this call also converts the new base address into a pointer in the CPU address space for the driver to use (see devBusToLocalAddr()).

Note: This routine calls devNoResponseProbe() to find an unoccupied block in the bus address space, so using it may have a bad effect on a busy VMEbus at allocation time; see the warning above.

Parameters

pOwnerName	Name of a driver that will own this range.
addrType	The bus address type.
size	Number of bytes to be allocated.
alignment	How many low bits in the address must all be zero.
pLocalAddress	Where to put the CPU pointer.

Returns: 0, or an error status value.

LIBCOM_API long devConnectInterruptVME	(	unsigned	vectorNumber,
		void()(void )	pFunction,
		void *	parameter
	)

Interrupt Service Routines (ISRs) are normally written in C, and get passed a context parameter given with them to this connection routine.

There are many restrictions on the routines that an ISR may call; see epicsEvent.h, epicsInterrupt.h, epicsMessageQueue.h, epicsRingBytes.h, epicsRingPointer.h and epicsTime.h for some APIs known to be suitable. It is safest just to trigger a high-priority task to handle any complex work that must happen as a result of the interrupt.

Parameters

vectorNumber	VME interrupt vector number.
pFunction	The ISR to be called.
parameter	Context parameter for the ISR.

Returns: 0, or an error status value.

LIBCOM_API long devDisconnectInterruptVME	(	unsigned	vectorNumber,
		void()(void )	pFunction
	)

Device drivers may disconnect an ISR they connected earlier using this routine. In addition to taking the vectorNumber the ISR itself is required and used as a check to prevent a driver from inadvertently removing an interrupt handler that it didn't install.

On a PowerPC target running VxWorks, this routine will always return with an error status.

Parameters

vectorNumber	VME interrupt vector number.
pFunction	The ISR to be disconnected.

Returns: 0, or an error status value.

LIBCOM_API int devInterruptInUseVME ( unsigned vectorNumber )

On a PowerPC target running VxWorks this routine will always return false, indicating that a vector is unused.

Parameters

vectorNumber Interrupt vector number.

Returns: True if vector has an ISR attached, otherwise false.

LIBCOM_API long devEnableInterruptLevelVME ( unsigned level )

The VMEbus allows multiple CPU boards to be installed in the same backplane. When this is done, the different VME interrupt levels must be assigned to the CPUs since they cannot be shared. This routine tells the VME interface that it should connect interrupts from the indicated interrupt level to a CPU interrupt line.

Parameters

level VMEbus interrupt level to enable, 1-7.

Returns: 0, or an error status value.

LIBCOM_API long devDisableInterruptLevelVME ( unsigned level )

This routine is the reverse of devEnableInterruptLevelVME().

Note: This routine should not normally be used, even by a driver that enabled the interrupt level. Disabling a VME interrupt level should only be done by software that knows for certain that no other interrupting device is also using that VME interrupt level.

Parameters

level VMEbus interrupt level to disable, 1-7.

Returns: 0, or an error status value.

LIBCOM_API void* devLibA24Malloc ( size_t size )

Allocate memory of a given size from a region that can be accessed from the VMEbus in the A24 address space.

Parameters

size	How many bytes to allocate

Returns: A pointer to the memory allocated, or NULL.

LIBCOM_API void* devLibA24Calloc ( size_t size )

Allocate and zero-fill a block of memory of a given size from a region that can be accessed from the VMEbus in the A24 address space.

Parameters

size	How many bytes to allocate and zero.

Returns: A pointer to the memory allocated, or NULL.

LIBCOM_API void devLibA24Free ( void * pBlock )

Free a block of memory that was allocated using either devLibA24Malloc() or devLibA24Calloc().

Parameters

pBlock Block to be released.

LIBCOM_API long devConnectInterruptISA	(	unsigned	interruptLevel,
		void()(void )	pFunction,
		void *	parameter
	)

Connect ISR to a ISA interrupt.

Warning: Not implemented!

Parameters

interruptLevel	Bus interrupt level to connect to.
pFunction	C function pointer to connect to.
parameter	Parameter to the called function.

Returns: Returns success or error.

LIBCOM_API long devDisconnectInterruptISA	(	unsigned	interruptLevel,
		void()(void )	pFunction
	)

Disconnect ISR from a ISA interrupt level.

Warning: Not implemented!

Parameters

interruptLevel	Interrupt level.
pFunction	C function pointer that was connected.

Returns: returns success or error.

LIBCOM_API int devInterruptLevelInUseISA ( unsigned interruptLevel )

Determine if an ISA interrupt level is in use

Warning: Not implemented!

Parameters

interruptLevel Interrupt level.

Returns: Returns True/False.

LIBCOM_API long devEnableInterruptLevelISA ( unsigned level )

Enable ISA interrupt level

Parameters

level Interrupt level.

Returns: Returns True/False.

LIBCOM_API long devDisableInterruptLevelISA ( unsigned level )

Disable ISA interrupt level

Parameters

level Interrupt level.

Returns: Returns True/False.

LIBCOM_API long devConnectInterrupt	(	epicsInterruptType	intType,
		unsigned	vectorNumber,
		void()(void )	pFunction,
		void *	parameter
	)

Note: This routine has been deprecated. It exists for backwards compatibility purposes only. Please use one of devConnectInterruptVME(), devConnectInterruptPCI(), devConnectInterruptISA() instead. devConnectInterrupt() will be removed in a future release.

LIBCOM_API long devDisconnectInterrupt	(	epicsInterruptType	intType,
		unsigned	vectorNumber,
		void()(void )	pFunction
	)

Note: This routine has been deprecated. It exists for backwards compatibility purposes only. Please use one of devDisconnectInterruptVME(), devDisconnectInterruptPCI(), devDisconnectInterruptISA() instead. devDisconnectInterrupt() will be removed in a future release.

LIBCOM_API long devEnableInterruptLevel	(	epicsInterruptType	intType,
		unsigned	level
	)

Note: This routine has been deprecated. It exists for backwards compatibility purposes only. Please use one of devEnableInterruptLevelVME(), devEnableInterruptLevelPCI(), devEnableInterruptLevelISA() instead. devEnableInterruptLevel() will be removed in a future release.

LIBCOM_API long devDisableInterruptLevel	(	epicsInterruptType	intType,
		unsigned	level
	)

Note: This routine has been deprecated. It exists for backwards compatibility purposes only. Please use one of devDisableInterruptLevelVME(), devDisableInterruptLevelISA(), devDisableInterruptLevelPCI() instead. devDisableInterruptLevel() will be removed in a future release.

LIBCOM_API long locationProbe	(	epicsAddressType	addrType,
		char *	pLocation
	)

Note: This routine has been deprecated. It exists for backwards compatibility purposes only. Please use devNoResponseProbe() instead. locationProbe() will be removed in a future release.

Enumerations

Functions

Variables

Deprecated Interfaces

Detailed Description

Enumeration Type Documentation

Function Documentation