[edk2-devel] [edk2-platforms][PATCH V3 07/17] Platform/ARM: Create NorFlashDeviceLib library interface for flash specific functions

["Sahil Kaushal" <sahil.kaushal@arm.com>]

From: sahil <sahil@arm.com>

NorFlashDeviceLib can be used to provide implementations of different
NOR Flash to NorFlashDxe, i.e. NorFlashDxe links with NorFlashDeviceLib
and the platforms can specify their respective NorFlashDeviceLib
instances.

This patch splits NorFlash.h and moves out the function prototypes and
macros that are expected by NorFlashDxe to be implemented by any
Nor Flash implementation to NorFlashDeviceLib.h file.

Signed-off-by: sahil <sahil@arm.com>
---
 Platform/ARM/ARM.dec                              |   1 +
 Platform/ARM/Drivers/NorFlashDxe/NorFlash.h       | 105 +--------
 Platform/ARM/Drivers/NorFlashDxe/NorFlashCommon.h |   1 +
 Platform/ARM/Include/Library/NorFlashDeviceLib.h  | 236 ++++++++++++++++++++
 4 files changed, 239 insertions(+), 104 deletions(-)

diff --git a/Platform/ARM/ARM.dec b/Platform/ARM/ARM.dec
index be7e6dc83fde..86d1fcb4878e 100644
--- a/Platform/ARM/ARM.dec
+++ b/Platform/ARM/ARM.dec
@@ -17,6 +17,7 @@
 
 [LibraryClasses]
   BdsLib|Include/Library/BdsLib.h
+  NorFlashDeviceLib|Include/Library/NorFlashDeviceLib.h
   NorFlashPlatformLib|Include/Library/NorFlashPlatformLib.h
 
 [Guids]
diff --git a/Platform/ARM/Drivers/NorFlashDxe/NorFlash.h b/Platform/ARM/Drivers/NorFlashDxe/NorFlash.h
index f30d499042ed..6cb1f64b9875 100644
--- a/Platform/ARM/Drivers/NorFlashDxe/NorFlash.h
+++ b/Platform/ARM/Drivers/NorFlashDxe/NorFlash.h
@@ -20,6 +20,7 @@
 
 #include <Library/DebugLib.h>
 #include <Library/IoLib.h>
+#include <Library/NorFlashDeviceLib.h>
 
 #define NOR_FLASH_ERASE_RETRY  10
 
@@ -40,7 +41,6 @@
 #define CREATE_NOR_ADDRESS(BaseAddr, OffsetAddr)       ((BaseAddr) + ((OffsetAddr) << 2))
 #define CREATE_DUAL_CMD(Cmd)                           ( ( Cmd << 16) | ( Cmd & LOW_16_BITS) )
 #define SEND_NOR_COMMAND(BaseAddr, Offset, Cmd)        MmioWrite32 (CREATE_NOR_ADDRESS(BaseAddr,Offset), CREATE_DUAL_CMD(Cmd))
-#define GET_NOR_BLOCK_ADDRESS(BaseAddr, Lba, LbaSize)  ( BaseAddr + (UINTN)((Lba) * LbaSize) )
 
 // Status Register Bits
 #define P30_SR_BIT_WRITE            (BIT7 << 16 | BIT7)
@@ -105,107 +105,4 @@
 #define P30_CMD_READ_CONFIGURATION_REGISTER_SETUP  0x0060
 #define P30_CMD_READ_CONFIGURATION_REGISTER        0x0003
 
-typedef struct _NOR_FLASH_INSTANCE NOR_FLASH_INSTANCE;
-
-#pragma pack (1)
-typedef struct {
-  VENDOR_DEVICE_PATH          Vendor;
-  UINT8                       Index;
-  EFI_DEVICE_PATH_PROTOCOL    End;
-} NOR_FLASH_DEVICE_PATH;
-#pragma pack ()
-
-struct _NOR_FLASH_INSTANCE {
-  UINT32                                 Signature;
-  EFI_HANDLE                             Handle;
-
-  UINTN                                  DeviceBaseAddress;
-  UINTN                                  RegionBaseAddress;
-  UINTN                                  Size;
-  EFI_LBA                                StartLba;
-
-  EFI_BLOCK_IO_PROTOCOL                  BlockIoProtocol;
-  EFI_BLOCK_IO_MEDIA                     Media;
-  EFI_DISK_IO_PROTOCOL                   DiskIoProtocol;
-
-  EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL    FvbProtocol;
-  VOID                                   *ShadowBuffer;
-
-  NOR_FLASH_DEVICE_PATH                  DevicePath;
-};
-
-//
-// NorFlash.c
-//
-EFI_STATUS
-NorFlashWriteSingleBlock (
-  IN        NOR_FLASH_INSTANCE  *Instance,
-  IN        EFI_LBA             Lba,
-  IN        UINTN               Offset,
-  IN OUT    UINTN               *NumBytes,
-  IN        UINT8               *Buffer
-  );
-
-EFI_STATUS
-NorFlashWriteBlocks (
-  IN  NOR_FLASH_INSTANCE  *Instance,
-  IN  EFI_LBA             Lba,
-  IN  UINTN               BufferSizeInBytes,
-  IN  VOID                *Buffer
-  );
-
-EFI_STATUS
-NorFlashReadBlocks (
-  IN NOR_FLASH_INSTANCE  *Instance,
-  IN EFI_LBA             Lba,
-  IN UINTN               BufferSizeInBytes,
-  OUT VOID               *Buffer
-  );
-
-EFI_STATUS
-NorFlashRead (
-  IN NOR_FLASH_INSTANCE  *Instance,
-  IN EFI_LBA             Lba,
-  IN UINTN               Offset,
-  IN UINTN               BufferSizeInBytes,
-  OUT VOID               *Buffer
-  );
-
-EFI_STATUS
-NorFlashReset (
-  IN  NOR_FLASH_INSTANCE  *Instance
-  );
-
-EFI_STATUS
-NorFlashEraseSingleBlock (
-  IN NOR_FLASH_INSTANCE  *Instance,
-  IN UINTN               BlockAddress
-  );
-
-EFI_STATUS
-NorFlashWriteFullBlock (
-  IN NOR_FLASH_INSTANCE  *Instance,
-  IN EFI_LBA             Lba,
-  IN UINT32              *DataBuffer,
-  IN UINT32              BlockSizeInWords
-  );
-
-EFI_STATUS
-NorFlashUnlockAndEraseSingleBlock (
-  IN NOR_FLASH_INSTANCE  *Instance,
-  IN UINTN               BlockAddress
-  );
-
-VOID
-EFIAPI
-NorFlashLock (
-  IN EFI_TPL  *OriginalTPL
-  );
-
-VOID
-EFIAPI
-NorFlashUnlock (
-  IN EFI_TPL OriginalTPL
-  );
-
 #endif /* __NOR_FLASH_H__ */
diff --git a/Platform/ARM/Drivers/NorFlashDxe/NorFlashCommon.h b/Platform/ARM/Drivers/NorFlashDxe/NorFlashCommon.h
index c0a3b5861532..7fcb949843e8 100644
--- a/Platform/ARM/Drivers/NorFlashDxe/NorFlashCommon.h
+++ b/Platform/ARM/Drivers/NorFlashDxe/NorFlashCommon.h
@@ -19,6 +19,7 @@
 #include <Protocol/FirmwareVolumeBlock.h>
 
 #include <Library/DebugLib.h>
+#include <Library/NorFlashDeviceLib.h>
 #include <Library/NorFlashPlatformLib.h>
 #include <Library/UefiLib.h>
 #include <Library/UefiRuntimeLib.h>
diff --git a/Platform/ARM/Include/Library/NorFlashDeviceLib.h b/Platform/ARM/Include/Library/NorFlashDeviceLib.h
new file mode 100644
index 000000000000..6833c1ddc456
--- /dev/null
+++ b/Platform/ARM/Include/Library/NorFlashDeviceLib.h
@@ -0,0 +1,236 @@
+/** @file  NorFlashDeviceLib.h
+
+  Copyright (c) 2011 - 2024, Arm Limited. All rights reserved.<BR>
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef NOR_FLASH_DEVICE_LIB_H_
+#define NOR_FLASH_DEVICE_LIB_H_
+
+#include <Protocol/BlockIo.h>
+#include <Protocol/DiskIo.h>
+#include <Protocol/FirmwareVolumeBlock.h>
+
+typedef struct _NOR_FLASH_INSTANCE NOR_FLASH_INSTANCE;
+
+#define GET_NOR_BLOCK_ADDRESS(BaseAddr, Lba, LbaSize)  ( BaseAddr + (UINTN)((Lba) * LbaSize) )
+
+/**
+  This structure describes the device path for a NOR flash device instance.
+**/
+#pragma pack (1)
+typedef struct {
+  VENDOR_DEVICE_PATH          Vendor;  ///< Vendor specific device path node.
+  UINT8                       Index;   ///< Index of a NOR flash device instance.
+  EFI_DEVICE_PATH_PROTOCOL    End;     ///< End node of a hardware device path.
+} NOR_FLASH_DEVICE_PATH;
+#pragma pack ()
+
+/**
+  NOR Flash instance structure used to identify different flash
+  or regions within a flash.
+**/
+struct _NOR_FLASH_INSTANCE {
+  UINT32                                 Signature; ///< NOR Flash instance signature.
+  EFI_HANDLE                             Handle;    ///< NOR Flash instance handle.
+
+  UINTN                                  DeviceBaseAddress; ///< NOR Flash device base address.
+  UINTN                                  RegionBaseAddress; ///< NOR Flash region base address.
+  UINTN                                  Size;              ///< NOR Flash region size.
+  EFI_LBA                                StartLba;          ///< Region start LBA.
+
+  EFI_BLOCK_IO_PROTOCOL                  BlockIoProtocol; ///< Instance's Block IO protocol handle.
+  EFI_BLOCK_IO_MEDIA                     Media;           ///< Instance's  Media information.
+  EFI_DISK_IO_PROTOCOL                   DiskIoProtocol;  ///< Instance's Disk IO protocol handle.
+
+  EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL    FvbProtocol;   ///< Instance's FVB protocol handle.
+  VOID                                   *ShadowBuffer; ///< Instance's shadow buffer.
+
+  NOR_FLASH_DEVICE_PATH                  DevicePath;  ///< Instance's device path.
+};
+
+/**
+  Write a full block to a given location.
+
+  @param[in]    Instance               NOR flash Instance.
+  @param[in]    Lba                    The logical block address in NOR flash.
+  @param[in]    DataBuffer             The data to write into NOR flash location.
+  @param[in]    BlockSizeInWords       The number of bytes to write.
+
+  @retval       EFI_SUCCESS            Write is complete.
+  @retval       EFI_DEVICE_ERROR       The device reported an error.
+  @retval       EFI_WRITE_PROTECTED    The block is write protected.
+  @retval       EFI_INVALID_PARAMETER  Invalid parameters passed.
+  @retval       EFI_BUFFER_TOO_SMALL   Insufficient buffer size.
+  @retval       EFI_BAD_BUFFER_SIZE    Invalid buffer size.
+**/
+EFI_STATUS
+NorFlashWriteFullBlock (
+  IN NOR_FLASH_INSTANCE  *Instance,
+  IN EFI_LBA             Lba,
+  IN UINT32              *DataBuffer,
+  IN UINT32              BlockSizeInWords
+  );
+
+/**
+  This function unlocks and erases an entire NOR Flash block.
+
+  @param[in]     Instance             NOR flash Instance.
+  @param[in]     BlockAddress         Block address to unlock and erase.
+
+  @retval        EFI_SUCCESS          Erase and unlock successfully completed.
+  @retval        EFI_DEVICE_ERROR     The device reported an error.
+  @retval        EFI_WRITE_PROTECTED  The block is write protected.
+**/
+EFI_STATUS
+NorFlashUnlockAndEraseSingleBlock (
+  IN NOR_FLASH_INSTANCE  *Instance,
+  IN UINTN               BlockAddress
+  );
+
+/**
+  Write a full or portion of a block.
+
+  @param[in]       Instance              NOR flash Instance.
+  @param[in]       Lba                   The starting logical block index to write to.
+  @param[in]       Offset                Offset into the block at which to begin writing.
+  @param[in, out]  NumBytes              The total size of the buffer.
+  @param[in]       Buffer                The pointer to a caller-allocated buffer that
+                                         contains the source for the write.
+
+  @retval          EFI_SUCCESS           Write is complete.
+  @retval          EFI_OUT_OF_RESOURCES  Invalid Buffer passed.
+  @retval          EFI_BAD_BUFFER_SIZE   Buffer size not enough.
+  @retval          EFI_DEVICE_ERROR      The device reported an error.
+  @retval          EFI_ACCESS_DENIED     Device is in write disabled mode.
+**/
+EFI_STATUS
+NorFlashWriteSingleBlock (
+  IN        NOR_FLASH_INSTANCE  *Instance,
+  IN        EFI_LBA             Lba,
+  IN        UINTN               Offset,
+  IN OUT    UINTN               *NumBytes,
+  IN        UINT8               *Buffer
+  );
+
+/**
+  Write multiple blocks.
+
+  @param[in]    Instance               NOR flash Instance.
+  @param[in]    Lba                    The starting logical block index.
+  @param[in]    BufferSizeInBytes      The number of bytes to write.
+  @param[in]    Buffer                 The pointer to a caller-allocated buffer that
+                                       contains the source for the write.
+
+  @retval       EFI_SUCCESS            Write is complete.
+  @retval       EFI_INVALID_PARAMETER  Invalid parameters passed.
+  @retval       EFI_BAD_BUFFER_SIZE    Invalid buffer size passed.
+  @retval       EFI_DEVICE_ERROR       The device reported an error.
+  @retval       EFI_WRITE_PROTECTED    The block is write protected.
+  @retval       EFI_BUFFER_TOO_SMALL   Insufficient buffer size.
+**/
+EFI_STATUS
+NorFlashWriteBlocks (
+  IN  NOR_FLASH_INSTANCE  *Instance,
+  IN  EFI_LBA             Lba,
+  IN  UINTN               BufferSizeInBytes,
+  IN  VOID                *Buffer
+  );
+
+/**
+  Read multiple blocks.
+
+  @param[in]     Instance               NOR flash Instance.
+  @param[in]     Lba                    The starting logical block index to read from.
+  @param[in]     BufferSizeInBytes      The number of bytes to read.
+  @param[out]    Buffer                 The pointer to a caller-allocated buffer that
+                                        should be copied with read data.
+
+  @retval        EFI_SUCCESS            Read is complete.
+  @retval        EFI_INVALID_PARAMETER  Invalid parameters passed.
+  @retval        EFI_BAD_BUFFER_SIZE    Invalid buffer size passed.
+**/
+EFI_STATUS
+NorFlashReadBlocks (
+  IN NOR_FLASH_INSTANCE  *Instance,
+  IN EFI_LBA             Lba,
+  IN UINTN               BufferSizeInBytes,
+  OUT VOID               *Buffer
+  );
+
+/**
+  Read from NOR flash.
+
+  @param[in]     Instance               NOR flash Instance.
+  @param[in]     Lba                    The starting logical block index to read from.
+  @param[in]     Offset                 Offset into the block at which to begin reading.
+  @param[in]     BufferSizeInBytes      The number of bytes to read.
+  @param[out]    Buffer                 The pointer to a caller-allocated buffer that
+                                        should be copied with read data.
+
+  @retval        EFI_SUCCESS            Read is complete.
+  @retval        EFI_INVALID_PARAMETER  Invalid parameters passed.
+**/
+EFI_STATUS
+NorFlashRead (
+  IN NOR_FLASH_INSTANCE  *Instance,
+  IN EFI_LBA             Lba,
+  IN UINTN               Offset,
+  IN UINTN               BufferSizeInBytes,
+  OUT VOID               *Buffer
+  );
+
+/**
+  NOR Flash Reset.
+
+  @param[in]    Instance          NOR flash instance.
+
+  @retval       EFI_SUCCESS       Return success on successful reset.
+  @retval       EFI_DEVICE_ERROR  The device reported an error.
+**/
+EFI_STATUS
+NorFlashReset (
+  IN  NOR_FLASH_INSTANCE  *Instance
+  );
+
+/**
+  The following function presumes that the block has already been unlocked.
+
+  @param[in]    Instance            NOR flash instance.
+  @param[in]    BlockAddress        Block address to erase.
+
+  @retval       EFI_SUCCESS         Request is executed successfully.
+  @retval       EFI_DEVICE_ERROR    The device reported an error.
+  @retval       EFI_WRITE_PROTECTED The block is write protected.
+ **/
+EFI_STATUS
+NorFlashEraseSingleBlock (
+  IN NOR_FLASH_INSTANCE  *Instance,
+  IN UINTN               BlockAddress
+  );
+
+/**
+  Lock all pending read/write to NOR flash device.
+
+  @param[in]     OriginalTPL     Pointer to NOR flash device Original TPL.
+**/
+VOID
+EFIAPI
+NorFlashLock (
+  IN EFI_TPL  *OriginalTPL
+  );
+
+/**
+  Unlock all pending read/write to NOR flash device.
+
+  @param[in]     OriginalTPL     NOR flash device Original TPL.
+**/
+VOID
+EFIAPI
+NorFlashUnlock (
+  IN EFI_TPL  OriginalTPL
+  );
+
+#endif /* NOR_FLASH_DEVICE_LIB_H_ */
-- 
2.25.1



-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#119149): https://edk2.groups.io/g/devel/message/119149
Mute This Topic: https://groups.io/mt/106260145/7686176
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [rebecca@openfw.io]
-=-=-=-=-=-=-=-=-=-=-=-