| 1 | /*␊ |
| 2 | * Copyright (c) 1998-2007 Apple Inc. All rights reserved.␊ |
| 3 | *␊ |
| 4 | * @APPLE_LICENSE_HEADER_START@␊ |
| 5 | * ␊ |
| 6 | * The contents of this file constitute Original Code as defined in and␊ |
| 7 | * are subject to the Apple Public Source License Version 1.2 (the␊ |
| 8 | * "License"). You may not use this file except in compliance with the␊ |
| 9 | * License. Please obtain a copy of the License at␊ |
| 10 | * http://www.apple.com/publicsource and read it before using this file.␊ |
| 11 | * ␊ |
| 12 | * This Original Code and all software distributed under the License are␊ |
| 13 | * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER␊ |
| 14 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,␊ |
| 15 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,␊ |
| 16 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. ␊ |
| 17 | * Please see the License for the specific language governing rights and ␊ |
| 18 | * limitations under the License.␊ |
| 19 | * ␊ |
| 20 | * @APPLE_LICENSE_HEADER_END@␊ |
| 21 | */␊ |
| 22 | ␊ |
| 23 | #ifndef __OPEN_SOURCE__␊ |
| 24 | /*␊ |
| 25 | *␊ |
| 26 | *␉$Log: IOUSBDevice.h,v $␊ |
| 27 | *␉Revision 1.65 2009/10/18 20:20:37 nano␊ |
| 28 | *␉Bring in fixes in 390.4.0 QL: 7310698 7301024 7307079 and 7310698␊ |
| 29 | *␊ |
| 30 | *␉Revision 1.64.32.4 2009/10/15 21:17:43 nano␊ |
| 31 | *␉If OverrideAtLocationID does not see a override property, return true␊ |
| 32 | *␉␊ |
| 33 | *␉Revision 1.64.32.3.2.1 2009/10/15 21:36:27 nano␊ |
| 34 | *␉If OverrideAtLocationID does not see a override property, return true␊ |
| 35 | *␉␊ |
| 36 | *␉Revision 1.64.32.3 2009/10/14 19:16:15 nano␊ |
| 37 | *␉Minor name changes␊ |
| 38 | *␉␊ |
| 39 | *␉Revision 1.64.32.2 2009/10/14 19:05:21 nano␊ |
| 40 | *␉7284477 7293893 Simplify scheme to decide whether we want to override a property for a hub at a particular ID for a particular MacModel. Added a IOUSBDevice API that tells us if we are in the right model and locationID to override a property␊ |
| 41 | *␉␊ |
| 42 | *␉Revision 1.64.32.1 2009/10/08 19:55:56 nano␊ |
| 43 | *␉rdar://7284477 Allow us to overide the config descriptor of a 2514 hub on a K23F␊ |
| 44 | *␉␊ |
| 45 | *␉Revision 1.64 2009/09/08 12:28:45 nano␊ |
| 46 | *␉<rdar://problem/7195788> IOUSBDevice headerdoc comment problem - GetNumConfigs name is wrong, should be GetNumConfigurations␊ |
| 47 | *␉␊ |
| 48 | *␉Revision 1.63 2009/05/07 19:43:09 nano␊ |
| 49 | *␉Move our SnowLeopard branch to TOT␊ |
| 50 | *␉␊ |
| 51 | *␉Revision 1.57.84.6 2009/03/13 22:45:11 nano␊ |
| 52 | *␉Bring in branches to fix 6676089 6675858 6567987 6490273␊ |
| 53 | *␉␊ |
| 54 | *␉Revision 1.57.84.5.4.1 2009/03/11 20:01:56 nano␊ |
| 55 | *␉rdar://6567987 Do not let a Reset or a ReEnumerate through while the other is executing.␊ |
| 56 | *␉␊ |
| 57 | *␉Revision 1.57.84.5 2009/02/26 13:44:32 nano␊ |
| 58 | *␉Bring in rdar://6536090&6586312 to SL branch␊ |
| 59 | *␉␊ |
| 60 | *␉Revision 1.57.84.4.10.1 2009/02/25 00:51:06 rhoads␊ |
| 61 | *␉change the mechanism of getConfigLock so as to prevent a deadlock␊ |
| 62 | *␉␊ |
| 63 | *␉Revision 1.57.84.4 2009/02/13 15:57:33 rhoads␊ |
| 64 | *␉roll in rdars: 6213394, 6489431, 6513000, 6515115, 6535200, 6567783␊ |
| 65 | *␉␊ |
| 66 | *␉Revision 1.57.84.3.48.3 2009/02/11 19:19:08 rhoads␊ |
| 67 | *␉add back an expansionData variable to preserve binary compatibility␊ |
| 68 | *␉␊ |
| 69 | *␉Revision 1.57.84.3.48.2 2009/02/11 03:05:56 arulchan␊ |
| 70 | *␉more ::SuspendDevice changes␊ |
| 71 | *␉␊ |
| 72 | *␉Revision 1.57.84.3.48.1 2009/01/23 21:34:15 arulchan␊ |
| 73 | *␉fix for rdar://6213394␊ |
| 74 | *␉␊ |
| 75 | *␉Revision 1.57.84.3 2008/06/16 21:31:16 nano␊ |
| 76 | *␉Bring in changes from Foxhound 320.2.17␊ |
| 77 | *␉␊ |
| 78 | *␉Revision 1.57.84.2 2008/04/22 22:38:01 nano␊ |
| 79 | *␉Bring in changes from Foxhound-320.2.9␊ |
| 80 | *␉␊ |
| 81 | *␉Revision 1.60.28.2 2008/05/22 17:36:18 nano␊ |
| 82 | *␉Fix the reporting of the internal bit for GetDeviceInformation␊ |
| 83 | *␉␊ |
| 84 | *␉Revision 1.60.28.1 2008/05/21 17:51:43 nano␊ |
| 85 | *␉<rdar://problem/5952635> GetDeviceInformation needs some fixes␊ |
| 86 | *␉␊ |
| 87 | *␉Revision 1.60 2008/04/18 22:03:28 nano␊ |
| 88 | *␉Bring in fix for rdar://5874560␊ |
| 89 | *␉␊ |
| 90 | *␉Revision 1.59.4.1 2008/04/18 21:55:55 nano␊ |
| 91 | *␉<rdar://problem/5874560> Need API to know how much extra power has been allocated␊ |
| 92 | *␉␊ |
| 93 | *␉Revision 1.59 2008/04/17 16:56:57 nano␊ |
| 94 | *␉Bring in branches for rdar://5867990 & rdar://5768343␊ |
| 95 | *␉␊ |
| 96 | *␉Revision 1.58.4.1 2008/04/16 20:26:13 nano␊ |
| 97 | *␉<rdar://problem/5867990> Add API to allocate sleep current, as well as making sure that we return any extra power if our client dies or our device is terminated without returning it␊ |
| 98 | *␉␊ |
| 99 | *␉Revision 1.58 2008/04/14 16:08:38 nano␊ |
| 100 | *␉Add new APIs for high power and for GetDeviceInformation.␊ |
| 101 | *␉␊ |
| 102 | *␉Revision 1.57.126.2 2008/04/13 05:25:40 nano␊ |
| 103 | *␉Call into PolicyMaker for the GetPortInformation␊ |
| 104 | *␉␊ |
| 105 | *␉Revision 1.57.126.1 2008/04/11 22:25:44 nano␊ |
| 106 | *␉Initial work on new user-client APIs and new IOUSBDevice APIs to return port state information and manage extra power requests, as well as groundwork for calling the policy maker directly from the IOUSBDevice␊ |
| 107 | *␉␊ |
| 108 | *␉Revision 1.57 2007/08/07 20:30:36 rhoads␊ |
| 109 | *␉rolled in a few branches to TOT␊ |
| 110 | *␉␊ |
| 111 | *␉Revision 1.56.92.1 2007/08/07 03:43:34 nano␊ |
| 112 | *␉Bring in more changes for M89 suppport -- like actually use the dang power if the properties are available␊ |
| 113 | *␉␊ |
| 114 | *␉Revision 1.56 2007/03/06 12:23:41 rhoads␊ |
| 115 | *␉roll in 5024412, 5035829, and 5039670␊ |
| 116 | *␉␊ |
| 117 | *␉Revision 1.55.30.1 2007/02/27 16:08:33 rhoads␊ |
| 118 | *␉some fine tuning of our IOService overrides, including not overriding willTerminate and didTerminate (5024412)␊ |
| 119 | *␉␊ |
| 120 | *␉Revision 1.55 2007/01/19 17:58:48 rhoads␊ |
| 121 | *␉roll in branches for a leopard build␊ |
| 122 | *␉␊ |
| 123 | *␉Revision 1.54.30.1 2007/01/17 16:37:02 rhoads␊ |
| 124 | *␉remove the IOUSBDevice::attach method which is not really useful␊ |
| 125 | *␉␊ |
| 126 | *␉Revision 1.54 2006/10/06 04:42:01 rhoads␊ |
| 127 | *␉roll in branches 4727961, 4758404, 4759810, 4760274, and 4762769␊ |
| 128 | *␉␊ |
| 129 | *␉Revision 1.53.4.1 2006/10/04 16:03:57 rhoads␊ |
| 130 | *␉better IOUSBHubDevice design␊ |
| 131 | *␉␊ |
| 132 | */␊ |
| 133 | #endif␊ |
| 134 | ␊ |
| 135 | #ifndef _IOKIT_IOUSBDEVICE_H␊ |
| 136 | #define _IOKIT_IOUSBDEVICE_H␊ |
| 137 | ␊ |
| 138 | #include <IOKit/usb/IOUSBNub.h>␊ |
| 139 | #include <IOKit/usb/IOUSBPipe.h>␊ |
| 140 | #include <IOKit/IOBufferMemoryDescriptor.h>␊ |
| 141 | #include <IOKit/IOWorkLoop.h>␊ |
| 142 | #include <IOKit/IOCommandGate.h>␊ |
| 143 | ␊ |
| 144 | #include <kern/thread_call.h>␊ |
| 145 | ␊ |
| 146 | // The following are definitions for errata properties needed for different devices. This␊ |
| 147 | // should be but in the dictionary of the IOUSBDevice in question. This can be achieved␊ |
| 148 | // by using the AppleUSBMergeNub class and having an IOProviderMergeProperties dictionary␊ |
| 149 | // with the required properties.␊ |
| 150 | ␊ |
| 151 | // This property allows a device to specify a configuration value of 0 in its configuration␊ |
| 152 | // descriptor. This does not follow the spec, but we will allow it in order to get the device ␊ |
| 153 | // to work. The property should be a Boolean␊ |
| 154 | //␊ |
| 155 | #define kAllowConfigValueOfZero␉␉"kAllowZeroConfigValue"␊ |
| 156 | #define kAllowNumConfigsOfZero␉␉"kAllowZeroNumConfigs"␊ |
| 157 | ␊ |
| 158 | ␊ |
| 159 | class IOUSBController;␊ |
| 160 | class IOUSBControllerV2;␊ |
| 161 | class IOUSBInterface;␊ |
| 162 | class IOUSBHubPolicyMaker;␊ |
| 163 | /*!␊ |
| 164 | @class IOUSBDevice␊ |
| 165 | @abstract The IOService object representing a device on the USB bus.␊ |
| 166 | @discussion This class provides functionality to configure a device and to create␊ |
| 167 | ␉IOUSBInterface objects to represent the interfaces of the device.␊ |
| 168 | */␊ |
| 169 | ␊ |
| 170 | class IOUSBDevice : public IOUSBNub␊ |
| 171 | {␊ |
| 172 | friend class IOUSBController;␊ |
| 173 | friend class IOUSBControllerV2;␊ |
| 174 | friend class IOUSBInterface;␊ |
| 175 | friend class IOUSBPipe;␊ |
| 176 | ␊ |
| 177 | OSDeclareDefaultStructors(IOUSBDevice)␊ |
| 178 | ␊ |
| 179 | protected:␊ |
| 180 | ␊ |
| 181 | USBDeviceAddress␉␉␉␉_address;␊ |
| 182 | IOUSBController *␉ ␉␉_controller;␊ |
| 183 | IOUSBPipe *␉␉␉␉␉␉_pipeZero;␊ |
| 184 | IOUSBDeviceDescriptor␉␉␉_descriptor;␊ |
| 185 | UInt32␉␉␉␉␉␉␉_busPowerAvailable;␊ |
| 186 | UInt8␉␉␉␉␉␉␉_speed;␊ |
| 187 | IOUSBEndpointDescriptor␉␉␉_endpointZero; ␉␉␉␉// Fake ep for control pipe␊ |
| 188 | void *␉␉␉␉␉␉␉_port;␉␉␉␉␉// Obsolete, do not use␊ |
| 189 | IOBufferMemoryDescriptor**␉␉_configList;␊ |
| 190 | IOUSBInterface**␉␉␉␉_interfaceList;␊ |
| 191 | UInt8␉␉␉␉␉␉␉_currentConfigValue;␊ |
| 192 | UInt8␉␉␉␉␉␉␉_numInterfaces;␊ |
| 193 | ␊ |
| 194 | struct ExpansionData ␊ |
| 195 | {␊ |
| 196 | UInt32␉␉␉␉␉_portNumber;␊ |
| 197 | thread_call_t␉␉␉_doPortResetThread;␊ |
| 198 | IOUSBDevice *␉␉␉_usbPlaneParent;␊ |
| 199 | bool␉␉␉␉␉_portResetThreadActive;␊ |
| 200 | bool␉␉␉␉␉_allowConfigValueOfZero;␊ |
| 201 | thread_call_t␉␉␉_doPortSuspendThread;␊ |
| 202 | bool␉␉␉␉␉_portSuspendThreadActive;␊ |
| 203 | thread_call_t␉␉␉_doPortReEnumerateThread;␊ |
| 204 | bool␉␉␉␉␉_resetInProgress;␊ |
| 205 | bool␉␉␉␉␉_portHasBeenReset;␊ |
| 206 | IORecursiveLock*␉␉_XgetConfigLock;␉␉␉␉// Obsolete␊ |
| 207 | bool␉␉␉␉␉_doneWaiting; // Obsolete␊ |
| 208 | bool␉␉␉␉␉_notifiedWhileBooting; // Obsolete␊ |
| 209 | IOWorkLoop *␉␉␉_workLoop;␊ |
| 210 | IOTimerEventSource *␉_notifierHandlerTimer;␊ |
| 211 | UInt32␉␉␉␉␉_notificationType;␊ |
| 212 | bool␉␉␉␉␉_suspendInProgress;␊ |
| 213 | bool␉␉␉␉␉_portHasBeenSuspendedOrResumed;␊ |
| 214 | bool␉␉␉␉␉_addExtraResetTime;␊ |
| 215 | ␉␉bool␉␉␉␉␉_suspendCommand;␊ |
| 216 | ␉␉IOCommandGate *␉␉␉_commandGate;␊ |
| 217 | ␉␉OSSet *␉␉␉␉␉_openInterfaces;␊ |
| 218 | ␉␉bool␉␉␉␉␉_resetCommand;␊ |
| 219 | ␉␉IOReturn␉␉␉␉_resetError;␊ |
| 220 | ␉␉IOReturn␉␉␉␉_suspendError;␊ |
| 221 | thread_call_t␉␉␉_doMessageClientsThread;␊ |
| 222 | ␉␉IOUSBHubPolicyMaker *␉_hubPolicyMaker;␊ |
| 223 | ␉␉UInt32␉␉␉␉␉_sleepPowerAllocated;␉␉␉␉// how much sleep power we already gave to our client␊ |
| 224 | ␉␉UInt32␉␉␉␉␉_wakePowerAllocated;␉␉␉␉// how much extra power during wake did we already give our client␊ |
| 225 | ␉␉UInt32␉␉␉␉␉_devicePortInfo;␊ |
| 226 | ␉␉bool␉␉␉␉␉_deviceIsInternal;␉␉␉␉␉// Will be set if all our upstream hubs are captive (internal to the computer)␊ |
| 227 | ␉␉bool␉␉␉␉␉_deviceIsInternalIsValid;␉␉␉// true if we have already determined whether the device is internal␊ |
| 228 | ␉␉bool␉␉␉␉␉_newGetConfigLock;␉␉␉␉␉// new lock, taken within the WL gate, when doing a GetConfig␊ |
| 229 | ␉␉UInt32␉␉␉␉␉_resetAndReEnumerateLock;␉␉␉// "Lock" to prevent us from doing a reset or a re-enumerate while the other one is in progress␉␉␊ |
| 230 | ␉␉UInt32␉␉␉␉␉_locationID;␊ |
| 231 | };␉␊ |
| 232 | ExpansionData * _expansionData;␊ |
| 233 | ␊ |
| 234 | const IOUSBConfigurationDescriptor *FindConfig(UInt8 configValue, UInt8 *configIndex=0);␊ |
| 235 | ␊ |
| 236 | virtual IOUSBInterface * GetInterface(const IOUSBInterfaceDescriptor *interface);␊ |
| 237 | ␊ |
| 238 | public:␊ |
| 239 | virtual IOReturn SetFeature(UInt8 feature);␊ |
| 240 | ␊ |
| 241 | protected: ␊ |
| 242 | virtual IOReturn GetConfigDescriptor(UInt8 configIndex, void *data, UInt32 len);␊ |
| 243 | ␊ |
| 244 | virtual IOReturn GetDeviceDescriptor(IOUSBDeviceDescriptor *desc, UInt32 size);␊ |
| 245 | ␊ |
| 246 | virtual bool init(USBDeviceAddress deviceAddress, UInt32 powerAvaiable, UInt8 speed, UInt8 maxPacketSize );␊ |
| 247 | ␊ |
| 248 | virtual bool matchPropertyTable(OSDictionary * table, SInt32 *score);␊ |
| 249 | ␊ |
| 250 | public:␊ |
| 251 | // IOService methods␊ |
| 252 | virtual bool␉␉init( void );␊ |
| 253 | virtual bool␉␉start( IOService *provider );␉␊ |
| 254 | ␉virtual bool␉␉handleIsOpen(const IOService *forClient) const;␊ |
| 255 | ␉virtual bool␉␉handleOpen(IOService *forClient, IOOptionBits options, void *arg);␊ |
| 256 | ␉virtual void␉␉handleClose(IOService *forClient, IOOptionBits options);␊ |
| 257 | virtual IOReturn ␉message( UInt32 type, IOService * provider, void * argument = 0 );␊ |
| 258 | virtual bool␉␉terminate( IOOptionBits options = 0 );␊ |
| 259 | virtual bool␉␉requestTerminate( IOService * provider, IOOptionBits options );␊ |
| 260 | virtual void␉␉stop( IOService *provider );␊ |
| 261 | virtual bool␉␉finalize(IOOptionBits options);␊ |
| 262 | ␉virtual void␉␉free( void );␉␊ |
| 263 | ␊ |
| 264 | ␉// IOUSBDevice methods␊ |
| 265 | virtual void SetProperties();␊ |
| 266 | ␊ |
| 267 | static IOUSBDevice *NewDevice(void);␊ |
| 268 | ␊ |
| 269 | virtual void SetPort(void *port);␉␉␉// Obsolete, do NOT use␊ |
| 270 | ␊ |
| 271 | /*!␊ |
| 272 | ␉@function FindNextInterfaceDescriptor␊ |
| 273 | ␉return a pointer to the next interface descriptor within the given full configuration descriptor satisfying the requirements specified, or NULL if there aren't any.␊ |
| 274 | @param configDescIn the configuration descriptor within which to search. obtained from GetFullConfigurationDescriptor(configIndex). use NULL to specify the current configuration's descriptor.␊ |
| 275 | @param intfDesc interface descriptor from which to start the search. NULL for the first interface descriptor in the given configuration descriptor␊ |
| 276 | @param request IOUSBFindInterfaceRequest specifying the desired interface. Not changed.␊ |
| 277 | @param descOut pointer to placeholder for the returned descriptor ptr␊ |
| 278 | ␉@result returns kIOReturnBadArgument if configDesc is not correct, or if configDesc is NULL and the device is not configured, or if intfDesc is not in configDesc. Otherwise returns kIOReturnSuccess or kIOUSBInterfaceNotFound.␊ |
| 279 | */␊ |
| 280 | virtual IOReturn FindNextInterfaceDescriptor(const IOUSBConfigurationDescriptor *configDescIn, ␊ |
| 281 | const IOUSBInterfaceDescriptor *intfDesc,␊ |
| 282 | const IOUSBFindInterfaceRequest *request,␊ |
| 283 | IOUSBInterfaceDescriptor **descOut);␊ |
| 284 | /*!␊ |
| 285 | ␉@function FindNextInterface␊ |
| 286 | ␉return an pointer to an IOUSBInterface object satisfying the requirements specified in request, or NULL if there aren't any. the device␊ |
| 287 | must be configured for there to be any interfaces.␊ |
| 288 | @param current interface to start searching from, NULL to start at the beginning of the device's interface list for the current configuration.␊ |
| 289 | ␉@param request specifies what properties an interface must have to match.␊ |
| 290 | ␉@result Pointer to a matching IOUSBInterface, or NULL if none match. Note: The IOUSBInterface is NOT retained for the caller. If the caller wishes to continue to use the returned object, it should call retain() on that object.␊ |
| 291 | */␊ |
| 292 | virtual IOUSBInterface *FindNextInterface(IOUSBInterface *current,␊ |
| 293 | IOUSBFindInterfaceRequest *request);␊ |
| 294 | ␊ |
| 295 | /*!␊ |
| 296 | @function CreateInterfaceIterator ␊ |
| 297 | return an OSIterator to iterate through interfaces satisfying the requirements specified in request. ␊ |
| 298 | @param request specifies what properties an interface must have to match.␊ |
| 299 | @result Pointer to an OSIterator.␊ |
| 300 | */␊ |
| 301 | virtual OSIterator *CreateInterfaceIterator(IOUSBFindInterfaceRequest *request);␊ |
| 302 | ␊ |
| 303 | // Get pointer to full config info (cached in device, don't free returned pointer)␊ |
| 304 | /*!␊ |
| 305 | ␉@function GetFullConfigurationDescriptor␊ |
| 306 | ␉return a pointer to all the descriptors for the requested configuration.␊ |
| 307 | @param configIndex The configuration index (not the configuration value)␊ |
| 308 | ␉@result Pointer to the descriptors, which are cached in the IOUSBDevice object.␊ |
| 309 | */␊ |
| 310 | virtual const IOUSBConfigurationDescriptor *GetFullConfigurationDescriptor(UInt8 configIndex);␊ |
| 311 | ␊ |
| 312 | /*!␊ |
| 313 | ␉@function GetConfigurationDescriptor␊ |
| 314 | Copy the specified amount of data for a configuration into the suppled buffer.␊ |
| 315 | @param configValue The configuration value␊ |
| 316 | ␉@param data Buffer to copy data into␊ |
| 317 | ␉@param len number of bytes to copy␊ |
| 318 | */␊ |
| 319 | virtual IOReturn GetConfigurationDescriptor(UInt8 configValue, void *data, UInt32 len);␊ |
| 320 | ␊ |
| 321 | /*!␊ |
| 322 | ␉@function ResetDevice␊ |
| 323 | ␉Reset the device, returning it to the addressed, unconfigured state.␊ |
| 324 | ␉This is useful if a device has got badly confused. Note that the AppleUSBComposite driver will automatically␊ |
| 325 | reconfigure the device if it is a composite device.␊ |
| 326 | */␊ |
| 327 | virtual IOReturn ResetDevice();␊ |
| 328 | ␊ |
| 329 | /*!␊ |
| 330 | ␉@function SetConfiguration␊ |
| 331 | ␉Do a USB SetConfiguration call to the device. The caller must have the device open() in order to ␊ |
| 332 | ␉actually cause a configuration change. If the device is currently configured, all IOUSBInterface objects␊ |
| 333 | ␉associated with the device are freed. After the new configuration has been set, all of its IOUSBInterface objects are␊ |
| 334 | ␉instantiated automatically.␊ |
| 335 | ␉@param forClient The client requesting the configuration change␊ |
| 336 | ␉@param configValue The desired configuration value.␊ |
| 337 | ␉@param startInterfaceMatching A boolean specifying whether IOKit should begin the process of finding␊ |
| 338 | ␉matching drivers for the new IOUSBInterface objects.␊ |
| 339 | */␊ |
| 340 | virtual IOReturn SetConfiguration(IOService *forClient, UInt8 configValue, bool startInterfaceMatching=true);␊ |
| 341 | ␊ |
| 342 | // Access to addressing and cached info␊ |
| 343 | /*!␊ |
| 344 | @function GetAddress␊ |
| 345 | returns the bus address of the device␊ |
| 346 | */␊ |
| 347 | virtual USBDeviceAddress GetAddress(void);␊ |
| 348 | ␊ |
| 349 | /*!␊ |
| 350 | @function GetSpeed␊ |
| 351 | returns the speed of the device␊ |
| 352 | */␊ |
| 353 | virtual UInt8 GetSpeed(void);␊ |
| 354 | /*!␊ |
| 355 | @function GetBus␊ |
| 356 | returns a pointer to the IOUSBController object for the device␊ |
| 357 | */␊ |
| 358 | virtual IOUSBController *GetBus(void);␊ |
| 359 | /*!␊ |
| 360 | @function GetBusPowerAvailable␊ |
| 361 | returns the power available to the device, in units of 2mA␊ |
| 362 | */␊ |
| 363 | virtual UInt32 GetBusPowerAvailable( void );␊ |
| 364 | /*!␊ |
| 365 | @function GetMaxPacketSize␊ |
| 366 | returns the maximum packet size for endpoint zero (only 8, 16, 32, 64 are valid)␊ |
| 367 | */␊ |
| 368 | virtual UInt8 GetMaxPacketSize(void);␊ |
| 369 | /*!␊ |
| 370 | @function GetVendorID␊ |
| 371 | returns the Vendor ID of the device␊ |
| 372 | */␊ |
| 373 | virtual UInt16 GetVendorID(void);␊ |
| 374 | /*!␊ |
| 375 | @function GetProductID␊ |
| 376 | returns the Product ID of the device␊ |
| 377 | */␊ |
| 378 | virtual UInt16 GetProductID(void);␊ |
| 379 | /*!␊ |
| 380 | @function GetDeviceRelease␊ |
| 381 | returns the DeviceRelease information␊ |
| 382 | */␊ |
| 383 | virtual UInt16 GetDeviceRelease(void);␊ |
| 384 | /*!␊ |
| 385 | @function GetNumConfigurations␊ |
| 386 | returns the number of configs in the device config descriptor␊ |
| 387 | */␊ |
| 388 | virtual UInt8 GetNumConfigurations(void);␊ |
| 389 | /*!␊ |
| 390 | @function GetManufacturerStringIndex␊ |
| 391 | returns the index of string descriptor describing manufacturer␊ |
| 392 | */␊ |
| 393 | virtual UInt8 GetManufacturerStringIndex(void );␊ |
| 394 | /*!␊ |
| 395 | @function GetProductStringIndex␊ |
| 396 | returns the index of string descriptor describing product␊ |
| 397 | */␊ |
| 398 | virtual UInt8 GetProductStringIndex(void );␊ |
| 399 | /*!␊ |
| 400 | @function GetSerialNumberStringIndex␊ |
| 401 | returns the index of string descriptor describing the device's serial number␊ |
| 402 | */␊ |
| 403 | virtual UInt8 GetSerialNumberStringIndex(void );␊ |
| 404 | /*!␊ |
| 405 | @function GetPipeZero␊ |
| 406 | returns a pointer to the device's default control pipe␊ |
| 407 | */␊ |
| 408 | virtual IOUSBPipe * GetPipeZero(void);␊ |
| 409 | ␊ |
| 410 | ␉// Deprecated but needed for binary compatibility␊ |
| 411 | virtual IOUSBPipe*␉MakePipe(const IOUSBEndpointDescriptor *ep);␊ |
| 412 | ␊ |
| 413 | // this method is deprecated. use the other DeviceRequest methods␊ |
| 414 | virtual IOReturn DeviceRequest(IOUSBDevRequest␉*request,␊ |
| 415 | IOUSBCompletion␉*completion = 0);␊ |
| 416 | ␊ |
| 417 | // Same but with a memory descriptor␊ |
| 418 | virtual IOReturn DeviceRequest(IOUSBDevRequestDesc␉*request,␊ |
| 419 | IOUSBCompletion␉*completion = 0);␊ |
| 420 | ␊ |
| 421 | /*!␊ |
| 422 | ␉@function GetConfiguration␊ |
| 423 | ␉Gets the current configuration from the IOUSBDevice object. Note that this call will send a control␊ |
| 424 | request on the bus to get the current configuration from the physical device.␊ |
| 425 | ␉@param configNum Pointer to place to store configuration value.␊ |
| 426 | */␊ |
| 427 | virtual IOReturn GetConfiguration(UInt8 *configNumber);␊ |
| 428 | ␊ |
| 429 | /*!␊ |
| 430 | @function GetDeviceStatus␊ |
| 431 | Gets the device's status. Note that this sends a control request to the physical device.␊ |
| 432 | @param status Pointer to place to store the status.␊ |
| 433 | */␊ |
| 434 | virtual IOReturn GetDeviceStatus(USBStatus *status);␊ |
| 435 | ␊ |
| 436 | /*! ␊ |
| 437 | ␉@function GetStringDescriptor␊ |
| 438 | ␉Get a string descriptor as ASCII, in the specified language (default is US English)␊ |
| 439 | ␉@param index Index of the string descriptor to get.␊ |
| 440 | ␉@param buf Pointer to place to store ASCII string␊ |
| 441 | ␉@param maxLen Size of buffer pointed to by buf␊ |
| 442 | @param lang Language to get string in (default is US English)␊ |
| 443 | */␊ |
| 444 | virtual IOReturn GetStringDescriptor(UInt8 index, char *buf, int maxLen, UInt16 lang=0x409);␊ |
| 445 | ␊ |
| 446 | /*! ␊ |
| 447 | ␉@function GetChildLocationID␊ |
| 448 | ␉Get the locationID (UInt32) given the port number and the parent's location␊ |
| 449 | ␉@param parentLocationID locationID for the hub to which this device is attached.␊ |
| 450 | ␉@param port Port number of the hub where this device is attached␊ |
| 451 | */␊ |
| 452 | virtual UInt32 GetChildLocationID(UInt32 parentLocationID, int port);␊ |
| 453 | ␊ |
| 454 | virtual const IOUSBDescriptorHeader* FindNextDescriptor(const void *cur, UInt8 descType);␊ |
| 455 | ␊ |
| 456 | virtual void ␉DisplayNotEnoughPowerNotice();␊ |
| 457 | ␊ |
| 458 | // this is a non-virtual function so that we don't have to take up a binary compatibility slot.␊ |
| 459 | UInt16␉GetbcdUSB(void);␊ |
| 460 | UInt8␉GetProtocol(void);␊ |
| 461 | ␉void␉SetBusPowerAvailable(UInt32 newPower);␊ |
| 462 | ␊ |
| 463 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 0);␊ |
| 464 | /*!␊ |
| 465 | ␉@function DeviceRequest␊ |
| 466 | @abstract execute a control request to the default control pipe (pipe zero)␊ |
| 467 | @param request The parameter block to send to the device␊ |
| 468 | @param noDataTimeout Specifies an amount of time (in ms) after which the command will be aborted␊ |
| 469 | if no data has been transferred on the bus.␊ |
| 470 | @param completionTimeout Specifies an amount of time (in ms) after which the command will be aborted if the entire command has␊ |
| 471 | not been completed.␊ |
| 472 | ␉␉@param completion Function to call when request completes. If omitted then␊ |
| 473 | ␉ DeviceRequest() executes synchronously, blocking until the request is complete. If the request is asynchronous, the client must make sure that␊ |
| 474 | ␉ the IOUSBDevRequest is not released until the callback has occurred.␊ |
| 475 | ␊ |
| 476 | */␊ |
| 477 | virtual IOReturn DeviceRequest(IOUSBDevRequest␉*request,␊ |
| 478 | ␉␉␉␉UInt32 noDataTimeout,␊ |
| 479 | ␉␉␉␉UInt32 completionTimeout,␊ |
| 480 | IOUSBCompletion␉*completion = 0);␊ |
| 481 | ␊ |
| 482 | /*!␊ |
| 483 | ␉ @function DeviceRequest␊ |
| 484 | ␉ @abstract execute a control request to the default control pipe (pipe zero)␊ |
| 485 | ␉ @param request The parameter block to send to the device (with the pData as an IOMemoryDesriptor)␊ |
| 486 | ␉ @param noDataTimeout Specifies an amount of time (in ms) after which the command will be aborted␊ |
| 487 | ␉ if no data has been transferred on the bus.␊ |
| 488 | ␉ @param completionTimeout Specifies an amount of time (in ms) after which the command will be aborted if the entire command has␊ |
| 489 | ␉ not been completed.␊ |
| 490 | ␉ @param completion Function to call when request completes. If omitted then␊ |
| 491 | ␉ DeviceRequest() executes synchronously, blocking until the request is complete. If the request is asynchronous, the client must make sure that␊ |
| 492 | ␉ the IOUSBDevRequest is not released until the callback has occurred.␊ |
| 493 | ␉ ␊ |
| 494 | ␉ */␊ |
| 495 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 1);␊ |
| 496 | virtual IOReturn DeviceRequest(IOUSBDevRequestDesc␉*request,␊ |
| 497 | ␉␉␉␉ UInt32 noDataTimeout,␊ |
| 498 | ␉␉␉␉ UInt32 completionTimeout,␊ |
| 499 | ␉␉␉␉ IOUSBCompletion␉*completion = 0);␊ |
| 500 | ␊ |
| 501 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 2);␊ |
| 502 | /*!␊ |
| 503 | ␉@function SuspendDevice␊ |
| 504 | @abstract Instruct the hub to which this device is attached to suspend or resume the port to which the device is attached.␊ |
| 505 | Note that if there are any outstanding transactions on any pipes in the device, those transactions will get returned with a ␊ |
| 506 | kIOReturnNotResponding error.␊ |
| 507 | @param suspend Boolean value. true = suspend, false = resume.␊ |
| 508 | */␊ |
| 509 | virtual IOReturn SuspendDevice( bool suspend);␊ |
| 510 | ␊ |
| 511 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 3);␊ |
| 512 | /*!␊ |
| 513 | ␉@function ReEnumerateDevice␊ |
| 514 | @abstract Instruct the hub to which this device is attached to reset the port to which this device is attached. This causes the␊ |
| 515 | IOUSBDevice object and any child objects (IOUSBInterface objects or driver objects) to be terminated, and the device to be␊ |
| 516 | completely reenumerated, as if it had been detached and reattached.␊ |
| 517 | @param options Reserved for future use.␊ |
| 518 | */␊ |
| 519 | virtual IOReturn ReEnumerateDevice( UInt32 options );␊ |
| 520 | ␊ |
| 521 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 4);␊ |
| 522 | /*!␊ |
| 523 | @function DisplayUserNotification␊ |
| 524 | @abstract Will use the KUNCUserNotification mechanism to display a notification to the user.␊ |
| 525 | @param notificationType Which notification to display.␊ |
| 526 | */␊ |
| 527 | virtual void␉DisplayUserNotification(UInt32 notificationType);␊ |
| 528 | ␊ |
| 529 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 5);␊ |
| 530 | ␉/*!␊ |
| 531 | @function MakePipe␊ |
| 532 | ␉ @abstract build a pipe on a given endpoint␊ |
| 533 | ␉ @param ep A description of the endpoint␊ |
| 534 | ␉ @param interface The IOUSBInterface object requesting the pipe␊ |
| 535 | ␉ returns the desired IOUSBPipe object␊ |
| 536 | ␉ */␊ |
| 537 | virtual IOUSBPipe*␉MakePipe(const IOUSBEndpointDescriptor *ep, IOUSBInterface *interface);␊ |
| 538 | ␊ |
| 539 | ␉␊ |
| 540 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 6);␊ |
| 541 | ␉/*!␊ |
| 542 | ␉ @function SetHubParent␊ |
| 543 | ␉ @abstract Used by the hub driver to give the nub a pointer to its HubPolicyMaker object␊ |
| 544 | ␉ @param hubPolicyMaker␉The object representing the Hub driver␊ |
| 545 | ␉ */␊ |
| 546 | virtual void␉SetHubParent(IOUSBHubPolicyMaker *hubParent);␊ |
| 547 | ␊ |
| 548 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 7);␊ |
| 549 | ␉/*!␊ |
| 550 | ␉ @function GetHubParent␊ |
| 551 | ␉ @abstract Used by the hub driver to give the nub a pointer to its HubPolicyMaker object␊ |
| 552 | ␉ @param hubPolicyMaker␉The object representing the Hub driver␊ |
| 553 | ␉ */␊ |
| 554 | virtual IOUSBHubPolicyMaker*␉GetHubParent();␊ |
| 555 | ␊ |
| 556 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 8);␊ |
| 557 | /*!␊ |
| 558 | ␉ @function ␉GetDeviceInformation␊ |
| 559 | ␉ @abstract ␉Returns status information about the USB device, such as whether the device is captive or whether it is in the suspended state.␊ |
| 560 | ␉ @param requestedPower ␉The desired amount of power that the client wishes to reserve␊ |
| 561 | ␉ @result ␉␉Actual power that was reserved␊ |
| 562 | ␉ ␊ |
| 563 | ␉␉*/␊ |
| 564 | ␉virtual IOReturn␉GetDeviceInformation(UInt32 *info);␊ |
| 565 | ␊ |
| 566 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 9);␊ |
| 567 | /*!␊ |
| 568 | ␉ @function␉␉␉␉RequestExtraPower␊ |
| 569 | ␉ @abstract␉␉␉␉Clients can use this API to reserve extra power for use by this device while the machine is asleep or while it is awake. Units are milliAmps (mA).␊ |
| 570 | ␉ @param type␉␉␉Indicates whether the power is to be used during wake or sleep (One of kUSBPowerDuringSleep or kUSBPowerDuringWake)␊ |
| 571 | ␉ @param requestedPower ␉Amount of power desired, in mA␊ |
| 572 | ␉ @result␉␉␉␉Amount of power actually reserved, in mA. It can be less than the requested or zero.␊ |
| 573 | ␉ ␊ |
| 574 | ␉ */␊ |
| 575 | ␉virtual UInt32␉RequestExtraPower(UInt32 type, UInt32 requestedPower);␊ |
| 576 | ␊ |
| 577 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 10);␊ |
| 578 | /*!␊ |
| 579 | ␉ @function␉␉␉␉ReturnExtraPower␊ |
| 580 | ␉ @abstract␉␉␉␉Clients can use this API to tell the system that they will not use power that was previously reserved by using the RequestExtraPower API.␊ |
| 581 | ␉ @param type␉␉␉Indicates whether the power is to be used during wake or sleep (One of kUSBPowerDuringSleep or kUSBPowerDuringWake)␊ |
| 582 | ␉ @param returnedPower ␉Amount of power that is no longer needed, in mA␊ |
| 583 | ␉ @result␉␉␉␉If the returnedPower was not previously allocated, an error will be returned. This will include the case for power that was requested for sleep but was returned for wake.␊ |
| 584 | ␉ ␊ |
| 585 | ␉ */␊ |
| 586 | ␉virtual IOReturn␉␉ReturnExtraPower(UInt32 type, UInt32 returnedPower);␊ |
| 587 | ␊ |
| 588 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 11);␊ |
| 589 | /*!␊ |
| 590 | ␉ @function␉␉␉␉GetExtraPowerAllocated␊ |
| 591 | ␉ @abstract␉␉␉␉Clients can use this API to ask how much extra power has already been reserved by this device. Units are milliAmps (mA).␊ |
| 592 | ␉ @param type␉␉␉Indicates whether the allocated power was to be used during wake or sleep (One of kUSBPowerDuringSleep or kUSBPowerDuringWake)␊ |
| 593 | ␉ @result␉␉␉␉Amount of power allocated, in mA.␊ |
| 594 | ␉ ␊ |
| 595 | ␉ */␊ |
| 596 | ␉virtual UInt32␉␉␉GetExtraPowerAllocated(UInt32 type);␊ |
| 597 | ␊ |
| 598 | OSMetaClassDeclareReservedUsed(IOUSBDevice, 12);␊ |
| 599 | /*!␊ |
| 600 | ␉ @function␉␉␉␉DoLocationOverrideAndModelMatch␊ |
| 601 | ␉ @abstract␉␉␉␉Will look for a kOverrideIfAtLocationID array proerty with locationID entries and a "MacModel" property. If any of the locationIDs match to the Mac Model, will return true.␊ |
| 602 | ␉ ␉␉␉␉␉␉If there is no kOverrideAtLocationID property, it will also return true.␊ |
| 603 | ␉ @result␉␉␉␉True if we have a match, false otherwise␊ |
| 604 | ␉ */␊ |
| 605 | ␉virtual␉bool␉␉␉DoLocationOverrideAndModelMatch();␊ |
| 606 | ␉␊ |
| 607 | OSMetaClassDeclareReservedUnused(IOUSBDevice, 13);␊ |
| 608 | OSMetaClassDeclareReservedUnused(IOUSBDevice, 14);␊ |
| 609 | OSMetaClassDeclareReservedUnused(IOUSBDevice, 15);␊ |
| 610 | OSMetaClassDeclareReservedUnused(IOUSBDevice, 16);␊ |
| 611 | OSMetaClassDeclareReservedUnused(IOUSBDevice, 17);␊ |
| 612 | OSMetaClassDeclareReservedUnused(IOUSBDevice, 18);␊ |
| 613 | OSMetaClassDeclareReservedUnused(IOUSBDevice, 19);␊ |
| 614 | ␊ |
| 615 | private:␊ |
| 616 | ␊ |
| 617 | static void ␉ProcessPortResetEntry(OSObject *target);␊ |
| 618 | void ␉␉ProcessPortReset(void);␊ |
| 619 | ␊ |
| 620 | void ␉␉TerminateInterfaces(void);␊ |
| 621 | ␊ |
| 622 | static void ␉ProcessPortReEnumerateEntry(OSObject *target, thread_call_param_t options);␊ |
| 623 | void ␉␉ProcessPortReEnumerate(UInt32 options);␊ |
| 624 | ␉␊ |
| 625 | static void ␉DoMessageClientsEntry(OSObject *target, thread_call_param_t messageStruct);␊ |
| 626 | void ␉␉DoMessageClients( void * messageStructPtr);␊ |
| 627 | ␉␊ |
| 628 | static void ␉DisplayUserNotificationForDeviceEntry (OSObject *owner, IOTimerEventSource *sender);␊ |
| 629 | void␉␉DisplayUserNotificationForDevice( );␊ |
| 630 | ␊ |
| 631 | UInt32 SimpleUnicodeToUTF8(UInt16 uChar, UInt8 utf8Bytes[4]);␊ |
| 632 | void SwapUniWords (UInt16 **unicodeString, UInt32 uniSize);␊ |
| 633 | ␊ |
| 634 | IOReturn␉␉␉TakeGetConfigLock(void);␊ |
| 635 | IOReturn␉␉␉ReleaseGetConfigLock(void);␊ |
| 636 | static IOReturn␉␉ChangeGetConfigLock(OSObject *target, void *arg0, void *arg1, void *arg2, void *arg3);␊ |
| 637 | };␊ |
| 638 | ␊ |
| 639 | #endif /* _IOKIT_IOUSBDEVICE_H */␊ |
| 640 | |
