From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received-SPF: None (no SPF record) identity=mailfrom; client-ip=2a00:1450:400c:c0c::22b; helo=mail-wr0-x22b.google.com; envelope-from=mw@semihalf.com; receiver=edk2-devel@lists.01.org Received: from mail-wr0-x22b.google.com (mail-wr0-x22b.google.com [IPv6:2a00:1450:400c:c0c::22b]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 7984D21E1B764 for ; Sun, 24 Sep 2017 18:42:54 -0700 (PDT) Received: by mail-wr0-x22b.google.com with SMTP id m18so5213516wrm.2 for ; Sun, 24 Sep 2017 18:46:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=semihalf-com.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=OnmGu2C9TFSnAbTiBL4s28PsgCK/uyZSRE3VI8w/1nc=; b=dADriURePEWEE3DTQOpL0Z5AqOAawoVD2uWhuO4OWFVXFMFKYAO7eCV86/6DWyDJ6Y M2M1vetjZeploYF6+BIw6lvbzGSv7PhPpm+3LwqAmZs2eiK2QVnl7eZvWGYl6VaoBF0J 7/FFnqIfWKaoC+8kmyC88IbsV1D5iAhevfluQ0/OmGIthZqX7flYotQn5PaBCQwVbHdl 3ABax3uePnOyjRKb00okiKL1/3jHWnBrCLjzese0Uk+qJmfrpwP4rOTZzFC4CGl2Q9qY FFKdkauulKPMSiZxD0UWCuofHLRGFNrGMKoT0lTmfhPbjaOxpYly/l6n/LDxjcaqaXQm ifgQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=OnmGu2C9TFSnAbTiBL4s28PsgCK/uyZSRE3VI8w/1nc=; b=Uy36jVLdR+Qu9wxoqFfuTB8VLHd7EfFn1eoXCFrnQ2KK+8k+85LkQwocoF/fqMobx2 qaqJupHCTR/8lYeHp0JBh8TKlk2tDFnddstJc7NHuBXND1Y9dovIUtp9KomeMnwAZsLU bMvl64+fNHyUqB6F1KFvK/Z6AuKTTmU3Hqb2KvWjavBQe5jUPE4DGtHEIZV727oKFSkr rk9sDpRPj/9xMYPsC+pmBZb6wIsSCp5NYhFqhlLg7SkAgzRCw1gmcWG4xvifwE9Y1hvp z/G5cNaw+fflW5bJJBp49iPHMM/fjPLdKb6TeerjCG7lW3kTKXob5w7HkotiXcjjecQD glpA== X-Gm-Message-State: AHPjjUgi7jEodyNxwWe2DMyLl1abZHE15ZFHdMr8j5pdkb6eW1rzIzRs nBNGXFbrRzt7FldMJQJpFLMj8WRr6XA= X-Google-Smtp-Source: AOwi7QDMctE7tYK52TV9Z4z3tfw59QHqV08A4Pr2zz24uEBXw/rdzKGsuT0bijR7egfjc7gmrAcSjA== X-Received: by 10.25.233.8 with SMTP id g8mr1822386lfh.197.1506303962118; Sun, 24 Sep 2017 18:46:02 -0700 (PDT) Received: from enkidu.local (31-172-191-173.noc.fibertech.net.pl. [31.172.191.173]) by smtp.gmail.com with ESMTPSA id f16sm809520lfe.66.2017.09.24.18.46.00 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sun, 24 Sep 2017 18:46:01 -0700 (PDT) From: Marcin Wojtas To: edk2-devel@lists.01.org Cc: leif.lindholm@linaro.org, ard.biesheuvel@linaro.org, nadavh@marvell.com, neta@marvell.com, kostap@marvell.com, jinghua@marvell.com, agraf@suse.de, mw@semihalf.com, jsd@semihalf.com, Nir Erez Date: Mon, 25 Sep 2017 03:51:50 +0200 Message-Id: <1506304319-8620-2-git-send-email-mw@semihalf.com> X-Mailer: git-send-email 1.8.3.1 In-Reply-To: <1506304319-8620-1-git-send-email-mw@semihalf.com> References: <1506304319-8620-1-git-send-email-mw@semihalf.com> Subject: [platforms: PATCH 01/10] Silicon/Marvell: Refactor Documentation X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 25 Sep 2017 01:42:55 -0000 From: Nir Erez This patch introduces following improvements to the PortingGuide * Replace split documentation with single file * Update paths to new directory structure in edk2-platforms * Align format to Doxygen constraints Moreover the PortingGuide and remaining Drivers' documentation is moved to the new location under Silicon/Marvell, where in future all other bits of the support will be moved. Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Marcin Wojtas --- Platform/Marvell/Documentation/Drivers/EepromDriver.txt | 96 ----- Platform/Marvell/Documentation/Drivers/I2cDriver.txt | 64 ---- Platform/Marvell/Documentation/Drivers/SpiDriver.txt | 116 ------ Platform/Marvell/Documentation/PortingGuide/ComPhy.txt | 45 --- Platform/Marvell/Documentation/PortingGuide/I2c.txt | 20 -- Platform/Marvell/Documentation/PortingGuide/Mdio.txt | 7 - Platform/Marvell/Documentation/PortingGuide/Mpp.txt | 48 --- Platform/Marvell/Documentation/PortingGuide/PciEmulation.txt | 31 -- Platform/Marvell/Documentation/PortingGuide/Phy.txt | 45 --- Platform/Marvell/Documentation/PortingGuide/Pp2.txt | 35 -- Platform/Marvell/Documentation/PortingGuide/Reset.txt | 7 - Platform/Marvell/Documentation/PortingGuide/Spi.txt | 16 - Platform/Marvell/Documentation/PortingGuide/SpiFlash.txt | 23 -- Platform/Marvell/Documentation/PortingGuide/Utmi.txt | 35 -- Silicon/Marvell/Documentation/Drivers/EepromDriver.txt | 96 +++++ Silicon/Marvell/Documentation/Drivers/I2cDriver.txt | 64 ++++ Silicon/Marvell/Documentation/Drivers/SpiDriver.txt | 116 ++++++ Silicon/Marvell/Documentation/PortingGuide.txt | 373 ++++++++++++++++++++ 18 files changed, 649 insertions(+), 588 deletions(-) diff --git a/Platform/Marvell/Documentation/Drivers/EepromDriver.txt b/Platform/Marvell/Documentation/Drivers/EepromDriver.txt deleted file mode 100644 index d3b3b9f..0000000 --- a/Platform/Marvell/Documentation/Drivers/EepromDriver.txt +++ /dev/null @@ -1,96 +0,0 @@ -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 deleted file mode 100644 index 2f890de..0000000 --- a/Platform/Marvell/Documentation/Drivers/I2cDriver.txt +++ /dev/null @@ -1,64 +0,0 @@ -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 deleted file mode 100644 index 42b5e3c..0000000 --- a/Platform/Marvell/Documentation/Drivers/SpiDriver.txt +++ /dev/null @@ -1,116 +0,0 @@ -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. diff --git a/Platform/Marvell/Documentation/PortingGuide/ComPhy.txt b/Platform/Marvell/Documentation/PortingGuide/ComPhy.txt deleted file mode 100644 index a96015e..0000000 --- a/Platform/Marvell/Documentation/PortingGuide/ComPhy.txt +++ /dev/null @@ -1,45 +0,0 @@ -COMPHY configuration ---------------------------- -In order to configure ComPhy library, following PCDs are available: - - gMarvellTokenSpaceGuid.PcdComPhyDevices - -This array indicates, which ones of the ComPhy chips defined in -MVHW_COMPHY_DESC template will be configured. - -Every ComPhy PCD has part where stands for chip ID (order is not -important, but configuration will be set for first PcdComPhyChipCount chips). - -Every chip has 3 ComPhy PCDs and three of them comprise per-board lanes -settings for this chip. Their format is unicode string, containing settings -for up to 10 lanes. Setting for each one is separated with semicolon. -These PCDs together describe outputs of PHY integrated in simple cihp. -Below is example for the first chip (Chip0). - - gMarvellTokenSpaceGuid.PcdChip0ComPhyTypes - -Unicode string indicating PHY types. Currently supported are: - -{ L"unconnected", L"PCIE0", L"PCIE1", L"PCIE2", L"PCIE3", -L"SATA0", L"SATA1", L"SATA2", L"SATA3", L"SGMII0", -L"SGMII1", L"SGMII2", L"SGMII3", -L"USB3_HOST0", L"USB3_HOST1", L"USB3_DEVICE", -L"RXAUI0", L"RXAUI1", L"SFI" } - - gMarvellTokenSpaceGuid.PcdChip0ComPhySpeeds - -Indicates PHY speeds in MHz. Currently supported are: - -{ 1250, 1500, 2500, 3000, 3125, 5000, 6000, 6250, 10310 } - - gMarvellTokenSpaceGuid.PcdChip0ComPhyInvFlags - -Indicates lane polarity invert. - -Example -------- - #ComPhy - gMarvellTokenSpaceGuid.PcdComPhyDevices|{ 0x1 } - gMarvellTokenSpaceGuid.PcdChip0ComPhyTypes|L"SGMII1;USB3_HOST0;SFI;SATA1;USB3_HOST1;PCIE2" - gMarvellTokenSpaceGuid.PcdChip0ComPhySpeeds|L"1250;5000;10310;5000;5000;5000" - diff --git a/Platform/Marvell/Documentation/PortingGuide/I2c.txt b/Platform/Marvell/Documentation/PortingGuide/I2c.txt deleted file mode 100644 index 020ffb4..0000000 --- a/Platform/Marvell/Documentation/PortingGuide/I2c.txt +++ /dev/null @@ -1,20 +0,0 @@ -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: - Platform/Marvell/Drivers/I2c/MvI2cDxe/MvI2cDxe.inf - - add following line to .fdf file: - INF Platform/Marvell/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) diff --git a/Platform/Marvell/Documentation/PortingGuide/Mdio.txt b/Platform/Marvell/Documentation/PortingGuide/Mdio.txt deleted file mode 100644 index c341d9e..0000000 --- a/Platform/Marvell/Documentation/PortingGuide/Mdio.txt +++ /dev/null @@ -1,7 +0,0 @@ -MDIO driver configuration -------------------------- -MDIO driver provides access to network PHYs' registers via MARVELL_MDIO_READ and -MARVELL_MDIO_WRITE functions (MARVELL_MDIO_PROTOCOL). Following PCD is required: - - gMarvellTokenSpaceGuid.PcdMdioBaseAddress - (base address of SMI management register) diff --git a/Platform/Marvell/Documentation/PortingGuide/Mpp.txt b/Platform/Marvell/Documentation/PortingGuide/Mpp.txt deleted file mode 100644 index 68f0e9d..0000000 --- a/Platform/Marvell/Documentation/PortingGuide/Mpp.txt +++ /dev/null @@ -1,48 +0,0 @@ -MPP configuration ------------------ -Multi-Purpose Ports (MPP) are configurable through platform PCDs. -In order to set desired pin multiplexing, .dsc file needs to be modified. -(Platform/Marvell/Armada/{platform_name}.dsc - please refer to -Documentation/Build.txt for currently supported {platftorm_name} ) -Following PCDs are available: - - gMarvellTokenSpaceGuid.PcdMppChipCount - -Indicates how many different chips are placed on board. So far up to 4 chips -are supported. - -Every MPP PCD has part where - stands for chip ID (order is not important, but configuration will be - set for first PcdMppChipCount chips). - -Below is example for the first chip (Chip0). - - gMarvellTokenSpaceGuid.PcdChip0MppReverseFlag - -Indicates that register order is reversed. (Needs to be used only for AP806-Z1) - - gMarvellTokenSpaceGuid.PcdChip0MppBaseAddress - -This is base address for MPP configuration register. - - gMarvellTokenSpaceGuid.PcdChip0MppPinCount - -Defines how many MPP pins are available. - - gMarvellTokenSpaceGuid.PcdChip0MppSel0 - gMarvellTokenSpaceGuid.PcdChip0MppSel1 - gMarvellTokenSpaceGuid.PcdChip0MppSel2 - -This registers defines functions of 10 pins in ascending order. - -Examples --------- -#APN806-A0 MPP SET - gMarvellTokenSpaceGuid.PcdChip0MppReverseFlag|FALSE - gMarvellTokenSpaceGuid.PcdChip0MppBaseAddress|0xF06F4000 - gMarvellTokenSpaceGuid.PcdChip0MppRegCount|3 - gMarvellTokenSpaceGuid.PcdChip0MppSel0|{ 0x1, 0x1, 0x1, 0x1, 0x1, 0x1, 0x1, 0x1, 0x1, 0x0 } - gMarvellTokenSpaceGuid.PcdChip0MppSel1|{ 0x0, 0x0, 0x0, 0x1, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 } - -Set pin 6 and 7 to 0xa function: - gMarvellTokenSpaceGuid.PcdChip0MppSel0|{ 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0xa, 0xa, 0x0, 0x0 } diff --git a/Platform/Marvell/Documentation/PortingGuide/PciEmulation.txt b/Platform/Marvell/Documentation/PortingGuide/PciEmulation.txt deleted file mode 100644 index ec1afbc..0000000 --- a/Platform/Marvell/Documentation/PortingGuide/PciEmulation.txt +++ /dev/null @@ -1,31 +0,0 @@ -PciEmulation configuration --------------------------- -Installation of various NonDiscoverable devices via PciEmulation driver is performed -via set of PCDs. Following are available: - - gMarvellTokenSpaceGuid.PcdPciEXhci - -Indicates, which Xhci devices are used. - - gMarvellTokenSpaceGuid.PcdPciEAhci - -Indicates, which Ahci devices are used. - - gMarvellTokenSpaceGuid.PcdPciESdhci - -Indicates, which Sdhci devices are used. - -All above PCD's correspond to hardware description in a dedicated structure: - -STATIC PCI_E_PLATFORM_DESC A70x0PlatDescTemplate - -in Platforms/Marvell/PciEmulation/PciEmulation.c file. It comprises device -count, base addresses, register region size and DMA-coherency type. - -Examples --------- -Assuming we want to enable second XHCI port and one SDHCI port on Armada -70x0 board, following needs to be declared: - - gMarvellTokenSpaceGuid.PcdPciEXhci|{ 0x0 0x1 } - gMarvellTokenSpaceGuid.PcdPciESdhci|{ 0x1 } diff --git a/Platform/Marvell/Documentation/PortingGuide/Phy.txt b/Platform/Marvell/Documentation/PortingGuide/Phy.txt deleted file mode 100644 index 69dae02..0000000 --- a/Platform/Marvell/Documentation/PortingGuide/Phy.txt +++ /dev/null @@ -1,45 +0,0 @@ -PHY driver configuration ------------------------- -MvPhyDxe provides basic initialization and status routines for Marvell PHYs. -Currently only 1512 series PHYs are supported. Following PCDs are required: - - gMarvellTokenSpaceGuid.PcdPhyConnectionTypes - (list of values corresponding to PHY_CONNECTION enum) - gMarvellTokenSpaceGuid.PcdPhyStartupAutoneg - (boolean - if true, driver waits for autonegotiation on startup) - gMarvellTokenSpaceGuid.PcdPhyDeviceIds - (list of values corresponding to MV_PHY_DEVICE_ID enum) - -PHY_CONNECTION enum type is defined as follows: - - typedef enum { -0 PHY_CONNECTION_RGMII, -1 PHY_CONNECTION_RGMII_ID, -2 PHY_CONNECTION_RGMII_TXID, -3 PHY_CONNECTION_RGMII_RXID, -4 PHY_CONNECTION_SGMII, -5 PHY_CONNECTION_RTBI, -6 PHY_CONNECTION_XAUI, -7 PHY_CONNECTION_RXAUI - } PHY_CONNECTION; - -MV_PHY_DEVICE_ID: - - typedef enum { -0 MV_PHY_DEVICE_1512, - } MV_PHY_DEVICE_ID; - -It should be extended when adding support for other PHY -models. - -Thus in order to set RGMII for 1st PHY and SGMII for 2nd, PCD should be: - - gMarvellTokenSpaceGuid.PcdPhyConnectionTypes|{ 0x0, 0x4 } - -with disabled autonegotiation: - - gMarvellTokenSpaceGuid.PcdPhyStartupAutoneg|FALSE - -assuming, that PHY models are 1512: - - gMarvellTokenSpaceGuid.PcdPhyDeviceIds|{ 0x0, 0x0 } diff --git a/Platform/Marvell/Documentation/PortingGuide/Pp2.txt b/Platform/Marvell/Documentation/PortingGuide/Pp2.txt deleted file mode 100644 index f05ba27..0000000 --- a/Platform/Marvell/Documentation/PortingGuide/Pp2.txt +++ /dev/null @@ -1,35 +0,0 @@ -Pp2Dxe porting guide --------------------- -Pp2Dxe is driver supporting PP2 NIC on Marvell platforms. Following PCDs -are required to operate: - -Array with used controllers - Set to 0x1 for enabled, 0x0 for disabled: - gMarvellTokenSpaceGuid.PcdPp2Controllers - -Array specifying, to which controller the port belongs to: - gMarvellTokenSpaceGuid.PcdPp2Port2Controller - -Addresses of PHY devices: - gMarvellTokenSpaceGuid.PcdPhySmiAddresses - -Identificators of PP2 ports: - gMarvellTokenSpaceGuid.PcdPp2PortIds - -Indexes used in GOP operation: - gMarvellTokenSpaceGuid.PcdPp2GopIndexes - -Set to 0x1 for always-up interface, 0x0 otherwise: - gMarvellTokenSpaceGuid.PcdPp2InterfaceAlwaysUp - -Values corresponding to PHY_SPEED enum: - gMarvellTokenSpaceGuid.PcdPp2InterfaceSpeed - -PHY_SPEED (in Mbps) is defined as follows: - typedef enum { - 0 NO_SPEED, - 1 SPEED_10, - 2 SPEED_100, - 3 SPEED_1000, - 4 SPEED_2500, - 5 SPEED_10000 - } PHY_SPEED; diff --git a/Platform/Marvell/Documentation/PortingGuide/Reset.txt b/Platform/Marvell/Documentation/PortingGuide/Reset.txt deleted file mode 100644 index 30dec86..0000000 --- a/Platform/Marvell/Documentation/PortingGuide/Reset.txt +++ /dev/null @@ -1,7 +0,0 @@ -MarvellResetSystemLib configuration ------------------------------------ -This simple library allows to mask given bits in given reg at UEFI 'reset' -command call. These variables are configurable through PCDs: - - gMarvellTokenSpaceGuid.PcdResetRegAddress - gMarvellTokenSpaceGuid.PcdResetRegMask diff --git a/Platform/Marvell/Documentation/PortingGuide/Spi.txt b/Platform/Marvell/Documentation/PortingGuide/Spi.txt deleted file mode 100644 index be498a6..0000000 --- a/Platform/Marvell/Documentation/PortingGuide/Spi.txt +++ /dev/null @@ -1,16 +0,0 @@ -Spi driver configuration ------------------------- -Following PCDs are available for configuration of spi driver: - - gMarvellTokenSpaceGuid.PcdSpiClockFrequency - -Frequency (in Hz) of SPI clock - - gMarvellTokenSpaceGuid.PcdSpiMaxFrequency - -Max SCLK line frequency (in Hz) (max transfer frequency) - - gMarvellTokenSpaceGuid.PcdSpiDefaultMode - -default SCLK mode (see SPI_MODE enum in file -Platform/Marvell/Drivers/Spi/MvSpi.h) diff --git a/Platform/Marvell/Documentation/PortingGuide/SpiFlash.txt b/Platform/Marvell/Documentation/PortingGuide/SpiFlash.txt deleted file mode 100644 index 226db40..0000000 --- a/Platform/Marvell/Documentation/PortingGuide/SpiFlash.txt +++ /dev/null @@ -1,23 +0,0 @@ -SpiFlash driver configuration ------------------------------ -Folowing PCDs for spi flash driver configuration must be set properly: - - gMarvellTokenSpaceGuid.PcdSpiFlashAddressCycles - -Size of SPI flash address in bytes (3 or 4) - - gMarvellTokenSpaceGuid.PcdSpiFlashEraseSize - -Size of minimal erase block in bytes - - gMarvellTokenSpaceGuid.PcdSpiFlashPageSize - -Size of SPI flash page - - gMarvellTokenSpaceGuid.PcdSpiFlashId - -Id of SPI flash - - gMarvellTokenSpaceGuid.PcdSpiFlashPollCmd - -Spi flash polling flag diff --git a/Platform/Marvell/Documentation/PortingGuide/Utmi.txt b/Platform/Marvell/Documentation/PortingGuide/Utmi.txt deleted file mode 100644 index cff4843..0000000 --- a/Platform/Marvell/Documentation/PortingGuide/Utmi.txt +++ /dev/null @@ -1,35 +0,0 @@ -UTMI PHY configuration ----------------------- -In order to configure UTMI, following PCDs are available: - - gMarvellTokenSpaceGuid.PcdUtmiPhyCount - -Indicates how many UTMI PHYs are available on platform. - -Next four PCDs are in unicode string format containing settings for all devices -separated with semicolon. - - gMarvellTokenSpaceGuid.PcdUtmiPhyRegUtmiUnit - -Indicates base address of the UTMI unit. - - gMarvellTokenSpaceGuid.PcdUtmiPhyRegUsbCfg - -Indicates address of USB Configuration register. - - gMarvellTokenSpaceGuid.PcdUtmiPhyRegUtmiCfg - -Indicates address of external UTMI configuration. - - gMarvellTokenSpaceGuid.PcdUtmiPhyUtmiPort - -Indicates type of the connected USB port. - -Example -------- -#UtmiPhy - gMarvellTokenSpaceGuid.PcdUtmiPhyCount|2 - gMarvellTokenSpaceGuid.PcdUtmiPhyRegUtmiUnit|L"0xF2580000;0xF2581000" - gMarvellTokenSpaceGuid.PcdUtmiPhyRegUsbCfg|L"0xF2440420;0xF2440420" - gMarvellTokenSpaceGuid.PcdUtmiPhyRegUtmiCfg|L"0xF2440440;0xF2440444" - gMarvellTokenSpaceGuid.PcdUtmiPhyUtmiPort|L"0x0;0x1" diff --git a/Silicon/Marvell/Documentation/Drivers/EepromDriver.txt b/Silicon/Marvell/Documentation/Drivers/EepromDriver.txt new file mode 100644 index 0000000..d3b3b9f --- /dev/null +++ b/Silicon/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/Silicon/Marvell/Documentation/Drivers/I2cDriver.txt b/Silicon/Marvell/Documentation/Drivers/I2cDriver.txt new file mode 100644 index 0000000..2f890de --- /dev/null +++ b/Silicon/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/Silicon/Marvell/Documentation/Drivers/SpiDriver.txt b/Silicon/Marvell/Documentation/Drivers/SpiDriver.txt new file mode 100644 index 0000000..42b5e3c --- /dev/null +++ b/Silicon/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. diff --git a/Silicon/Marvell/Documentation/PortingGuide.txt b/Silicon/Marvell/Documentation/PortingGuide.txt new file mode 100644 index 0000000..aa53329 --- /dev/null +++ b/Silicon/Marvell/Documentation/PortingGuide.txt @@ -0,0 +1,373 @@ +UEFI Porting Guide +================== + +This document provides instructions for adding support for new Marvell Armada +board. For the sake of simplicity new Marvell board will be called "new_board". + +1. Create configuration files for new target + 1.1 Create FDF file for new board + + - Copy and rename edk2-platforms/Platform/Marvell/Armada/Armada70x0.fdf to + edk2-platforms/Platform/Marvell/Armada/new_board.fdf + - Change the first no-comment line: + [FD.Armada70x0_EFI] to [FD.{new_board}_EFI] + + 1.2 Create DSC file for new board + + - Add new_board.dsc file to edk2-platforms/Platform/Marvell/Armada directory + - Insert following [Defines] section to new_board.dsc: + + [Defines] + PLATFORM_NAME = {new_board} + PLATFORM_GUID = {newly_generated_GUID} + PLATFORM_VERSION = 0.1 + DSC_SPECIFICATION = 0x00010019 + OUTPUT_DIRECTORY = {output_directory} + SUPPORTED_ARCHITECTURES = AARCH64 + BUILD_TARGETS = DEBUG|RELEASE + SKUID_IDENTIFIER = DEFAULT + FLASH_DEFINITION = {path_to_fdf_file} + + - Add "!include Armada.dsc.inc" entry to new_board.dsc + +2. Driver support + - According to content of files from + edk2-platforms/Silicon/Marvell/Documentation/PortingGuide.txt + insert PCD entries into new_board.dsc for every needed interface (as listed below). + +3. Compilation + - Refer to edk2-platforms/Platform/Marvell/Readme.md. Remember to change + {platform} to new_board in order to point build system to newly created DSC file. + +4. Output file + - Output files (and among others FD file, which may be used by ATF) are + generated under directory pointed by "OUTPUT_DIRECTORY" entry (see point 1.2). + + +COMPHY configuration +==================== +In order to configure ComPhy library, following PCDs are available: + + - gMarvellTokenSpaceGuid.PcdComPhyDevices + +This array indicates, which ones of the ComPhy chips defined in +MVHW_COMPHY_DESC template will be configured. + +Every ComPhy PCD has part where stands for chip ID (order is not +important, but configuration will be set for first PcdComPhyChipCount chips). + +Every chip has 3 ComPhy PCDs and three of them comprise per-board lanes +settings for this chip. Their format is unicode string, containing settings +for up to 10 lanes. Setting for each one is separated with semicolon. +These PCDs together describe outputs of PHY integrated in simple cihp. +Below is example for the first chip (Chip0). + + - gMarvellTokenSpaceGuid.PcdChip0ComPhyTypes + (Unicode string indicating PHY types. Currently supported are: + + { L"unconnected", L"PCIE0", L"PCIE1", L"PCIE2", L"PCIE3", + L"SATA0", L"SATA1", L"SATA2", L"SATA3", L"SGMII0", + L"SGMII1", L"SGMII2", L"SGMII3", L"QSGMII", + L"USB3_HOST0", L"USB3_HOST1", L"USB3_DEVICE", + L"XAUI0", L"XAUI1", L"XAUI2", L"XAUI3", L"RXAUI0", + L"RXAUI1", L"KR" } ) + + - gMarvellTokenSpaceGuid.PcdChip0ComPhySpeeds + (Indicates PHY speeds in MHz. Currently supported are: + { 1250, 1500, 2500, 3000, 3125, 5000, 6000, 6250, 1031 } ) + + - gMarvellTokenSpaceGuid.PcdChip0ComPhyInvFlags + (Indicates lane polarity invert) + +Example +------- + + #ComPhy + gMarvellTokenSpaceGuid.PcdComPhyDevices|{ 0x1 } + gMarvellTokenSpaceGuid.PcdChip0ComPhyTypes|L"SGMII1;USB3_HOST0;SFI;SATA1;USB3_HOST1;PCIE2" + gMarvellTokenSpaceGuid.PcdChip0ComPhySpeeds|L"1250;5000;10310;5000;5000;5000" + + +PHY Driver configuration +======================== +MvPhyDxe provides basic initialization and status routines for Marvell PHYs. +Currently only 1518 series PHYs are supported. Following PCDs are required: + + - gMarvellTokenSpaceGuid.PcdPhyConnectionTypes + (list of values corresponding to PHY_CONNECTION enum) + - gMarvellTokenSpaceGuid.PcdPhyStartupAutoneg + (boolean - if true, driver waits for autonegotiation on startup) + - gMarvellTokenSpaceGuid.PcdPhyDeviceIds + (list of values corresponding to MV_PHY_DEVICE_ID enum) + +PHY_CONNECTION enum type is defined as follows: + + typedef enum { + 0 PHY_CONNECTION_RGMII, + 1 PHY_CONNECTION_RGMII_ID, + 2 PHY_CONNECTION_RGMII_TXID, + 3 PHY_CONNECTION_RGMII_RXID, + 4 PHY_CONNECTION_SGMII, + 5 PHY_CONNECTION_RTBI, + 6 PHY_CONNECTION_XAUI, + 7 PHY_CONNECTION_RXAUI + } PHY_CONNECTION; + +MV_PHY_DEVICE_ID: + + typedef enum { + 0 MV_PHY_DEVICE_1512, + } MV_PHY_DEVICE_ID; + +It should be extended when adding support for other PHY models. +Thus in order to set RGMII for 1st PHY and SGMII for 2nd, PCD should be: + + gMarvellTokenSpaceGuid.PcdPhyConnectionTypes|{ 0x0, 0x4 } + +with disabled autonegotiation: + + gMarvellTokenSpaceGuid.PcdPhyStartupAutoneg|FALSE + +assuming, that PHY models are 1512: + + gMarvellTokenSpaceGuid.PcdPhyDeviceIds|{ 0x0, 0x0 } + + +MDIO configuration +================== +MDIO driver provides access to network PHYs' registers via EFI_MDIO_READ and +EFI_MDIO_WRITE functions (EFI_MDIO_PROTOCOL). Following PCD is required: + + - gMarvellTokenSpaceGuid.PcdMdioBaseAddress + (base address of SMI management register) + + +I2C configuration +================= +In order to enable driver on a new platform, following steps need to be taken: + - add following line to .dsc file: + edk2-platforms/Platform/Marvell/Drivers/I2c/MvI2cDxe/MvI2cDxe.inf + - add following line to .fdf file: + INF edk2-platforms/Platform/Marvell/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) + + +PciEmulation configuration +========================== +Installation of various NonDiscoverable devices via PciEmulation driver is performed +via set of PCDs. Following are available: + + - gMarvellTokenSpaceGuid.PcdPciEXhci + (Indicates, which Xhci devices are used) + + - gMarvellTokenSpaceGuid.PcdPciEAhci + (Indicates, which Ahci devices are used) + + - gMarvellTokenSpaceGuid.PcdPciESdhci + (Indicates, which Sdhci devices are used) + +All above PCD's correspond to hardware description in a dedicated structure: + +STATIC PCI_E_PLATFORM_DESC A70x0PlatDescTemplate + +in Platform/Marvell/PciEmulation/PciEmulation.c file. It comprises device +count, base addresses, register region size and DMA-coherency type. + +Example +------- + +Assuming we want to enable second XHCI port and one SDHCI port on Armada +70x0 board, following needs to be declared: + + gMarvellTokenSpaceGuid.PcdPciEXhci|{ 0x0 0x1 } + gMarvellTokenSpaceGuid.PcdPciESdhci|{ 0x1 } + + +SATA configuration +================== +There is one additional PCD for AHCI: + + - gMarvellTokenSpaceGuid.PcdSataBaseAddress + (Base address of SATA controller register space - used in SATA ComPhy init + sequence) + + +Pp2Dxe configuration +==================== +Pp2Dxe is driver supporting PP2 NIC on Marvell platforms. Following PCDs +are required to operate: + + - gMarvellTokenSpaceGuid.PcdPp2Controllers + (Array with used controllers + Set to 0x1 for enabled, 0x0 for disabled) + + - gMarvellTokenSpaceGuid.PcdPp2Port2Controller + (Array specifying, to which controller the port belongs to) + + - gMarvellTokenSpaceGuid.PcdPhySmiAddresses + (Addresses of PHY devices) + + - gMarvellTokenSpaceGuid.PcdPp2PortIds + (Identificators of PP2 ports) + + - gMarvellTokenSpaceGuid.PcdPp2GopIndexes + (Indexes used in GOP operation) + + - gMarvellTokenSpaceGuid.PcdPp2InterfaceAlwaysUp + (Set to 0x1 for always-up interface, 0x0 otherwise) + + - gMarvellTokenSpaceGuid.PcdPp2InterfaceSpeed + (Values corresponding to PHY_SPEED enum. + PHY_SPEED is defined as follows: + + typedef enum { + 0 NO_SPEED, + 1 SPEED_10, + 2 SPEED_100, + 3 SPEED_1000, + 4 SPEED_2500, + 5 SPEED_10000 + } PHY_SPEED; + + +UTMI PHY configuration +====================== +In order to configure UTMI, following PCDs are available: + + - gMarvellTokenSpaceGuid.PcdUtmiPhyCount + (Indicates how many UTMI PHYs are available on platform) + +Next four PCDs are in unicode string format containing settings for all devices +separated with semicolon. + + - gMarvellTokenSpaceGuid.PcdUtmiPhyRegUtmiUnit + (Indicates base address of the UTMI unit) + + - gMarvellTokenSpaceGuid.PcdUtmiPhyRegUsbCfg + (Indicates address of USB Configuration register) + + - gMarvellTokenSpaceGuid.PcdUtmiPhyRegUtmiCfg + (Indicates address of external UTMI configuration) + + - gMarvellTokenSpaceGuid.PcdUtmiPhyUtmiPort + (Indicates type of the connected USB port) + +Example +------- + + # UtmiPhy + gMarvellTokenSpaceGuid.PcdUtmiPhyCount|2 + gMarvellTokenSpaceGuid.PcdUtmiPhyRegUtmiUnit|L"0xF2580000;0xF2581000" + gMarvellTokenSpaceGuid.PcdUtmiPhyRegUsbCfg|L"0xF2440420;0xF2440420" + gMarvellTokenSpaceGuid.PcdUtmiPhyRegUtmiCfg|L"0xF2440440;0xF2440444" + gMarvellTokenSpaceGuid.PcdUtmiPhyUtmiPort|L"0x0;0x1" + + +SPI driver configuration +======================== +Following PCDs are available for configuration of spi driver: + + - gMarvellTokenSpaceGuid.PcdSpiClockFrequency + (Frequency (in Hz) of SPI clock) + + - gMarvellTokenSpaceGuid.PcdSpiMaxFrequency + (Max SCLK line frequency (in Hz) (max transfer frequency) ) + + - gMarvellTokenSpaceGuid.PcdSpiDefaultMode + (default SCLK mode (see SPI_MODE enum in file + edk2-platforms/Platform/Marvell/Drivers/Spi/MvSpi.h) ) + + +SpiFlash configuration +====================== +Folowing PCDs for spi flash driver configuration must be set properly: + + - gMarvellTokenSpaceGuid.PcdSpiFlashAddressCycles + (Size of SPI flash address in bytes (3 or 4) ) + + - gMarvellTokenSpaceGuid.PcdSpiFlashEraseSize + (Size of minimal erase block in bytes) + + - gMarvellTokenSpaceGuid.PcdSpiFlashPageSize + (Size of SPI flash page) + + - gMarvellTokenSpaceGuid.PcdSpiFlashId + (Id of SPI flash) + + - gMarvellTokenSpaceGuid.PcdSpiFlashPollCmd + (Spi flash polling flag) + + +MPP configuration +================= +Multi-Purpose Ports (MPP) are configurable through platform PCDs. +In order to set desired pin multiplexing, .dsc file needs to be modified. +(edk2-platforms/Platform/Marvell/Armada/{platform_name}.dsc - please refer to +Documentation/Build.txt for currently supported {platftorm_name} ) +Following PCDs are available: + + - gMarvellTokenSpaceGuid.PcdMppChipCount + (Indicates how many different chips are placed on board. So far up to 4 chips + are supported) + +Every MPP PCD has part where + stands for chip ID (order is not important, but configuration will be + set for first PcdMppChipCount chips). + +Below is example for the first chip (Chip0). + + - gMarvellTokenSpaceGuid.PcdChip0MppReverseFlag + (Indicates that register order is reversed. (Needs to be used only for AP806-Z1) ) + + - gMarvellTokenSpaceGuid.PcdChip0MppBaseAddress + (This is base address for MPP configuration register) + + - gMarvellTokenSpaceGuid.PcdChip0MppPinCount + (Defines how many MPP pins are available) + + - gMarvellTokenSpaceGuid.PcdChip0MppSel0 + - gMarvellTokenSpaceGuid.PcdChip0MppSel1 + - gMarvellTokenSpaceGuid.PcdChip0MppSel2 + (This registers defines functions of 10 pins in ascending order) + +Examples +-------- + + # APN806-A0 MPP SET + gMarvellTokenSpaceGuid.PcdChip0MppReverseFlag|FALSE + gMarvellTokenSpaceGuid.PcdChip0MppBaseAddress|0xF06F4000 + gMarvellTokenSpaceGuid.PcdChip0MppRegCount|3 + gMarvellTokenSpaceGuid.PcdChip0MppSel0|{ 0x1, 0x1, 0x1, 0x1, 0x1, 0x1, 0x1, 0x1, 0x1, 0x0 } + gMarvellTokenSpaceGuid.PcdChip0MppSel1|{ 0x0, 0x0, 0x0, 0x1, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 } + +Set pin 6 and 7 to 0xa function: + gMarvellTokenSpaceGuid.PcdChip0MppSel0|{ 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0xa, 0xa, 0x0, 0x0 } + + +MarvellResetSystemLib configuration +=================================== +This simple library allows to mask given bits in given reg at UEFI 'reset' +command call. These variables are configurable through PCDs: + + - gMarvellTokenSpaceGuid.PcdResetRegAddress + - gMarvellTokenSpaceGuid.PcdResetRegMask + + +Ramdisk configuration +===================== +There is one PCD available for Ramdisk configuration + + - gMarvellTokenSpaceGuid.PcdRamDiskSize + (Defines size of Ramdisk) -- 1.8.3.1