Record TI2C

Unit

Declaração

type TI2C = record

Descrição

Este record representa um dispositivo escravo conectado ao barramento I2C acessado a partir da classe TPasRipherals

Visão Geral

Campos

FController: TI2CController;
FPasRipherals: TCustomPasRipherals;

Métodos

function Read(out ABuffer: PUInt8; ABufferSize: UInt32): TI2CTransferResult; overload;
function Read16Bits(out AValue: UInt16; ASwapBytes: Boolean): TI2CTransferResult; overload;
function Read8Bits(out AValue: UInt8): TI2CTransferResult; overload;
function Write(const ABuffer: PUInt8; ABufferSize: UInt32): TI2CTransferResult; overload;
function Write16Bits(AValue: UInt16; ASwapBytes: Boolean): TI2CTransferResult; overload;
function Write8Bits(AValue: UInt8): TI2CTransferResult; overload;
function GetDataLength: UInt16;
function GetEnabled: Boolean;
function GetFIFO: UInt8;
function GetFIFOCanAcceptData: Boolean;
function GetFIFOContainsData: Boolean;
function GetNak: Boolean;
function GetTimeOut: Boolean;
function GetTransferActive: Boolean;
function GetTransferDone: Boolean;
function GetTransferType: TI2CTransferType;
function RegisterA: PUInt32;
function RegisterC: PUInt32;
function RegisterCLKT: PUint32;
function RegisterDEL: PUInt32;
function RegisterDIV: PUInt32;
function RegisterDLEN: PUInt32;
function RegisterFIFO: PUInt32;
function RegisterS: PUInt32;
procedure ClearFIFO;
procedure Read16Bits(out AValue: UInt16; ABaseErrorMessage: String; ASwapBytes: Boolean); overload;
procedure Read8Bits(out AValue: UInt8; ABaseErrorMessage: String); overload;
procedure ResetStatus;
procedure StartTransfer(ATransferType: TI2CTransferType; AClearFifo: Boolean = False);
procedure Write(const ABuffer: PUInt8; ABufferSize: UInt32; ABaseErrorMessage: String); overload;
procedure Write16Bits(AValue: UInt16; ABaseErrorMessage: String; ASwapBytes: Boolean); overload;
procedure Write8Bits(AValue: UInt8; ABaseErrorMessage: String); overload;
procedure SetDataLength(ADataLength: UInt16);
procedure SetEnabled(AEnabled: Boolean);
procedure SetFIFO(AValue: UInt8);
procedure SetNak(AResetNackStatus: Boolean);
procedure SetSlaveAddress(ASalaveAddress: TI2CSlaveAddress);
procedure SetTimeOut(AResetClockStretchStatus: Boolean);
procedure SetTransferDone(AResetTransferDoneStatus: Boolean);

Properties

property DataLength: UInt16 read GetDataLength write SetDataLength;
property Enabled: Boolean read GetEnabled write SetEnabled;
property FIFO: UInt8 read GetFIFO write SetFIFO;
property FIFOCanAcceptData: Boolean read GetFIFOCanAcceptData;
property FIFOContainsData: Boolean read GetFIFOContainsData;
property Nak: Boolean read GetNak write SetNak;
property TimeOut: Boolean read GetTimeOut write SetTimeOut;
property TransferActive: Boolean read GetTransferActive;
property TransferDone: Boolean read GetTransferDone write SetTransferDone;
property TransferType: TI2CTransferType read GetTransferType;

Descrição

Campos

FController: TI2CController;
 
FPasRipherals: TCustomPasRipherals;
 

Métodos

function Read(out ABuffer: PUInt8; ABufferSize: UInt32): TI2CTransferResult; overload;

Lê uma determinada quantidade de bytes a partir do dispositivo escravo. Este método funciona lendo bytes a partir do FIFO.

Segundo o que eu pude entender do DataSheet (p. 33) o registrador FIFO, por meio do seu campo DATA de apenas 8 bits, é apenas a "porta" para o FIFO "real" que tem 16 bytes de tamanho total. Acredito que este FIFO de 16 bytes seja um buffer, o qual é lido por meio do registrador FIFO, de 8 em 8 bits (1 em 1 Byte) até que não haja mais nenhum byte a ser lido a partir do FIFO "real". Uma pista para este comportamento é a descrição do campo RXD do registrador S. Segundo o DataSheet "quando o campo RXD contém 1, significa que o FIFO contém <<pelo menos>> 1 byte". Ora, se o FIFO mencionado fosse o registrador, não faria sentido falar em "pelo menos", já que o campo DATA do registrador FIFO só comporta no máximo 1 UInt8 (8 bits). Logo, concluo que o campo DATA do registrador FIFO é uma "porta" através da qual eu consigo ler o (ou escrver no) FIFO "real", que tem 128 bits (16 Bytes)

Parâmetros
ABuffer
Variável não inicializada que receberá os Bytes lidos a partir do FIFO. Esta variável será inicializada automáticamente pela função e precisará ser desalocada posteriormente pelo chamador
ABufferSize
Quantidade de Bytes que se pretende ler. Este valor será usado pela função para inicializar a variável retornada no parâmetro ABuffer
Retornos

A função retorna um dos possíveis valores da enumeraçao TI2CTransferResult

function Read16Bits(out AValue: UInt16; ASwapBytes: Boolean): TI2CTransferResult; overload;

Esta função lê 2 Bytes (16 bits) a partir do dispositivo escravo, lendo 2 bytes a partir do FIFO.

Parâmetros
AValue
Este parâmetro de saída recebe os dois bytes lidos
ASwapBytes
Caso este parâmetro seja true, os Bytes em AValue são trocados de posição. Eventualmente isso é necessário por causa da incompatibilidade entre a represetação de um PByte com dois bytes e um UInt16 (que tem dois bytes). Para entender melhor, use como exemplo o valor padrão do registrador CONFIG do ADS1115, que é 8583h. Na memória, o buffer lido é semelhante a um array com dois bytes [85,83]. Como se pode ver, a posição dos bytes na memória é na ordem correta de leitura, no entanto números são armazenados na memória da direita para a esquerda, fazendo com que o cast direto a partir dos dois bytes apontandos pelo buffer resultasse no número 8385h, que é errado. Para resolver, usa-se a função Swap, que troca a posição de dois bytes dentro de um UInt16, fazendo com que o resultado fique correto. Alguns sites da internet dizem que isso é por causa do ENDIANESS, a ordem de representação de Bytes na memória, no entanto eu discordo disso porque a comunicação feita com um dispositivo I2C é uma transferência Byte a Byte por meio de um buffer FIFO (first-in, first-out) e isso, naturalmente, enviaria os dois bytes do exemplo na ordem em que eles são vistos no array, por exemplo, [85,83]. Imagine o envio desse array sempre feito na ordem de leitura natural (esquerda para a direita), sendo assim o primeiro byte a chegar no dispositivo escravo é 83 e em seguida 85. O mesmo ocorre quando o dispositivo escravo envia dados ao mestre. Portanto, acho que isso não é um problema clássico de endianess, é simplemente um efeito colataral da forma de envio dos bytes através de um buffer FIFO
Retornos

A função retorna um dos possíveis valores da enumeraçao TI2CTransferResult

function Read8Bits(out AValue: UInt8): TI2CTransferResult; overload;

Esta função lê 1 Byte (8 bits) a partir do dispositivo escravo, lendo 1 byte a partir do FIFO.

Parâmetros
AValue
Este parâmetro de saída recebe o Byte lido
Retornos

A função retorna um dos possíveis valores da enumeraçao TI2CTransferResult

function Write(const ABuffer: PUInt8; ABufferSize: UInt32): TI2CTransferResult; overload;

Escreve uma determinada quantidade de bytes no dispositivo escravo. Este método funciona escrevendo bytes no FIFO.

Parâmetros
ABuffer
Memória que contém os bytes a serem escritos
ABufferSize
Quantidade de bytes a serem escritos. Normalmente este valor é o mesmo valor utilizado para inicializar a variável que será passada em ABuffer
Retornos

A função retorna um dos possíveis valores da enumeração TI2CTransferResult

function Write16Bits(AValue: UInt16; ASwapBytes: Boolean): TI2CTransferResult; overload;

Esta função escreve 2 Bytes (16 bits) no dispositivo escravo, escrevendo 2 Byte no FIFO. ATENÇÃO: NÃO UTILIZE ESTA FUNÇÃO PARA ESCREVER VALORES DE 8 BITS. PARA ESSA FINALIDADE, USE UMA DAS FORMAS DA FUNÇÃO Write8Bits

Parâmetros
AValue
Valor (2 Bytes) a serem escritos
ASwapBytes
Caso este parâmetro seja true, os Bytes em AValue são trocados de posição
See also
Read16Bits
Esta função lê 2 Bytes (16 bits) a partir do dispositivo escravo, lendo 2 bytes a partir do FIFO de forma protegida.
function Write8Bits(AValue: UInt8): TI2CTransferResult; overload;

Esta função escreve 1 Byte (8 bits) no dispositivo escravo, escrevendo 1 Byte no FIFO.

Parâmetros
AValue
Valor a ser escrito
Retornos

A função retorna um dos possíveis valores da enumeraçao TI2CTransferResult

function GetDataLength: UInt16;
 
function GetEnabled: Boolean;
 
function GetFIFO: UInt8;
 
function GetFIFOCanAcceptData: Boolean;
 
function GetFIFOContainsData: Boolean;
 
function GetNak: Boolean;
 
function GetTimeOut: Boolean;
 
function GetTransferActive: Boolean;
 
function GetTransferDone: Boolean;
 
function GetTransferType: TI2CTransferType;
 
function RegisterA: PUInt32;

Esta função retorna um ponteiro para o registrador A, que contém apenas um campo ADDR (Slave Address) de 7 bits que deve conter o endreço do dispositivo a ser acessado. Segundo literatura online, internamente o I2C usa dois valores de endreço, um para escrita e outro para leitura e ambos estes valores derivam do endereço do dispositivo. O que é feito nos bastidores é que é dado um shift left no valor do endereço e o bit menos significante dentre oito bits, indicará a operação, 1 para leitura e 0 para escrita.

Considere o endereço 0x48, cuja forma binária é 0100 1000. Internamente, caso uma operação de leitura for solicitada para este endereço, a informação de endereço a trafegar será 0x91, cuja forma binária é 1001 0001, note que foi aplicado um shift left, o que coloca os bits correspondentes a 0x48 alinhados à esquerda do byte. O bit menos significativo representa a operação de leitura, por isso foi colocado 1 em seu lugar. Da mesma maneira uma operação de escrita, seria representada internamente por 0x90, resultado de 0x48 shl 1, mas mantendo no bit menos significante o valor zero, que neste caso indica uma operação de escrita

function RegisterC: PUInt32;

Esta função retorna um ponteiro para o registrador C, cujos campos são explicados com detalhes nas páginas 29 e 30 do DataSheet

function RegisterCLKT: PUint32;

Esta função retorna um ponteiro para o registrador CLKT, cujo únic campo (TOUT) é explicado com detalhes na página 35 do DataSheet

function RegisterDEL: PUInt32;

Esta função retorna um ponteiro para o registrador DEL, cujos campos são explicados com detalhes na página 34 do DataSheet

function RegisterDIV: PUInt32;

Esta função retorna um ponteiro para o registrador DIV, cujo únic campo (CDIV) é explicado com detalhes na página 34 do DataSheet

function RegisterDLEN: PUInt32;

Esta função retorna um ponteiro para o registrador S, cujos campos são explicados com detalhes nas páginas 32 e 33 do DataSheet

function RegisterFIFO: PUInt32;

Esta função retorna um ponteiro para o registrador FIFO, cujo únic campo (DATA) é explicado com detalhes na página 33 do DataSheet

function RegisterS: PUInt32;

Esta função retorna um ponteiro para o registrador S, cujos campos são explicados com detalhes nas páginas 31 e 32 do DataSheet

procedure ClearFIFO;

Limpa o campo DATA do registrador FIFO, escrevendo 1 no campo CLEAR do registrador C

procedure Read16Bits(out AValue: UInt16; ABaseErrorMessage: String; ASwapBytes: Boolean); overload;

Esta função lê 2 Bytes (16 bits) a partir do dispositivo escravo, lendo 2 bytes a partir do FIFO de forma protegida. Ela levanta exceções em caso de erros. Após executar esta função, caso o fluxo de execução passe dela, signitica que os Bytes foram lidos com suceso

Parâmetros
AValue
Este parâmetro de saída recebe os dois bytes lidos
ABaseErrorMessage
Mensagem de erro a ser apresentada de forma concatenada com o motivo do erro no formato ABaseErrorMessage: Motivo do erro
ASwapBytes
Caso este parâmetro seja true, os Bytes em AValue são trocados de posição
Exceptions raised
EPasRipherals
Esta exceção é levantada com a mensagem de erro informada em ABaseErrorMessage, concatenada com um dos possíveis motivos da falha
See also
TI2CTransferResult
Esta enumeração representa os possíves retornos das funções TI2C.Read e TI2C.Write
procedure Read8Bits(out AValue: UInt8; ABaseErrorMessage: String); overload;

Esta função lê 1 Byte (8 bits) a partir do dispositivo escravo, lendo 1 byte a partir do FIFO de forma protegida. Ela levanta exceções em caso de erro. Após executar esta função, caso o fluxo de execução passe dela, signitica que o Byte foi lido com suceso

Parâmetros
AValue
Este parâmetro de saída recebe o Byte lido
ABaseErrorMessage
Mensagem de erro a ser apresentada de forma concatenada com o motivo do erro no formato ABaseErrorMessage: Motivo do erro
Exceptions raised
EPasRipherals
Esta exceção é levantada com a mensagem de erro informada em ABaseErrorMessage, concatenada com um dos possíveis motivos da falha
See also
TI2CTransferResult
Esta enumeração representa os possíves retornos das funções TI2C.Read e TI2C.Write
procedure ResetStatus;

Resseta os campos DONE, ERR e CLKT do registrador S escrevendo 1 nestes campos

procedure StartTransfer(ATransferType: TI2CTransferType; AClearFifo: Boolean = False);

Inicia a transferência do, ou para o, dispositivo escravo, escrevendo 1 no campo ST do registrador C. Este método também habilita o controlador BSC escrevendo 1 no campo I2CEN do mesmo registrador

Parâmetros
ATransferType
Indica o tipo de transferência a iniciar
AClearFifo
Quando true, também limpa o FIFO em uma única operação. Segundo o DataSheet, caso o campo ST do registrador C seja configurado como 1 ao mesmo tempo que o campo CLEAR do mesmo registrador também o seja, é garantido que o FIFO será limpo antes do início da transferência
See also
TI2CTransferType
Esta enumeração representa o valor do campo READ do registrador C
procedure Write(const ABuffer: PUInt8; ABufferSize: UInt32; ABaseErrorMessage: String); overload;

Escreve uma determinada quantidade de bytes no dispositivo escravo. Este método funciona escrevendo bytes no FIFO de forma protegida. Ela levanta exceções em caso de erros. Após executar esta função, caso o fluxo de execução passe dela, signitica que os Bytes foram escritos com suceso

Parâmetros
ABuffer
Memória que contém os bytes a serem escritos
ABufferSize
Quantidade de bytes a serem escritos. Normalmente este valor é o mesmo valor utilizado para inicializar a variável que será passada em ABuffer
ABaseErrorMessage
Mensagem de erro a ser apresentada de forma concatenada com o motivo do erro no formato ABaseErrorMessage: Motivo do erro
Exceptions raised
EPasRipherals
Esta exceção é levantada com a mensagem de erro informada em ABaseErrorMessage, concatenada com um dos possíveis motivos da falha
See also
TI2CTransferResult
Esta enumeração representa os possíves retornos das funções TI2C.Read e TI2C.Write
procedure Write16Bits(AValue: UInt16; ABaseErrorMessage: String; ASwapBytes: Boolean); overload;

Esta função escreve 2 Bytes (16 bits) no dispositivo escravo, escrevendo 2 Byte no FIFO de forma protegida. Ela levanta exceções em caso de erros. Após executar esta função, caso o fluxo de execução passe dela, signitica que os Bytes foram escritos com suceso. ATENÇÃO: NÃO UTILIZE ESTA FUNÇÃO PARA ESCREVER VALORES DE 8 BITS. PARA ESSA FINALIDADE, USE UMA DAS FORMAS DA FUNÇÃO Write8Bits

Parâmetros
AValue
Valor (2 Bytes) a serem escritos
ABaseErrorMessage
Mensagem de erro a ser apresentada de forma concatenada com o motivo do erro no formato ABaseErrorMessage: Motivo do erro
ASwapBytes
Caso este parâmetro seja true, os Bytes em AValue são trocados de posição
Exceptions raised
EPasRipherals
Esta exceção é levantada com a mensagem de erro informada em ABaseErrorMessage, concatenada com um dos possíveis motivos da falha
See also
TI2CTransferResult
Esta enumeração representa os possíves retornos das funções TI2C.Read e TI2C.Write
procedure Write8Bits(AValue: UInt8; ABaseErrorMessage: String); overload;

Esta função escreve 1 Byte (8 bits) no dispositivo escravo, escrevendo 1 Byte no FIFO de forma protegida. Ela levanta exceções em caso de erros. Após executar esta função, caso o fluxo de execução passe dela, signitica que o byte foi escrito com suceso

Parâmetros
AValue
Valor (1 Byte) a ser escrito
ABaseErrorMessage
Mensagem de erro a ser apresentada de forma concatenada com o motivo do erro no formato ABaseErrorMessage: Motivo do erro
Exceptions raised
EPasRipherals
Esta exceção é levantada com a mensagem de erro informada em ABaseErrorMessage, concatenada com um dos possíveis motivos da falha
See also
TI2CTransferResult
Esta enumeração representa os possíves retornos das funções TI2C.Read e TI2C.Write
procedure SetDataLength(ADataLength: UInt16);
 
procedure SetEnabled(AEnabled: Boolean);
 
procedure SetFIFO(AValue: UInt8);
 
procedure SetNak(AResetNackStatus: Boolean);
 
procedure SetSlaveAddress(ASalaveAddress: TI2CSlaveAddress);
 
procedure SetTimeOut(AResetClockStretchStatus: Boolean);
 
procedure SetTransferDone(AResetTransferDoneStatus: Boolean);
 

Properties

property DataLength: UInt16 read GetDataLength write SetDataLength;

Esta propriedade corresponde ao campo DLEN do registrador DLEN. Ao escrever nela se está definindo a quantidade de bytes que serão lidos ou escritos, dependendo da operação ativa (TransferType). O valor lido desta propriedade quando TransferActive = true ou TransferDone = true, representa o número de bytes que ainda precisam ser lidos ou escritos. Já o valor lido desta propriedade quando TransferActive = false e TransferDone = false, representa o último valor que foi escrito no campo DLEN, pois este campo fica com "sobras" entre envios de vários pacotes.

OBS.: Este texto foi todo traduzido a partir do datasheet. Não foi possível entender muito bem

property Enabled: Boolean read GetEnabled write SetEnabled;

indica se o controlador BSC está ativo ou não. Esta propriedade corresponde ao campo I2CEN do registrador C

property FIFO: UInt8 read GetFIFO write SetFIFO;
 
property FIFOCanAcceptData: Boolean read GetFIFOCanAcceptData;

Se o valor dessa propriedade for false, o FIFO está cheio, do contrário o FIFO tem espaço para pelo menos 1 byte. Esta propriedade corresponde ao campo TXD do registrador S

property FIFOContainsData: Boolean read GetFIFOContainsData;

Se o valor desta propriedade for true, o FIFO contém ao menos 1 byte. Se o valor for false, o FIFO está vazio. Esta propriedade corresponde ao campo RXD do registrador S

property Nak: Boolean read GetNak write SetNak;

Esta propriedade assume o valor true quando o dispositivo referenciado não reconhece seu endereço ou os dados escritos nele (negative acknowledgement). Esta propriedade é uma propriedade cuja escrita tem a função especial de "ressetar" o campo correspondente (campo ERR do registrador S), portanto, apenas configure esta propriedade como True com o intuito de ressetá-la. Configurar esta propriedade como false, não tem efeito algum

property TimeOut: Boolean read GetTimeOut write SetTimeOut;

Esta propriedade assume o valor true quando o dispositivo mantém o sinal SCL num mesmo estado por um período muido longo, o que configura a condição de erro conhecida por "clock stretching". Esta propriedade é uma propriedade cuja escrita tem a função especial de "ressetar" o campo correspondente (campo CLKT do registrador S), portanto, apenas configure esta propriedade como True com o intuito de ressetá-la. Configurar esta propriedade como false, não tem efeito algum

property TransferActive: Boolean read GetTransferActive;

Esta propriedade informa se á alguma transferência ativa. Ela corresponde ao campo TA do registrdor S

property TransferDone: Boolean read GetTransferDone write SetTransferDone;

Esta propriedade assume o valor true quando a transferência for concluída. Ela é uma propriedade cuja escrita tem a função especial de "ressetar" o campo correspondente (campo DONE do registrador S), portanto, apenas configure esta propriedade como True com o intuito de ressetá-la. Configurar esta propriedade como false, não tem efeito algum

property TransferType: TI2CTransferType read GetTransferType;

Informa o tipo de transferência, que pode ser leitura ou escrita. Esta propriedade corresponde ao campo READ do registrador C. Para mais informações leia a respeito de TI2CTransferType


Gerado por PasDoc 0.15.0.