Kick off

Basics

• Create an appropriate .inf file (for Windows) and a .plist (for OSX) matching the device or kernel node you want to create.
  Following skeleton creates everything needed for a fully working kernel driver node (including PNP and power event handling):

  #include "version.h"
  #include <dxd_device.h>
  #ifdef WIN32
  WDF_EXTERN_C::NTSTATUS DriverEntry(
      ::DRIVER_OBJECT* driver,
      ::UNICODE_STRING* registry){$
      return dxd::create<dxd::driver<>>(driver, registry, DX_GUID);
  }
  #endif //WIN32

  Add a version.h describing your product:

  #define DX_PRODUCT      MyProduct
  #define DX_PRODUCT_ID   com_mycompany_myproduct
  #define DX_PRODUCT_URID com.mycompany.myproduct

• Change the plist to match your device name defined in version.h. In the above case this would be the generic device defined by dxd (there is some macro magic going on in dx_macros.h defining the concatenated strings):

  [...]
  <key>IOKitPersonalities</key>
  <dict>
      <key>DX_PRODUCT</key>
      <dict>
          <key>IOClass</key>
          <string>com_mycompany_myproduct_device</string>
          <key>CFBundleIdentifier</key>
          <string>DX_PRODUCT_URID</string>
          <key>IOProviderClass</key>
          <string>IODevice</string>
          <key>IOUserClientClass</key>
          <string>DX_CLIENT</string>
      </dict>
  </dict>
  [...]

Selecting a specific device type

• Decide which device or bus types sweet your needs best.
  To simply add generic PCI device handling functionality change the above code fragment to:

  [...]
  WDF_EXTERN_C::NTSTATUS DriverEntry(
      ::DRIVER_OBJECT* driver,
      ::UNICODE_STRING* registry){$
      return dxd::create<dxd::driver<dxd::pci>>(driver, registry, DX_GUID);
  }
  [...]

  ... and change the plist to

  [...]
      <key>IOKitPersonalities</key>
      <dict>
          <key>DX_PRODUCT</key>
          <dict>
              [...]
              <key>IOClass</key>
              <string>com_mycompany_myproduct_pci</string>
              [...]
          </dict>
      </dict>
  [...]

Creating your own device

• To extended or change the generic USB device event handling add a derived device:

  [...]
  #ifdef __MACH__
  #define user_device DX_DEVICE
  #endif//__MACH__
  class user_device: public dxd::usb_stream_device{
      typedef dxd::usb_stream_device super;
      #ifdef __MACH__
      OSDeclareDefaultStructors(user_device);
      #endif//__MACH__
      dxd::os_result launch() override{
          // hello world!
          log(DX_STRINGIFY(DX_VENDOR)" "DX_STRINGIFY(DX_PRODUCT)" driver "DX_STRINGIFY(DX_VERSION)" "__DATE__" "__TIME__"\n");
          log(DX_STRINGIFY(DX_COPYRIGHT)"\n");
          // launch usb device
          dxd::os_result status= super::launch();
      catch:
          return status;
      }
   
      void conclude() override{
          // optionally overwrite to handle user device removal requests
          super::conclude();
      }
  public:
      dxd::os_result wake() override{
          // optionally overwrite to handle user device wake requests
          dxd::os_result status;
          try(status=super::wake());
      catch:
          return status;
      }
      dxd::os_result sleep() override{
          // optionally overwrite to handle user device sleep requests
          dxd::os_result status;
          try(status=super::sleep());
      catch:
          return status;
      }
      #ifdef WIN32
      user_device(::WDFDEVICE_INIT* wdf_device_init, const ::GUID& guid): super(wdf_device_init, guid){}
      #endif//WIN32
  };
  #ifdef __MACH__
  OSDefineMetaClassAndStructors(user_device, user_device::super);
  #endif//__MACH__

Adding a user client

• An applications connects to the driver through the means of an user client. To be able to handle application requests you need to add a user_client:

  #ifdef __MACH__
  #define user_client DX_CLIENT
  #endif//__MACH__
  class user_client: public dxd::client{
      typedef dxd::client super;
      #ifdef __MACH__
      OSDeclareDefaultStructors(user_client);
      virtual bool start(::IOService* provider){
          device= OSDynamicCast(user_device, provider);
          if(!super::start(provider))
              return false;
          return true;
      }
      #endif//__MACH__
      user_device* device;
   
      dxd::os_result launch() override{
          // optionally overwrite to handle user client creation
          return super::launch();
      }
   
      void dxd::os_result conclude() override{
          // optionally overwrite to handle user client disconnection
          super::conclude();
      }
   
      dxd::os_result ioctl(
          unsigned int ioctl, 
          const void* in,     
          size_t size_in,     
          void* out,          
          size_t size_out,    
          size_t& size        
          )override{
          // optionally overwrite to handle user client request from application
          dxd::os_result status;
          switch(ioctl){
                 - my_namespace::version
              case my_namespace::version:{
                  try(status= (!size_in && size_out==sizeof(unsigned int))? dxd::ok: dxd::invalid);
                  // write data & return size of written data
                   *reinterpret_cast<unsigned int*>(out)= DX_VERSION32;
                  size= sizeof(uint32_t);
                  trace("  my_namespace::version:" DX_STRINGIFY(DX_VERSION) "\n");
                  break;
              }
          }
      }
  public:
      #ifdef WIN32
      user_client(user_device*device): device(device){}
      #endif//WIN32
  };
  #ifdef __MACH__
  OSDefineMetaClassAndStructors(user_client,user_client::super);
  #endif//__MACH__
  #ifdef WIN32
  dxd::client*user_device::client_create(){return new user_client(this);};
  #endif//WIN32

  The plist containing the user client magic:

  [...]
      <key>IOKitPersonalities</key>
      <dict>
          <key>DX_PRODUCT</key>
          <dict>
              [...]
              <key>IOUserClientClass</key>
              <string>DX_CLIENT</string>
              [...]
          </dict>
      </dict>
  [...]