IOI2CInterface.h Reference

Declared in
IOI2CInterface.h

Overview

Functions

See the Overview section above for header-level documentation.

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
IOI2CInterface.h

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
IOI2CInterface.h

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
IOI2CInterface.h

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
IOI2CInterface.h

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
IOI2CInterface.h

Data Types

See the Overview section above for header-level documentation.

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 {
   IOOptionBits sendTransactionType;
   IOOptionBits replyTransactionType;
   uint32_t sendAddress;
   uint32_t replyAddress;
   uint8_t sendSubAddress;
   uint8_t replySubAddress;
   uint8_t __reservedA[2];
   uint64_t minReplyDelay;
   IOReturn result;
   IOOptionBits commFlags;
   #if defined(__LP64__)
   uint32_t __padA;
   #else
   vm_address_t sendBuffer;
   #endif
   uint32_t sendBytes;
   uint32_t __reservedB[2];
   #if defined(__LP64__)
   uint32_t __padB;
   #else
   vm_address_t replyBuffer;
   #endif
   uint32_t replyBytes;
   IOI2CRequestCompletion completion;
   #if !defined(__LP64__)
   uint32_t __padC[5];
   #else
   vm_address_t sendBuffer;
   vm_address_t replyBuffer;
   #endif
   uint32_t __reservedC[10];
   #ifdef __ppc__
   uint32_t __reservedD;
   #endif
};
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.