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#ifndef _IOKIT_IOI2CINTERFACE_H 24#define _IOKIT_IOI2CINTERFACE_H 25 26/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 27 28typedef struct IOI2CRequest IOI2CRequest; 29typedef struct IOI2CBuffer IOI2CBuffer; 30 31typedef void (*IOI2CRequestCompletion) (IOI2CRequest * request); 32 33// IOI2CRequest.sendTransactionType, IOI2CRequest.replyTransactionType 34enum { 35 kIOI2CNoTransactionType = 0, 36 kIOI2CSimpleTransactionType = 1, 37 kIOI2CDDCciReplyTransactionType = 2, 38 kIOI2CCombinedTransactionType = 3, 39 kIOI2CDisplayPortNativeTransactionType = 4 40}; 41 42// IOI2CRequest.commFlags 43enum { 44 kIOI2CUseSubAddressCommFlag = 0x00000002 45}; 46 47/*! 48 * @struct IOI2CRequest 49 * @abstract A structure defining an I2C bus transaction. 50 * @discussion This structure is used to request an I2C transaction consisting of a send (write) to and reply (read) from a device, either of which is optional, to be carried out atomically on an I2C bus. 51 * @field __reservedA Set to zero. 52 * @field result The result of the transaction. Common errors are kIOReturnNoDevice if there is no device responding at the given address, kIOReturnUnsupportedMode if the type of transaction is unsupported on the requested bus. 53 * @field completion A completion routine to be executed when the request completes. If NULL is passed, the request is synchronous, otherwise it may execute asynchronously. 54 * @field commFlags Flags that modify the I2C transaction type. The following flags are defined:<br> 55 * kIOI2CUseSubAddressCommFlag Transaction includes a subaddress.<br> 56 * @field minReplyDelay Minimum delay as absolute time between send and reply transactions. 57 * @field sendAddress I2C address to write. 58 * @field sendSubAddress I2C subaddress to write. 59 * @field __reservedB Set to zero. 60 * @field sendTransactionType The following types of transaction are defined for the send part of the request:<br> 61 * kIOI2CNoTransactionType No send transaction to perform. <br> 62 * kIOI2CSimpleTransactionType Simple I2C message. <br> 63 * kIOI2CCombinedTransactionType Combined format I2C R/~W transaction. <br> 64 * @field sendBuffer Pointer to the send buffer. 65 * @field sendBytes Number of bytes to send. Set to actual bytes sent on completion of the request. 66 * @field replyAddress I2C Address from which to read. 67 * @field replySubAddress I2C Address from which to read. 68 * @field __reservedC Set to zero. 69 * @field replyTransactionType The following types of transaction are defined for the reply part of the request:<br> 70 * kIOI2CNoTransactionType No reply transaction to perform. <br> 71 * kIOI2CSimpleTransactionType Simple I2C message. <br> 72 * kIOI2CDDCciReplyTransactionType DDC/ci message (with embedded length). See VESA DDC/ci specification. <br> 73 * kIOI2CCombinedTransactionType Combined format I2C R/~W transaction. <br> 74 * @field replyBuffer Pointer to the reply buffer. 75 * @field replyBytes Max bytes to reply (size of replyBuffer). Set to actual bytes received on completion of the request. 76 * @field __reservedD Set to zero. 77 */ 78 79#pragma pack(push, 4) 80struct IOI2CRequest 81{ 82 IOOptionBits sendTransactionType; 83 IOOptionBits replyTransactionType; 84 uint32_t sendAddress; 85 uint32_t replyAddress; 86 uint8_t sendSubAddress; 87 uint8_t replySubAddress; 88 uint8_t __reservedA[2]; 89 90 uint64_t minReplyDelay; 91 92 IOReturn result; 93 IOOptionBits commFlags; 94 95#if defined(__LP64__) 96 uint32_t __padA; 97#else 98 vm_address_t sendBuffer; 99#endif 100 uint32_t sendBytes; 101 102 uint32_t __reservedB[2]; 103 104#if defined(__LP64__) 105 uint32_t __padB; 106#else 107 vm_address_t replyBuffer; 108#endif 109 uint32_t replyBytes; 110 111 IOI2CRequestCompletion completion; 112#if !defined(__LP64__) 113 uint32_t __padC[5]; 114#else 115 vm_address_t sendBuffer; 116 vm_address_t replyBuffer; 117#endif 118 119 uint32_t __reservedC[10]; 120#ifdef __ppc__ 121 uint32_t __reservedD; 122#endif 123}; 124#pragma pack(pop) 125 126/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 127 128#define kIOI2CInterfaceClassName "IOI2CInterface" 129 130#define kIOI2CInterfaceIDKey "IOI2CInterfaceID" 131#define kIOI2CBusTypeKey "IOI2CBusType" 132#define kIOI2CTransactionTypesKey "IOI2CTransactionTypes" 133#define kIOI2CSupportedCommFlagsKey "IOI2CSupportedCommFlags" 134 135#define kIOFBI2CInterfaceInfoKey "IOFBI2CInterfaceInfo" 136#define kIOFBI2CInterfaceIDsKey "IOFBI2CInterfaceIDs" 137 138// kIOI2CBusTypeKey values 139enum { 140 kIOI2CBusTypeI2C = 1, 141 kIOI2CBusTypeDisplayPort = 2 142}; 143 144/*! 145 * @struct IOI2CBusTiming 146 * @abstract A structure defining low level timing for an I2C bus. 147 * @discussion This structure is used to specify timeouts and pulse widths for an I2C bus implementation. 148 * @field bitTimeout Maximum time a slave can delay (by pulling the clock line low) a single bit response. 149 * @field byteTimeout Maximum time a slave can delay (by pulling the clock line low) the first bit of a byte response. 150 * @field acknowledgeTimeout Maximum time to wait for a slave to respond with an ACK after writing a byte. 151 * @field startTimeout Maximum time to wait for a slave to respond after a start signal. 152 * @field riseFallTime Time to wait after any change in output signal. 153 * @field __reservedA Set to zero. 154 */ 155 156struct IOI2CBusTiming 157{ 158 AbsoluteTime bitTimeout; 159 AbsoluteTime byteTimeout; 160 AbsoluteTime acknowledgeTimeout; 161 AbsoluteTime startTimeout; 162 AbsoluteTime holdTime; 163 AbsoluteTime riseFallTime; 164 UInt32 __reservedA[8]; 165}; 166typedef struct IOI2CBusTiming IOI2CBusTiming; 167 168#ifndef KERNEL 169 170/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 171 172// options for IOFBCopyI2CInterfaceForBus() 173enum { 174 kIOI2CBusNumberMask = 0x000000ff 175}; 176 177 178/*! @function IOFBGetI2CInterfaceCount 179 @abstract Returns a count of I2C interfaces available associated with an IOFramebuffer instance. 180 @discussion Returns a count of I2C interfaces available associated with an IOFramebuffer instance. 181 @param framebuffer The io_service_t of an IOFramebuffer instance. CoreGraphics will provide this for a CGDisplay with the CGDisplayIOServicePort() call. 182 @param count Interface count is returned. 183 @result An IOReturn code. */ 184 185IOReturn IOFBGetI2CInterfaceCount( io_service_t framebuffer, IOItemCount * count ); 186 187/*! @function IOFBCopyI2CInterfaceForBus 188 @abstract Returns an instance of an I2C bus interface, associated with an IOFramebuffer instance / bus index pair. 189 @discussion Some graphics devices will allow access to an I2C bus routed through a display connector in order to control external devices on that bus. This function returns an instance of an I2C bus interface, associated with an IOFramebuffer instance / bus index pair. The number of I2C buses is available from the IOFBGetI2CInterfaceCount() call. The interface may be used with the IOI2CInterfaceOpen/Close/SendRequest() calls to carry out I2C transactions on that bus. Not all graphics devices support this functionality. 190 @param bus The zero based index of the bus on the requested framebuffer. 191 @param interface The interface instance is returned. The caller should release this instance with IOObjectRelease(). 192 @result An IOReturn code. */ 193 194IOReturn IOFBCopyI2CInterfaceForBus( io_service_t framebuffer, IOOptionBits bus, io_service_t * interface ); 195 196typedef struct IOI2CConnect * IOI2CConnectRef; /* struct IOI2CConnect is opaque */ 197 198IOReturn IOI2CCopyInterfaceForID( CFTypeRef identifier, io_service_t * interface ); 199 200/*! @function IOI2CInterfaceOpen 201 @abstract Opens an instance of an I2C bus interface, allowing I2C requests to be made. 202 @discussion An instance of an I2C bus interface, obtained by IOFBCopyI2CInterfaceForBus, is opened with this function allowing I2C requests to be made. 203 @param interface An I2C bus interface (see IOFBCopyI2CInterfaceForBus). The interface may be released after this call is made. 204 @param options Pass kNilOptions. 205 @param connect The opaque IOI2CConnectRef is returned, for use with IOI2CSendRequest() and IOI2CInterfaceClose(). 206 @result An IOReturn code. */ 207 208IOReturn IOI2CInterfaceOpen( io_service_t interface, IOOptionBits options, 209 IOI2CConnectRef * connect ); 210 211/*! @function IOI2CInterfaceClose 212 @abstract Closes an IOI2CConnectRef. 213 @discussion Frees the resources associated with an IOI2CConnectRef. 214 @param connect The opaque IOI2CConnectRef returned by IOI2CInterfaceOpen(). 215 @param options Pass kNilOptions. 216 @result An IOReturn code. */ 217 218IOReturn IOI2CInterfaceClose( IOI2CConnectRef connect, IOOptionBits options ); 219 220/*! @function IOI2CSendRequest 221 @abstract Carries out the I2C transaction specified by an IOI2CRequest structure. 222 @discussion Frees the resources associated with an IOI2CConnectRef. 223 @param connect The opaque IOI2CConnectRef returned by IOI2CInterfaceOpen(). 224 @param options Pass kNilOptions. 225 @param request Pass a pointer to a IOI2CRequest structure describing the request. If an asynchronous request (with a non-NULL completion routine) the request structure must be valid for the life of the request. 226 @result An IOReturn code reflecting only the result of starting the transaction. If the result of IOI2CSendRequest() is kIOReturnSuccess, the I2C transaction result is returned in the result field of the request structure. */ 227 228IOReturn IOI2CSendRequest( IOI2CConnectRef connect, IOOptionBits options, 229 IOI2CRequest * request ); 230 231#else 232 233/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 234 235/*! @class IOI2CInterface 236 @abstract The base class for an I2C bus interface. 237 @discussion The IOI2CInterface base class defines an I2C bus interface. Not useful for developers. */ 238 239class IOI2CInterface : public IOService 240{ 241 OSDeclareDefaultStructors(IOI2CInterface) 242 243protected: 244 UInt64 fID; 245 246public: 247 IOReturn newUserClient( task_t owningTask, 248 void * security_id, 249 UInt32 type, 250 IOUserClient ** handler ); 251 252 bool registerI2C( UInt64 id ); 253 254 virtual IOReturn startIO( IOI2CRequest * request ) = 0; 255}; 256 257/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 258 259#endif /* KERNEL */ 260 261#endif /* ! _IOKIT_IOI2CINTERFACE_H */ 262 263