What is it?

devLib2 is an extension to the EPICS OS independent VME bus access library found in the EPICS Base. The MMIO API is included in EPICS Base >=3.15.0.2

Source

Releases can be found at https://github.com/epics-modules/devlib2/tags

VCS source browser https://github.com/epics-modules/devlib2

Or checked out with

git clone https://github.com/epics-modules/devlib2.git

The canonical version of this page is https://epics-modules.github.io/devlib2

Requires

EPICS Base >= 3.14.8.2

http://www.aps.anl.gov/epics/

Features

devLib2 adds features in several areas: PCI bus access, VME64x CSR/CSR, and memory mapped I/O (MMIO) operations.

PCI Bus

The PCI bus access interface is entirely new. It is currently implemented for RTEMS, vxWorks, and Linux (with some limitations). The PCI interface provides functions for: searching the bus, mapping devices into process memory, and (dis)connecting interrupts.

Runtime selection of implementations is also supported. This allows code using this interface to compile and link for all target, even those which lack an implementation.

API Documentation

PCI Usage

PCI driver/hardware development tool

IOCsh functions for PCI devices

Generic PCI driver

The exploreApp PCI driver/hardware development tool is a generic EPICS driver intended to support development of custom PCI/PCIe devices. It provides a set of records which read/write to individual registers. Basic support for interrupts is also available (Linux only).

VME CSR

The VME64x library provides several functions for accessing the CSR/CR address space defined by VME64 and extended by VME64x. This includes: probing by slot number and matching by identifier registers, definitions of standard registers, and functions to access them.

API Docmentation

VME64 CSR Usage

CSR/CR Register Definitions

IOCsh functions for VME devices

MMIO

The MMIO library provides an OS and CPU architecture independent way to safely access memory mapped I/O devices. Makes guarantees of the width and order of accesses.

API Docmentation

Changelog

2.12 (January 2024)

Fix missing include (shareLib.h)
Various fixes for Linux, and preparation for Windows support (Dirk Zimoch)
Fix redirection of iocsh functions

2.11 (Apr 2020)

Set SHRLIB_VERSION
Fix handling of PCI mmap() on Linux (Dirk Zimoch)

2.10 (Nov 2018)

Support Base 7.0.x
Publish module version to user makefiles
Minor bug fixes

2.9 (July 2017)

pci: change devPCIFindSpec() to parse B:D.F as hex. This is an incompatible change!
pci: Fixups for vxWorks 5 (Dirk Zimoch)
pci: Add missing offset bounds check to PCI iocsh functions
vme: Various fixes for VME iocsh functions
explore: Add exploreApp toolkit for PCI driver/hardware development (PCI driver/hardware development tool)
linux: Add pci_generic_msi.c UIO driver to support devices with single vector MSI

2.8 (Sept. 2016)

Fixes an bug with epicsMMIO.h for some targets where a single read macro expands to either 2 (16 bit) or 4 (32 bit) loads in situations where a byte swap is necessary. Effects all targets except RTEMS on powerpc to some degree. On Linux be_*() or le_*() are effected (depending on target byte order). On vxWorks nat_*() and le_* are effected on big endian targets, and le_*() on little endian targets.
pci: Bump API version to 1.3
pci: Add PCI ID match macro DEVPCI_DEVICE_ANY()
pci: Add member epicsPCIDevice::slot and macro DEVPCI_NO_SLOT
pci/linux: Look at /sys/bus/pci/slots/*/address to populate slot member.
pci: Add function devPCIFindSpec() to search by text string. Understands PCI bus address, slot number, and/or instance number
Add devPCIShowMatch() variant of devPCIShow() using devPCIFindSpec().

2.7 (Jan. 2016)

configure: optionally include $(TOP)/configure/RELEASE.local and $(TOP)/../RELEASE.local. $(EPICS_BASE) is no longer defined by default in configure/RELEASE and must be explicitly set in one of the possible RELEASE* files.
Fix compile failure on vxWorks (Eric Bjorklund)
Add missing extern "C" in epicsMMIO.h for vxWorks (Eric Bjorklund)
In epicsMMIODef.h replace 'inline' with 'static inline' for C compatibility.
RTEMS: handle BSPs with offset PCI addresses
pci/linux: devPCIDebug>1 enables more debug output when searching/matching PCI devices.
pci/linux: fix error preventing use of uio devices other than uio0.
vme: add vmewrite(), vmeirqattach(), and vmeirq() iocsh commands for debugging/development with VME devices.

2.6 (May 2015)

VCS repository moved to github.com
Increment API version to 1.2 (was 1.0)
epicsMMIO.h included in EPICS Base 3.15.1, not installed by this module.

Work by Andrew Johnson

Import support for vxWorks 5.5 on m68k and powerpc from EPICS Base.

Work by Till Straumann

Add PCI Config space access functions devPCIConfigRead##() and devPCIConfigWrite##()
Add devPCIEnableInterrupt() and devPCIDisableInterrupt().
- Linux: invoke the UIO irqcontrol callback function with a 1 or 0.
- vxWorks: call intEnable or intDisable (enabled by default). (Dirk Zimoch)

Work by Dirk Zimoch

Rework of the Linux PCI bus scan to support PCI domains. Previously domain 0 was used implicitly.
Rework of the vxWorks/RTEMS PCI bus scan to allow wildcards in device search. This allows devPCIShow for all PCI devices like in Linux.
Fixes for 64 bit BARs.
vxWorks: use BAR address directly if sysBusToLocalAdrs does not support PCI.
Changes in devPCIShow to get nicer output.

Work by Michael Davidsaver

Add the pciconfread() iocsh function.
devLibPCIRegisterDriver() is now a macro wrapping devLibPCIRegisterDriver2() which performs a consistency check on the size of the devLibPCI structure.
provide bswap16() and bswap32() for RTEMS PPC targets. Previously omitted.
Change name format of Linux user "ISR" thread to include PCI BDF.

2.5 (May 2014)

Linux: possible string corruption in vallocPrintf() Found by Till Straumann
vxWorks: lookup symbols including sysBusToLocalAdrs at runtime. Work by Eric and Dirk Zimoch
RTEMS: Select no-op MMIO implementation for m68k (no special handling required)

2.4 (Oct. 2012)

Remove C++ style comments from epicsMMIODef.h and devcsr.h
Fix Issue preventing Custom PCI bus implementation. (Found by Dan Eichel)
Linux "ISR" thread stack size not correct (Fixed by Till Straumann)
Linux: Previous versions expected Linux kernel modules to leave gaps for un-mappable PCI BARs (I/O Ports). However, most existing kernel modules don't do this. Add a flag to devPCIToLocalAddr() to specify how a device's kernel module does mapping. The default is to map as in previous versions. (New behavior by Till Straumann) See documentation of devPCIToLocalAddr().

2.3 (Apr. 2012)

Include proper headers to enable memory barriers for vxWorks >= 6.6
Fallback to noop when vxWorks memory barriers are not available
Fix incorrect return code when connecting pci interrupts on vxWorks

2.2 (Sept. 2011)

linux: follow changes to /sys (needed for kernel >2.6.26)
pci: IOC shell functions added: pciread()
pci: vxworks translate PCI addresses
Build on vxWorks 6.8 (Thanks to Andrew Johnson)
pci: Make operations reentrant on RTEMS and vxWorks (previously was not oops.)
pci: Fix bug with devPCIBarLen on RTEMS and vxWorks.

2.1 (Jan. 2011)

Fix build issue with 3.14.12 with RTEMS pc386 (found by Jim Chen from Hytec)
Add notification of missed PCI interrupt events on Linux
Additional arguement 'count' for vmeread() to show blocks of registers
Add section to PCI Usage on x86 Port I/O
Add section to PCI Access in Linux concerning hardware requirements

2.0 (Sept. 2010)

Initial release.

Author: Michael Davidsaver mdavi.nosp@m.dsav.nosp@m.er@gm.nosp@m.ail..nosp@m.com; Till Straumann strau.nosp@m.man@.nosp@m.slac..nosp@m.stan.nosp@m.ford..nosp@m.edu; Dirk Zimoch dirk..nosp@m.zimo.nosp@m.ch@ps.nosp@m.i.ch; Gabriel Fedel gabri.nosp@m.el.f.nosp@m.edel@.nosp@m.ess..nosp@m.eu