devLibVME.c File Reference

#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#include "dbDefs.h"
#include "epicsMutex.h"
#include "errlog.h"
#include "ellLib.h"
#include "devLibVME.h"
#include "devLibVMEImpl.h"

Include dependency graph for devLibVME.c:

Go to the source code of this file.

Classes
struct	rangeItem

Macros
#define	NO_DEVLIB_COMPAT
#define	SUCCESS   0

Functions
long	devBusToLocalAddr (epicsAddressType addrType, size_t busAddr, volatile void **ppLocalAddress)
	Translate a bus address to a pointer the CPU can use. More...
long	devRegisterAddress (const char *pOwnerName, epicsAddressType addrType, size_t base, size_t size, volatile void **ppPhysicalAddress)
	Register a bus address range with a name. More...
long	devReadProbe (unsigned wordSize, volatile const void *ptr, void *pValue)
	Probe the bus for reading from a specific address. More...
long	devWriteProbe (unsigned wordSize, volatile void *ptr, const void *pValue)
	Probe the bus for writing to a specific address. More...
long	devUnregisterAddress (epicsAddressType addrType, size_t baseAddress, const char *pOwnerName)
	Release a bus address range previously registered. More...
long	devAllocAddress (const char *pOwnerName, epicsAddressType addrType, size_t size, unsigned alignment, volatile void **pLocalAddress)
	Allocate and register an unoccupied address block. More...
long	devAddressMap (void)
	Print a map of registered bus addresses. More...
long	devNoResponseProbe (epicsAddressType addrType, size_t base, size_t size)
	Read-probe a range of bus addresses, looking for empty space. More...
long	devConnectInterruptVME (unsigned vectorNumber, void(*pFunction)(void *), void *parameter)
	Connect an ISR up to a VME interrupt vector. More...
long	devDisconnectInterruptVME (unsigned vectorNumber, void(*pFunction)(void *))
	Disconnect an ISR from its VME interrupt vector. More...
int	devInterruptInUseVME (unsigned level)
	Determine if a VME interrupt vector is in use. More...
long	devEnableInterruptLevelVME (unsigned level)
	Enable a VME interrupt level onto the CPU. More...
long	devDisableInterruptLevelVME (unsigned level)
	Disable a VME interrupt level. More...
long	devConnectInterrupt (epicsInterruptType intType, unsigned vectorNumber, void(*pFunction)(void *), void *parameter)
long	devDisconnectInterrupt (epicsInterruptType intType, unsigned vectorNumber, void(*pFunction)(void *))
long	devEnableInterruptLevel (epicsInterruptType intType, unsigned level)
long	devDisableInterruptLevel (epicsInterruptType intType, unsigned level)
long	locationProbe (epicsAddressType addrType, char *pLocation)
void *	devLibA24Calloc (size_t size)
	calloc() for VME drivers that support DMA. More...
void *	devLibA24Malloc (size_t size)
	malloc() for VME drivers that support DMA. More...
void	devLibA24Free (void *pBlock)
	free() for VME drivers that support DMA. More...

Variables
const char *	epicsAddressTypeName []
	A string representation of each of the bus address types. More...
int	devLibA24Debug = 0

Macro Definition Documentation

#define NO_DEVLIB_COMPAT

Definition at line 31 of file devLibVME.c.

#define SUCCESS   0

Definition at line 137 of file devLibVME.c.

Function Documentation

long devAddressMap

(

void

)

Print a map of registered bus addresses.

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

Returns

0, or an error status value

Definition at line 737 of file devLibVME.c.

{
    return devListAddressMap(addrAlloc);
}

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

Allocate and register an unoccupied address block.

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.

Definition at line 604 of file devLibVME.c.

{
    int s;
    rangeItem *pRange;
    size_t base = 0;

    if (!devLibInitFlag) {
        s = devLibInit();
        if(s){
            return s;
        }
    }

    s = addrVerify (addrType, 0, size);
    if(s){
        return s;
    }

    if (size == 0) {
        return S_dev_lowValue;
    }

    epicsMutexMustLock(addrListLock);
    pRange = (rangeItem *) ellFirst (&addrFree[addrType]);
    while (pRange) {
        if ((pRange->end - pRange->begin) + 1 >= size){
            s = blockFind (
                addrType,
                pRange,
                size,
                alignment,
                &base);
            if (s==SUCCESS) {
                break;
            }
        }
        pRange = (rangeItem *) pRange->node.next;
    }
    epicsMutexUnlock(addrListLock);

    if(!pRange){
        s = S_dev_deviceDoesNotFit;
        errMessage(s, epicsAddressTypeName[addrType]);
        return s;
    }

    s = devInstallAddr (pRange, pOwnerName, addrType, base,
            size, pLocalAddress);

    return s;
}

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

Translate a bus address to a pointer the CPU can use.

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.

Definition at line 142 of file devLibVME.c.

{
    long status;
    volatile void *localAddress;

    /*
     * Make sure that devLib has been intialized
     */
    if (!devLibInitFlag) {
        status = devLibInit();
        if(status){
            return status;
        }
    }

    /*
     * Make sure we have a valid bus address
     */
    status = addrVerify (addrType, busAddr, 4);
    if (status) {
        return status;
    }

    /*
     * Call the virtual os routine to map the bus address to a CPU address
     */
    status = (*pdevLibVME->pDevMapAddr) (addrType, 0, busAddr, 4, &localAddress);
    if (status) {
        errPrintf (status, __FILE__, __LINE__, "%s bus address =0X%X\n",
            epicsAddressTypeName[addrType], (unsigned int)busAddr);
        return status;
    }

    /*
     * Return the local CPU address if the pointer is supplied
     */
    if (ppLocalAddress) {
        *ppLocalAddress = localAddress;
    }

    return SUCCESS;

}/*end devBusToLocalAddr()*/

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.

Definition at line 992 of file devLibVME.c.

{
    long status;

    if (!devLibInitFlag) {
        status = devLibInit();
        if (status) {
            return status;
        }
    }

    switch(intType){
    case intVME:
    case intVXI:
        return (*pdevLibVME->pDevConnectInterruptVME) (vectorNumber,
                    pFunction, parameter);
    default:
        return S_dev_uknIntType;
    }
}

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

Connect an ISR up to a VME interrupt vector.

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.

Definition at line 911 of file devLibVME.c.

{
    long status;

    if (!devLibInitFlag) {
        status = devLibInit();
        if (status) {
            return status;
        }
    }

    return (*pdevLibVME->pDevConnectInterruptVME) (vectorNumber,
                    pFunction, parameter);
}

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.

Definition at line 1080 of file devLibVME.c.

{
    long status;

    if (!devLibInitFlag) {
        status = devLibInit();
        if (status) {
            return status;
        }
    }

    switch(intType){
    case intVME:
    case intVXI:
        return (*pdevLibVME->pDevDisableInterruptLevelVME) (level);
    default:
        return S_dev_uknIntType;
    }
}

long devDisableInterruptLevelVME

(

unsigned

level

)

Disable a VME interrupt 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.

Definition at line 973 of file devLibVME.c.

{
    long status;

    if (!devLibInitFlag) {
        status = devLibInit();
        if (status) {
            return status;
        }
    }

    return (*pdevLibVME->pDevDisableInterruptLevelVME) (level);
}

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.

Definition at line 1023 of file devLibVME.c.

{
    long status;

    if (!devLibInitFlag) {
        status = devLibInit();
        if (status) {
            return status;
        }
    }

    switch(intType){
    case intVME:
    case intVXI:
        return (*pdevLibVME->pDevDisconnectInterruptVME) (vectorNumber,
                    pFunction);
    default:
        return S_dev_uknIntType;
    }
}

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

Disconnect an ISR from its VME interrupt vector.

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.

Definition at line 929 of file devLibVME.c.

{
    long status;

    if (!devLibInitFlag) {
        status = devLibInit();
        if (status) {
            return status;
        }
    }

    return (*pdevLibVME->pDevDisconnectInterruptVME) (vectorNumber, pFunction);
}

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.

Definition at line 1053 of file devLibVME.c.

{
    long status;

    if (!devLibInitFlag) {
        status = devLibInit();
        if (status) {
            return status;
        }
    }

    switch(intType){
    case intVME:
    case intVXI:
        return (*pdevLibVME->pDevEnableInterruptLevelVME) (level);
    default:
        return S_dev_uknIntType;
    }
}

long devEnableInterruptLevelVME

(

unsigned

level

)

Enable a VME interrupt level onto the CPU.

The VMEbus allows multiple CPU boards to be installed in the same backplane. When this is done, the differente 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.

Definition at line 959 of file devLibVME.c.

{
    long status;

    if (!devLibInitFlag) {
        status = devLibInit();
        if (status) {
            return status;
        }
    }

    return (*pdevLibVME->pDevEnableInterruptLevelVME) (level);
}

int devInterruptInUseVME

(

unsigned

vectorNumber

)

Determine if a VME interrupt vector is in use.

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.

Definition at line 945 of file devLibVME.c.

{
    long status;

    if (!devLibInitFlag) {
        status = devLibInit();
        if (status) {
            return status;
        }
    }

    return (*pdevLibVME->pDevInterruptInUseVME) (level);
}

void* devLibA24Calloc

(

size_t

size

)

calloc() for VME drivers that support DMA.

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.

Definition at line 1125 of file devLibVME.c.

{
  void *ret;

  ret = devLibA24Malloc(size);

  if (ret == NULL)
    return (NULL);

  memset(ret, 0x00, size);
  return(ret);
}

void devLibA24Free

(

void *

pBlock

)

free() for VME drivers that support DMA.

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

Parameters

pBlock

Block to be released.

Definition at line 1149 of file devLibVME.c.

{
    if (devLibA24Debug)
        epicsPrintf("devLibA24Free(%p) entered\n", pBlock);

    pdevLibVME->pDevA24Free(pBlock);
}

void* devLibA24Malloc

(

size_t

size

)

malloc() for VME drivers that support DMA.

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.

Definition at line 1138 of file devLibVME.c.

{
    void *ret;

    if (devLibA24Debug)
        epicsPrintf ("devLibA24Malloc(%u) entered\n", (unsigned int)size);

    ret = pdevLibVME->pDevA24Malloc(size);
    return(ret);
}

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

Read-probe a range of bus addresses, looking for empty space.

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.

Definition at line 847 of file devLibVME.c.

{
    volatile void *pPhysical;
    size_t probe;
    size_t byteNo;
    unsigned wordSize;
    union {
        char charWord;
        short shortWord;
        int intWord;
        long longWord;
    }allWordSizes;
    long s;

    if (!devLibInitFlag) {
        s = devLibInit();
        if (s) {
            return s;
        }
    }

    byteNo = 0;
    while (byteNo < size) {

        probe = base + byteNo;

        /*
         * for all word sizes
         */
        for (wordSize=1; wordSize<=sizeof(allWordSizes); wordSize <<= 1) {
            /*
             * only check naturally aligned words
             */
            if ( (probe&(wordSize-1)) != 0 ) {
                break;
            }

            if (byteNo+wordSize>size) {
                break;
            }

            /*
             * every byte in the block must
             * map to a physical address
             */
            s = (*pdevLibVME->pDevMapAddr) (addrType, 0, probe, wordSize, &pPhysical);
            if (s!=SUCCESS) {
                return s;
            }

            /*
             * verify that no device is present
             */
            s = (*pdevLibVME->pDevReadProbe)(wordSize, pPhysical, &allWordSizes);
            if (s==SUCCESS) {
                return S_dev_addressOverlap;
            }
        }
        byteNo++;
    }
    return SUCCESS;
}

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

Probe the bus for reading from a specific address.

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.

Definition at line 268 of file devLibVME.c.

{
    long status;

    if (!devLibInitFlag) {
        status = devLibInit();
        if (status) {
            return status;
        }
    }

    return (*pdevLibVME->pDevReadProbe) (wordSize, ptr, pValue);
}

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

Register a bus address range with a name.

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.

Definition at line 193 of file devLibVME.c.

{
    rangeItem *pRange;
    long s;

    if (!devLibInitFlag) {
        s = devLibInit();
        if(s){
            return s;
        }
    }

    s = addrVerify (addrType, base, size);
    if (s) {
        return s;
    }

    if (size == 0) {
        return S_dev_lowValue;
    }

#ifdef DEBUG
    printf ("Req Addr 0X%X Size 0X%X\n", base, size);
#endif

    epicsMutexMustLock(addrListLock);
    pRange = (rangeItem *) ellFirst(&addrFree[addrType]);
    while (TRUE) {
        if (pRange->begin > base) {
            pRange = NULL;
#           ifdef DEBUG
                printf ("Unable to locate a free block\n");
                devListAddressMap (&addrFree[addrType]);
#           endif
            break;
        }
        else if (base + (size - 1) <= pRange->end) {
#           ifdef DEBUG
                printf ("Found free block Begin 0X%X End 0X%X\n",
                        pRange->begin, pRange->end);
#           endif
            break;
        }

        pRange = (rangeItem *) ellNext (&pRange->node);
    }
    epicsMutexUnlock(addrListLock);

    if (pRange==NULL) {
        report_conflict (addrType, base, size, pOwnerName);
        return S_dev_addressOverlap;
    }

    s = devInstallAddr(
            pRange, /* item on the free list to be split */
            pOwnerName,
            addrType,
            base,
            size,
            ppPhysicalAddress);

    return s;
}

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

Release a bus address range previously registered.

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.

Definition at line 467 of file devLibVME.c.

{
    rangeItem *pRange;
    int s;

    if (!devLibInitFlag) {
        s = devLibInit();
        if(s) {
            return s;
        }
    }

    s = addrVerify (addrType, baseAddress, 1);
    if (s != SUCCESS) {
        return s;
    }

    epicsMutexMustLock(addrListLock);
    pRange = (rangeItem *) ellFirst(&addrAlloc[addrType]);
    while (pRange) {
        if (pRange->begin == baseAddress) {
            break;
        }
        if (pRange->begin > baseAddress) {
            pRange = NULL;
            break;
        }
        pRange = (rangeItem *) ellNext(&pRange->node);
    }
    epicsMutexUnlock(addrListLock);

    if (!pRange) {
        return S_dev_addressNotFound;
    }

    if (strcmp(pOwnerName,pRange->pOwnerName)) {
        s = S_dev_addressOverlap;
        errPrintf (
            s,
            __FILE__,
            __LINE__,
    "unregister address for %s at 0X%X failed because %s owns it",
            pOwnerName,
            (unsigned int)baseAddress,
            pRange->pOwnerName);
        return s;
    }

    epicsMutexMustLock(addrListLock);
    ellDelete (&addrAlloc[addrType], &pRange->node);
    epicsMutexUnlock(addrListLock);

    pRange->pOwnerName = "<released fragment>";
    devInsertAddress (&addrFree[addrType], pRange);
    s = devCombineAdjacentBlocks (&addrFree[addrType], pRange);
    if(s){
        errMessage (s, "devCombineAdjacentBlocks error");
        return s;
    }

    return SUCCESS;
}

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

Probe the bus for writing to a specific address.

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.

Definition at line 288 of file devLibVME.c.

{
    long status;

    if (!devLibInitFlag) {
        status = devLibInit();
        if (status) {
            return status;
        }
    }

    return (*pdevLibVME->pDevWriteProbe) (wordSize, ptr, pValue);
}

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.

Definition at line 1107 of file devLibVME.c.

{
    return devNoResponseProbe (addrType, (size_t) pLocation, sizeof(long));
}

Variable Documentation

int devLibA24Debug = 0

Definition at line 1123 of file devLibVME.c.

const char* epicsAddressTypeName[]

Initial value:

= {
        "VME A16",
        "VME A24",
        "VME A32",
        "ISA",
        "VME CR/CSR"
    }

A string representation of each of the bus address types.

Definition at line 66 of file devLibVME.c.