Linux kernel framework for PCIe device emulation, in userspace
Recorded: Jan. 20, 2026, 10:03 a.m.
| Original | Summarized |
GitHub - cakehonolulu/pciem: A Linux framework to enable userspace-defined "Virtual" PCIe card shims to enable in-host PCIe card driver development. Skip to content Navigation Menu Toggle navigation
Sign in
Appearance settings PlatformAI CODE CREATIONGitHub CopilotWrite better code with AIGitHub SparkBuild and deploy intelligent appsGitHub ModelsManage and compare promptsMCP RegistryNewIntegrate external toolsDEVELOPER WORKFLOWSActionsAutomate any workflowCodespacesInstant dev environmentsIssuesPlan and track workCode ReviewManage code changesAPPLICATION SECURITYGitHub Advanced SecurityFind and fix vulnerabilitiesCode securitySecure your code as you buildSecret protectionStop leaks before they startEXPLOREWhy GitHubDocumentationBlogChangelogMarketplaceView all featuresSolutionsBY COMPANY SIZEEnterprisesSmall and medium teamsStartupsNonprofitsBY USE CASEApp ModernizationDevSecOpsDevOpsCI/CDView all use casesBY INDUSTRYHealthcareFinancial servicesManufacturingGovernmentView all industriesView all solutionsResourcesEXPLORE BY TOPICAISoftware DevelopmentDevOpsSecurityView all topicsEXPLORE BY TYPECustomer storiesEvents & webinarsEbooks & reportsBusiness insightsGitHub SkillsSUPPORT & SERVICESDocumentationCustomer supportCommunity forumTrust centerPartnersOpen SourceCOMMUNITYGitHub SponsorsFund open source developersPROGRAMSSecurity LabMaintainer CommunityAcceleratorArchive ProgramREPOSITORIESTopicsTrendingCollectionsEnterpriseENTERPRISE SOLUTIONSEnterprise platformAI-powered developer platformAVAILABLE ADD-ONSGitHub Advanced SecurityEnterprise-grade security featuresCopilot for BusinessEnterprise-grade AI featuresPremium SupportEnterprise-grade 24/7 supportPricing Search or jump to... Search code, repositories, users, issues, pull requests...
Search Clear
Search syntax tips Provide feedback Include my email address so I can be contacted Cancel Submit feedback Saved searches
Name Query To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up
Appearance settings Resetting focus You signed in with another tab or window. Reload to refresh your session. Dismiss alert cakehonolulu pciem Public
Notifications
Fork
Star A Linux framework to enable userspace-defined "Virtual" PCIe card shims to enable in-host PCIe card driver development. MIT license 39 1 Branches Tags Activity
Star
Notifications Code Issues Pull requests Actions Projects Security Uh oh! There was an error while loading. Please reload this page. Insights
Additional navigation options
Code Issues Pull requests Actions Projects Security Insights
cakehonolulu/pciem
mainBranchesTagsGo to fileCodeOpen more actions menuFolders and filesNameNameLast commit messageLast commit dateLatest commit History90 Commitsincludeinclude kernelkernel qemuqemu resourcesresources userspaceuserspace .gitignore.gitignore LICENSELICENSE MakefileMakefile README.mdREADME.md test_system.shtest_system.sh View all filesRepository files navigationREADMEMIT license A Linux kernel framework for synthetic PCIe device emulation entirely in userspace. https://cakehonolulu.github.io/introducing-pciem/ What is PCIem? Current Features BAR Support: Register and manage BARs programmatically Examples License Blog post: https://cakehonolulu.github.io/introducing-pciem/
About A Linux framework to enable userspace-defined "Virtual" PCIe card shims to enable in-host PCIe card driver development. Readme MIT license Uh oh! There was an error while loading. Please reload this page. Activity 39 0 1 Report repository Releases 2 Packages No packages published Uh oh! There was an error while loading. Please reload this page. Contributors cakehonolulu
00xc
joebue-oc
Languages C Other Footer © 2026 GitHub, Inc. Footer navigation Terms Privacy Security Status Community Docs Contact Manage cookies Do not share my personal information You can’t perform that action at this time. |
The PCIem framework represents a novel approach to PCIe device emulation within the Linux ecosystem, enabling developers to create and test virtualized PCIe devices without relying on physical hardware. Developed by the project maintainer "cakehonolulu," this open-source initiative leverages a combination of kernel-level and userspace techniques to simulate PCIe cards, allowing for the development and debugging of device drivers in a controlled environment. The framework is designed to bridge the gap between hardware-dependent driver development and software-based testing, offering a scalable solution for scenarios where physical PCIe devices are unavailable or impractical. By abstracting the complexities of real hardware, PCIem facilitates experimentation with PCIe protocols, memory management, and interrupt handling in a highly customizable manner. Its architecture is structured to integrate seamlessly with the Linux kernel while maintaining flexibility for userspace implementations, making it a valuable tool for both academic research and industrial development. At its core, PCIem functions as a Linux kernel framework that mimics the behavior of physical PCIe devices through synthetic constructs. This is achieved by populating synthetic PCI configurations and managing memory-mapped I/O (MMIO) regions, which are typically associated with real hardware. The framework's design allows users to define custom "shims" in userspace, effectively creating virtual PCIe cards that appear as legitimate devices to the host operating system. These shims interact with the Linux kernel through a dedicated interface, such as `/dev/pciem`, which serves as a communication channel between the kernel and userspace components. The key innovation lies in its ability to replicate critical PCIe functionalities, including memory bar (BAR) management, interrupt handling (legacy IRQ, MSI, and MSI-X), direct memory access (DMA), and peer-to-peer DMA (P2P DMA) operations, all while operating entirely within the userspace. This decoupling of driver logic from physical hardware enables developers to focus on the software aspects of PCIe communication without being constrained by the limitations of actual devices. A critical component of PCIem's architecture is its support for BARs, which are memory-mapped regions that allow devices to access system memory. The framework provides mechanisms for registering and managing these BARs programmatically, giving developers granular control over memory allocation and address mapping. This feature is particularly useful for emulating devices with complex memory requirements, as it allows users to simulate the behavior of real hardware in a reproducible manner. Additionally, PCIem incorporates watchpoints—event-driven mechanisms that monitor memory accesses and trigger specific actions when predefined conditions are met. These watchpoints are implemented using CPU-level features, enabling the framework to detect and respond to read/write operations on memory-mapped registers. This capability is essential for debugging and testing driver logic, as it allows developers to track how their code interacts with the virtualized hardware. Interrupt handling is another cornerstone of PCIem's functionality, as it supports a wide range of interrupt types commonly found in PCIe devices. The framework enables dynamic triggering of interrupts, which is crucial for simulating real-world scenarios where device activity generates asynchronous events. This includes legacy interrupt requests (IRQs), message-signaled interrupts (MSIs), and their extended variants (MSI-X). By emulating these interrupt mechanisms, PCIem allows developers to test the reliability and performance of their drivers under various conditions, ensuring compatibility with different PCIe configurations. Moreover, the framework includes a PCI capability framework that provides a modular system for managing device-specific capabilities, such as power management and error reporting. This capability is implemented using a linked-list structure, which allows for the dynamic addition of capabilities without requiring changes to the core framework. This modularity is particularly beneficial for simulating advanced PCIe features that are not commonly found in basic hardware. The DMA system within PCIem is another significant aspect of its design, as it enables direct memory access between the virtualized device and the host system. The framework supports both IOMMU-aware DMA operations and atomic memory transactions, ensuring that users can simulate the behavior of devices that interact with system memory in a secure and efficient manner. This is especially important for testing drivers that require high-performance data transfers, as it allows developers to evaluate the performance and stability of their code under realistic conditions. Additionally, PCIem includes support for peer-to-peer DMA (P2P DMA), which allows devices to communicate directly with each other without involving the host CPU. This feature is implemented using a whitelist-based access control mechanism, ensuring that only authorized devices can initiate or respond to P2P DMA transactions. This level of control is critical for applications that require low-latency data transfers, such as high-speed networking or graphics processing. One of the most notable applications of PCIem is its integration with QEMU, a popular open-source emulator that allows users to run virtual machines and simulate hardware environments. The framework leverages QEMU's capabilities to implement userspace-defined PCIe prototypes, such as the "ProtoPCIem" card. In this scenario, QEMU acts as a userspace component that handles the initialization and command processing for the virtualized device, while the host system's PCIe driver interacts with it as if it were a real hardware card. This setup enables developers to test drivers for applications like software-rendered DOOM, where the game engine generates graphics data that is transmitted to the virtualized device via DMA. QEMU then renders these frames, effectively creating a complete simulation of a PCIe graphics card. Similarly, the framework can be used to emulate OpenGL 1.X applications by implementing a custom OpenGL state machine within QEMU, which software-renders command lists and updates the internal state of the virtualized device. These examples demonstrate PCIem's versatility in handling complex graphics and multimedia workloads, making it a valuable tool for developers working on specialized hardware drivers. The licensing model of PCIem is designed to accommodate both open-source and commercial use cases. The framework's core components, including the `pciem_framework.c` and `protopciem_driver.c` files, are released under a dual license of MIT and GPLv2. This allows developers to use the framework freely in both open-source projects and proprietary software, provided they comply with the terms of the licenses. Other parts of the repository are licensed under the MIT license, which further broadens its accessibility and encourages contributions from a wide range of developers. This licensing strategy ensures that the framework remains flexible and adaptable to different use cases, fostering a collaborative development environment. The documentation for PCIem is hosted on the project's website, providing detailed guides on installation, configuration, and usage. These resources are invaluable for developers who are new to the framework, as they offer step-by-step instructions and best practices for implementing virtual PCIe devices. The project's documentation also includes references to the PCI Express specification, which serves as the foundation for PCIe device emulation in PCIem. This ensures that the framework adheres to industry standards, making it a reliable tool for testing drivers against real-world hardware specifications. The blog post and documentation pages on the project's website provide additional insights into the framework's design principles, use cases, and future development plans. These resources are particularly useful for developers who want to understand the technical details of PCIe emulation and how PCIem can be integrated into their workflows. The project's GitHub repository also serves as a central hub for collaboration, with features such as issues and pull requests that allow users to report bugs, request new features, and contribute improvements. In terms of practical applications, PCIem is well-suited for scenarios where physical PCIe devices are either unavailable or prohibitively expensive. This includes academic research, embedded systems development, and the testing of custom hardware designs. By eliminating the need for actual hardware, the framework reduces development costs and accelerates the testing process, allowing developers to iterate quickly on their code. Additionally, PCIem can be used for training and education purposes, providing students with hands-on experience in PCIe driver development without requiring access to specialized equipment. The framework's modular design and extensive feature set make it a powerful tool for exploring the intricacies of PCIe communication, from low-level memory management to high-level application integration. The project's documentation emphasizes the importance of userspace-defined implementations, allowing developers to create custom PCIe prototypes in their preferred programming languages. This flexibility is a key advantage of PCIem, as it enables users to tailor their virtualized devices to specific requirements. For example, developers can implement custom logic for handling PCI configuration spaces, BAR mappings, and interrupt events, all within the userspace environment. This level of control is particularly beneficial for testing edge cases or exploring non-standard PCIe configurations that may not be supported by existing hardware. The framework's ability to handle complex scenarios makes it a valuable tool for developers working on advanced applications, such as high-performance computing or real-time systems. In conclusion, the PCIem framework offers a comprehensive solution for PCIe device emulation in the Linux ecosystem, combining kernel-level and userspace techniques to create virtualized hardware environments. Its architecture supports a wide range of PCIe functionalities, including BAR management, interrupt handling, DMA operations, and P2P DMA communication, all while maintaining flexibility for userspace implementations. The framework's integration with QEMU and its support for custom PCIe prototypes demonstrate its versatility in handling complex applications, from gaming to graphics processing. With a licensing model that encourages open-source collaboration and detailed documentation for developers, PCIem is positioned as a valuable tool for both academic and industrial use. As the project continues to evolve, it has the potential to become an essential resource for developers working on PCIe driver development and hardware simulation. |