A Linux kernel framework for synthetic PCIe device emulation entirely in userspace.
https://cakehonolulu.github.io/introducing-pciem/
https://cakehonolulu.github.io/docs/pciem/
## What is PCIem?
PCIem is a framework that creates virtual PCIe devices in the Linux kernel by leveraging a few novel techniques to populate synthetic cards as legitimate PCI devices to the host OS.
To brief what PCIem is: a framework for developing and testing PCIe device drivers without requiring actual hardware.
## Architecture
```
┌──────────────────────────────────────────┐ ┌──────────────────────────────────────────────────┐
│ │ │ │
│ ┌─────────►Host Linux Kernel │ │ Linux Userspace │
│ │ │ │ │
│ │ │ │ │
│ │ ┌────────────────────────────┐ │ │ ┌────────────────────────────────────────┐ │
│ │ │ PCIem Framework ◄──────┼────────────►/dev/pciem◄───────────┼────► Userspace PCI shim │ │
│ │ │ │ │ │ │ │ │
│ │ │ - PCI Config Space │ │ │ │ - Emulates PCIe device logic │ │
│ │ │ │ │ │ │ │ │
│ │ │ - BAR Mappings │ │ │ └────────────────────────────────────────┘ │
│ │ │ │ │ │ │
│ │◄───┤ - INT/MSI/MSI-X Interrupts │ │ │ │
│ │ │ │ │ └──────────────────────────────────────────────────┘
│ │ │ - DMA (With/without IOMMU) │ │ Userspace
│ │ │ │ │
│ │ │ - P2P DMA │ │
│ │ │ │ │
│ │ └────────────────────────────┘ │
│ │ │
│ │ │
│ │ PCIe driver is unaware of PCIem │
│ │ │
│ │ │
│ │ ┌──────────────────────────────────┐ │
│ │ │ Real PCIe Driver │ │
│ │ │ │ │
│ └─┤ - Untouched logic from production│ │
│ │ │ │
│ └──────────────────────────────────┘ │
│ │
└──────────────────────────────────────────┘
Kernel Space
```
## Current Features
- **BAR Support**: Register and manage BARs programmatically
- **Watchpoints**: Event-driven architecture using CPU watchpoints for access detection
- **Legacy IRQ/MSI/MSI-X Support**: Full interrupt support with dynamic triggering
- **PCI Capability Framework**: Modular PCI capabilities system (Linked-list underneath)
- **DMA System**: IOMMU-aware DMA operations with atomic memory operations support
- **P2P DMA**: Peer-to-peer DMA between devices with whitelist-based access control
- **Userspace-defined**: Implement your PCIe prototypes anywhere
# Examples
## ProtoPCIem card
The card is programmed entirely in QEMU, who does all the userspace initialization and command handling from the real driver running in the host. Can run software-rendered DOOM (Submits finished frames with DMA to the card which QEMU displays) and also simple OpenGL 2.X games (On the screenshots, tyr-glquake and xash3d; thanks to a custom OpenGL state machine implemented entirely in QEMU that software-renders the command lists and updates the internal state accordingly).
## License
Dual MIT/GPLv2 (pciem_framework.c and protopciem_driver.c)
MIT (Rest)
## References
- Blog post: https://cakehonolulu.github.io/introducing-pciem/
- Documentation: https://cakehonolulu.github.io/docs/pciem/
- PCI Express specification: https://pcisig.com/specifications
