EDT PDV SDK Documentation 6.1.0
lib_two_wire.h File Reference

(git 08d871f, 2023-10-06)

#include "edtinc.h"
Include dependency graph for lib_two_wire.h:

Data Structures

struct  edt_two_wire
 
struct  EdtRegisterDescriptor
 

Macros

#define TWO_WIRE_SFP   0x03
 
#define TWO_WIRE_XFP   0x06
 
#define TWO_WIRE_SERIAL_ID_DEVICE   0x50
 

Typedefs

typedef struct edt_two_wire EdtTwoWire
 

Enumerations

enum  EdtTwoWireOptions { TWO_WIRE_OPT_CLK_STRETCH = (1 << 0) }
 Two-Wire interface options, for use in EdtTwoWire config struct. More...
 

Functions

int edt_two_wire_reset (EdtDev edt_p, const EdtTwoWire *tw_ptr)
 Reset two wire interface in FPGA. More...
 
uint16_t edt_two_wire_read (EdtDev edt_p, const EdtTwoWire *tw_ptr, uint8_t chip_id, uint32_t address, uint16_t len_data, uint8_t *data)
 Block read transaction. More...
 
int edt_two_wire_write_byte (EdtDev edt_p, const EdtTwoWire *tw_ptr, uint8_t chip_id, uint32_t address, uint8_t data)
 Write a single byte. More...
 
void edt_serial_dev_reg_write (EdtDev edt_p, uint32_t base_desc, uint8_t device_id, uint8_t address, uint8_t value)
 Write to a two-wire I2C or SPI device. More...
 
uint8_t edt_serial_dev_reg_read (EdtDev edt_p, uint32_t base_desc, uint8_t device_id, uint8_t address)
 Read from a two-wire I2C or SPI device. More...
 
uint16_t edt_serial_dev_reg_read_block (EdtDev edt_p, uint32_t base_desc, uint8_t device_id, uint8_t address, uint16_t length, uint8_t *block)
 Block read from a two-wire I2C or SPI device. More...
 
uint16_t edt_serial_dev_reg_write_block (EdtDev edt_p, uint32_t base_desc, uint8_t device_id, uint8_t address, uint16_t length, uint8_t *block)
 Block write to a two-wire I2C or SPI device. More...
 
uint8_t edt_serial_dev_set_bits (EdtDev edt_p, uint32_t base_desc, uint8_t device_id, uint8_t address, uint8_t value, uint8_t offset, uint8_t mask)
 Read/modify/write bits in a data byte on target device. More...
 
uint32_t edt_get_two_wire_value (EdtDev edt_p, const EdtRegisterDescriptor *map, uint32_t base_desc, uint8_t device)
 Read arbitrary value up to 32-bits wide from an 8-bit interface. More...
 
int edt_set_two_wire_value (EdtDev edt_p, const EdtRegisterDescriptor *map, uint32_t base_desc, uint32_t device, uint32_t value)
 Write arbitrary value up to 32-bits wide. More...
 
int edt_two_wire_reg_dump_raw (EdtDev edt_p, const EdtRegisterDescriptor *map, uint32_t base_desc, uint32_t device)
 Read all registers included in a given register map and print to STDOUT. More...
 
int edt_two_wire_reg_dump (EdtDev edt_p, const EdtRegisterDescriptor *map, uint32_t base_desc, uint32_t device)
 Read register fields from a register map and print to STDOUT. More...
 

Detailed Description

Library to read a 2 wire protocol device such as a serial EEPROM or a diagnostic port on a serial transceiver.

The port must be implemented as a register address like the PCISS/GS OCM

  • bit 1 is the two wire clock, it is always an output
  • bit 2 is the two wire serial data out, it is enable onto the serial data when
  • bit 3 enables bit 2 onto the serial data bus when low
  • bit 4 reads back the stat of the serial data wire, it should follow bit 2 when bit 3 is on

The OCM has three 2-wire device addresses:

  1. channel 0 SFP transceiver at 0x23
  2. channel 1 SFP transceiver at 0x33
  3. serial EEPROM calibration - [!] currently unimplemented

Some two wire devices have 1 byte address others 2 etc. The EdtTwoWire::address_length field designates number of bytes.

The page write size varies from device to device. Setting to 1 will work on anything but writes will be slow.

Macro Definition Documentation

◆ TWO_WIRE_SFP

#define TWO_WIRE_SFP   0x03

ID of SFP-type transceivers. Section 4.2 in [1]

◆ TWO_WIRE_XFP

#define TWO_WIRE_XFP   0x06

ID of XFP-type transceivers. Section 4.2 in [1]

◆ TWO_WIRE_SERIAL_ID_DEVICE

#define TWO_WIRE_SERIAL_ID_DEVICE   0x50

I2C Chip ID of SFF transceiver devices.

Typedef Documentation

◆ EdtTwoWire

typedef struct edt_two_wire EdtTwoWire

Two-wire interface configuration.

Enumeration Type Documentation

◆ EdtTwoWireOptions

Two-Wire interface options, for use in EdtTwoWire config struct.

Enumerator
TWO_WIRE_OPT_CLK_STRETCH 

Enable support for I2C targets which may hold the SCL line until data is ready ("clock stretching"). This will cause the software to tristate the FPGA I2C SCL line during a transaction and wait until the line actually goes high.

Function Documentation

◆ edt_two_wire_reset()

int edt_two_wire_reset ( EdtDev  edt_p,
const EdtTwoWire tw_ptr 
)

Reset two wire interface in FPGA.

Send up to 9 SCLKs while reading SDA until SDA is high. Then enable SDA and bring it low to make an I2C start condition.

Parameters
edt_pThe open EDT device handle.
tw_ptrTwo-wire configuration.
Returns
Zero if successful.
Here is the call graph for this function:

◆ edt_two_wire_read()

uint16_t edt_two_wire_read ( EdtDev  edt_p,
const EdtTwoWire tw_ptr,
uint8_t  chip_id,
uint32_t  address,
uint16_t  len_data,
uint8_t *  data 
)

Block read transaction.

Parameters
edt_pThe open EDT device handle.
tw_ptrTwo-wire configuration.
chip_idI2C chip ID of the target device.
addressAddress/command to send to target. Number of bits in address configured by EdtTwoWire::address_length.
len_dataNumber of bytes to read from target device.
[out]dataData read from target device. Must be at least len_data bytes.
Returns
Number of bytes actually read from target.

◆ edt_two_wire_write_byte()

int edt_two_wire_write_byte ( EdtDev  edt_p,
const EdtTwoWire tw_ptr,
uint8_t  chip_id,
uint32_t  address,
uint8_t  data 
)

Write a single byte.

Parameters
edt_pThe open EDT device handle.
tw_ptrTwo-wire configuration.
chip_idI2C chip ID of the target device.
addressAddress/command to send to target. Number of bits in address configured by EdtTwoWire::address_length.
dataByte to send to target.
Returns
Zero if successful.

◆ edt_serial_dev_reg_write()

void edt_serial_dev_reg_write ( EdtDev  edt_p,
uint32_t  base_desc,
uint8_t  device_id,
uint8_t  address,
uint8_t  value 
)

Write to a two-wire I2C or SPI device.

Parameters
edt_pThe open EDT device handle.
base_descThe base address of the FPGA two-wire interface.
device_id7-bit I2C chip id, or address extension for SPI.
addressTarget address/command.
valueData to write to the target.
Here is the caller graph for this function:

◆ edt_serial_dev_reg_read()

uint8_t edt_serial_dev_reg_read ( EdtDev  edt_p,
uint32_t  base_desc,
uint8_t  device_id,
uint8_t  address 
)

Read from a two-wire I2C or SPI device.

Parameters
edt_pThe open EDT device handle.
base_descThe base address of the FPGA two-wire interface.
device_id7-bit I2C chip id, or address extension for SPI.
addressTarget address/command.
Returns
Data read from target.
Here is the caller graph for this function:

◆ edt_serial_dev_reg_read_block()

uint16_t edt_serial_dev_reg_read_block ( EdtDev  edt_p,
uint32_t  base_desc,
uint8_t  device_id,
uint8_t  address,
uint16_t  length,
uint8_t *  block 
)

Block read from a two-wire I2C or SPI device.

Parameters
edt_pThe open EDT device handle.
base_descThe base address of the FPGA two-wire interface.
device_id7-bit I2C chip id, or address extension for SPI.
addressTarget address/command.
lengthNumber of bytes to read from target device.
[out]blockArray of data read from target. Must be at least length bytes.
Returns
Number of bytes read from target.

◆ edt_serial_dev_reg_write_block()

uint16_t edt_serial_dev_reg_write_block ( EdtDev  edt_p,
uint32_t  base_desc,
uint8_t  device_id,
uint8_t  address,
uint16_t  length,
uint8_t *  block 
)

Block write to a two-wire I2C or SPI device.

Address in address will be incremented and sent before each data byte.

Parameters
edt_pThe open EDT device handle.
base_descThe base address of the FPGA two-wire interface.
device_id7-bit I2C chip id, or address extension for SPI.
addressTarget address/command.
lengthNumber of bytes to write to target device.
blockData to send. Must be at least length bytes.
Returns
Number of bytes sent to target.
Here is the call graph for this function:

◆ edt_serial_dev_set_bits()

uint8_t edt_serial_dev_set_bits ( EdtDev  edt_p,
uint32_t  base_desc,
uint8_t  device_id,
uint8_t  address,
uint8_t  value,
uint8_t  offset,
uint8_t  mask 
)

Read/modify/write bits in a data byte on target device.

Useful to set specific bits in a bitfield of a target device register. For example, to set a value of 3 to a 2-bit field with an offset of 4 bits, pass 3 to value, 4 to offset, and 0x3 to mask.

Parameters
edt_pThe open EDT device handle.
base_descThe base address of the FPGA two-wire interface.
device_id7-bit I2C chip id, or address extension for SPI.
addressTarget address/command.
valueData value to write in the bitfield.
offsetBit offset in the target register. value will be left-shifted by this amount.
maskBit mask to clear in byte read from target. Typically indicates the width of the bitfield. The mask will be shifted by offset.
Returns
Copy of the value written to the target.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_get_two_wire_value()

uint32_t edt_get_two_wire_value ( EdtDev  edt_p,
const EdtRegisterDescriptor map,
uint32_t  base_desc,
uint8_t  device 
)

Read arbitrary value up to 32-bits wide from an 8-bit interface.

Parameters
edt_pThe open EDT device handle.
mapDescriptor of register to read from.
base_descThe base address of the FPGA two-wire interface.
device7-bit I2C chip id, or address extension for SPI.
Returns
Data value read from target device.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_set_two_wire_value()

int edt_set_two_wire_value ( EdtDev  edt_p,
const EdtRegisterDescriptor map,
uint32_t  base_desc,
uint32_t  device,
uint32_t  value 
)

Write arbitrary value up to 32-bits wide.

Parameters
edt_pThe open EDT device handle.
mapDescriptor of register to read from.
base_descThe base address of the FPGA two-wire interface.
device7-bit I2C chip id, or address extension for SPI.
valueData value to write to target.
Returns
Zero if successful.
Here is the call graph for this function:

◆ edt_two_wire_reg_dump_raw()

int edt_two_wire_reg_dump_raw ( EdtDev  edt_p,
const EdtRegisterDescriptor map,
uint32_t  base_desc,
uint32_t  device 
)

Read all registers included in a given register map and print to STDOUT.

The entire 8-bit data value read from the target registers is shown. The field offsets and shifts specified in the register map are ignored.

Parameters
edt_pThe open EDT device handle.
mapArray of register descriptors to read from. Last element in the map MUST be all zeros to indicate the end of the array.
base_descThe base address of the FPGA two-wire interface.
device7-bit I2C chip id, or address extension for SPI.
Returns
Zero if successful.
Here is the call graph for this function:

◆ edt_two_wire_reg_dump()

int edt_two_wire_reg_dump ( EdtDev  edt_p,
const EdtRegisterDescriptor map,
uint32_t  base_desc,
uint32_t  device 
)

Read register fields from a register map and print to STDOUT.

Only shows the values of the register fields defined in the provided register map.

Parameters
edt_pThe open EDT device handle.
mapArray of register descriptors to read from. Last element in the map MUST be all zeros to indicate the end of the array.
base_descThe base address of the FPGA two-wire interface.
device7-bit I2C chip id, or address extension for SPI.
Returns
Zero if successful.
Here is the call graph for this function: