Drivers/I2c: Create MvI2cDxe driver

MvI2cDxe driver was adapted to generic UEFI I2C stack. Connection with
following interfaces was required:
 - EFI_I2C_MASTER_PROTOCOL
 - EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL
 - EFI_I2C_ENUMERATE_PROTOCOL

Driver exports configuration options via PCDs. Configurable options
include:
 - PcdI2cSlaveAddresses - should contain a list of valid I2C devices'
   addresses on bus
 - PcdI2cBaseAddresses - physical address of I2C controller registers
 - PcdI2cClockFrequency - I2c clock frequency on platform

Drivers of devices on I2C bus should never use EFI_I2C_MASTER_PROTOCOL
directly. Instead, these ought to utilise EFI_I2C_IO_PROTOCOL produced
by generic UEFI stack.

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Bartosz Szczepanek <bsz@semihalf.com>
Signed-off-by: Marcin Wojtas <mw@semihalf.com>
Reviewed-by: Leif Lindholm <leif.lindholm@linaro.org>

2 files changed, 84 insertions, 0 deletions

diff --git a/Documentation/Marvell/Drivers/I2cDriver.txt b/Documentation/Marvell/Drivers/I2cDriver.txt
new file mode 100644
index 0000000..2f890de
--- /dev/null
+++ b/Documentation/Marvell/Drivers/I2cDriver.txt
@@ -0,0 +1,64 @@
+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.

+

diff --git a/Documentation/Marvell/PortingGuide/I2c.txt b/Documentation/Marvell/PortingGuide/I2c.txt
new file mode 100644
index 0000000..28ae1ef
--- /dev/null
+++ b/Documentation/Marvell/PortingGuide/I2c.txt
@@ -0,0 +1,20 @@
+1. Porting I2C driver to a new SOC

+----------------------------------

+In order to enable driver on a new platform, following steps need to be taken:

+ - add following line to .dsc file:

+   OpenPlatformPkg/Drivers/I2c/MvI2cDxe/MvI2cDxe.inf

+ - add following line to .fdf file:

+   INF OpenPlatformPkg/Drivers/I2c/MvI2cDxe/MvI2cDxe.inf

+ - add PCDs with relevant values to .dsc file:

+     gMarvellTokenSpaceGuid.PcdI2cSlaveAddresses|{ 0x50, 0x57 }

+   (addresses of I2C slave devices on bus)

+     gMarvellTokenSpaceGuid.PcdI2cSlaveBuses|{ 0x0, 0x0 }

+   (buses to which accoring slaves are attached)

+     gMarvellTokenSpaceGuid.PcdI2cBusCount|2

+   (number of SoC's I2C buses)

+     gMarvellTokenSpaceGuid.PcdI2cBaseAddresses|L"0xF2701000;0xF2701100"

+   (base addresses of I2C controller buses)

+     gMarvellTokenSpaceGuid.PcdI2cClockFrequency|200000000

+   (I2C host controller clock frequency)

+     gMarvellTokenSpaceGuid.PcdI2cBaudRate|100000

+   (baud rate used in I2C transmission)