IOService
The base class for most I/O Kit families, devices, and drivers.
Declaration
class IOService : IORegistryEntryOverview
IOService provides general utility functions that are useful across all families. It defines APIs used to publish services, instantiates other services based on the existence of a providing service such as driver stacking, destroys a service and its dependent stack, and notifies interested parties of service state changes.
This class uses a matching dictionary that contains service type properties to discover supported devices. For example, a matching dictionary may describe a IOUSBHostDevice (or subclass), an IOUSBHostDevice with a certain class code, or an IOPCIDevice with a set of matching names or device and vendor IDs. The list of properties considered for matching depends on the family that creates the dictionary.
Matching dictionaries are associated with IOService classes by the catalogue, as driver property tables, and also supplied by clients of the notification APIs.
IOService performs matching based on several criteria: the C++ class (using OSMetaClass dynamic casting), the registry entry name, a registry path to the service (which includes device tree paths), a name assigned by BSD, or location (point of attachment).
Instantiate Drivers
Drivers are subclasses of IOService, and the catalogue manages their availability. The system instantiates drivers based on the publication of an IOService they use (for example, an IOPCIDevice or IOUSBHostDevice), or when they are added to the catalogue and the I/O services they use are already available.
When registerService publishes the IOService, the matching and probing process begins. This is always single threaded per provider. The system constructs a list of matching dictionaries from the catalogue and installed publish notification requests that successfully match the service, along with ordering supplied by kIOProbeScoreKey in the dictionary, or supplied with the notification. Each entry in the list is then processed in order. For notifications, the notification is delivered. For driver property tables, a lot more happens.
The system instantiates the driver class and calls init() with its property table, attaches the new driver instance to the provider, and calls probe with the provider as an argument. The default probe method returns success — your driver should implement this method to interrogate the provider to make sure it can work with it. It may also modify its probe score at this time. After probing, the system detaches the driver and attaches the next one in the list for probing.
When the probing phase completes, the list consists of successfully probed drivers, in order of their probe score (after adjustments during the probe call). The system divides the list into categories based on the kIOMatchCategoryKey property. Drivers without a match category are considered in one default category. Match categories allow multiple clients of a provider to attach and start, though the provider may also enforce open/close semantics to gain active access to it.
For each category, the system attaches the highest scoring driver in that category to the provider, then calls start. If the method returns success, the system discards the rest of the drivers in the same match category; otherwise, it starts the next highest scoring driver.
The driver should only consider itself ready for work when the system calls its start method. This indicates that the driver is using the provider and consuming that match category. The driver should also be prepared for allocation, probing and freeing, even if the probe is successful.
After the drivers are synchronously started, the system delivers the installed “matched” notifications that match the registered service.
Match with Service Properties
Here are the service properties you can use when setting up the matching dictionary.
kIOClassKeyThe class of the driver to instantiate on matching providers.
kIOProviderClassKeyThe class of the provider(s) to be considered for matching, checked with OSDynamicCast so subclasses will also match.
kIOProbeScoreKeyThe probe score initially used to order multiple matching drivers.
kIOMatchCategoryKeyA string defining the driver category for matching purposes. All drivers without the kIOMatchCategoryKey property are considered to be in the same default category. Only one driver in a category can be started on each provider.
kIONameMatchKeyA string or collection of strings that match the provider’s name. The comparison is implemented with the compareNames method, which supports a single string, or any collection such as
OSArray, OSSet, or OSDictionary. of strings. IOService objects with device tree properties such as IOPCIDevice are matched based on that standard’s “compatible”, “name”, “device_type” properties. The matching name is left in the driver’s property table in the kIONameMatchedKey property.kIONameMatchedKeyThe successfully matched name from the kIONameMatchKey property is left in the driver’s property table as the kIONameMatchedKey property.
kIOPropertyMatchKeyA dictionary of properties that must exist in the matching IOService, and compare successfully with isEqualTo.
kIOUserClientClassKeyThe class name that the service will attempt to allocate when a user client connection is requested. The system queries the device nub first, then the nub’s provider.
kIOKitDebugKeyDebug flags for logging the driver loading process. Flags are defined in
IOKit/IOKitDebug.h.
Topics
Miscellaneous
acknowledgePowerChangeacknowledgeSetPowerStateactivityTickleaddLocationaddMatchingNotificationaddNotificationaddPowerChildadjustBusyattachcallPlatformFunctioncauseInterruptchangePowerStateTochangePowerStateToPrivclampPowerOnclosecommand_receivedcomparePropertiescompareProperty(OSDictionary *, const char *)compareProperty(OSDictionary *, const OSString *)configureReportcopyClientWithCategorycopyMatchingServicecurrentCapabilitycurrentPowerConsumptiondeRegisterInterestedDriverdetachdidTerminatedidYouWakeSystemdisableInterruptenableInterrupterrnoFromReturnfinalizefreegetAggressivenessgetBusyStategetClientgetClientIteratorgetDeviceMemorygetDeviceMemoryCountgetDeviceMemoryWithIndexgetInterruptTypegetMatchingServicesgetOpenClientIteratorgetOpenProviderIteratorgetPlatformgetPMRootDomaingetPMworkloopgetPowerStategetProvidergetProviderIteratorgetResourcesgetResourceServicegetServiceRootgetStategetWorkLoophandleClosehandleIsOpenhandleOpeninitialPowerStateForDomainStateisInactiveisOpenjoinPMtreelockForArbitrationmakeUsablemapDeviceMemoryWithIndexmatchLocationmatchPropertyTablemaxCapabilityForDomainStatemessagemessageClientmessageClientsnameMatching(const char *, OSDictionary *)nameMatching(const OSString *, OSDictionary *)newTemperaturenewUserClientnextIdleTimeoutopenPM_Clamp_Timer_ExpiredPM_idle_timer_expirationPMinitPMstoppowerChangeDonepowerOverrideOffPrivpowerOverrideOnPrivpowerStateDidChangeTopowerStateForDomainStatepowerStateWillChangeToprobepropertyMatchingpublishResource(const char *, OSObject *)publishResource(const OSSymbol *, OSObject *)registerInterestedDriverregisterInterruptregisterPowerDriverregisterServiceregistryEntryIDMatchingremovePowerChildrequestPowerDomainStaterequestProberequestTerminateresourceMatching(const char *, OSDictionary *)resourceMatching(const OSString *, OSDictionary *)serviceMatching(const char *, OSDictionary *)serviceMatching(const OSString *, OSDictionary *)setAggressivenesssetDeviceMemorysetIdleTimerPeriodsetPowerParentsetPowerStatestartstart_PM_idle_timerstopstringFromReturnsystemWakesystemWillShutdowntemperatureCriticalForZonetemporaryPowerClampOnterminateterminateClientunlockForArbitrationunregisterInterruptupdateReportwaitForMatchingServicewaitForServicewaitQuietwillTerminateyouAreRoot
DataTypes
Instance Variables
Instance Methods
AdjustBusyAdjustBusy_ImplChangePowerStateChangePowerState_ImplClientCrashedClientCrashed_ImplConfigureReportConfigureReport_ImplCopyDispatchQueue_ImplCopyNameCopyName_ImplCopyPropertiesCopyProperties_ImplCopyProviderPropertiesCopyProviderProperties_ImplCopySystemStateNotificationServiceCopySystemStateNotificationService_ImplCoreAnalyticsSendEventCoreAnalyticsSendEvent_ImplCreateCreateDefaultDispatchQueueCreateDefaultDispatchQueue_ImplCreate_ImplDispatchGetBusyStateGetBusyState_ImplGetProviderGetRegistryEntryIDGetRegistryEntryID_ImplJoinPMTreeJoinPMTree_ImplNewUserClientNewUserClient_ImplPMinitPMstopRegisterServiceRegisterService_ImplRemovePropertyRemoveProperty_ImplRequireMaxBusStallRequireMaxBusStall_ImplSearchPropertySearchProperty_ImplSendIOMessageServicePropertyChangeSendIOMessageServicePropertyChange_ImplSetDispatchQueue_ImplSetLegendSetLegend_ImplSetNameSetName_ImplSetPowerOverrideSetPowerOverride_ImplSetPowerStateSetPowerState_ImplSetPropertiesSetProperties_ImplStartStart_ImplStateNotificationItemCopyStateNotificationItemCopy_ImplStateNotificationItemCreateStateNotificationItemCreate_ImplStateNotificationItemSetStateNotificationItemSet_ImplStopStop_ImplStop_asyncStop_async_ImplStringFromReturnStringFromReturnStringFromReturn_ImplTerminateTerminate_ImplUpdateReportUpdateReport_ImplUserSetPropertiesUserSetProperties_ImplacknowledgeNotificationacknowledgePowerChangeactivityTickleaddInterruptStatisticsaddNeededResourceaddPowerChildadjustBusyallowPowerChangeapplyToClientsapplyToClientsapplyToInterestedapplyToProvidersapplyToProvidersaskChangeDownattachcallPlatformFunctioncallPlatformFunctioncanTerminateForReplacementcancelPowerChangecauseInterruptchangePowerStateTochangePowerStateToPrivcheckResourcecheckResourcesclosecomparePropertiescomparePropertycomparePropertyconfigureReportcopyClientWithCategorycopyNotifierscurrentCapabilitycurrentPowerConsumptiondeRegisterInterestedDriverdeliverNotificationdetachdidTerminatedisableInterruptdoServiceMatchdoServiceTerminateenableInterrupterrnoFromReturnfinalizefreegetAggressivenessgetBusyStategetClientgetClientIteratorgetClientWithCategorygetDeviceMemorygetDeviceMemoryCountgetDeviceMemoryWithIndexgetInterruptTypegetMetaClassgetOpenClientIteratorgetOpenProviderIteratorgetPowerStategetProvidergetProviderIteratorgetResourcesgetStategetWorkLoophandleClosehandleIsOpenhandleOpenhasParentinitinitinitialPowerStateForDomainStateinvokeNotifierinvokeNotifiersisInactiveisOpenjoinPMtreelockForArbitrationlookupInterruptmakeUsablemapDeviceMemoryWithIndexmatchInternalmatchLocationmatchPassivematchPropertyTablematchPropertyTablemaxCapabilityForDomainStatemessagemessageClientmessageClientsnewUserClientnewUserClientnewUserClientnewUserClientnextIdleTimeoutopenpassiveMatchpowerChangeDonepowerOverrideOffPrivpowerOverrideOnPrivpowerStateDidChangeTopowerStateForDomainStatepowerStateWillChangeToprobeprobeCandidatesregisterInterestregisterInterestregisterInterestedDriverregisterInterruptregisterInterruptBlockregisterPowerDriverregisterServiceremoveInterruptStatisticsremovePowerChildrequestPowerDomainStaterequestProberequestTerminaterequireMaxBusStallrequireMaxInterruptDelayresolveInterruptscheduleStopscheduleTerminatePhase2serializePropertiessetAggressivenesssetDeviceMemorysetIdleTimerPeriodstartstartCandidatestartMatchingstart_PM_idle_timerstopstringFromReturnsystemWillShutdowntellChangeDowntellChangeUptellNoChangeDowntemporaryPowerClampOnterminateterminateClientterminatePhase1unlockForArbitrationunregisterAllInterestunregisterAllInterruptsunregisterInterruptupdateReportwaitForStatewaitForStatewaitQuietwaitQuietwillTerminate
Type Methods
AdjustBusy_InvokeChangePowerState_InvokeClientCrashed_InvokeConfigureReport_InvokeCopyName_InvokeCopyProperties_InvokeCopyProviderProperties_InvokeCopySystemStateNotificationService_InvokeCoreAnalyticsSendEvent_InvokeCreateDefaultDispatchQueue_InvokeCreateKernelClassMatchingDictionaryCreateKernelClassMatchingDictionaryCreateNameMatchingDictionaryCreateNameMatchingDictionaryCreatePropertyMatchingDictionaryCreatePropertyMatchingDictionaryCreateUserClassMatchingDictionaryCreateUserClassMatchingDictionaryCreate_InvokeGetBusyState_InvokeGetRegistryEntryID_InvokeJoinPMTree_InvokeNewUserClient_InvokeRegisterService_InvokeRemoveProperty_InvokeRequireMaxBusStall_InvokeSearchProperty_InvokeSendIOMessageServicePropertyChange_InvokeSetLegend_InvokeSetName_InvokeSetPowerOverride_InvokeSetPowerState_InvokeSetProperties_InvokeStart_InvokeStateNotificationItemCopy_InvokeStateNotificationItemCreate_InvokeStateNotificationItemSet_InvokeStop_InvokeStop_async_InvokeStringFromReturn_InvokeTerminate_InvokeUpdateReport_InvokeUserSetProperties_InvokeactionDidStopactionDidTerminateactionFinalizeactionStopactionWillStopactionWillTerminateaddLocationaddMatchingNotificationaddMatchingNotificationaddNotificationcopyExistingServicescopyMatchingServicedoInstallNotificationgetMatchingServicesgetPMRootDomaingetPlatformgetResourceServicegetServiceRootgetSystemStateNotificationServiceinstanceMatchnameMatchingnameMatchingpropertyMatchingpublishHiddenMediapublishHiddenMediaApplierpublishResourcepublishResourcepublishUserResourceregistryEntryIDMatchingresourceMatchingresourceMatchingserviceMatchingserviceMatchingsetNotificationsetRootMediasyncNotificationHandlerterminateThreadterminateWorkeruserServerCheckInTokenCancellationHandlerwaitForMatchingServicewaitForServicewaitToBecomeTerminateThread