Difference between revisions of "Unit I2C"

Revision as of 02:37, 27 May 2022

For the purpose of this interface a device is the I2C controller attached to the local system and may be either a master or a slave. Since the protocol does not include any form of enumeration or identification the interface does not attempt to represent the devices connected to the bus,any driver written to communicate with a connected I2C device should know (or allow configuration of) the address to read and write to and the specific message format required for that device. The Intel System Management Bus (SMBus) is a variation of the I2C bus and in certain cases the two are compatible with each other.

Constants

I2C specific constants I2C_*

`I2C_NAME_PREFIX = 'I2C';`	Name prefix for I2C Devices

I2C device type I2C_TYPE_*

`I2C_TYPE_NONE = 0;`

`I2C_TYPE_MAX = 0;`

I2C device state I2C_STATE_*

`I2C_STATE_DISABLED = 0;`
`I2C_STATE_ENABLED = 1;`

`I2C_STATE_MAX = 1;`

I2C device flag I2C_FLAG_*

`I2C_FLAG_NONE = $00000000;`
`I2C_FLAG_SLAVE = $00000001;`	Device is a slave not a master
`I2C_FLAG_10BIT = $00000002;`	Device supports 10bit addressing
`I2C_FLAG_16BIT = $00000004;`	Device supports 16bit addressing

I2C logging I2C_LOG_*

`I2C_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG;`	I2C debugging messages
`I2C_LOG_LEVEL_INFO = LOG_LEVEL_INFO;`	I2C informational messages, such as a device being attached or detached
`I2C_LOG_LEVEL_WARN = LOG_LEVEL_WARN;`	I2C warning messages
`I2C_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;`	I2C error messages
`I2C_LOG_LEVEL_NONE = LOG_LEVEL_NONE;`	No I2C messages

Type definitions

I2C properties

PI2CProperties = ^TI2CProperties;

TI2CProperties = record

`Flags:LongWord;`	Device flags (eg I2C_FLAG_SLAVE)
`MaxSize:LongWord;`	Maximum supported data transfer size
`MinClock:LongWord;`	Minimum supported clock rate
`MaxClock:LongWord;`	Maximum supported clock rate
`ClockRate:LongWord;`	Current clock rate
`SlaveAddress:Word;`	Current slave address

I2C enumeration callback

`TI2CEnumerate = function(I2C:PI2CDevice; Data:Pointer):LongWord;`

I2C notification callback

`TI2CNotification = function(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;`

I2C device start

`TI2CDeviceStart = function(I2C:PI2CDevice;Rate:LongWord):LongWord;`

I2C device stop

`TI2CDeviceStop = function(I2C:PI2CDevice):LongWord;`

I2C device read

`TI2CDeviceRead = function(I2C:PI2CDevice; Address:Word; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;`

I2C device write

`TI2CDeviceWrite = function(I2C:PI2CDevice; Address:Word; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;`

I2C device write read

`TI2CDeviceWriteRead = function(I2C:PI2CDevice; Address:Word; Initial:Pointer; Len:LongWord; Data:Pointer; Size:LongWord; var Count:LongWord):LongWord;`

I2C device write write

`TI2CDeviceWriteWrite = function(I2C:PI2CDevice; Address:Word; Initial:Pointer; Len:LongWord; Data:Pointer; Size:LongWord; var Count:LongWord):LongWord;`

I2C device get rate

`TI2CDeviceGetRate = function(I2C:PI2CDevice):LongWord;`

I2C device set rate

`TI2CDeviceSetRate = function(I2C:PI2CDevice; Rate:LongWord):LongWord;`

I2C device get address

`TI2CDeviceGetAddress = function(I2C:PI2CDevice):Word;`

I2C device set address

`TI2CDeviceSetAddress = function(I2C:PI2CDevice; Address:Word):LongWord;`

I2C device get properties

`TI2CDeviceGetProperties = function(I2C:PI2CDevice; Properties:PI2CProperties):LongWord;`

I2C device

PI2CDevice = ^TI2CDevice;

TI2CDevice = record

Device Properties
`Device:TDevice;`	The Device entry for this I2C
I2C Properties
`I2CId:LongWord;`	Unique Id of this I2C in the I2C table
`I2CState:LongWord;`	I2C state (eg I2C_STATE_ENABLED)
`DeviceStart:TI2CDeviceStart;`	A Device specific DeviceStart method implementing the standard I2C device interface (Mandatory)
`DeviceStop:TI2CDeviceStop;`	A Device specific DeviceStop method implementing the standard I2C device interface (Mandatory)
`DeviceRead:TI2CDeviceRead;`	A Device specific DeviceRead method implementing the standard I2C device interface (Mandatory)
`DeviceWrite:TI2CDeviceWrite;`	A Device specific DeviceWrite method implementing the standard I2C device interface (Mandatory)
`DeviceWriteRead:TI2CDeviceWriteRead;`	A Device specific DeviceWriteRead method implementing the standard I2C device interface (Or nil if the default method is suitable)
`DeviceWriteWrite:TI2CDeviceWriteWrite;`	A Device specific DeviceWriteWrite method implementing the standard I2C device interface (Or nil if the default method is suitable)
`DeviceGetRate:TI2CDeviceGetRate;`	A Device specific DeviceGetRate method implementing the standard I2C device interface (Or nil if the default method is suitable)
`DeviceSetRate:TI2CDeviceSetRate;`	A Device specific DeviceSetRate method implementing the standard I2C device interface (Or nil if the default method is suitable)
`DeviceGetAddress:TI2CDeviceGetAddress;`	A Device specific DeviceGetAddress method implementing the standard I2C device interface (Or nil if the default method is suitable)
`DeviceSetAddress:TI2CDeviceSetAddress;`	A Device specific DeviceSetAddress method implementing the standard I2C device interface (Or nil if the default method is suitable)
`DeviceGetProperties:TI2CDeviceGetProperties;`	A Device specific DeviceGetProperties method implementing the standard I2C device interface (Or nil if the default method is suitable)
Statistics Properties
`ReadCount:LongWord;`
`WriteCount:LongWord;`
`ReadErrors:LongWord;`
`WriteErrors:LongWord;`
Driver Properties
`Lock:TMutexHandle;`	Device lock
`Wait:TSemaphoreHandle;`	Read/Write wait event
`ClockRate:LongWord;`	Clock rate (Hz)
`SlaveAddress:Word;`	Slave address
`Properties:TI2CProperties;`	Device properties
Internal Properties
`Prev:PI2CDevice;`	Previous entry in I2C table
`Next:PI2CDevice;`	Next entry in I2C table

Public variables

I2C logging

`I2C_DEFAULT_LOG_LEVEL:LongWord = I2C_LOG_LEVEL_DEBUG;`	Minimum level for I2C messages. Only messages with level greater than or equal to this will be printed.

`I2C_LOG_ENABLED:Boolean;`

Function declarations

Initialization functions

procedure I2CInit;

Description: Initialize the I2C unit and I2C device table

Note	Called only during system startup

I2C functions

function I2CDeviceStart(I2C:PI2CDevice; Rate:LongWord):LongWord;

Description: Start the specified I2C device ready for reading and writing

I2C	The I2C device to start
Rate	The clock rate to set for the device (0 to use the default rate)
Return	ERROR_SUCCESS if completed or another error code on failure

function I2CDeviceStop(I2C:PI2CDevice):LongWord;

Description: Stop the specified I2C device and terminate reading and writing

I2C	The I2C device to stop
Return	ERROR_SUCCESS if completed or another error code on failure

function I2CDeviceRead(I2C:PI2CDevice; Address:Word; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;

Description: Read data from the specified I2C device

I2C	The I2C device to read from
Address	The slave address to read from (I2C_ADDRESS_INVALID to use the current address)
Buffer	Pointer to a buffer to receive the data
Size	The size of the buffer
Count	The number of bytes read on return
Return	ERROR_SUCCESS if completed or another error code on failure

function I2CDeviceWrite(I2C:PI2CDevice; Address:Word; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;

Description: Write data to the specified I2C device

I2C	The I2C device to write to
Address	The slave address to write to (I2C_ADDRESS_INVALID to use the current address)
Buffer	Pointer to a buffer of data to transmit
Size	The size of the buffer
Count	The number of bytes written on return
Return	ERROR_SUCCESS if completed or another error code on failure

function I2CDeviceWriteRead(I2C:PI2CDevice; Address:Word; Initial:Pointer; Len:LongWord; Data:Pointer; Size:LongWord; var Count:LongWord):LongWord;

Description: Write data to and Read data from the specified I2C device in one operation

I2C	The I2C device to write to and read from
Address	The slave address to write to (I2C_ADDRESS_INVALID to use the current address)
Initial	Pointer to the initial buffer to transmit
Len	The size of the initial buffer
Data	Pointer to a buffer to receive the data
Size	The size of the data buffer
Count	The number of bytes read on return
Return	ERROR_SUCCESS if completed or another error code on failure
Note	Useful for devices that require a register address specified before a read (eg EEPROM devices)

function I2CDeviceWriteWrite(I2C:PI2CDevice; Address:Word; Initial:Pointer; Len:LongWord; Data:Pointer; Size:LongWord; var Count:LongWord):LongWord;

Description: Write 2 data blocks to the specified I2C device in one operation

I2C	The I2C device to write to
Address	The slave address to write to (I2C_ADDRESS_INVALID to use the current address)
Initial	Pointer to the initial buffer to transmit
Len	The size of the initial buffer
Data	Pointer to a buffer of data to transmit
Size	The size of the data buffer
Count	The number of bytes of data written on return
Return	ERROR_SUCCESS if completed or another error code on failure
Note	Useful for devices that require a register address specified before a write (eg EEPROM devices)

function I2CDeviceGetRate(I2C:PI2CDevice):LongWord;

Description: Get the clock rate of the specified I2C device

I2C	The I2C device to get the clock rate from
Return	The clock rate in Hz or 0 on failure

function I2CDeviceSetRate(I2C:PI2CDevice; Rate:LongWord):LongWord;

Description: Set the clock rate for the specified I2C device

I2C	The I2C device to set the clock rate for
Rate	The clock rate to set in Hz
Return	ERROR_SUCCESS if completed or another error code on failure

function I2CDeviceGetAddress(I2C:PI2CDevice):Word;

Description: Get the slave address for the specified I2C device

I2C	The I2C device to get the slave address from
Return	The slave address or I2C_ADDRESS_INVALID on failure

function I2CDeviceSetAddress(I2C:PI2CDevice; Address:Word):LongWord;

Description: Set the slave address for the specified I2C device

I2C	The I2C device to set the slave address for
Address	The slave address to set
Return	ERROR_SUCCESS if completed or another error code on failure

function I2CDeviceProperties(I2C:PI2CDevice; Properties:PI2CProperties):LongWord; inline;

Description: Get the properties for the specified I2C device

I2C	The I2C device to get properties from
Properties	Pointer to a TI2CProperties structure to fill in
Return	ERROR_SUCCESS if completed or another error code on failure
Note	Replaced by I2CDeviceGetProperties for consistency

function I2CDeviceGetProperties(I2C:PI2CDevice; Properties:PI2CProperties):LongWord;

Description: Get the properties for the specified I2C device

I2C	The I2C device to get properties from
Properties	Pointer to a TI2CProperties structure to fill in
Return	ERROR_SUCCESS if completed or another error code on failure

function I2CDeviceCreate:PI2CDevice;

Description: Create a new I2C entry

Return	Pointer to new I2C entry or nil if I2C could not be created

function I2CDeviceCreateEx(Size:LongWord):PI2CDevice;

Description: Create a new I2C entry

Size	Size in bytes to allocate for new I2C (Including the I2C entry)
Return	Pointer to new I2C entry or nil if I2C could not be created

function I2CDeviceDestroy(I2C:PI2CDevice):LongWord;

Description: Destroy an existing I2C entry

Note	None documented

function I2CDeviceRegister(I2C:PI2CDevice):LongWord;

Description: Register a new I2C in the I2C table

Note	None documented

function I2CDeviceDeregister(I2C:PI2CDevice):LongWord;

Description: Deregister a I2C from the I2C table

Note	None documented

function I2CDeviceFind(I2CId:LongWord):PI2CDevice;

Description: To be documented

Note	None documented

function I2CDeviceFindByName(const Name:String):PI2CDevice; inline;

Description: To be documented

Note	None documented

function I2CDeviceFindByDescription(const Description:String):PI2CDevice; inline;

Description: To be documented

Note	None documented

function I2CDeviceEnumerate(Callback:TI2CEnumerate; Data:Pointer):LongWord;

Description: To be documented

Note	None documented

function I2CDeviceNotification(I2C:PI2CDevice; Callback:TI2CNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;

Description: To be documented

Note	None documented

RTL I2C functions

function SysI2CAvailable:Boolean;

Description: Check if an I2C device is available

Note	None documented

function SysI2CStart(Rate:LongWord):LongWord;

Description: Start the default I2C device ready for reading and writing

Rate	The clock rate to set for the device (0 to use the default rate)
Return	ERROR_SUCCESS if completed or another error code on failure

function SysI2CStop:LongWord;

Description: Stop the default I2C device and terminate reading and writing

Return	ERROR_SUCCESS if completed or another error code on failure

function SysI2CRead(Address:Word; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;

Description: Read data from the default I2C device

Address	The slave address to read from (I2C_ADDRESS_INVALID to use the current address)
Buffer	Pointer to a buffer to receive the data
Size	The size of the buffer
Count	The number of bytes read on return
Return	ERROR_SUCCESS if completed or another error code on failure

function SysI2CWrite(Address:Word; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;

Description: Write data to the default I2C device

Address	The slave address to write to (I2C_ADDRESS_INVALID to use the current address)
Buffer	Pointer to a buffer of data to transmit
Size	The size of the buffer
Count	The number of bytes written on return
Return	ERROR_SUCCESS if completed or another error code on failure

function SysI2CWriteRead(Address:Word; Initial:Pointer; Len:LongWord; Data:Pointer; Size:LongWord; var Count:LongWord):LongWord;

Description: Write data to and Read data from the default I2C device in one operation

Address	The slave address to write to (I2C_ADDRESS_INVALID to use the current address)
Initial	Pointer to the initial buffer to transmit
Len	The size of the initial buffer
Data	Pointer to a buffer to receive the data
Size	The size of the data buffer
Count	The number of bytes read on return
Return	ERROR_SUCCESS if completed or another error code on failure
Note	Useful for devices that require a register address specified before a read (eg EEPROM devices)

function SysI2CWriteWrite(Address:Word; Initial:Pointer; Len:LongWord; Data:Pointer; Size:LongWord; var Count:LongWord):LongWord;

Description: Write 2 data blocks to the default I2C device in one operation

Address	The slave address to write to (I2C_ADDRESS_INVALID to use the current address)
Initial	Pointer to the initial buffer to transmit
Len	The size of the initial buffer
Data	Pointer to a buffer of data to transmit
Size	The size of the data buffer
Count	The number of bytes of data written on return
Return	ERROR_SUCCESS if completed or another error code on failure
Note	Useful for devices that require a register address specified before a write (eg EEPROM devices)

function SysI2CGetRate:LongWord;

Description: Get the clock rate of the default I2C device

Return	The clock rate in Hz or 0 on failure

function SysI2CSetRate(Rate:LongWord):LongWord;

Description: Set the clock rate for the default I2C device

Rate	The clock rate to set in Hz
Return	ERROR_SUCCESS if completed or another error code on failure

function SysI2CGetAddress:Word;

Description: Get the slave address for the default I2C device

Return	The slave address or I2C_ADDRESS_INVALID on failure

function SysI2CSetAddress(Address:Word):LongWord;

Description: Set the slave address for the default I2C device

Address	The slave address to set
Return	ERROR_SUCCESS if completed or another error code on failure

I2C helper functions

function I2CGetCount:LongWord; inline;

Description: Get the current I2C count

Note	None documented

function I2CDeviceGetDefault:PI2CDevice; inline;

Description: Get the current default I2C device

Note	None documented

function I2CDeviceSetDefault(I2C:PI2CDevice):LongWord;

Description: Set the current default I2C device

Note	None documented

function I2CDeviceCheck(I2C:PI2CDevice):PI2CDevice;

Description: Check if the supplied I2C is in the I2C table

Note	None documented

function I2CTypeToString(I2CType:LongWord):String;

Description: Convert an I2C type value to a string

Note	None documented

function I2CStateToString(I2CState:LongWord):String;

Description: Convert an I2C state value to a string

Note	None documented

function I2CIs7BitAddress(Address:Word):Boolean;

Description: Determine if the supplied address is a 7bit address

Note	None documented

function I2CIs10BitAddress(Address:Word):Boolean;

Description: Determine if the supplied address is a 10bit address

Note	None documented

procedure I2CLog(Level:LongWord; I2C:PI2CDevice; const AText:String);

Description: To be documented

Note	None documented

procedure I2CLogInfo(I2C:PI2CDevice; const AText:String); inline;

Description: To be documented

Note	None documented

procedure I2CLogWarn(I2C:PI2CDevice; const AText:String); inline;

Description: To be documented

Note	None documented

procedure I2CLogError(I2C:PI2CDevice; const AText:String); inline;

Description: To be documented

Note	None documented

procedure I2CLogDebug(I2C:PI2CDevice; const AText:String); inline;

Description: To be documented

Note	None documented

Return to Unit Reference

@@ Line 12: / Line 12: @@
 Each device is assigned a 7bit address which is used by the host (or master) to signal the device that a message written to the bus is intended for that device or that the host wants to read data from that device.
+A small number of devices and hosts support 10bit addressing which expands the number of available addresses. The 10bit address format is defined here https://www.i2c-bus.org/addressing/10-bit-addressing/ and the reserved addresses are defined on this page https://www.i2c-bus.org/addressing/
 Speeds range from 10Kbps to 3.4Mbps although the typical speed is either 100Kbps or 400Kbps.
@@ Line 1,066: / Line 1,068: @@
 <pre style="border: 0; padding-bottom:0px;">function I2CStateToString(I2CState:LongWord):String;</pre>
 <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Convert an I2C state value to a string</div>
+<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
+{| class="wikitable" style="font-size: 14px; background: white;"
+|-
+! Note
+| None documented
+|-
+|}
+</div></div>
+<br />
+<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
+<pre style="border: 0; padding-bottom:0px;">function I2CIs7BitAddress(Address:Word):Boolean;</pre>
+<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Determine if the supplied address is a 7bit address</div>
+<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
+{| class="wikitable" style="font-size: 14px; background: white;"
+|-
+! Note
+| None documented
+|-
+|}
+</div></div>
+<br />
+<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
+<pre style="border: 0; padding-bottom:0px;">function I2CIs10BitAddress(Address:Word):Boolean;</pre>
+<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Determine if the supplied address is a 10bit address</div>
 <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 {| class="wikitable" style="font-size: 14px; background: white;"

Difference between revisions of "Unit I2C"

Revision as of 02:37, 27 May 2022

Contents

Description

Constants

Type definitions

Public variables

Function declarations

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools