dunedaq::timing::I2CMasterNode Class Reference

#include <I2CMasterNode.hpp>

Inheritance diagram for dunedaq::timing::I2CMasterNode:

Collaboration diagram for dunedaq::timing::I2CMasterNode:

Public Member Functions
	I2CMasterNode (const uhal::Node &node)
	I2CMasterNode (const I2CMasterNode &node)
virtual	~I2CMasterNode ()
virtual uint16_t	get_i2c_clock_prescale () const
virtual std::vector< std::string >	get_slaves () const
virtual uint8_t	get_slave_address (const std::string &name) const
virtual const I2CSlave &	get_slave (const std::string &name) const
void	reset () const
virtual uint8_t	read_i2c (uint8_t i2c_device_address, uint32_t i2c_reg_address, bool atomic=false) const
	commodity functions
virtual void	write_i2c (uint8_t i2c_device_address, uint32_t i2c_reg_address, uint8_t data, bool send_stop=true) const
virtual std::vector< uint8_t >	read_i2cArray (uint8_t i2c_device_address, uint32_t i2c_reg_address, uint32_t number_of_words, bool atomic=false) const
virtual void	write_i2cArray (uint8_t i2c_device_address, uint32_t i2c_reg_address, std::vector< uint8_t > data, bool send_stop=true) const
virtual std::vector< uint8_t >	read_i2cPrimitive (uint8_t i2c_device_address, uint32_t number_of_bytes) const
virtual void	write_i2cPrimitive (uint8_t i2c_device_address, const std::vector< uint8_t > &data, bool send_stop=true) const
bool	ping (uint8_t i2c_device_address, bool throw_excp=false) const
std::vector< uint8_t >	scan () const

Protected Member Functions
virtual std::vector< uint8_t >	read_block_i2c (uint8_t i2c_device_address, uint32_t number_of_bytes, bool send_reset=true) const
virtual void	write_block_i2c (uint8_t i2c_device_address, const std::vector< uint8_t > &data, bool send_stop=true) const
uint8_t	send_i2c_command_and_read_data (uint8_t command) const
void	send_i2c_command_and_write_data (uint8_t command, uint8_t data) const

Protected Attributes
std::unordered_map< std::string, uint8_t >	m_i2c_device_addresses
	Slaves.

Private Member Functions
void	constructor ()
void	wait_until_finished (bool require_acknowledgement=true, bool require_bus_idle_at_end=false) const

Private Attributes
uint16_t	m_clock_prescale
	clock prescale factor
std::unordered_map< std::string, I2CSlave * >	m_i2c_devices
	I2C slaves attached to this node.

Static Private Attributes
static const std::string	kPreHiNode = "ps_hi"
	IPBus register names for i2c bus.
static const std::string	kPreLoNode = "ps_lo"
static const std::string	kCtrlNode = "ctrl"
static const std::string	kTxNode = "data"
static const std::string	kRxNode = "data"
static const std::string	kCmdNode = "cmd_stat"
static const std::string	kStatusNode = "cmd_stat"
static const uint8_t	kStartCmd = 0x80
static const uint8_t	kStopCmd = 0x40
static const uint8_t	kReadFromSlaveCmd = 0x20
static const uint8_t	kWriteToSlaveCmd = 0x10
static const uint8_t	kAckCmd = 0x08
static const uint8_t	kInterruptAck = 0x01
static const uint8_t	kReceivedAckBit = 0x80
static const uint8_t	kBusyBit = 0x40
static const uint8_t	kArbitrationLostBit = 0x20
static const uint8_t	kInProgressBit = 0x2
static const uint8_t	kInterruptBit = 0x1

Friends
class	I2CSlave

Detailed Description

Definition at line 40 of file I2CMasterNode.hpp.

Constructor & Destructor Documentation

I2CMasterNode() [1/2]

I2CMasterNode::I2CMasterNode ( const uhal::Node & node )

explicit

Definition at line 59 of file I2CMasterNode.cpp.

  : uhal::Node(node)
{
  constructor();
}

I2CMasterNode() [2/2]

I2CMasterNode::I2CMasterNode

(

const I2CMasterNode &

node

)

Definition at line 67 of file I2CMasterNode.cpp.

  : uhal::Node(node)
{
  constructor();
}

~I2CMasterNode()

I2CMasterNode::~I2CMasterNode ( )

virtual

Definition at line 98 of file I2CMasterNode.cpp.

{
  std::unordered_map<std::string, I2CSlave*>::iterator it;
  for (it = m_i2c_devices.begin(); it != m_i2c_devices.end(); ++it) {
    // Delete slaves
    delete it->second; // NOLINT
  }
}

Member Function Documentation

constructor()

void I2CMasterNode::constructor ( )

private

Definition at line 76 of file I2CMasterNode.cpp.

{
  // 16 bit clock prescale factor.
  // formula: m_clockPrescale = (input_frequency / 5 / desired_frequency) -1
  // for typical IPbus applications: input frequency = IPbus clock = 31.x MHz
  // target frequency 100 kHz to play it safe (first revision of i2c standard),
  m_clock_prescale = 0x40;
  // m_clock_prescale = 0x100;
 
  // Build the list of slaves
  // Loop over node parameters. Each parameter becomes a slave node.
  const std::unordered_map<std::string, std::string>& parameters = this->getParameters();
  std::unordered_map<std::string, std::string>::const_iterator it;
  for (it = parameters.begin(); it != parameters.end(); ++it) {
    uint32_t slave_addr = (boost::lexical_cast<timing::stoul<uint32_t>>(it->second) & 0x7f); // NOLINT(build/unsigned)
    m_i2c_device_addresses.insert(std::make_pair(it->first, slave_addr));
    m_i2c_devices.insert(std::make_pair(it->first, new I2CSlave(this, slave_addr)));
  }
}

get_i2c_clock_prescale()

virtual uint16_t dunedaq::timing::I2CMasterNode::get_i2c_clock_prescale ( ) const

inlinevirtual

Definition at line 49 of file I2CMasterNode.hpp.

{ return m_clock_prescale; } // NOLINT(build/unsigned)

get_slave()

const I2CSlave & I2CMasterNode::get_slave ( const std::string & name ) const

virtual

Definition at line 134 of file I2CMasterNode.cpp.

{
  std::unordered_map<std::string, I2CSlave*>::const_iterator it = m_i2c_devices.find(name);
  if (it == m_i2c_devices.end()) {
    throw I2CDeviceNotFound(ERS_HERE, getId(), name);
  }
  return *(it->second);
}

get_slave_address()

uint8_t I2CMasterNode::get_slave_address ( const std::string & name ) const

virtual

Definition at line 121 of file I2CMasterNode.cpp.

{
  std::unordered_map<std::string, uint8_t>::const_iterator it = // NOLINT(build/unsigned)
    m_i2c_device_addresses.find(name);
  if (it == m_i2c_device_addresses.end()) {
    throw I2CDeviceNotFound(ERS_HERE, getId(), name);
  }
  return it->second;
}

get_slaves()

std::vector< std::string > I2CMasterNode::get_slaves ( ) const

virtual

Definition at line 110 of file I2CMasterNode.cpp.

{
  std::vector<std::string> slaves;
 
  boost::copy(m_i2c_device_addresses | boost::adaptors::map_keys, std::back_inserter(slaves));
  return slaves;
}

ping()

bool I2CMasterNode::ping	(	uint8_t	i2c_device_address,
		bool	throw_excp = false ) const

Definition at line 309 of file I2CMasterNode.cpp.

{
  // Reset bus before beginning
  reset();
 
  try {
    send_i2c_command_and_write_data(kStartCmd, (i2c_device_address << 1) | 0x01);
    send_i2c_command_and_read_data(kStopCmd | kAckCmd);
    return true;
  } catch (const timing::I2CException& excp) {
    if (throw_excp) {
      throw excp;
    }
    return false;
  }
}

read_block_i2c()

std::vector< uint8_t > I2CMasterNode::read_block_i2c ( uint8_t i2c_device_address, uint32_t number_of_bytes, bool send_reset = true ) const

protectedvirtual

Definition at line 269 of file I2CMasterNode.cpp.

{
  // transmit reg definitions
  // bits 7-1: 7-bit slave address during address transfer
  //           or first 7 bits of byte during data transfer
  // bit 0: RW flag during address transfer or LSB during data transfer.
  //        '1' = reading from slave
  //        '0' = writing to slave
  // command reg definitions
  // bit 7:   Generate start condition
  // bit 6:   Generate stop condition
  // bit 5:   Read from slave
  // bit 4:   Write to slave
  // bit 3:   0 when acknowledgement is received
  // bit 2:1: Reserved
  // bit 0:   Interrupt acknowledge. When set, clears a pending interrupt
 
  // Reset bus before beginning
  if (send_reset)
  {
    reset();
  }
 
  // Open the connection & send the target i2c address. Bit 0 set to 1 (read)
  send_i2c_command_and_write_data(kStartCmd, (i2c_device_address << 1) | 0x01);
 
  std::vector<uint8_t> lArray; // NOLINT(build/unsigned)
  for (unsigned ibyte = 0; ibyte < number_of_bytes; ibyte++) {
 
    uint8_t cmd = ((ibyte == number_of_bytes - 1) ? (kStopCmd | kAckCmd) : 0x0); // NOLINT(build/unsigned)
 
    // Push the cmd on the bus, retrieve the result and put it in the arrary
    lArray.push_back(send_i2c_command_and_read_data(cmd));
  }
  return lArray;
}

read_i2c()

uint8_t I2CMasterNode::read_i2c ( uint8_t i2c_device_address, uint32_t i2c_reg_address, bool atomic = false ) const

virtual

commodity functions

Definition at line 146 of file I2CMasterNode.cpp.

{
  // // write one word containing the address
  // std::vector<uint8_t> array(1, i2c_reg_address & 0x7f);
  // this->write_block_i2c(i2c_device_address, array);
  // // request the content at the specific address
  // return this->read_block_i2c(i2c_device_address, 1) [0];
  return this->read_i2cArray(i2c_device_address, i2c_reg_address, 1, atomic)[0];
}

read_i2cArray()

std::vector< uint8_t > I2CMasterNode::read_i2cArray ( uint8_t i2c_device_address, uint32_t i2c_reg_address, uint32_t number_of_words, bool atomic = false ) const

virtual

Definition at line 175 of file I2CMasterNode.cpp.

{
  // write one word containing the address
  std::vector<uint8_t> lArray{ (uint8_t)(i2c_reg_address & 0xff) }; // NOLINT(build/unsigned)
 
  // do not send stop if read transaction is atomic
  this->write_block_i2c(i2c_device_address, lArray, !atomic);
 
  // request the content at the specific address, 
  // and do not reset bus at begining of transaction (atomic)
  return this->read_block_i2c(i2c_device_address, number_of_words, !atomic);
}

read_i2cPrimitive()

std::vector< uint8_t > I2CMasterNode::read_i2cPrimitive ( uint8_t i2c_device_address, uint32_t number_of_bytes ) const

virtual

Definition at line 213 of file I2CMasterNode.cpp.

{
  return this->read_block_i2c(i2c_device_address, number_of_bytes);
}

reset()

void I2CMasterNode::reset

(

)

const

Definition at line 356 of file I2CMasterNode.cpp.

{
  // Resets the I2C bus
  //
  // This function does the following:
  //        1) Disables the I2C core
  //        2) Sets the clock prescale registers
  //        3) Enables the I2C core
  //        4) Sets all writable bus-master registers to default values
 
  auto ctrl = getNode(kCtrlNode).read();
  auto pre_hi = getNode(kPreHiNode).read();
  auto pre_lo = getNode(kPreLoNode).read();
  getClient().dispatch();
 
  bool full_reset(false);
 
  full_reset = (m_clock_prescale != (pre_hi << 8) + pre_lo);
 
  if (full_reset) {
    // disable the I2C core
    getNode(kCtrlNode).write(0x00);
    getClient().dispatch();
    // set the clock prescale
    getNode(kPreHiNode).write((m_clock_prescale & 0xff00) >> 8);
    // getClient().dispatch();
    getNode(kPreLoNode).write(m_clock_prescale & 0xff);
    // getClient().dispatch();
    // set all writable bus-master registers to default values
    getNode(kTxNode).write(0x00);
    getNode(kCmdNode).write(0x00);
    getClient().dispatch();
 
    // enable the I2C core
    getNode(kCtrlNode).write(0x80);
    getClient().dispatch();
  } else {
    // set all writable bus-master registers to default values
    getNode(kTxNode).write(0x00);
    getNode(kCmdNode).write(0x00);
    getClient().dispatch();
  }
}

scan()

std::vector< uint8_t > I2CMasterNode::scan

(

)

const

Definition at line 329 of file I2CMasterNode.cpp.

{
 
  std::vector<uint8_t> address_vector; // NOLINT(build/unsigned)
 
  // Reset bus before beginning
  reset();
 
  for (uint8_t iaddr(0); iaddr < 0x7f; ++iaddr) { // NOLINT(build/unsigned)
    // Open the connection & send the target i2c address. Bit 0 set to 1 (read)
    try {
      send_i2c_command_and_write_data(kStartCmd, (iaddr << 1) | 0x01);
      send_i2c_command_and_read_data(kStopCmd | kAckCmd);
    } catch (const timing::I2CException& excp) {
      // TIMING_LOG(kError) << std::showbase << std::hex << (uint32_t)iaddr << "  " << excp.what();
      continue;
    }
    address_vector.push_back(iaddr);
    // TIMING_LOG(kNotice) << std::showbase << std::hex << (uint32_t)iaddr << " found";
  }
 
  return address_vector;
}

send_i2c_command_and_read_data()

uint8_t I2CMasterNode::send_i2c_command_and_read_data ( uint8_t command ) const

protected

Definition at line 403 of file I2CMasterNode.cpp.

{
 
  assert(!(command & kWriteToSlaveCmd));
 
  uint8_t full_cmd = command | kReadFromSlaveCmd;                                     // NOLINT(build/unsigned)
  TLOG_DEBUG(10) << ">> sending read cmd  = " << format_reg_value((uint32_t)full_cmd); // NOLINT(build/unsigned)
 
  // Force the read bit high and set them cmd bits
  getNode(kCmdNode).write(full_cmd);
  getClient().dispatch();
 
  // Wait for transaction to finish. Require idle bus at the end if stop bit is high)
  wait_until_finished(/*req ack*/ false, command & kStopCmd);
 
  // Pull the data out of the rx register.
  uhal::ValWord<uint32_t> result = getNode(kRxNode).read(); // NOLINT(build/unsigned)
  getClient().dispatch();
 
  TLOG_DEBUG(10) << "<< receive data      = " << format_reg_value((uint32_t)result); // NOLINT(build/unsigned)v
 
  return (result & 0xff);
}

send_i2c_command_and_write_data()

void I2CMasterNode::send_i2c_command_and_write_data ( uint8_t command, uint8_t data ) const

protected

Definition at line 430 of file I2CMasterNode.cpp.

{
 
  //
  assert(!(command & kReadFromSlaveCmd));
 
  uint8_t full_cmd = command | kWriteToSlaveCmd; // NOLINT(build/unsigned)
  std::stringstream debug_stream;
  debug_stream << ">> sending write cmd = " << std::showbase << std::hex << (uint32_t)full_cmd // NOLINT(build/unsigned)
               << " data = " << std::showbase << std::hex << (uint32_t)data;                   // NOLINT(build/unsigned)
  TLOG_DEBUG(10) << debug_stream.str();
 
  // write the payload
  getNode(kTxNode).write(data);
  getClient().dispatch();
 
  // Force the write bit high and set them cmd bits
  getNode(kCmdNode).write(full_cmd);
 
  // Run the commands and wait for transaction to finish
  getClient().dispatch();
 
  // Wait for transaction to finish. Require idle bus at the end if stop bit is high
  // wait_until_finished(req_hack, requ_idle)
  wait_until_finished( true, command & kStopCmd); // NOLINT
}

wait_until_finished()

void I2CMasterNode::wait_until_finished ( bool require_acknowledgement = true, bool require_bus_idle_at_end = false ) const

private

Definition at line 460 of file I2CMasterNode.cpp.

{
  // Ensures the current bus transaction has finished successfully
  // before allowing further I2C bus transactions
  // This method monitors the status register
  // and will not allow execution to continue until the
  // I2C bus has completed properly.  It will throw an exception
  // if it picks up bus problems or a bus timeout occurs.
  const unsigned max_retry = 20;
  unsigned attempt = 1;
  bool received_acknowledge, busy;
 
  const uhal::Node& status_node = getNode(kStatusNode);
 
  while (attempt <= max_retry) {
    usleep(10);
    // Get the status
    uhal::ValWord<uint32_t> i2c_status = status_node.read(); // NOLINT(build/unsigned)
    getClient().dispatch();
 
    received_acknowledge = !(i2c_status & kReceivedAckBit);
    busy = (i2c_status & kBusyBit);
    bool arbitration_lost = (i2c_status & kArbitrationLostBit);
    bool transfer_in_progress = (i2c_status & kInProgressBit);
 
    if (arbitration_lost) {
      // This is an instant error at any time
      throw I2CBusArbitrationLost(ERS_HERE, getId());
    }
 
    if (!transfer_in_progress) {
      // The transfer looks to have completed successfully,
      // pending further checks
      break;
    }
 
    attempt += 1;
  }
 
  // At this point, we've either had too many retries, or the
  // Transfer in Progress (TIP) bit went low.  If the TIP bit
  // did go low, then we do a couple of other checks to see if
  // the bus operated as expected:
 
  if (attempt > max_retry) {
    throw I2CTransactionTimeout(ERS_HERE, getId());
  }
 
  if (require_acknowledgement && !received_acknowledge) {
    throw I2CNoAcknowledgeReceived(ERS_HERE, getId());
  }
 
  if (require_bus_idle_at_end && busy) {
    throw I2CTransferFinishedBusStillBusy(ERS_HERE, getId());
  }
}

write_block_i2c()

void I2CMasterNode::write_block_i2c ( uint8_t i2c_device_address, const std::vector< uint8_t > & data, bool send_stop = true ) const

protectedvirtual

Definition at line 231 of file I2CMasterNode.cpp.

{
  // transmit reg definitions
  // bits 7-1: 7-bit slave address during address transfer
  //           or first 7 bits of byte during data transfer
  // bit 0: RW flag during address transfer or LSB during data transfer.
  // '1' = reading from slave
  // '0' = writing to slave
  // command reg definitions
  // bit 7: Generate start condition
  // bit 6: Generate stop condition
  // bit 5: Read from slave
  // bit 4: Write to slave
  // bit 3: 0 when acknowledgement is received
  // bit 2:1: Reserved
  // bit 0: Interrupt acknowledge. When set, clears a pending interrupt
 
  // Reset bus before beginning
  reset();
 
  // Open the connection and send the slave address, bit 0 set to zero
  send_i2c_command_and_write_data(kStartCmd, (i2c_device_address << 1) & 0xfe);
 
  for (unsigned ibyte = 0; ibyte < data.size(); ibyte++) {
 
    // Send stop if last element of the array (and not vetoed)
    uint8_t cmd = (((ibyte == data.size() - 1) && send_stop) ? kStopCmd : 0x0); // NOLINT(build/unsigned)
 
    // Push the byte on the bus
    send_i2c_command_and_write_data(cmd, data[ibyte]);
  }
}

write_i2c()

void I2CMasterNode::write_i2c ( uint8_t i2c_device_address, uint32_t i2c_reg_address, uint8_t data, bool send_stop = true ) const

virtual

Definition at line 159 of file I2CMasterNode.cpp.

{
  // std::vector<uint8_t> block(2);
  // block[0] = (i2c_reg_address & 0xff);
  // block[1] = (data & 0xff);
  // this->write_block_i2c(i2c_device_address, block);
 
  this->write_i2cArray(i2c_device_address, i2c_reg_address, { data }, send_stop);
}

write_i2cArray()

void I2CMasterNode::write_i2cArray ( uint8_t i2c_device_address, uint32_t i2c_reg_address, std::vector< uint8_t > data, bool send_stop = true ) const

virtual

Definition at line 194 of file I2CMasterNode.cpp.

{
  // std::cout << "Writing " << data.size() << " from " << std::showbase <<  std::hex << i2c_reg_address << " on " <<
  // (uint32_t)i2c_device_address << std::endl; // HACK
  std::vector<uint8_t> block(data.size() + 1); // NOLINT(build/unsigned)
  block[0] = (i2c_reg_address & 0xff);
 
  for (size_t i(0); i < data.size(); ++i)
    block[i + 1] = data[i];
 
  this->write_block_i2c(i2c_device_address, block, send_stop);
}

write_i2cPrimitive()

void I2CMasterNode::write_i2cPrimitive ( uint8_t i2c_device_address, const std::vector< uint8_t > & data, bool send_stop = true ) const

virtual

Definition at line 221 of file I2CMasterNode.cpp.

{
  this->write_block_i2c(i2c_device_address, data, send_stop);
}

Friends And Related Symbol Documentation

I2CSlave

friend class I2CSlave

friend

Definition at line 134 of file I2CMasterNode.hpp.

Member Data Documentation

kAckCmd

const uint8_t I2CMasterNode::kAckCmd = 0x08

staticprivate

Definition at line 118 of file I2CMasterNode.hpp.

kArbitrationLostBit

const uint8_t I2CMasterNode::kArbitrationLostBit = 0x20

staticprivate

Definition at line 123 of file I2CMasterNode.hpp.

kBusyBit

const uint8_t I2CMasterNode::kBusyBit = 0x40

staticprivate

Definition at line 122 of file I2CMasterNode.hpp.

kCmdNode

const std::string I2CMasterNode::kCmdNode = "cmd_stat"

staticprivate

Definition at line 111 of file I2CMasterNode.hpp.

kCtrlNode

const std::string I2CMasterNode::kCtrlNode = "ctrl"

staticprivate

Definition at line 108 of file I2CMasterNode.hpp.

kInProgressBit

const uint8_t I2CMasterNode::kInProgressBit = 0x2

staticprivate

Definition at line 124 of file I2CMasterNode.hpp.

kInterruptAck

const uint8_t I2CMasterNode::kInterruptAck = 0x01

staticprivate

Definition at line 119 of file I2CMasterNode.hpp.

kInterruptBit

const uint8_t I2CMasterNode::kInterruptBit = 0x1

staticprivate

Definition at line 125 of file I2CMasterNode.hpp.

kPreHiNode

const std::string I2CMasterNode::kPreHiNode = "ps_hi"

staticprivate

IPBus register names for i2c bus.

Definition at line 106 of file I2CMasterNode.hpp.

kPreLoNode

const std::string I2CMasterNode::kPreLoNode = "ps_lo"

staticprivate

Definition at line 107 of file I2CMasterNode.hpp.

kReadFromSlaveCmd

const uint8_t I2CMasterNode::kReadFromSlaveCmd = 0x20

staticprivate

Definition at line 116 of file I2CMasterNode.hpp.

kReceivedAckBit

const uint8_t I2CMasterNode::kReceivedAckBit = 0x80

staticprivate

Definition at line 121 of file I2CMasterNode.hpp.

kRxNode

const std::string I2CMasterNode::kRxNode = "data"

staticprivate

Definition at line 110 of file I2CMasterNode.hpp.

kStartCmd

const uint8_t I2CMasterNode::kStartCmd = 0x80

staticprivate

Definition at line 114 of file I2CMasterNode.hpp.

kStatusNode

const std::string I2CMasterNode::kStatusNode = "cmd_stat"

staticprivate

Definition at line 112 of file I2CMasterNode.hpp.

kStopCmd

const uint8_t I2CMasterNode::kStopCmd = 0x40

staticprivate

Definition at line 115 of file I2CMasterNode.hpp.

kTxNode

const std::string I2CMasterNode::kTxNode = "data"

staticprivate

Definition at line 109 of file I2CMasterNode.hpp.

kWriteToSlaveCmd

const uint8_t I2CMasterNode::kWriteToSlaveCmd = 0x10

staticprivate

Definition at line 117 of file I2CMasterNode.hpp.

m_clock_prescale

uint16_t dunedaq::timing::I2CMasterNode::m_clock_prescale

private

clock prescale factor

Definition at line 128 of file I2CMasterNode.hpp.

m_i2c_device_addresses

std::unordered_map<std::string, uint8_t> dunedaq::timing::I2CMasterNode::m_i2c_device_addresses

protected

Slaves.

Definition at line 96 of file I2CMasterNode.hpp.

m_i2c_devices

std::unordered_map<std::string, I2CSlave*> dunedaq::timing::I2CMasterNode::m_i2c_devices

private

I2C slaves attached to this node.

Definition at line 132 of file I2CMasterNode.hpp.

---

The documentation for this class was generated from the following files:

• /github/workspace/dunedaq/sourcecode/timing/include/timing/I2CMasterNode.hpp
• /github/workspace/dunedaq/sourcecode/timing/src/I2CMasterNode.cpp