DriverKit driver: the plain C++ object its shell holds, making the devices the host asks for. More...

#include <dxd_platform_driver.h>

Inheritance diagram for dxd::platform::driver:

Collaboration diagram for dxd::platform::driver:

Classes
class	client
	an open of the driver itself: one per dxd_user_client of the type dx::ioctl::driver::client the driver's shell opens - the one way to create and destroy devices More...
struct	form
	a form's construction: it registers with the OS, then installs dispatch() More...

Public Member Functions
client*	client_create() override
	a client for an open of the driver itself: none where the platform gives the driver no access point of its own
	driver(::DRIVER_OBJECT* wdm_driver, ::UNICODE_STRING* registry, const dxd::guid& guid= 0)
	driver(::IOService* service)
virtual os_result	ioctl(unsigned int ioctl, const void* in, size_t size_in, void* out, size_t size_out, size_t& size)
	driver-wide control I/O: the version, and the log mask - the input sets it, the output reads it back
	operator const ::HANDLE() const
template<typename type_t>
os_result	query(const ::UNICODE_STRING& key, type_t& value)
template<typename key_t, typename type_t>
os_result	query(key_t* key, type_t& value)
os_result	remove()
os_result	set(const ::UNICODE_STRING& key, const ::GUID& value)
os_result	set(const ::UNICODE_STRING& key, const ::UNICODE_STRING& value, unsigned long type= REG_SZ)
os_result	set(const ::UNICODE_STRING& key, const char* value)
os_result	set(const ::UNICODE_STRING& key, const wchar_t* value)
os_result	set(const ::UNICODE_STRING& key, unsigned int value)
template<typename key_t, typename type_t>
os_result	set(key_t* key, const type_t& value)
device*	start(::IOService* shell, ::IOService* provider)
	a device's shell starts on its provider: the device of the pending request, or of the hardware the OS matched, launched
void	stop(::IOService* shell)
	a device's shell stops: it leaves the driver's devices
template<typename type_t>
unsigned long	type()
	~driver() override
	the devices go with their driver: a shell stopping after it concludes its device alone

Static Public Member Functions
static device*	hosted(::IOService* shell)
	the device a device shell hosts, the driver a driver shell hosts - the shells name no framework type, iig would take it for one of its own
static driver*	hosting(::IOService* shell)
static driver*	owned(::IOService* shell)
	the driver a device shell on hardware owns: this one, a product composing dxd::power defines its own

Public Attributes
const ::GUID	guid
	< the driver's, not the Parameters key's
dx::log	log{}
	log mask: every module at error until dx::ioctl::log sets it
bool	managed{}
	dxd::power binds the OS's power management to the devices' sleep() and wake()
::IOService*	service
	the driver's shell
os_result	status
uint32_t	version{DX_VERSION32}
	what dx::ioctl::version answers

Protected Member Functions
virtual device*	create(::DEVICE_OBJECT* wdm_device, ::DEVICE_OBJECT* wdm_pdo, ::DEVICE_OBJECT* wdm_bus)= 0
	device factory, on the OS's arrival of a device - the plain form's AddDevice, a form's own start
os_result	create(const void* request, size_t size)
os_result	destroy(const char* id)
void	dispatch(::DRIVER_OBJECT* wdm_driver)
	installs the clients' dispatch and the removal over what the form's registration wrote
	driver(::DRIVER_OBJECT* wdm_driver, ::UNICODE_STRING* registry, const dxd::guid& guid, form)
::IOService*	find(const char* id) const
	the shell hosting the device of the given id
virtual::NTSTATUS	forward(::DEVICE_OBJECT* wdm_device, ::IRP* irp)
	an IRP that is not a control client's: down the stack
virtual os_result	started(device &)
	a device started, in every form: what a driver binds per device (dxd::power) binds here

Static Protected Member Functions
::NTSTATUS	__cleanup(::DEVICE_OBJECT* wdm_device, ::IRP* irp)
	IRP_MJ_CLEANUP concludes the client, IRP_MJ_CLOSE deletes it and lets its device go.
::NTSTATUS	__close(::DEVICE_OBJECT* wdm_device, ::IRP* irp)
::NTSTATUS	__create(::DEVICE_OBJECT* wdm_device, ::IRP* irp)
	control opens carry no file name; a KS filter open carries its reference string
::NTSTATUS	__device_add(::DRIVER_OBJECT* wdm_driver, ::DEVICE_OBJECT* wdm_pdo)
	the plain form's arrival: an FDO on the PDO's stack and its device at once, which the resource filter and the start reach
::NTSTATUS	__forward(::DEVICE_OBJECT* wdm_device, ::IRP* irp)
::NTSTATUS	__ioctl(::DEVICE_OBJECT* wdm_device, ::IRP* irp)
	METHOD_BUFFERED: SystemBuffer carries input and output.
::NTSTATUS	__plain(::DEVICE_OBJECT* wdm_device, ::IRP* irp)
	the plain form's PnP around the forms' own (__pnp) The start launches the device with its resources once the bus started it. A stop - a rebalance - retires the device as its clients see a removal: unplugged(), conclude(), removed; a successor takes its place, which the next start launches on the new resources, and the retired one goes with its last client. The resource requirements pass the device's filter on their way up, the capabilities state a surprise removal expected, the device object goes behind the remove.
::NTSTATUS	__pnp(::DEVICE_OBJECT* wdm_device, ::IRP* irp)
static void	__unload(::DRIVER_OBJECT* wdm_driver)
::NTSTATUS	complete(::IRP* irp, os_result status, size_t information= 0)
static device *&	context(::DEVICE_OBJECT* wdm_device)
static driver&	context(::DRIVER_OBJECT* wdm_driver)
static device::client *&	context(::FILE_OBJECT* wdm_file)
static bool	ours(::FILE_OBJECT* wdm_file)
	a control open: no file name, the device it opened in FsContext2 - which a rebalance may have retired since

Protected Attributes
size_t	extension{}
	where a device's context sits in its device extension

Detailed Description

DriverKit driver: the plain C++ object its shell holds, making the devices the host asks for.

plain WDM driver: the driver object's dispatch of the control clients and of a device's removal

macOS has no software device API, so the host's dx::ioctl::driver::create and destroy reach the driver's own client: create() starts a device shell (dxd_device) on the driver's shell with IOService::Create, whose Start takes the request made at that moment (start()), destroy() terminates it. A dext whose devices the OS matches on their hardware has no driver shell: every device shell owns a driver of its own, which makes its device as it starts.

Its context hangs at the DRIVER_OBJECT, a device's at extension in the device extension - a driver form owning the extension's head (PortCls) states where. Control opens carry no file name: they get a client in FsContext and the device in FsContext2, which identifies them; every other IRP goes to forward() - down the stack here, into its own dispatch in a form owning one (PortCls). The plain form is the public constructor: it makes its devices on AddDevice and starts and filters them itself (__plain). A form constructs through form, registers with the OS and installs this dispatch after (dispatch()), since a registration like PcInitializeAdapterDriver writes the table itself.

Constructor & Destructor Documentation

◆ driver() [1/3]

dxd::platform::driver::driver(::IOService* service)

inline

Here is the caller graph for this function:

◆ ~driver()

dxd::platform::driver::~driver()

inlineoverridevirtual

the devices go with their driver: a shell stopping after it concludes its device alone

Reimplemented from dxd::driver.

◆ driver() [2/3]

dxd::platform::driver::driver(::DRIVER_OBJECT* wdm_driver, ::UNICODE_STRING* registry, const dxd::guid& guid, form)

inlineprotected

Here is the call graph for this function:

◆ driver() [3/3]

dxd::platform::driver::driver(::DRIVER_OBJECT* wdm_driver, ::UNICODE_STRING* registry, const dxd::guid& guid= 0)

inline

Parameters

wdm_driver	the driver's WDM driver object
registry	the driver's service key, whose Parameters it opens
guid	the product's GUID

Here is the call graph for this function:

Member Function Documentation

◆ __cleanup()

::NTSTATUS dxd::platform::driver::__cleanup(::DEVICE_OBJECT* wdm_device, ::IRP* irp)

inlinestaticprotected

IRP_MJ_CLEANUP concludes the client, IRP_MJ_CLOSE deletes it and lets its device go.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ __close()

::NTSTATUS dxd::platform::driver::__close(::DEVICE_OBJECT* wdm_device, ::IRP* irp)

inlinestaticprotected

Here is the call graph for this function:

Here is the caller graph for this function:

◆ __create()

::NTSTATUS dxd::platform::driver::__create(::DEVICE_OBJECT* wdm_device, ::IRP* irp)

inlinestaticprotected

control opens carry no file name; a KS filter open carries its reference string

Here is the call graph for this function:

Here is the caller graph for this function:

◆ __device_add()

::NTSTATUS dxd::platform::driver::__device_add(::DRIVER_OBJECT* wdm_driver, ::DEVICE_OBJECT* wdm_pdo)

inlinestaticprotected

the plain form's arrival: an FDO on the PDO's stack and its device at once, which the resource filter and the start reach

Here is the call graph for this function:

Here is the caller graph for this function:

◆ __forward()

::NTSTATUS dxd::platform::driver::__forward(::DEVICE_OBJECT* wdm_device, ::IRP* irp)

inlinestaticprotected

Here is the call graph for this function:

Here is the caller graph for this function:

◆ __ioctl()

::NTSTATUS dxd::platform::driver::__ioctl(::DEVICE_OBJECT* wdm_device, ::IRP* irp)

inlinestaticprotected

METHOD_BUFFERED: SystemBuffer carries input and output.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ __plain()

::NTSTATUS dxd::platform::driver::__plain(::DEVICE_OBJECT* wdm_device, ::IRP* irp)

inlinestaticprotected

the plain form's PnP around the forms' own (__pnp) The start launches the device with its resources once the bus started it. A stop - a rebalance - retires the device as its clients see a removal: unplugged(), conclude(), removed; a successor takes its place, which the next start launches on the new resources, and the retired one goes with its last client. The resource requirements pass the device's filter on their way up, the capabilities state a surprise removal expected, the device object goes behind the remove.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ __pnp()

::NTSTATUS dxd::platform::driver::__pnp(::DEVICE_OBJECT* wdm_device, ::IRP* irp)

inlinestaticprotected

the device outlives the stack's own remove handling: what tears down below may still reach it. The surprise removal comes with the clients' handles open, the remove after their close: unplugged() and conclude() each go ahead of their IRP, the destructor frees memory alone, with the device's last reference. A form's stop is refused: its device launches once (dxd::device); the plain form rebalances (__plain)

Here is the call graph for this function:

Here is the caller graph for this function:

◆ __unload()

void dxd::platform::driver::__unload(::DRIVER_OBJECT* wdm_driver)

inlinestaticprotected

Here is the call graph for this function:

Here is the caller graph for this function:

◆ client_create()

client* dxd::platform::driver::client_create()

inlineoverridevirtual

a client for an open of the driver itself: none where the platform gives the driver no access point of its own

Reimplemented from dxd::driver.

◆ complete()

::NTSTATUS dxd::platform::driver::complete(::IRP* irp, os_result status, size_t information= 0)

inlinestaticprotected

Here is the caller graph for this function:

◆ context() [1/3]

device *& dxd::platform::driver::context(::DEVICE_OBJECT* wdm_device)

inlinestaticprotected

Here is the call graph for this function:

Here is the caller graph for this function:

◆ context() [2/3]

driver& dxd::platform::driver::context(::DRIVER_OBJECT* wdm_driver)

inlinestaticprotected

Here is the call graph for this function:

◆ context() [3/3]

device::client *& dxd::platform::driver::context(::FILE_OBJECT* wdm_file)

inlinestaticprotected

◆ create() [1/2]

virtual device* dxd::platform::driver::create(::DEVICE_OBJECT* wdm_device, ::DEVICE_OBJECT* wdm_pdo, ::DEVICE_OBJECT* wdm_bus)

protectedpure virtual

device factory, on the OS's arrival of a device - the plain form's AddDevice, a form's own start

Implemented in dxd::portcls::adapter.

◆ create() [2/2]

os_result dxd::platform::driver::create(const void* request, size_t size)

inlineprotected

Here is the call graph for this function:

Here is the caller graph for this function:

◆ destroy()

os_result dxd::platform::driver::destroy(const char* id)

inlineprotected

Here is the call graph for this function:

◆ dispatch()

void dxd::platform::driver::dispatch(::DRIVER_OBJECT* wdm_driver)

inlineprotected

installs the clients' dispatch and the removal over what the form's registration wrote

Here is the call graph for this function:

Here is the caller graph for this function:

◆ find()

::IOService* dxd::platform::driver::find(const char* id) const

inlineprotected

the shell hosting the device of the given id

Here is the call graph for this function:

Here is the caller graph for this function:

◆ forward()

virtual::NTSTATUS dxd::platform::driver::forward(::DEVICE_OBJECT* wdm_device, ::IRP* irp)

inlineprotected

an IRP that is not a control client's: down the stack

Here is the call graph for this function:

◆ hosted()

dxd::platform::device* dxd::platform::driver::hosted(::IOService* shell)

static

the device a device shell hosts, the driver a driver shell hosts - the shells name no framework type, iig would take it for one of its own

Here is the call graph for this function:

Here is the caller graph for this function:

◆ hosting()

dxd::platform::driver* dxd::platform::driver::hosting(::IOService* shell)

static

Here is the call graph for this function:

◆ ioctl()

virtual os_result dxd::driver::ioctl(unsigned int ioctl, const void* in, size_t size_in, void* out, size_t size_out, size_t& size)

inlinevirtualinherited

driver-wide control I/O: the version, and the log mask - the input sets it, the output reads it back

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator const ::HANDLE()

dxd::wdm::registry::operator const ::HANDLE() const

inlineinherited

Here is the caller graph for this function:

◆ ours()

bool dxd::platform::driver::ours(::FILE_OBJECT* wdm_file)

inlinestaticprotected

a control open: no file name, the device it opened in FsContext2 - which a rebalance may have retired since

Here is the caller graph for this function:

◆ owned()

driver* dxd::platform::driver::owned(::IOService* shell)

static

the driver a device shell on hardware owns: this one, a product composing dxd::power defines its own

Here is the call graph for this function:

◆ query() [1/2]

template<typename type_t>

os_result dxd::wdm::registry::query(const ::UNICODE_STRING& key, type_t& value)

inlineinherited

◆ query() [2/2]

template<typename key_t, typename type_t>

os_result dxd::wdm::registry::query(key_t* key, type_t& value)

inlineinherited

Here is the call graph for this function:

Here is the caller graph for this function:

◆ remove()

os_result dxd::wdm::registry::remove()

inlineinherited

◆ set() [1/6]

os_result dxd::wdm::registry::set(const ::UNICODE_STRING& key, const ::GUID& value)

inlineinherited

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set() [2/6]

os_result dxd::wdm::registry::set(const ::UNICODE_STRING& key, const ::UNICODE_STRING& value, unsigned long type= REG_SZ)

inlineinherited

Here is the call graph for this function:

◆ set() [3/6]

os_result dxd::wdm::registry::set(const ::UNICODE_STRING& key, const char* value)

inlineinherited

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set() [4/6]

os_result dxd::wdm::registry::set(const ::UNICODE_STRING& key, const wchar_t* value)

inlineinherited

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set() [5/6]

os_result dxd::wdm::registry::set(const ::UNICODE_STRING& key, unsigned int value)

inlineinherited

Here is the caller graph for this function:

◆ set() [6/6]

template<typename key_t, typename type_t>

os_result dxd::wdm::registry::set(key_t* key, const type_t& value)

inlineinherited

Here is the call graph for this function:

Here is the caller graph for this function:

◆ start()

device* dxd::platform::driver::start(::IOService* shell, ::IOService* provider)

inline

a device's shell starts on its provider: the device of the pending request, or of the hardware the OS matched, launched

Here is the call graph for this function:

◆ started()

virtual os_result dxd::platform::driver::started(device&)

inlineprotectedvirtual

a device started, in every form: what a driver binds per device (dxd::power) binds here

Reimplemented in dxd::power< portcls::adapter >.

◆ stop()

void dxd::platform::driver::stop(::IOService* shell)

inline

a device's shell stops: it leaves the driver's devices

◆ type()

template<typename type_t>

unsigned long dxd::wdm::registry::type()

inherited

Here is the caller graph for this function:

Member Data Documentation

◆ extension

size_t dxd::platform::driver::extension{}

protected

where a device's context sits in its device extension

◆ guid

const ::GUID dxd::platform::driver::guid

< the driver's, not the Parameters key's

the product's: the control clients' device interface and property key //////////////////////////////////////////////////////////////////////////// the plain form: its devices made on AddDevice, every IRP the driver's, its PnP the plain one's

◆ log

dx::log dxd::driver::log{}

inherited

log mask: every module at error until dx::ioctl::log sets it

◆ managed

bool dxd::driver::managed{}

inherited

dxd::power binds the OS's power management to the devices' sleep() and wake()

◆ service

::IOService* dxd::platform::driver::service

the driver's shell

◆ status

os_result dxd::driver::status

◆ version

uint32_t dxd::driver::version{DX_VERSION32}

inherited

what dx::ioctl::version answers

The documentation for this class was generated from the following files:

Classes

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ driver() [1/3]

◆ ~driver()

◆ driver() [2/3]

◆ driver() [3/3]

Member Function Documentation

◆ __cleanup()

◆ __close()

◆ __create()

◆ __device_add()

◆ __forward()

◆ __ioctl()

◆ __plain()

◆ __pnp()

◆ __unload()

◆ client_create()

◆ complete()

◆ context() [1/3]

◆ context() [2/3]

◆ context() [3/3]

◆ create() [1/2]

◆ create() [2/2]

◆ destroy()

◆ dispatch()

◆ find()

◆ forward()

◆ hosted()

◆ hosting()

◆ ioctl()

◆ operator const ::HANDLE()

◆ ours()

◆ owned()

◆ query() [1/2]

◆ query() [2/2]

◆ remove()

◆ set() [1/6]

◆ set() [2/6]

◆ set() [3/6]

◆ set() [4/6]

◆ set() [5/6]

◆ set() [6/6]

◆ start()

◆ started()

◆ stop()

◆ type()

Member Data Documentation

◆ extension

◆ guid

◆ log

◆ managed

◆ service

◆ status

◆ version