/** @page pciusage PCI Usage When working with a PCI device the first step is finding the identifiers used by the device. These will likely be included in the card vendor's documentation, but can be verified by observing the OS boot messages or with the devPCIShow() function. Including this identifying information in your code provides an important safe guard against user mis-configuration. This provides an easy way to prevent your code from trying to access the wrong type of device. PCI devices are uniquely identified by the triplet bus:device.function. While it is possible to automatically detect cards it is preferable to have a user defined mapping between physical id (b:d.f) and logical id (Asyn port, device ID, etc.). This allows for consistent naming even if cards are added or removed from the system. For EPICS drivers initialization will usually be done with an IOC shell function. For example: @code myPCICardSetup("dac", 2, 1, 0 ) @endcode Would set card "dac" to be function 0 of device 1 on bus 2. Since all PCI devices will be automatically configured by the system this is the only piece of information required to access the card. Below is an example implementation of myPCICardSetup(). @code static const epicsPCIID mydevids[] = {...} int myPCICardSetup(const char* port, int b, int d, int f) { volatile void* bar; epicsPCIDevice *dev; devpriv *priv; if( portExists(port) ) return 1; if (devPCIFindBDF(mydevids, b,d,f, &dev, 0)) return 2; @endcode The first step is to probe the PCI location to ensure that the card is present. If the location is empty or populated with an unsupported card then we will abort here. @code if (devPCIToLocalAddr(dev, 2, &bar, 0)) return 3; @endcode Next we get a pointer for bar #2. @code priv=calloc(1, sizeof(mydevpriv)); if (!priv) return 4; if (devPCIConnectInterrupt(dev, &myisr, priv)) return 5; @endcode Then connect the interrupt service routine. @code portCreate(port, priv); return 0; } @endcode And that is it. @section pciiotypes Note on PCI I/O Types The PCI bus has the notion of two different I/O address types: Memory Mapped, and Port. This distinction comes from the x86 processor for which these are two separate address spaces which must be accessed using different instructions (load/store vs. out/in). Each BAR must either be accessed using Memory Mapped I/O (MMIO), or Port I/O (PIO) operations. This can be determined by inspecting the 'ioport' member of the ::PCIBar structure. If the value is false (0) then @ref mmio "MMIO operations" should be used. If however, the value is true (1) then the pointer returned by devPCIToLocalAddr() needs to be treated as a PIO address. It should be cast to the appropriate type and access using OS defined PIO operations (ie inb/outb). */ /** @page vmeusage VME64 CSR Usage When working with a CSR/CR device the first step is to find the identifiers for the board. This should be included in vendor documentation, and can be verified by probing the appropriate VME slot at runtime. The library functions vmecsrdump(lvl) and vmecsrprint(slot,lvl) can be used for this. See the IOC shell section for detail on these functions. Including this identifying information in your code provides an important safe guard against user mis-configuration. This provides an easy way to prevent your code from trying to access the wrong type of device. To initialize you must know its slot number. While it is possible to automatically detect cards it is preferable to have a user defined mapping between physical id (slot#) and logical id (Asyn port, device ID, etc.). This allows for consistent naming even if cards are added or removed from the system. For EPICS drivers initialization will usually be done with an IOC shell function. For example: @code myVMECardSetup("dac", 5, 0x210000, 4, 0x60) @endcode Would set card "dac" to be the card in slot 5. This imaginary card is given an A24 base address of 0x210000, and set to generate interrupt vector 0x60 at level 4. Below is an example implementation of myVMECardSetup(). @code static const struct VMECSRID mydevids[] = {...} int myVMECardSetup(const char* port, int slot, unsigned long base, int level, int vector) { volatile void* csr, a24; devpriv *priv; if( portExists(port) ) return 1; csr=devCSRTestSlot(mydevids, slot, NULL); if (!csr) return 2; @endcode The first step is to probe the VME slot and get the CSR base address. If the slot were empty or populated with an unsupported card then we would abort here. @code #if card is VME64 CSRWrite24(csr + MYCSR_BAR_BASE, base); #elif card is VME64x CSRSetBase(csr, 0, base, VME_AM_STD_SUP_DATA); #endif @endcode Assuming the card supports full jumperless configuration then then base address will be programmed using the CSR space. While newer VME64x cards have standard base address registers for this, older VME64 cards do not. For these card the vendor should document the correct way to set the base address. @code if (devRegisterAddress("mydrv", atVMEA24, base, 0xff, &a24)) return 3; @endcode Once the A24 base address is set we map it into the process' address space with the standard devLib mapping call. @code priv=calloc(1, sizeof(mydevpriv)); if (!priv) return 4; if (devConnectInterruptVME(vector&0xff, &myisr, priv)) return 5; if (devEnableInterruptLevelVME(level&0x7)) return 6; @endcode Always attach the interrupt handler before enabling interrupts. @code CSRWrite8(csr + MYCSR_IRQ_LEVEL, level&0x7); CSRWrite8(csr + MYCSR_IRQ_VECTOR, vector&0xff); @endcode Neither VME64 or VME64x specifies standard registers for interrupt level or vector code. Vendor documention must specify how to set this. .Note ************************************************* This may not be done in the CSR space, but rather in another address space. ************************************************* @code portCreate(port, priv); return 0; } @endcode */