ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference

IOI2CInterface.h

Include Path:	<IOKit/i2c/IOI2CInterface.h>
Path:	/System/Library/Frameworks/IOKit.framework/Versions/A/Headers/i2c/IOI2CInterface.h

Overview

This header contains data structures, functions, and classes related to I2C (I-squared-C, or Inter-IC) busses.

Functions

IOFBCopyI2CInterfaceForBus: Returns an instance of an I2C bus interface, associated with an IOFramebuffer instance / bus index pair.
IOFBGetI2CInterfaceCount: Returns a count of I2C interfaces available associated with an IOFramebuffer instance.
IOI2CInterfaceClose: Closes an IOI2CConnectRef.
IOI2CInterfaceOpen: Opens an instance of an I2C bus interface, allowing I2C requests to be made.
IOI2CSendRequest: Carries out the I2C transaction specified by an IOI2CRequest structure.

IOFBCopyI2CInterfaceForBus

Returns an instance of an I2C bus interface, associated with an IOFramebuffer instance / bus index pair.

IOReturn IOFBCopyI2CInterfaceForBus(
    io_service_t framebuffer,
    IOOptionBits bus,
    io_service_t *interface );

Parameters

bus: The zero based index of the bus on the requested framebuffer.
interface: The interface instance is returned. The caller should release this instance with IOObjectRelease().

Return Value

An IOReturn code.

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.

IOFBGetI2CInterfaceCount

Returns a count of I2C interfaces available associated with an IOFramebuffer instance.

IOReturn IOFBGetI2CInterfaceCount(
    io_service_t framebuffer,
    IOItemCount *count );

Parameters

framebuffer: The io_service_t of an IOFramebuffer instance. CoreGraphics will provide this for a CGDisplay with the CGDisplayIOServicePort() call.
count: Interface count is returned.

Return Value

An IOReturn code.

Discussion

Returns a count of I2C interfaces available associated with an IOFramebuffer instance.

IOI2CInterfaceClose

Closes an IOI2CConnectRef.

IOReturn IOI2CInterfaceClose(
    IOI2CConnectRef connect,
    IOOptionBits options );

Parameters

connect: The opaque IOI2CConnectRef returned by IOI2CInterfaceOpen().
options: Pass kNilOptions.

Return Value

An IOReturn code.

Discussion

Frees the resources associated with an IOI2CConnectRef.

IOI2CInterfaceOpen

Opens an instance of an I2C bus interface, allowing I2C requests to be made.

IOReturn IOI2CInterfaceOpen(
    io_service_t interface,
    IOOptionBits options, 
    IOI2CConnectRef *connect );

Parameters

interface: An I2C bus interface (see IOFBCopyI2CInterfaceForBus). The interface may be released after this call is made.
options: Pass kNilOptions.
connect: The opaque IOI2CConnectRef is returned, for use with IOI2CSendRequest() and IOI2CInterfaceClose().

Return Value

An IOReturn code.

Discussion

An instance of an I2C bus interface, obtained by IOFBCopyI2CInterfaceForBus, is opened with this function allowing I2C requests to be made.

IOI2CSendRequest

Carries out the I2C transaction specified by an IOI2CRequest structure.

IOReturn IOI2CSendRequest(
    IOI2CConnectRef connect,
    IOOptionBits options, 
    IOI2CRequest *request );

Parameters

connect: The opaque IOI2CConnectRef returned by IOI2CInterfaceOpen().
options: Pass kNilOptions.
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.

Return Value

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.

Discussion

Frees the resources associated with an IOI2CConnectRef.

Structs and Unions

IOI2CBusTiming

A structure defining low level timing for an I2C bus.

struct IOI2CBusTiming { 
    AbsoluteTime bitTimeout; 
    AbsoluteTime byteTimeout; 
    AbsoluteTime acknowledgeTimeout; 
    AbsoluteTime startTimeout; 
    AbsoluteTime holdTime; 
    AbsoluteTime riseFallTime; 
    UInt32 __reservedA[8]; 
};

Fields

bitTimeout: Maximum time a slave can delay (by pulling the clock line low) a single bit response.
byteTimeout: Maximum time a slave can delay (by pulling the clock line low) the first bit of a byte response.
acknowledgeTimeout: Maximum time to wait for a slave to respond with an ACK after writing a byte.
startTimeout: Maximum time to wait for a slave to respond after a start signal.
riseFallTime: Time to wait after any change in output signal.
__reservedA: Set to zero.

Discussion

This structure is used to specify timeouts and pulse widths for an I2C bus implementation.

IOI2CRequest

A structure defining an I2C bus transaction.

struct IOI2CRequest { 
    UInt64 __reservedA; 
    IOReturn result; 
    IOI2CRequestCompletion completion; 
    IOOptionBits commFlags; 
    uint64_t minReplyDelay; 
    UInt8 sendAddress; 
    UInt8 sendSubAddress; 
    UInt8 __reservedB[2]; 
    IOOptionBits sendTransactionType; 
    vm_address_t sendBuffer; 
    IOByteCount sendBytes; 
    UInt8 replyAddress; 
    UInt8 replySubAddress; 
    UInt8 __reservedC[2]; 
    IOOptionBits replyTransactionType; 
    vm_address_t replyBuffer; 
    IOByteCount replyBytes; 
    UInt32 __reservedD[16]; 
};

Fields

__reservedA: Set to zero.
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.
completion: A completion routine to be executed when the request completes. If NULL is passed, the request is synchronous, otherwise it may execute asynchronously.
commFlags: Flags that modify the I2C transaction type. The following flags are defined:
kIOI2CUseSubAddressCommFlag Transaction includes a subaddress.
minReplyDelay: Minimum delay as absolute time between send and reply transactions.
sendAddress: I2C address to write.
sendSubAddress: I2C subaddress to write.
__reservedB: Set to zero.
sendTransactionType: The following types of transaction are defined for the send part of the request:
kIOI2CNoTransactionType No send transaction to perform.
kIOI2CSimpleTransactionType Simple I2C message.
kIOI2CCombinedTransactionType Combined format I2C R/~W transaction.
sendBuffer: Pointer to the send buffer.
sendBytes: Number of bytes to send. Set to actual bytes sent on completion of the request.
replyAddress: I2C Address from which to read.
replySubAddress: I2C Address from which to read.
__reservedC: Set to zero.
replyTransactionType: The following types of transaction are defined for the reply part of the request:
kIOI2CNoTransactionType No reply transaction to perform.
kIOI2CSimpleTransactionType Simple I2C message.
kIOI2CDDCciReplyTransactionType DDC/ci message (with embedded length). See VESA DDC/ci specification.
kIOI2CCombinedTransactionType Combined format I2C R/~W transaction.
replyBuffer: Pointer to the reply buffer.
replyBytes: Max bytes to reply (size of replyBuffer). Set to actual bytes received on completion of the request.
__reservedD: Set to zero.

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.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2009-02-23