diff options
Diffstat (limited to 'Platform/Marvell/Documentation/Drivers')
| -rw-r--r-- | Platform/Marvell/Documentation/Drivers/EepromDriver.txt | 96 | ||||
| -rw-r--r-- | Platform/Marvell/Documentation/Drivers/I2cDriver.txt | 64 | ||||
| -rw-r--r-- | Platform/Marvell/Documentation/Drivers/SpiDriver.txt | 116 |
3 files changed, 276 insertions, 0 deletions
diff --git a/Platform/Marvell/Documentation/Drivers/EepromDriver.txt b/Platform/Marvell/Documentation/Drivers/EepromDriver.txt new file mode 100644 index 0000000000..d3b3b9f0d0 --- /dev/null +++ b/Platform/Marvell/Documentation/Drivers/EepromDriver.txt @@ -0,0 +1,96 @@ +1. Introduction
+---------------
+**MvEeprom** driver creates MARVELL_EEPROM_PROTOCOL, which
++is used for managing eeprom.
+
+2. MvEeprom driver design
+-------------------------
+Every I2C device driver should implement EFI_DRIVER_BINDING_PROTOCOL and
+consume EFI_I2C_IO_PROTOCOL for transactions on I2C bus. MvEeprom driver
+additionally implements MARVELL_EEPROM_PROTOCOL.
+
+ 2.1 EFI_DRIVER_BINDING_PROTOCOL
+ -------------------------------
+ Driver Binding protocol is extensively covered in UEFI documentation, as
+ it is not specific to I2C stack. The only difference is that Supported()
+ function should check if EFI_I2C_IO_PROTOCOL provides valid EFI_GUID and
+ DeviceIndex values.
+ Excerpt from MvEepromSupported():
+
+ Status = gBS->OpenProtocol (
+ ControllerHandle,
+ &gEfiI2cIoProtocolGuid,
+ (VOID **) &TmpI2cIo,
+ gImageHandle,
+ ControllerHandle,
+ EFI_OPEN_PROTOCOL_BY_DRIVER
+ );
+ if (EFI_ERROR(Status)) {
+ return EFI_UNSUPPORTED;
+ }
+
+ /* get EEPROM devices' addresses from PCD */
+ EepromAddresses = PcdGetPtr (PcdEepromI2cAddresses);
+ if (EepromAddresses == 0) {
+ Status = EFI_UNSUPPORTED;
+ goto out;
+ }
+
+ Status = EFI_UNSUPPORTED;
+ for (i = 0; EepromAddresses[i] != '\0'; i++) {
+ /* I2C guid must fit and valid DeviceIndex must be provided */
+ if (CompareGuid(TmpI2cIo->DeviceGuid, &I2cGuid) &&
+ TmpI2cIo->DeviceIndex == EepromAddresses[i]) {
+ DEBUG((DEBUG_INFO, "A8kEepromSupported: attached to EEPROM device\n"));
+ Status = EFI_SUCCESS;
+ break;
+ }
+ }
+
+ 2.2 EFI_I2C_IO_PROTOCOL
+ -----------------------
+ This protocol is provided by generic I2C stack. Multiple drivers can use IO
+ protocol at once, as queueing is implemented.
+
+ QueueRequest is a routine that queues an I2C transaction to the I2C
+ controller for execution on the I2C bus.
+
+ 2.3 MARVELL_EEPROM_PROTOCOL
+ -----------------------
+ typedef struct _MARVELL_EEPROM_PROTOCOL MARVELL_EEPROM_PROTOCOL;
+
+ #define EEPROM_READ 0x1
+ #define EEPROM_WRITE 0x0
+ typedef
+ EFI_STATUS
+ (EFIAPI *EFI_EEPROM_TRANSFER) (
+ IN CONST MARVELL_EEPROM_PROTOCOL *This,
+ IN UINT16 Address,
+ IN UINT32 Length,
+ IN UINT8 *Buffer,
+ IN UINT8 Operation
+ );
+
+ struct _MARVELL_EEPROM_PROTOCOL {
+ EFI_EEPROM_TRANSFER Transfer;
+ UINT8 Identifier;
+ };
+
+3. Adding new I2C slave device drivers
+--------------------------------------
+In order to support I2C slave device other than EEPROM, new driver should
+be created. Required steps follow.
+
+ 1. Create driver directory (Platform/Marvell/Drivers/I2c/Devices/...).
+ 2. Create stubs of .inf and .c files (MvEeprom files are a reference),
+ include .inf file in platform .dsc and .fdf files.
+ 3. Implement EFI_DRIVER_BINDING_PROTOCOL - Start(), Stop(), Supported()
+ functions' implementation is a must. EFI_DRIVER_BINDING_PROTOCOL
+ should be installed at driver's entry point.
+ 4. Add I2C address of device to PcdI2cSlaveAddresses in .dsc file.
+ 5. Test available EFI_I2C_IO_PROTOCOLs in Supported() - find instance
+ with valid GUID and DeviceIndex (I2C slave address).
+ 6. Open EFI_I2C_IO_PROTOCOL for usage in Start(). After that, QueueRequest
+ function should be available.
+ 7. Implement core functionality of driver (using QueueRequest to access I2C).
+ 8. (not mandatory) Produce/consume additional protocols.
diff --git a/Platform/Marvell/Documentation/Drivers/I2cDriver.txt b/Platform/Marvell/Documentation/Drivers/I2cDriver.txt new file mode 100644 index 0000000000..2f890de3db --- /dev/null +++ b/Platform/Marvell/Documentation/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/Platform/Marvell/Documentation/Drivers/SpiDriver.txt b/Platform/Marvell/Documentation/Drivers/SpiDriver.txt new file mode 100644 index 0000000000..42b5e3ce3b --- /dev/null +++ b/Platform/Marvell/Documentation/Drivers/SpiDriver.txt @@ -0,0 +1,116 @@ +1. Introduction
+---------------
+**SpiDxe** driver implements MARVELL_SPI_MASTER_PROTOCOL in order to manage SPI
+controller on Marvell A8k boards. It exposes below functionalities:
+ - create and setup SPI slaves
+ - raw transfer over SPI bus
+
+2. SpiDxe driver design
+-----------------------
+
+ 2.1 MARVELL_SPI_MASTER_PROTOCOL
+ -----------------------
+ First member of SPI_MASTER protocol is Init function, implemented for SPI
+ master controller initialization.
+
+ ->Init()
+
+ //
+ //Initializes the host controller to execute SPI commands.
+ //
+
+ param[IN] This Pointer to the MARVELL_SPI_MASTER_PROTOCOL instance
+
+ return EFI_SUCCESS Opcode initialization on the SPI host
+ controller completed.
+ return EFI_ACCESS_DENIED The SPI configuration interface is
+ locked.
+ return EFI_OUT_OF_RESOURCES Not enough resource available to
+ initialize the device.
+ return EFI_DEVICE_ERROR Device error, operation failed.
+
+ ********
+
+ SPI devices (slaves) do not support any kind of automatic discovery or
+ enumaration, so every device needs manual configuration, which may be done
+ with SetupDevice function.
+
+ ->SetupDevice()
+
+ //
+ //Allocate and zero all fields in the SPI_DEVICE struct. Set the chip
+ //select, max frequency and transfer mode supported by slave device.
+ //
+
+ param[IN] Cs Chip select ID of the slave chip.
+ param[IN] MaxFreq Maximum SCK rate in Hz.
+ param[IN] Mode Clock polarity and clock phase.
+
+ return *SPI_DEVICE Pointer to new allocated struct SPI_DEVICE.
+ return NULL NULL pointer if any eroor occured.
+
+ ********
+
+ Developers have to destroy all created SPI device structs (with FreeDevice
+ function) in order to prevent from memory leak.
+
+ ->FreeDevice()
+
+ //
+ //Free any memory associated with a SPI device.
+ //
+
+ param[in] SpiDev Pointer to the SPI_DEVICE struct.
+
+ return EFI_SUCCESS Memory fried succesfully.
+ return EFI_DEVICE_ERROR Device error, operation failed.
+
+ ********
+
+ Transfer function allows write/read raw bytes over SPI bus.
+
+ ->Transfer()
+
+ //
+ //Perform transfer over SPI bus
+ //
+ param[in] This Pointer to the MARVELL_SPI_MASTER_PROTOCOL
+ instance.
+ param[in] Slave Pointer to the SPI_DEVICE struct.
+ param[in] DataByteCount Number of bytes in the data portion of
+ the SPI cycle.
+ param[in] DataOut Pointer to caller-allocated buffer
+ containing the data to send.
+ param[out] DataIn Pointer to caller-allocated buffer
+ where received data will be placed.
+ param[in] Flag Flags which indicate state of CS line
+ during/after transfer (see file
+ Drivers/Spi/Devices/A8kSpiFlash.h)
+
+ return EFI_SUCCESS Memory fried succesfully.
+ return EFI_DEVICE_ERROR Device error, operation failed.
+
+ *********
+
+ When working with SPI devices it is often necessary to perform "command and
+ address" transactions. It may be done via ReadWrite function.
+
+ ->ReadWrite()
+
+ //
+ //Perform two steps transactions. First write Command, then read/write
+ //buffer
+ //
+
+ param[in] This Pointer to the MARVELL_SPI_MASTER_PROTOCOL
+ instance.
+ param[in] Slave Pointer to the SPI_DEVICE struct.
+ param[in] Cmd Pointer to caller-allocated buffer
+ containing the command to send.
+ param[in] CmdSize Size of command (in bytes).
+ param[in] DataOut Pointer to caller-allocated buffer
+ containing the data to send.
+ param[out] DataIn Pointer to caller-allocated buffer
+ where received data will be placed.
+ param[in] DataSize Number of bytes in the data portion of
+ the SPI cycle.
|