New upstream version 2.9

Makefile

@@ -5,6 +5,7 @@ DIRS := $(DIRS) $(filter-out $(DIRS), configure)
 DIRS := $(DIRS) $(filter-out $(DIRS), common)
 DIRS := $(DIRS) $(filter-out $(DIRS), pciApp)
 DIRS := $(DIRS) $(filter-out $(DIRS), vmeApp)
+DIRS := $(DIRS) $(filter-out $(DIRS), exploreApp)
 DIRS := $(DIRS) $(filter-out $(DIRS), testApp)
 
 # 3.14.10 style directory dependencies
@@ -20,6 +21,7 @@ iocBoot_DEPEND_DIRS += $(filter %App,$(DIRS))
 pciApp_DEPEND_DIRS += common
 vmeApp_DEPEND_DIRS += common
 testApp_DEPEND_DIRS += pciApp
+exploreApp_DEPEND_DIRS += pciApp
 
 include $(TOP)/configure/RULES_TOP
 

README.md

@@ -17,6 +17,6 @@ VCS sources
 git clone https://github.com/epics-modules/devlib2.git
 ```
 
-This is file is generated from git revision aaf8baff70421f0549ee86f070c26834668f2144
+This is file is generated from git revision bc6c46921f5ae3cf367dac5ab22b15c8c05ce1a2
 
 <a href="https://travis-ci.org/epics-modules/devlib2"><img src="https://travis-ci.org/epics-modules/devlib2.svg">CI Build Status</img></a>

documentation/Doxyfile

@@ -31,7 +31,7 @@ PROJECT_NAME           = devLib2
 # This could be handy for archiving the generated documentation or 
 # if some version control system is used.
 
-PROJECT_NUMBER         = 2.8
+PROJECT_NUMBER         = 2.9
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
 # base path where the generated documentation will be put. 

documentation/mainpage.h

@@ -50,6 +50,17 @@ even those which lack an implementation.
 
 @li @subpage pciusage
 
+@li @ref exploreapp
+
+@li @ref iocshpci
+
+@subsubsection explorepci Generic PCI driver
+
+The exploreApp @ref exploreapp 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).
+
 @subsection vmesec VME CSR
 
 The VME64x library provides several functions for accessing the CSR/CR
@@ -63,6 +74,8 @@ definitions of standard registers, and functions to access them.
 
 @li @ref vmecsrregs "CSR/CR Register Definitions"
 
+@li @ref iocshvme
+
 @subsection mmiosec MMIO
 
 The MMIO library provides an OS and CPU architecture independent way to
@@ -73,6 +86,16 @@ the width and order of accesses.
 
 @section changelog Changelog
 
+@subsection ver29 2.9 (July 2017)
+
+@li pci: change devPCIFindSpec() to parse B:D.F as hex.
+         This is an incompatible change!
+@li pci: Fixups for vxWorks 5 (Dirk Zimoch)
+@li pci: Add missing offset bounds check to PCI iocsh functions
+@li vme: Various fixes for VME iocsh functions
+@li explore: Add exploreApp toolkit for PCI driver/hardware development (@ref exploreapp)
+@li linux: Add pci_generic_msi.c UIO driver to support devices with single vector MSI
+
 @subsection ver28 2.8 (Sept. 2016)
 
 @li Fixes an bug with epicsMMIO.h for some targets where a single read
@@ -515,4 +538,122 @@ The kernel source tree contains several example drivers.
 
 */
 
+/** @page exploreapp PCI driver/hardware development tool
+
+@section exploreintro Purpose
+
+The exploreApp support is intended as a tool to explore new PCI devices.
+This may be useful when preparing to write a dedicated driver and/or
+during development of PCI/PCIe device firmware.
+exploreApp allows a PCI register to be read and/or written an EPICS record.
+For example:
+
+@code
+record(longout, "pcitestout") {
+  field(DTYP, "Explore Write32 LSB")
+  field(OUT , "@8:0.0 bar=0 offset=0xc")
+}
+@endcode
+
+The record @b pcitestout will be connected to the PCI device 8:0.0 (bus 8, device 0, function 0) with the first BAR.
+A single write of 4 bytes is made when the record is processed.
+
+The following can be added to some @b xyzApp/src/Makefile to include exploreApp.
+
+@code
+PROD_IOC += myioc
+DBD += myioc.dbd
+myioc_DBD += exploreSupport.dbd
+myioc_LIBS += explorepci epicspci
+@endcode
+
+@section exploreopts Options
+
+@b INP/OUT link strings may contain the following components
+
+@li "bar=#" (default: 0)
+@li "offset=#" in bytes (default: 0)
+@li "mask=#" bit mask (default: 0 aka. no mask)
+@li "shift=#" in bits (default: 0)
+@li "step=#" in bytes (default: read size.  eg Read32 defaults to step=4)
+@li "initread=1|0" bool (default: 1 for .OUT recordtypes, 0 otherwise)
+
+
+For record types: @b longout, @b bo, @b mbbo, @b mbboDirect, @b ao
+allowed @b DTYP are:
+
+@li Explore Write8
+@li Explore Write16 NAT
+@li Explore Write16 LSB
+@li Explore Write16 MSB
+@li Explore Write32 NAT
+@li Explore Write32 LSB
+@li Explore Write32 MSB
+
+For record types: @b longin, @b longout, @b bi, @b bo, @b mbbi, @b mbbo, @b mbbiDirect, @b mbboDirect, @b ai, @b ao
+
+@li Explore Read8
+@li Explore Read16 NAT
+@li Explore Read16 LSB
+@li Explore Read16 MSB
+@li Explore Read32 NAT
+@li Explore Read32 LSB
+@li Explore Read32 MSB
+
+The @b ao record type also accepts
+
+@li Explore WriteF32 LSB
+@li Explore WriteF32 MSB
+
+The @b ai record type also accepts
+
+@li Explore ReadF32 LSB
+@li Explore ReadF32 MSB
+
+The @b waveform record type accepts both integer Read and Write @b DTYP.
+The @b step= link option may be applied to change how the address counter is incremented.
+The default step size is the read size (eg. 4 for Read32).
+A step size of 0 will read the base address @b NELM times.
+
+@section exploreirq PCI Interrupt
+
+Limited support of PCI interrupts is available on Linux only.
+A @b longin record with DTYP="Explore IRQ Count" and SCAN="I/O Intr"
+will be processed each time an interrupt occurs.
+
+This requires that a UIO kernel module be installed.
+
+@section explorefrib FRIB Specific
+
+The DTYP="Explore FRIB Flash" support implements a FRIB specific protocol
+for accessing a SPI flash chip over PCI.
+The @b frib-flash.db file demonstrates use.
+
+*/
+
+/** @page iocsh IOC shell functions
+
+Several IOC shell functions are provided to access PCI and VME devices
+
+@section iocshpci IOCsh functions for PCI devices
+
+- devPCIShow() List PCI devices present
+- devLibPCIUse() Select PCI system access implementation
+- pcidiagset() Select device for read/write functions
+- pciwrite()
+- pciread()
+- pciconfread()
+
+To use, begin by calling pcidiagset() to select the device and BAR that subsequent
+read/write calls will operate on.
+
+@section iocshvme IOCsh functions for VME devices
+
+- vmeread()
+- vmewrite()
+- vmeirqattach()
+- vmeirq()
+
+*/
+
 #endif // MAINPAGE_H

exploreApp/Db/Makefile

@@ -0,0 +1,22 @@
+TOP=../..
+include $(TOP)/configure/CONFIG
+#----------------------------------------
+#  ADD MACRO DEFINITIONS AFTER THIS LINE
+
+#----------------------------------------------------
+#  Optimization of db files using dbst (DEFAULT: NO)
+#DB_OPT = YES
+
+#----------------------------------------------------
+# Create and install (or just install) into <top>/db
+# databases, templates, substitutions like this
+DB += frib-flash.db
+
+#----------------------------------------------------
+# If <anyname>.db template is not named <anyname>*.template add
+# <anyname>_template = <templatename>
+
+include $(TOP)/configure/RULES
+#----------------------------------------
+#  ADD RULES AFTER THIS LINE
+

exploreApp/Db/frib-flash.db

@@ -0,0 +1,35 @@
+record(waveform, "$(P)bitfile") {
+    field(DTYP, "Explore FRIB Flash")
+    field(INP , "@$(DEV) pci_offset=$(offset=0x2004) flash_offset=$(location=0) flash_size=$(size=16777216)")
+    field(FTVL, "UCHAR")
+    field(NELM, "$(NELM=4194304)")
+}
+
+record(mbbi, "$(P)sts") {
+    field(DTYP, "Explore FRIB Flash")
+    field(INP , "@$(DEV) pci_offset=$(offset=0x2004) flash_offset=$(location=0)")
+    field(SCAN, "I/O Intr")
+    field(PINI, "YES")
+    field(ZRVL, "0")
+    field(ONVL, "1")
+    field(TWVL, "2")
+    field(THVL, "3")
+    field(FRVL, "4")
+    field(FVVL, "5")
+    field(ZRST, "Idle")
+    field(ONST, "Erase")
+    field(TWST, "Program")
+    field(THST, "Verify")
+    field(FRST, "Success")
+    field(FVST, "Failure")
+    field(FVSV, "MAJOR")
+}
+
+# Write 1 to start sequence
+# Write 0 to abort sequence
+record(longout, "$(P)ctrl") {
+    field(DTYP, "Explore FRIB Flash")
+    field(OUT , "@$(DEV) pci_offset=$(offset=0x2004) flash_offset=$(location=0)")
+    # set TPRO to 2 or 3 to enable debugging prints
+    # field(TPRO, "2")
+}

exploreApp/Makefile

@@ -0,0 +1,8 @@
+TOP = ..
+include $(TOP)/configure/CONFIG
+DIRS := $(DIRS) $(filter-out $(DIRS), $(wildcard *src*))
+DIRS := $(DIRS) $(filter-out $(DIRS), $(wildcard *Src*))
+DIRS := $(DIRS) $(filter-out $(DIRS), $(wildcard *db*))
+DIRS := $(DIRS) $(filter-out $(DIRS), $(wildcard *Db*))
+include $(TOP)/configure/RULES_DIRS
+

exploreApp/README.md

@@ -0,0 +1,129 @@
+Record recipies for PCI "explorer" IOC
+======================================
+
+INP/OUT field values
+--------------------
+
+All records with DTYP="Explore ..." should begin the INP or OUT string
+in one of the following formats.
+
+* "@BB:DD.FF"
+* "@slot=#"
+
+Where "BB:DD.FF" is a PCI geographic address (bus, device, function),
+and "slot=SN" gives a PCI slot number (when OS support is present).
+
+A space seperated list of the following may follow.
+
+* "bar=#" (default: 0)
+* "offset=#" in bytes (default: 0)
+* "mask=#" bit mask (default: 0 aka. no mask)
+* "shift=#" in bits (default: 0)
+* "step=#" in bytes (default: read size.  eg Read32 defaults to step=4)
+* "initread=1|0" bool (default: 1 for .OUT recordtypes, 0 otherwise)
+
+```
+  field(INP , "@8:0.0 bar=1 offset=0x14")
+... or ...
+  field(OUT , "@8:0.0 bar=1 offset=0x14")
+```
+
+Selects device "8:0.0" BAR 1 starting with byte offset 0x14.
+
+Numbers prefixed with '0x' are hexidecimal.  Numbers w/o a prefix are decimal.
+
+Optional for all input/read records
+-----------------------------------
+
+```
+  field(PINI, "YES")
+```
+
+Read once on IOC startup
+
+```
+  field(SCAN, "1 second")
+```
+
+Read periodically, ever 1 second.  Other options are ".1 second", ".2 second",
+".5 second", "2 second", "5 second", and "10 second".
+
+
+Read a scalar value
+-------------------
+
+Reading a 32-bit register as an scalar integer in little endian byte order.
+Reads periodically at 1Hz.
+
+```
+record(longin, "pcitest0") {
+  field(DTYP, "Explore Read32 LSB")
+  field(INP , "@8:0.0 bar=0 offset=0")
+  field(SCAN, "1 second")
+}
+```
+
+Read an array of values
+-----------------------
+
+```
+record(waveform, "pcitest0_10") {
+  field(DTYP, "Explore Read32 LSB")
+  field(INP , "@8:0.0 bar=0 offset=8 step=4")
+  field(FTVL, "ULONG")
+  field(NELM, "16")
+  field(SCAN, "1 second")
+}
+```
+
+Makes 16 sequential reads of 4 bytes each.
+The first read is of address 8.
+
+The number of elements to read is determined by the NELM field.
+
+Write a scalar value
+--------------------
+
+```
+record(longout, "pcitestout") {
+  field(DTYP, "Explore Write32 LSB")
+  field(OUT , "@8:0.0 bar=0 offset=0xc")
+}
+```
+
+Make a single 4 byte write to address 0xc
+
+Bit-field access
+----------------
+
+A read-modify-write operation to address 0xc.
+
+```
+record(longout, "pcitestout") {
+  field(DTYP, "Explore Write32 LSB")
+  field(OUT , "@8:0.0 0 offset=0xc mask=0xff00 shift=8")
+}
+```
+
+Equivlant pseudo-code.
+
+```
+u32 newval = read()&~mask
+newval |= (VAL<<shift)&mask
+write(newval)
+```
+
+A masked read
+
+```
+record(longin, "pcitestin") {
+  field(DTYP, "Explore Read32 LSB")
+  field(OUT , "@8:0.0 0 offset=0xc mask=0xff00 shift=8")
+}
+```
+
+Equivlant pseudo-code.
+
+```
+VAL = (read()&mask)>>shift
+```