PCI bus support in Linux kernel

⚲ Most used API

🗝️ Acronyms:

• ACPI - Advanced Configuration and Power Interface
• ACS - Access Control Service
• AER - Advanced Error Reporting port service
• ASPM - Active State Power Management
• EDR - Error Disconnect Recover
• FLR - function level reset
• HT - Hypertransport
• BAR - Base Address Registers
• BW - Bandwidth
• DPC - Downstream Port Containment port service
• EP - Endpoint
• mmrbc - maximum memory read byte count
• mps - maximum payload size
• MWI - Memory-Write-Invalidate
• PM - Power Management
• PMC - ... ... Controller
• PME - ... ... Event, port service
• SR-IOV - Single-root input/output virtualization
• VF - virtual functions

⚲ User space API:

Querying information from a shell:

• man 8 lspci -vv
• column -t /proc/bus/pci/devices

• man 2 pciconfig_read, man 2 pciconfig_write, man 2 pciconfig_iobase - pci device information handling
• uapi/linux/pci.h _inc
• uapi/linux/pci_regs.h _inc

⚲ Kernel space API:

• linux/pci.h _inc
• pci_device_id _id - has vendor, device and class IDs. It is used for probing.
• pci_driver _id - the central struct
• module_pci_driver _id- helper macro to register pci_driver. It uses pci_register_driver _id and pci_unregister_driver _id.
• pci_dev _id - device descriptor
• pci_enable_device _id, pci_disable_device _id - must be called in probe and remove callbacks of pci_driver.
• pci_set_drvdata _id, pci_get_drvdata _id
• pci_name _id
• pci_set_master _id
• pcim_iomap_regions _id / pcim_iounmap_regions _id or pci_request_region _id, pci_request_regions _id/ pci_release_regions _id,
• pci_iomap _id, pci_iounmap _id
• pci_alloc_irq_vectors _id/ pci_free_irq_vectors _id, pci_request_irq _idor pci_irq_vector _id
• to_pci_dev _id
• pci_resource_flags _id, pci_resource_start _id, pci_resource_len _id
• pci_dev_put _id
• pci_read_config_dword _id, pci_write_config_dword _id
• pci_set_power_state _id

👁 Examples:

• PCI Linux Driver Template
• samples/v4l/v4l2-pci-skeleton.c _src
• pci _ltp

⚙️ Internals

linux/pci_ids.h _inc
drivers/pci _src
pci_ops _id

📚 Mainline documents with summary

PCI driver API _doc

PCI Support Library

PCI Support Library _doc

pci_bus_max_busnr _doc, pci_status_get_and_clear_errors _doc, pci_find_capability _doc, pci_bus_find_capability _doc, pci_find_next_ext_capability _doc, pci_find_ext_capability _doc, pci_get_dsn _doc, pci_find_next_ht_capability _doc, pci_find_ht_capability _doc, pci_find_parent_resource _doc, pci_find_resource _doc, pci_platform_power_transition _doc, pci_set_power_state _doc, pci_choose_state _doc, pci_save_state _doc, pci_restore_state _doc, pci_store_saved_state _doc, pci_load_saved_state _doc, pci_load_and_free_saved_state _doc, pci_reenable_device _doc, pci_enable_device_io _doc, pci_enable_device_mem _doc, pci_enable_device _doc, pcim_enable_device _doc, pcim_pin_device _doc, pci_disable_device _doc, pci_set_pcie_reset_state _doc, pci_pme_capable _doc, pci_pme_active _doc, pci_enable_wake _doc, pci_wake_from_d3 _doc, pci_prepare_to_sleep _doc, pci_back_from_sleep _doc, pci_dev_run_wake _doc, pci_d3cold_enable _doc, pci_d3cold_disable _doc, pci_enable_atomic_ops_to_root _doc, pci_common_swizzle _doc, pci_release_region _doc, pci_request_region _doc, pci_release_selected_regions _doc, pci_request_selected_regions _doc, pci_release_regions _doc, pci_request_regions _doc, pci_request_regions_exclusive _doc, pci_remap_iospace _doc, pci_unmap_iospace _doc, devm_pci_remap_iospace _doc, devm_pci_remap_cfgspace _doc, devm_pci_remap_cfg_resource _doc, pci_set_master _doc, pci_clear_master _doc, pci_set_cacheline_size _doc, pci_set_mwi _doc, pcim_set_mwi _doc, pci_try_set_mwi _doc, pci_clear_mwi _doc, pci_intx _doc, pci_check_and_mask_intx _doc, pci_check_and_unmask_intx _doc, pci_wait_for_pending_transaction _doc, pcie_has_flr _doc, pcie_flr _doc, pci_bridge_secondary_bus_reset _doc, __pci_reset_function_locked _doc, pci_reset_function _doc, pci_reset_function_locked _doc, pci_try_reset_function _doc, pci_probe_reset_slot _doc, pci_probe_reset_bus _doc, pci_reset_bus _doc, pcix_get_max_mmrbc _doc, pcix_get_mmrbc _doc, pcix_set_mmrbc _doc, pcie_get_readrq _doc, pcie_set_readrq _doc, pcie_get_mps _doc, pcie_set_mps _doc, pcie_bandwidth_available _doc, pcie_get_speed_cap _doc, pcie_get_width_cap _doc, pcie_print_link_status _doc, pci_select_bars _doc, pci_add_dynid _doc, pci_match_id _doc, __pci_register_driver _doc, pci_unregister_driver _doc, pci_dev_driver _doc, pci_dev_get _doc, pci_dev_put _doc, pci_stop_and_remove_bus_device _doc, pci_find_bus _doc, pci_find_next_bus _doc, pci_get_slot _doc, pci_get_domain_bus_and_slot _doc, pci_get_subsys _doc, pci_get_device _doc, pci_get_class _doc, pci_dev_present _doc, pci_msi_mask_irq _doc, pci_msi_unmask_irq _doc, pci_msi_vec_count _doc, pci_msix_vec_count _doc, pci_msi_enabled _doc, pci_enable_msix_range _doc, pci_alloc_irq_vectors_affinity _doc, pci_free_irq_vectors _doc, pci_irq_vector _doc, pci_irq_get_affinity _doc, pci_msi_create_irq_domain _doc, pci_bus_alloc_resource _doc, pci_bus_add_device _doc, pci_bus_add_devices _doc, pci_bus_set_ops _doc, pci_cfg_access_lock _doc, pci_cfg_access_trylock _doc, pci_cfg_access_unlock _doc, pci_request_irq _doc, pci_free_irq _doc, pcie_relaxed_ordering_enabled _doc, pci_scan_slot _doc, pci_scan_child_bus _doc, pci_rescan_bus _doc, pci_create_slot _doc, pci_destroy_slot _doc, pci_hp_create_module_link _doc, pci_hp_remove_module_link _doc, pci_enable_rom _doc, pci_disable_rom _doc, pci_map_rom _doc, pci_unmap_rom _doc, pci_enable_sriov _doc, pci_disable_sriov _doc, pci_num_vf _doc, pci_vfs_assigned _doc, pci_sriov_set_totalvfs _doc, pci_sriov_get_totalvfs _doc, pci_sriov_configure_simple _doc, pci_read_legacy_io _doc, pci_write_legacy_io _doc, pci_mmap_legacy_mem _doc, pci_mmap_legacy_io _doc, pci_adjust_legacy_attr _doc, pci_create_legacy_files _doc, pci_mmap_resource _doc, pci_remove_resource_files _doc, pci_create_resource_files _doc, pci_write_rom _doc, pci_read_rom _doc, pci_remove_sysfs_dev_files _doc,

PCI Hotplug Support Library _doc

__pci_hp_register _doc, __pci_hp_initialize _doc, pci_hp_add _doc, pci_hp_deregister _doc, pci_hp_del _doc, pci_hp_destroy _doc,

PCI Peer-to-Peer DMA Support

PCI Peer-to-Peer DMA Support _doc

ient-drivers _doc, pci_p2pdma_add_resource _doc, device _doc, pci_p2pdma_distance_many _doc, pci_has_p2pmem _doc, device _doc, pci_p2pmem_find_many _doc, pci_alloc_p2pmem _doc, pci_free_p2pmem _doc, pci_p2pmem_virt_to_bus _doc, pci_p2pmem_alloc_sgl _doc, pci_p2pmem_free_sgl _doc, pci_p2pmem_publish _doc, device _doc, pci_p2pdma_map_sg_attrs _doc, device _doc, pci_p2pdma_unmap_sg_attrs _doc, pci_p2pdma_enable_store _doc, pci_p2pdma_enable_show _doc,

📚 PCI subsystem docs

PCI subsystem _doc, newer on the top:

Boot Interrupts reroute _doc

X86_REROUTE_FOR_BROKEN_BOOT_IRQS

Kernel parameters _docpci=ioapicreroute

EP - Endpoint Framework _doc

Querying information from shell:

find /sys/kernel/config/pci_ep/

EPC - EP Controller:

linux/pci-epc.h _inc pci_epc_create _id, devm_pci_epc_create _id

EPF - EP Function:

linux/pci-epf.h _inc pci_epf_create _id

Internals: drivers/pci/endpoint/ _src

Driver to test endpoint functionality: drivers/pci/endpoint/functions/pci-epf-test.c _src

PCIe virtualization, SR-IOV _doc, 2009

API: pci_enable_sriov _id, pci_disable_sriov _id, sriov_configure _id

MSI - Message Signaled Interrupts _doc, 2008

MSI Example:

vectors = pci_alloc_irq_vectors _id(pci_dev, 1, 1, PCI_IRQ_MSI | PCI_IRQ_MSIX);
irq = pci_irq_vector _id(pci_dev, 0);

AER - Advanced Error Reporting _doc, 2006

API: linux/aer.h _inc, pci_enable_pcie_error_reporting _id, pci_disable_pcie_error_reporting _id, pci_aer_clear_nonfatal_status _id

ERS - Error Recovery System _doc:

API: pci_error_handlers _id, pci_ers_result _id, pci_channel_state_t _id

PCIe - PCI Express Port Bus Driver _doc, 2004

API: pcie_port_service_driver _id,pcie_port_service_register _id, pcie_port_service_unregister _id

Old manual PCI API _doc

pci_get_device _id, pci_get_class _id, pci_get_subsys _id, pci_dev_put _id

💾 Historical:

• LDD3:PCI Drivers
• LDD3:PCI Drivers, pdf
• http://www.tldp.org/LDP/tlk/dd/pci.html

📚 References

• PCI Express
• Category:Peripheral Component Interconnect
• https://wiki.osdev.org/PCI
• https://lwn.net/Kernel/Index/#PCI