Difference between revisions of "Unit I2C"

From Ultibo.org
Jump to: navigation, search
Line 4: Line 4:
 
=== Description ===
 
=== Description ===
 
----
 
----
 +
 +
'''Ultibo I2C interface unit'''
  
 
I2C (Inter-Integrated Circuit) is a serial bus for communication between peripheral components.
 
I2C (Inter-Integrated Circuit) is a serial bus for communication between peripheral components.

Revision as of 05:08, 19 December 2016

Return to Unit Reference


Description


Ultibo I2C interface unit

I2C (Inter-Integrated Circuit) is a serial bus for communication between peripheral components.

Originally invented by Phillips the I2C protocol is used by thousands of common chips that perform a wide range of tasks such as real time clocks, temperature and other sensors, small LCD displays and many more.

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.

Speeds range from 10Kbps to 3.4Mbps although the typical speed is either 100Kbps or 400Kbps.

This unit implements the standardized interface for I2C devices and allows reading or writing to a specific address, setting a clock rate for the communication and determining device properties.

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 constants I2C_TYPE_*
I2C_TYPE_NONE = 0;  


I2C device state constants I2C_STATE_*
I2C_STATE_DISABLED = 0;  
I2C_STATE_ENABLED = 1;  


I2C device flag constants 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 constants 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_ERROR = LOG_LEVEL_ERROR; I2C error messages
I2C_LOG_LEVEL_NONE = LOG_LEVEL_NONE; No I2C messages


Type definitions


To be documented

Public variables


To be documented

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. Useful for devices that require a register address specified before a read (eg EEPROM devices)
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


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. Useful for devices that require a register address specified before a write (eg EEPROM devices)
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


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;
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. Useful for devices that require a register address specified before a read (eg EEPROM devices)
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


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. Useful for devices that require a register address specified before a write (eg EEPROM devices)
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


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


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 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