pcidb

package module
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 19, 2021 License: Apache-2.0, Apache-2.0 Imports: 11 Imported by: 0

README

pcidb - the Golang PCI DB library Build Status

pcidb is a small Golang library for programmatic querying of PCI vendor, product and class information.

We currently test pcidb on Linux, Windows and MacOSX.

Usage

pcidb contains a PCI database inspection and querying facility that allows developers to query for information about hardware device classes, vendor and product information.

The pcidb.New() function returns a pcidb.PCIDB struct or an error if the PCI database could not be loaded.

pcidb's default behaviour is to first search for pci-ids DB files on the local host system in well-known filesystem paths. If pcidb cannot find a pci-ids DB file on the local host system, it will then fetch a current pci-ids DB file from the network. You can disable this network-fetching behaviour with the pcidb.WithDisableNetworkFetch() function or set the PCIDB_DISABLE_NETWORK_FETCH to a non-0 value.

The pcidb.PCIDB struct contains a number of fields that may be queried for PCI information:

  • pcidb.PCIDB.Classes is a map, keyed by the PCI class ID (a hex-encoded string) of pointers to pcidb.Class structs, one for each class of PCI device known to pcidb
  • pcidb.PCIDB.Vendors is a map, keyed by the PCI vendor ID (a hex-encoded string) of pointers to pcidb.Vendor structs, one for each PCI vendor known to pcidb
  • pcidb.PCIDB.Products is a map, keyed by the PCI product ID* (a hex-encoded string) of pointers to pcidb.Product structs, one for each PCI product known to pcidb

NOTE: PCI products are often referred to by their "device ID". We use the term "product ID" in pcidb because it more accurately reflects what the identifier is for: a specific product line produced by the vendor.

Overriding the root mountpoint pcidb uses

The default root mountpoint that pcidb uses when looking for information about the host system is /. So, for example, when looking up known PCI IDS DB files on Linux, pcidb will attempt to discover a pciids DB file at /usr/share/misc/pci.ids. If you are calling pcidb from a system that has an alternate root mountpoint, you can either set the PCIDB_CHROOT environment variable to that alternate path, or call the pcidb.New() function with the pcidb.WithChroot() modifier.

For example, if you are executing from within an application container that has bind-mounted the root host filesystem to the mount point /host, you would set PCIDB_CHROOT to /host so that pcidb can find files like /usr/share/misc/pci.ids at /host/usr/share/misc/pci.ids.

Alternately, you can use the pcidb.WithChroot() function like so:

pci := pcidb.New(pcidb.WithChroot("/host"))
PCI device classes

Let's take a look at the PCI device class information and how to query the PCI database for class, subclass, and programming interface information.

Each pcidb.Class struct contains the following fields:

  • pcidb.Class.ID is the hex-encoded string identifier for the device class
  • pcidb.Class.Name is the common name/description of the class
  • pcidb.Class.Subclasses is an array of pointers to pcidb.Subclass structs, one for each subclass in the device class

Each pcidb.Subclass struct contains the following fields:

  • pcidb.Subclass.ID is the hex-encoded string identifier for the device subclass
  • pcidb.Subclass.Name is the common name/description of the subclass
  • pcidb.Subclass.ProgrammingInterfaces is an array of pointers to pcidb.ProgrammingInterface structs, one for each programming interface for the device subclass

Each pcidb.ProgrammingInterface struct contains the following fields:

  • pcidb.ProgrammingInterface.ID is the hex-encoded string identifier for the programming interface
  • pcidb.ProgrammingInterface.Name is the common name/description for the programming interface
package main

import (
    "fmt"

    "github.com/jaypipes/pcidb"
)

func main() {
    pci, err := pcidb.New()
    if err != nil {
        fmt.Printf("Error getting PCI info: %v", err)
    }

    for _, devClass := range pci.Classes {
        fmt.Printf(" Device class: %v ('%v')\n", devClass.Name, devClass.ID)
        for _, devSubclass := range devClass.Subclasses {
            fmt.Printf("    Device subclass: %v ('%v')\n", devSubclass.Name, devSubclass.ID)
            for _, progIface := range devSubclass.ProgrammingInterfaces {
                fmt.Printf("        Programming interface: %v ('%v')\n", progIface.Name, progIface.ID)
            }
        }
    }
}

Example output from my personal workstation, snipped for brevity:

...
 Device class: Serial bus controller ('0c')
    Device subclass: FireWire (IEEE 1394) ('00')
        Programming interface: Generic ('00')
        Programming interface: OHCI ('10')
    Device subclass: ACCESS Bus ('01')
    Device subclass: SSA ('02')
    Device subclass: USB controller ('03')
        Programming interface: UHCI ('00')
        Programming interface: OHCI ('10')
        Programming interface: EHCI ('20')
        Programming interface: XHCI ('30')
        Programming interface: Unspecified ('80')
        Programming interface: USB Device ('fe')
    Device subclass: Fibre Channel ('04')
    Device subclass: SMBus ('05')
    Device subclass: InfiniBand ('06')
    Device subclass: IPMI SMIC interface ('07')
    Device subclass: SERCOS interface ('08')
    Device subclass: CANBUS ('09')
...
PCI vendors and products

Let's take a look at the PCI vendor information and how to query the PCI database for vendor information and the products a vendor supplies.

Each pcidb.Vendor struct contains the following fields:

  • pcidb.Vendor.ID is the hex-encoded string identifier for the vendor
  • pcidb.Vendor.Name is the common name/description of the vendor
  • pcidb.Vendor.Products is an array of pointers to pcidb.Product structs, one for each product supplied by the vendor

Each pcidb.Product struct contains the following fields:

  • pcidb.Product.VendorID is the hex-encoded string identifier for the product's vendor
  • pcidb.Product.ID is the hex-encoded string identifier for the product
  • pcidb.Product.Name is the common name/description of the subclass
  • pcidb.Product.Subsystems is an array of pointers to pcidb.Product structs, one for each "subsystem" (sometimes called "sub-device" in PCI literature) for the product

NOTE: A subsystem product may have a different vendor than its "parent" PCI product. This is sometimes referred to as the "sub-vendor".

Here's some example code that demonstrates listing the PCI vendors with the most known products:

package main

import (
    "fmt"
    "sort"

    "github.com/jaypipes/pcidb"
)

type ByCountProducts []*pcidb.Vendor

func (v ByCountProducts) Len() int {
    return len(v)
}

func (v ByCountProducts) Swap(i, j int) {
    v[i], v[j] = v[j], v[i]
}

func (v ByCountProducts) Less(i, j int) bool {
    return len(v[i].Products) > len(v[j].Products)
}

func main() {
    pci, err := pcidb.New()
    if err != nil {
        fmt.Printf("Error getting PCI info: %v", err)
    }

    vendors := make([]*pcidb.Vendor, len(pci.Vendors))
    x := 0
    for _, vendor := range pci.Vendors {
        vendors[x] = vendor
        x++
    }

    sort.Sort(ByCountProducts(vendors))

    fmt.Println("Top 5 vendors by product")
    fmt.Println("====================================================")
    for _, vendor := range vendors[0:5] {
        fmt.Printf("%v ('%v') has %d products\n", vendor.Name, vendor.ID, len(vendor.Products))
    }
}

which yields (on my local workstation as of July 7th, 2018):

Top 5 vendors by product
====================================================
Intel Corporation ('8086') has 3389 products
NVIDIA Corporation ('10de') has 1358 products
Advanced Micro Devices, Inc. [AMD/ATI] ('1002') has 886 products
National Instruments ('1093') has 601 products
Chelsio Communications Inc ('1425') has 525 products

The following is an example of querying the PCI product and subsystem information to find the products which have the most number of subsystems that have a different vendor than the top-level product. In other words, the two products which have been re-sold or re-manufactured with the most number of different companies.

package main

import (
    "fmt"
    "sort"

    "github.com/jaypipes/pcidb"
)

type ByCountSeparateSubvendors []*pcidb.Product

func (v ByCountSeparateSubvendors) Len() int {
    return len(v)
}

func (v ByCountSeparateSubvendors) Swap(i, j int) {
    v[i], v[j] = v[j], v[i]
}

func (v ByCountSeparateSubvendors) Less(i, j int) bool {
    iVendor := v[i].VendorID
    iSetSubvendors := make(map[string]bool, 0)
    iNumDiffSubvendors := 0
    jVendor := v[j].VendorID
    jSetSubvendors := make(map[string]bool, 0)
    jNumDiffSubvendors := 0

    for _, sub := range v[i].Subsystems {
        if sub.VendorID != iVendor {
            iSetSubvendors[sub.VendorID] = true
        }
    }
    iNumDiffSubvendors = len(iSetSubvendors)

    for _, sub := range v[j].Subsystems {
        if sub.VendorID != jVendor {
            jSetSubvendors[sub.VendorID] = true
        }
    }
    jNumDiffSubvendors = len(jSetSubvendors)

    return iNumDiffSubvendors > jNumDiffSubvendors
}

func main() {
    pci, err := pcidb.New()
    if err != nil {
        fmt.Printf("Error getting PCI info: %v", err)
    }

    products := make([]*pcidb.Product, len(pci.Products))
    x := 0
    for _, product := range pci.Products {
        products[x] = product
        x++
    }

    sort.Sort(ByCountSeparateSubvendors(products))

    fmt.Println("Top 2 products by # different subvendors")
    fmt.Println("====================================================")
    for _, product := range products[0:2] {
        vendorID := product.VendorID
        vendor := pci.Vendors[vendorID]
        setSubvendors := make(map[string]bool, 0)

        for _, sub := range product.Subsystems {
            if sub.VendorID != vendorID {
                setSubvendors[sub.VendorID] = true
            }
        }
        fmt.Printf("%v ('%v') from %v\n", product.Name, product.ID, vendor.Name)
        fmt.Printf(" -> %d subsystems under the following different vendors:\n", len(setSubvendors))
        for subvendorID, _ := range setSubvendors {
            subvendor, exists := pci.Vendors[subvendorID]
            subvendorName := "Unknown subvendor"
            if exists {
                subvendorName = subvendor.Name
            }
            fmt.Printf("      - %v ('%v')\n", subvendorName, subvendorID)
        }
    }
}

which yields (on my local workstation as of July 7th, 2018):

Top 2 products by # different subvendors
====================================================
RTL-8100/8101L/8139 PCI Fast Ethernet Adapter ('8139') from Realtek Semiconductor Co., Ltd.
 -> 34 subsystems under the following different vendors:
      - OVISLINK Corp. ('149c')
      - EPoX Computer Co., Ltd. ('1695')
      - Red Hat, Inc ('1af4')
      - Mitac ('1071')
      - Netgear ('1385')
      - Micro-Star International Co., Ltd. [MSI] ('1462')
      - Hangzhou Silan Microelectronics Co., Ltd. ('1904')
      - Compex ('11f6')
      - Edimax Computer Co. ('1432')
      - KYE Systems Corporation ('1489')
      - ZyXEL Communications Corporation ('187e')
      - Acer Incorporated [ALI] ('1025')
      - Matsushita Electric Industrial Co., Ltd. ('10f7')
      - Ruby Tech Corp. ('146c')
      - Belkin ('1799')
      - Allied Telesis ('1259')
      - Unex Technology Corp. ('1429')
      - CIS Technology Inc ('1436')
      - D-Link System Inc ('1186')
      - Ambicom Inc ('1395')
      - AOPEN Inc. ('a0a0')
      - TTTech Computertechnik AG (Wrong ID) ('0357')
      - Gigabyte Technology Co., Ltd ('1458')
      - Packard Bell B.V. ('1631')
      - Billionton Systems Inc ('14cb')
      - Kingston Technologies ('2646')
      - Accton Technology Corporation ('1113')
      - Samsung Electronics Co Ltd ('144d')
      - Biostar Microtech Int'l Corp ('1565')
      - U.S. Robotics ('16ec')
      - KTI ('8e2e')
      - Hewlett-Packard Company ('103c')
      - ASUSTeK Computer Inc. ('1043')
      - Surecom Technology ('10bd')
Bt878 Video Capture ('036e') from Brooktree Corporation
 -> 30 subsystems under the following different vendors:
      - iTuner ('aa00')
      - Nebula Electronics Ltd. ('0071')
      - DViCO Corporation ('18ac')
      - iTuner ('aa05')
      - iTuner ('aa0d')
      - LeadTek Research Inc. ('107d')
      - Avermedia Technologies Inc ('1461')
      - Chaintech Computer Co. Ltd ('270f')
      - iTuner ('aa07')
      - iTuner ('aa0a')
      - Microtune, Inc. ('1851')
      - iTuner ('aa01')
      - iTuner ('aa04')
      - iTuner ('aa06')
      - iTuner ('aa0f')
      - iTuner ('aa02')
      - iTuner ('aa0b')
      - Pinnacle Systems, Inc. (Wrong ID) ('bd11')
      - Rockwell International ('127a')
      - Askey Computer Corp. ('144f')
      - Twinhan Technology Co. Ltd ('1822')
      - Anritsu Corp. ('1852')
      - iTuner ('aa08')
      - Hauppauge computer works Inc. ('0070')
      - Pinnacle Systems Inc. ('11bd')
      - Conexant Systems, Inc. ('14f1')
      - iTuner ('aa09')
      - iTuner ('aa03')
      - iTuner ('aa0c')
      - iTuner ('aa0e')

Developers

Contributions to pcidb are welcomed! Fork the repo on GitHub and submit a pull request with your proposed changes. Or, feel free to log an issue for a feature request or bug report.

Running tests

You can run unit tests easily using the make test command, like so:

[jaypipes@uberbox pcidb]$ make test
go test github.com/jaypipes/pcidb
ok      github.com/jaypipes/pcidb    0.045s

Documentation

Index

Constants

View Source 
const (
	PCIIDS_URI = "https://pci-ids.ucw.cz/v2.2/pci.ids.gz"
)

Variables

View Source 
var (
	ERR_NO_DB = fmt.Errorf("No pci-ids DB files found (and network fetch disabled)")
)

Functions

This section is empty.

Types

type Class 

type Class struct {
	// hex-encoded PCI_ID for the device class
	ID string `json:"id"`
	// common string name for the class
	Name string `json:"name"`
	// any subclasses belonging to this class
	Subclasses []*Subclass `json:"subclasses"`
}

Class is the PCI class

type PCIDB 

type PCIDB struct {
	// hash of class ID -> class information
	Classes map[string]*Class `json:"classes"`
	// hash of vendor ID -> vendor information
	Vendors map[string]*Vendor `json:"vendors"`
	// hash of vendor ID + product/device ID -> product information
	Products map[string]*Product `json:"products"`
}

func New 

func New(opts ...*WithOption) (*PCIDB, error)

New returns a pointer to a PCIDB struct which contains information you can use to query PCI vendor, product and class information. It accepts zero or more pointers to WithOption structs. If you want to modify the behaviour of pcidb, use one of the option modifiers when calling New. For example, to change the root directory that pcidb uses when discovering pciids DB files, call New(WithChroot("/my/root/override"))

type Product 

type Product struct {
	// vendor ID for the product
	VendorID string `json:"vendor_id"`
	// hex-encoded PCI_ID for the product/model
	ID string `json:"id"`
	// common string name of the vendor
	Name string `json:"name"`
	// "subdevices" or "subsystems" for the product
	Subsystems []*Product `json:"subsystems"`
}

Product provides information about a PCI device model NOTE(jaypipes): In the hardware world, the PCI "device_id" is the identifier for the product/model

type ProgrammingInterface 

type ProgrammingInterface struct {
	// hex-encoded PCI_ID of the programming interface
	ID string `json:"id"`
	// common string name for the programming interface
	Name string `json:"name"`
}

ProgrammingInterface is the PCI programming interface for a class of PCI devices

type Subclass 

type Subclass struct {
	// hex-encoded PCI_ID for the device subclass
	ID string `json:"id"`
	// common string name for the subclass
	Name string `json:"name"`
	// any programming interfaces this subclass might have
	ProgrammingInterfaces []*ProgrammingInterface `json:"programming_interfaces"`
}

Subclass is a subdivision of a PCI class

type Vendor 

type Vendor struct {
	// hex-encoded PCI_ID for the vendor
	ID string `json:"id"`
	// common string name of the vendor
	Name string `json:"name"`
	// all top-level devices for the vendor
	Products []*Product `json:"products"`
}

Vendor provides information about a device vendor

type WithOption 

type WithOption struct {
	// Chroot is the directory that pcidb uses when attempting to discover
	// pciids DB files
	Chroot *string
	// CacheOnly is mostly just useful for testing. It essentially disables
	// looking for any non ~/.cache/pci.ids filepaths (which is useful when we
	// want to test the fetch-from-network code paths
	CacheOnly *bool
	// Disables the default behaviour of fetching a pci-ids from a known
	// location on the network if no local pci-ids DB files can be found.
	// Useful for secure environments or environments with no network
	// connectivity.
	DisableNetworkFetch *bool
	// DirectPath points to the absolute path of a pci.ids file in a non-standard
	// location.
	DirectPath *string
}

WithOption is used to represent optionally-configured settings

func WithCacheOnly 

func WithCacheOnly() *WithOption

func WithChroot 

func WithChroot(dir string) *WithOption

func WithDisableNetworkFetch 

func WithDisableNetworkFetch() *WithOption

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.