dxd - dynax driver framework

The dynax driver framework is a header-only C++20 framework of driver and device class templates for kernel and user mode drivers and for the applications, plugins and services that talk to them. A product composes its drivers from these layers and supplies the values alone: its device description, its entry points, its version and its packaging.

The framework consists of two parts:

• the kernel side (kernel/), platform independent classes over a platform layer
  • WDK (kernel/wdk): WDM drivers - a PortCls audio adapter with WaveRT and DMus miniports (kernel/wdk/portclass), USB (raw URBs, isochronous streaming pipes) and PCI devices, IRP, work item, timer, WMI and registry wrappers; a KMDF device base (kernel/wdk/kmdf) for the PCI and FireWire devices deriving from it
  • DriverKit (kernel/driverkit): the macOS system extension platform, in progress
  • IOKit (kernel/iokit): the classic kernel extension, legacy - kexts can no longer be built or distributed, the tree is kept for reference
  • a streaming device with rings and clients the miniports drive, the proxy control interface user mode reaches through IOCTLs, the license check
• the user mode interface (interface/), platform independent templates over the platform wrappers of interface/windows and interface/macOS
  • the stream layer: device descriptions (dx::stream::desc), devices, pins, streaming groups with their realtime clock, the engine that mixes clients into a device's rings
  • bus devices: USB from user mode (WinUSB, IOKit), the kernel driver through its proxy, the virtual device, the CoreAudio and ASIO/WASAPI clients, the service client over shared memory
  • hosts: the CoreAudio server plugin and the CoreMIDI server plugin (macOS), the ASIO driver, the device tree hosting service and the Windows MIDI Services client (Windows)
  • a launchd daemon capturing class compliant USB devices from usbaudiod (macOS), the driver package installer (Windows)
  • notification, communication (named pipes, XPC, shared memory) and synchronisation classes
  • licensing: certificates of the product's root CA, bound to a device or a machine, checked by every device - kernel and user mode alike
• the test harness (dx_test*.h): a command line exerciser every product builds, one bus per option - unit tests over the driver and device life cycle, a streaming monitor, device information and configuration
• the packaging (etc/): the Windows installer (WiX merge module and .msi), the macOS package scripts, the release pipeline

Implementation design rules:

• light weight implementation, adding as less as possible overhead
• synergetic code usage
• enable the user to reduce the code only to tasks handling specific device features
• sparse as possible implementation code
• strictly uncompromised object orientated design
• separation of flow and error control
• typesafty avoiding unclassified pointers and casting wherever possible
• strict RAII (let only the compiler create the code of balanced initialization and deconstruction)
• destruction always succeeds: a destructor never throws an exception.
• all object parameters are reasonably checked (ofcourse pointer validity can not be ensured without overhead, so its only checked against null pointer.
• it is always valid to directly forward an dx/dxd object as a parameter to another dx/dxd object. Validity is ensured.

User space

• Object construction might fail with exception.

Kernel space

• Object construction might fail with object status. Always check object status!

The framework is shared across products: nothing product specific - no name, value, quirk or example - goes into it. Generic mechanics live here, a product supplies its values and its composition. CLAUDE.md in the repository's root carries the conventions in detail.

git repository

please request git read access by inquiring to dxd@d.nosp@m.ynax.nosp@m..at

• https://dynax.at/dxd.git
  • stable release at tags of main branch
  • unstable current develop branch
• a product embeds the framework as the submodule dxd/ beside its own tree and commits the pointer it builds against; a push to origin rebuilds this documentation

Speed

The framework is lightweight. It precisely executes only the needed kernel KPI. If drivers are slow than due to a bad design and its inherent workarounds. dxd provides the means to help with a clean design, with less pitfalls. dxd takes care about tedious and error prone KPI requirements and therefor avoids the implementation of slow workarounds due to KPI misinterpretation and OS bugs.

C++ in the Kernel???

The dynax driver framework uses a subset of C++ without real exception handling and RTTI runtime type information.
However dxd does provide some kind of exception handling semantics based on macros. This way you can get at least most of the error handling out of the way of the drivers program flow.
There is a rather religious discussion about C++ and kernel development. You can loose your time and join the discussion or just get your driver done - probably faster in C++, better structured and platform independent with the support of dxd.
dxd classes do provide a way around most kernel pitfalls. Its uncompromised object orientated design helps keeping your code safe, fast, small, nice and clean.
you may spent the extra spare time and do something useful.