Return to IOUSBNub.h CVS log

Up to [Apple XNU] / XNU / iokit / IOKit / usb

Annotation of XNU/iokit/IOKit/usb/IOUSBNub.h, revision 1.1

1.1     ! root        1: /*
        !             2:  * Copyright (c) 1998-2000 Apple Computer, 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.1 (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 OR NON-INFRINGEMENT.  Please see the
        !            17:  * License for the specific language governing rights and limitations
        !            18:  * under the License.
        !            19:  * 
        !            20:  * @APPLE_LICENSE_HEADER_END@
        !            21:  */
        !            22: /*
        !            23:  * Copyright (c) 1998 Apple Computer, Inc.  All rights reserved.
        !            24:  *
        !            25:  * HISTORY
        !            26:  *
        !            27:  */
        !            28: 
        !            29: 
        !            30: #ifndef _IOKIT_IOUSBNUB_H
        !            31: #define _IOKIT_IOUSBNUB_H
        !            32: 
        !            33: #include <IOKit/IOService.h>
        !            34: #include <libkern/c++/OSData.h>
        !            35: #include <IOKit/IOMemoryDescriptor.h>
        !            36: 
        !            37: #include <IOKit/usb/USB.h>
        !            38: 
        !            39: class IOUSBController;
        !            40: class IOUSBPipe;
        !            41: 
        !            42: /*!
        !            43:     @struct IOUSBDevRequest
        !            44:     parameter block for control requests, using a simple pointer
        !            45:     for the data to be transferred.
        !            46:     @field rdDirection Direction of data part of request: kUSBIn or kUSBOut
        !            47:     @field rqType Request type: kUSBStandard, kUSBClass or kUSBVendor
        !            48:     @field rqRecipient Target of the request: kUSBDevice, kUSBInterface,
        !            49:        kUSBEndpoint or kUSBOther
        !            50:     @field bRequest Request code
        !            51:     @field wValue 16 bit parameter for request, low byte first
        !            52:     @field wIndex 16 bit parameter for request, low byte first
        !            53:     @field wLength Length of data part of request, 16 bits, low byte first
        !            54:     @field pData Pointer to data for request
        !            55:     @field wLenDone Set by standard completion routine to number of data bytes
        !            56:        actually transferred
        !            57: */
        !            58: typedef struct {
        !            59:     UInt8      rqDirection:1;  // bmRequestType:7
        !            60:     UInt8      rqType:2;       // bmRequestType:6..5
        !            61:     UInt8      rqRecipient:5;  // bmRequestType:4..0
        !            62:     UInt8      bRequest;
        !            63:     USBWord    wValue;
        !            64:     USBWord    wIndex;
        !            65:     USBWord    wLength;
        !            66:     void *     pData;          // data pointer
        !            67:     UInt32     wLenDone;       // # bytes transferred
        !            68: } IOUSBDevRequest;
        !            69: typedef IOUSBDevRequest * IOUSBDeviceRequestPtr;
        !            70: 
        !            71: /*!
        !            72:     @struct IOUSBDevRequestDesc
        !            73:     parameter block for control requests, using a memory descriptor
        !            74:     for the data to be transferred
        !            75:     @field rdDirection Direction of data part of request: kUSBIn or kUSBOut
        !            76:     @field rqType Request type: kUSBStandard, kUSBClass or kUSBVendor
        !            77:     @field rqRecipient Target of the request: kUSBDevice, kUSBInterface,
        !            78:         kUSBEndpoint or kUSBOther
        !            79:     @field bRequest Request code
        !            80:     @field wValue 16 bit parameter for request, low byte first
        !            81:     @field wIndex 16 bit parameter for request, low byte first
        !            82:     @field wLength Length of data part of request, 16 bits, low byte first
        !            83:     @field pData Pointer to memory descriptor for data for request
        !            84:     @field wLenDone Set by standard completion routine to number of data bytes
        !            85:      actually transferred
        !            86: */
        !            87: typedef struct {
        !            88:     UInt8      rqDirection:1;  // bmRequestType:7
        !            89:     UInt8      rqType:2;       // bmRequestType:6..5
        !            90:     UInt8      rqRecipient:5;  // bmRequestType:4..0
        !            91:     UInt8      bRequest;
        !            92:     USBWord    wValue;
        !            93:     USBWord    wIndex;
        !            94:     USBWord    wLength;
        !            95:     IOMemoryDescriptor *pData; // data pointer
        !            96:     UInt32     wLenDone;       // # bytes transferred
        !            97: } IOUSBDevRequestDesc;
        !            98: 
        !            99: /*!
        !           100:     @class IOUSBNub
        !           101:     @abstract abstract base class for IOUSBDevice and IOUSBInterface
        !           102:     @discussion This class provides functionality that is useful for both
        !           103:     a device driver (which would attach to an IOUSBDevice) and an interface driver
        !           104:     (which would attach to an IOUSBInterface).
        !           105: */
        !           106: 
        !           107: class IOUSBNub : public IOService
        !           108: {
        !           109:     OSDeclareDefaultStructors(IOUSBNub)
        !           110: 
        !           111: protected:
        !           112:     USBDeviceAddress           _address;
        !           113:     IOUSBController *          _controller;
        !           114:     IOUSBPipe *                        _pipeZero;
        !           115:     IOUSBDeviceDescriptor      _descriptor;
        !           116:     UInt32                     _busPowerAvailable;
        !           117:     UInt8                      _speed;
        !           118: 
        !           119: public:
        !           120:     virtual bool finalize(IOOptionBits options);
        !           121: 
        !           122:     /*!
        !           123:         @struct FindInterfaceRequest
        !           124:         Parameter block for finding interfaces in a device.
        !           125:        Initialize each field to the desired value
        !           126:         before calling findNextInterface, set a field to 0 if any value is OK.
        !           127:         @field theClass Requested class
        !           128:         @field subClass Requested subclass
        !           129:         @field protocol Requested protocol
        !           130:         @field maxPower max power consumption in 2mA units
        !           131:         @field busPowered 1 = not bus powered, 2 = bus powered
        !           132:         @field selfPowered 1 = not self powered, 2 = self powered
        !           133:         @field remoteWakeup 1 = doesn't support remote wakeup, 2 = does
        !           134:     */
        !           135:     struct FindInterfaceRequest {
        !           136:         UInt8 theClass;                // requested class,    0 = don't care
        !           137:         UInt8 subClass;                // requested subclass; 0 = don't care
        !           138:         UInt8 protocol;                // requested protocol; 0 = don't care
        !           139:         UInt8 maxPower;                // max power in 2ma increments; 0 = don't care
        !           140:         UInt8 busPowered:2;    // 1 = not bus powered, 2 = bus powered,
        !           141:         UInt8 selfPowered:2;   // 1 = not self powered, 2 = self powered,
        !           142:         UInt8 remoteWakeup:2;  // 1 = doesn't support remote wakeup; 2 = does
        !           143:         UInt8 reserved:2;
        !           144:     };
        !           145: 
        !           146:     /*!
        !           147:        @function findNextDescriptor
        !           148:         @abstract find next descriptor in configuration list of given type
        !           149:        (kUSBAnyDesc matches any type).
        !           150:         @discussion call this function with a pointer to a descriptor in a descriptor list,
        !           151:        for example the descriptor list returned by IOUSBDevice::getFullConfigurationDescriptor().
        !           152:         Returns NULL if no more descriptors match descType.
        !           153:         @param cur current descriptor in list
        !           154:         @param descType descriptor type to return (kUSBAnyDesc to match any type)
        !           155:        @result Pointer to the next matching descriptor, or NULL if no more match.
        !           156:     */
        !           157:     static const IOUSBDescriptorHeader *findNextDescriptor(const void *cur, UInt8 descType);
        !           158: 
        !           159:     /*! 
        !           160:        @function GetStringDescriptor
        !           161:        Get a string descriptor as ASCII, in the specified language (default is US English)
        !           162:        @param index Index of the string descriptor to get.
        !           163:        @param buf Pointer to place to store ASCII string
        !           164:        @param maxLen Size of buffer pointed to by buf
        !           165:         @param lang Language to get string in (default is US English)
        !           166:     */
        !           167:     virtual IOReturn GetStringDescriptor(UInt8 index,
        !           168:                                         char *buf, int maxLen, UInt16 lang=0x409);
        !           169: 
        !           170:     // Lowlevel requests for non-standard device requests
        !           171:     /*!
        !           172:        @function deviceRequest
        !           173:         @abstract execute a device request
        !           174:         @param request The parameter block to send to the device
        !           175:        @completion Function to call when request completes. If omitted then deviceRequest()
        !           176:        executes synchronously, blocking until the request is complete.
        !           177:     */
        !           178:     virtual IOReturn deviceRequest(IOUSBDevRequest     *request,
        !           179:                             IOUSBCompletion    *completion = 0);
        !           180: 
        !           181:     // Same but with a memory descriptor
        !           182:     virtual IOReturn deviceRequest(IOUSBDevRequestDesc *request,
        !           183:                             IOUSBCompletion    *completion = 0);
        !           184: 
        !           185:     /*!
        !           186:        @function GetConfiguration
        !           187:        Gets the current configuration from the device
        !           188:        @param configNum Pointer to place to store configuration value
        !           189:     */
        !           190:     virtual IOReturn GetConfiguration(UInt8 *configNumber);
        !           191: 
        !           192:     /*!
        !           193:         @function GetConfiguration
        !           194:         Gets the current configuration from the device
        !           195:         @param configNum Pointer to place to store configuration value
        !           196:     */
        !           197:     virtual IOReturn GetDeviceStatus(USBStatus *status);
        !           198: 
        !           199:     // Access to addressing and cached info
        !           200:     /*!
        !           201:         @function address
        !           202:         returns the bus address of the device
        !           203:     */
        !           204:     virtual USBDeviceAddress           address(void);
        !           205:     /*!
        !           206:         @function deviceDescriptor
        !           207:         returns a pointer to the device descriptor
        !           208:     */
        !           209:     virtual const IOUSBDeviceDescriptor *deviceDescriptor(void);
        !           210:     /*!
        !           211:         @function bus
        !           212:         returns a pointer to the bus object for the device
        !           213:     */
        !           214:     virtual IOUSBController *          bus(void);
        !           215:     /*!
        !           216:         @function busPowerAvailable
        !           217:         returns the power available to the device, in units of 2mA
        !           218:     */
        !           219:     virtual UInt32                     busPowerAvailable( void );
        !           220: 
        !           221:     /*!
        !           222:         @function GetBandwidthAvailable
        !           223:         Returns the available bandwidth (in bytes) per frame for
        !           224:         isochronous transfers.
        !           225:         @result maximum number of bytes that a new iso pipe could transfer
        !           226:         per frame given current allocations.
        !           227:     */
        !           228:     virtual UInt32 GetBandwidthAvailable();
        !           229: 
        !           230:     /*!
        !           231:         @function GetFrameNumber
        !           232:         Returns the full current frame number of the bus the device is
        !           233:        attached to
        !           234:         @result The frame number.
        !           235:     */
        !           236:     virtual UInt64 GetFrameNumber();
        !           237: 
        !           238:     /*!
        !           239:         @function pipeZero
        !           240:         returns a pointer to the device's default pipe
        !           241:     */
        !           242:     virtual IOUSBPipe *                        pipeZero();
        !           243: 
        !           244:     virtual bool init(OSDictionary * propTable);
        !           245:     virtual bool matchPropertyTable(OSDictionary * table);
        !           246: };
        !           247: 
        !           248: #ifdef __cplusplus
        !           249: extern "C" {
        !           250: #endif
        !           251: 
        !           252: void printDescriptor(IOUSBDescriptorHeader *desc);
        !           253: void printDeviceDescriptor(IOUSBDeviceDescriptor *desc);
        !           254: void printConfigDescriptor(IOUSBConfigurationDescriptor *cd);
        !           255: void printEndpointDescriptor(IOUSBEndpointDescriptor *ed);
        !           256: void printInterfaceDescriptor(IOUSBInterfaceDescriptor *id);
        !           257: 
        !           258: #ifdef __cplusplus
        !           259: }
        !           260: #endif
        !           261: 
        !           262: #endif /* _IOKIT_IOUSBNUB_H */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.