Documentation/Marvell/Drivers/I2cDriver.txt

1. Introduction
---------------
**MvI2cDxe** is a driver supporting I2C controller on Marvell SOCs boards.
It is connected through protocols to generic UEFI I2C stack, which exposes
IO functionality to drivers of specific devices on I2C bus.

2. MvI2cDxe driver design
--------------------------
MvI2cDxe produces several protocols from generic I2C stack:
 - EFI_I2C_MASTER_PROTOCOL,
 - EFI_I2C_ENUMERATE_PROTOCOL,
 - EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL
 - general-purpose EFI_DRIVER_BINDING_PROTOCOL.

  2.1 EFI_I2C_MASTER_PROTOCOL
  ---------------------------
  This is the most important protocol produced by MvI2cDxe. Following functions
  are implemented:

      ///
      /// Reset the I2C host controller.
      ///
      EFI_I2C_MASTER_PROTOCOL_RESET             Reset;

      ///
      /// Start an I2C transaction in master mode on the host controller.
      ///
      EFI_I2C_MASTER_PROTOCOL_START_REQUEST     StartRequest;

    StartRequest and Reset functions are used by I2cHost.
    These should **not** be used by I2C device drivers - required
    synchronization is not provided. Instead, members of EFI_I2C_IO_PROTOCOL
    should be used.

  2.2 EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL
  -------------------------------------------------
  The only function exposed via this protocol is MvI2cEnableConf. It is
  required by I2C stack in order to allow changing I2C bus configuration from
  device drivers.

  2.3 EFI_I2C_ENUMERATE_PROTOCOL
  ------------------------------
  Provides Enumerate function, which is used by I2cBus code as an iterator over
  devices on I2C bus.

    typedef
    EFI_STATUS
    (EFIAPI *EFI_I2C_ENUMERATE_PROTOCOL_ENUMERATE) (
      IN CONST EFI_I2C_ENUMERATE_PROTOCOL *This,
      IN OUT CONST EFI_I2C_DEVICE         **Device
    );

    ///
    /// Traverse the set of I2C devices on an I2C bus.  This routine
    /// returns the next I2C device on an I2C bus.
    ///
    EFI_I2C_ENUMERATE_PROTOCOL_ENUMERATE         Enumerate;

  MvI2cDevice creates EFI_I2C_DEVICE structure for every device on the bus.
  Due to the fact that hardware-based I2C enumeration isn't safe, information
  about attached devices should be provided through PCDs. After EFI_I2C_DEVICE
  structure is created and filled properly, it is returned to I2cBus. It is
  followed by attachment of I2C device driver.