[PATCH v3 15/16] ArmPkg: MTL Library interface and Null library implementation

[Girish Pathak <girish.pathak@arm.com>]

Upcoming new component ArmPkg/Drivers/ArmScmiDxe is dependent on
platform specific ArmMtlLib library implementation, however in order
to be able to build the ArmScmiDxe component outside of the context of a
particular platform, this change adds Null implementation of the
ArmMtlLib along with ARM MTL library header.

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Girish Pathak <girish.pathak@arm.com>
Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
---
 ArmPkg/ArmPkg.dec                              |   3 +-
 ArmPkg/Include/Library/ArmMtlLib.h             | 137 ++++++++++++++++++++
 ArmPkg/Library/ArmMtlNullLib/ArmMtlNullLib.c   | 108 +++++++++++++++
 ArmPkg/Library/ArmMtlNullLib/ArmMtlNullLib.inf |  26 ++++
 4 files changed, 273 insertions(+), 1 deletion(-)

diff --git a/ArmPkg/ArmPkg.dec b/ArmPkg/ArmPkg.dec
index a55b6268ff85ffd7da140be813ec875f7f242c4d..881751d81c6384a3eb0b4c180c76d01a58266a74 100644
--- a/ArmPkg/ArmPkg.dec
+++ b/ArmPkg/ArmPkg.dec
@@ -2,7 +2,7 @@
 # ARM processor package.
 #
 # Copyright (c) 2009 - 2010, Apple Inc. All rights reserved.<BR>
-# Copyright (c) 2011 - 2017, ARM Limited. All rights reserved.
+# Copyright (c) 2011 - 2018, ARM Limited. All rights reserved.
 #
 #    This program and the accompanying materials
 #    are licensed and made available under the terms and conditions of the BSD License
@@ -40,6 +40,7 @@ [LibraryClasses.common]
   ArmDisassemblerLib|Include/Library/ArmDisassemblerLib.h
   ArmGicArchLib|Include/Library/ArmGicArchLib.h
   ArmSvcLib|Include/Library/ArmSvcLib.h
+  ArmMtlLib|ArmPlatformPkg/Include/Library/ArmMtlLib.h
 
 [Guids.common]
   gArmTokenSpaceGuid       = { 0xBB11ECFE, 0x820F, 0x4968, { 0xBB, 0xA6, 0xF7, 0x6A, 0xFE, 0x30, 0x25, 0x96 } }
diff --git a/ArmPkg/Include/Library/ArmMtlLib.h b/ArmPkg/Include/Library/ArmMtlLib.h
new file mode 100644
index 0000000000000000000000000000000000000000..4218a741e5ebddd08022b94354d5ef47576cd3b8
--- /dev/null
+++ b/ArmPkg/Include/Library/ArmMtlLib.h
@@ -0,0 +1,137 @@
+/** @file
+
+  Copyright (c) 2017-2018, Arm Limited. All rights reserved.
+
+  This program and the accompanying materials
+  are licensed and made available under the terms and conditions of the BSD License
+  which accompanies this distribution.  The full text of the license may be found at
+  http://opensource.org/licenses/bsd-license.php
+
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+
+  System Control and Management Interface V1.0
+    http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/
+    DEN0056A_System_Control_and_Management_Interface.pdf
+**/
+
+#ifndef ARM_MTL_LIB_H_
+#define ARM_MTL_LIB_H_
+
+#include <Uefi/UefiBaseType.h>
+
+// Ideally we don't need packed struct. However we can't rely on compilers.
+#pragma pack(1)
+
+typedef struct {
+  UINT32 Reserved1;
+  UINT32 ChannelStatus;
+  UINT64 Reserved2;
+  UINT32 Flags;
+  UINT32 Length;
+  UINT32 MessageHeader;
+
+  // NOTE: Since EDK2 does not allow flexible array member [] we declare
+  // here array of 1 element length. However below is used as a variable
+  // length array.
+  UINT32 Payload[1];    // size less object gives offset to payload.
+} MTL_MAILBOX;
+
+#pragma pack()
+
+// Channel Type, Low-priority, and High-priority
+typedef enum {
+  MTL_CHANNEL_TYPE_LOW = 0,
+  MTL_CHANNEL_TYPE_HIGH = 1
+} MTL_CHANNEL_TYPE;
+
+typedef struct {
+  UINT64 PhysicalAddress;
+  UINT32 ModifyMask;
+  UINT32 PreserveMask;
+} MTL_DOORBELL;
+
+typedef struct {
+  MTL_CHANNEL_TYPE ChannelType;
+  MTL_MAILBOX      * CONST MailBox;
+  MTL_DOORBELL     DoorBell;
+} MTL_CHANNEL;
+
+/** Wait until channel is free.
+
+  @param[in] Channel                Pointer to a channel.
+  @param[in] TimeOutInMicroSeconds  Time out in micro seconds.
+
+  @retval EFI_SUCCESS               Channel is free.
+  @retval EFI_TIMEOUT               Time out error.
+**/
+EFI_STATUS
+MtlWaitUntilChannelFree (
+  IN MTL_CHANNEL  *Channel,
+  IN UINT64       TimeOutInMicroSeconds
+  );
+
+/** Return the address of the message payload.
+
+  @param[in] Channel   Pointer to a channel.
+
+  @retval UINT32*      Pointer to the payload.
+**/
+UINT32*
+MtlGetChannelPayload (
+  IN MTL_CHANNEL  *Channel
+  );
+
+/** Return pointer to a channel for the requested channel type.
+
+  @param[in] ChannelType        ChannelType, Low or High priority channel.
+                                MTL_CHANNEL_TYPE_LOW or
+                                MTL_CHANNEL_TYPE_HIGH
+
+  @param[out] Channel           Holds pointer to the channel.
+
+  @retval EFI_SUCCESS           Pointer to channel is returned.
+  @retval EFI_UNSUPPORTED       Requested channel type not supported.
+**/
+EFI_STATUS
+MtlGetChannel (
+  IN  MTL_CHANNEL_TYPE  ChannelType,
+  OUT MTL_CHANNEL       **Channel
+  );
+
+/** Mark the channel busy and ring the doorbell.
+
+  @param[in] Channel               Pointer to a channel.
+  @param[in] MessageHeader         Message header.
+
+  @param[out] PayloadLength        Message length.
+
+  @retval EFI_SUCCESS              Message sent successfully.
+  @retval EFI_DEVICE_ERROR         Channel is busy.
+**/
+EFI_STATUS
+MtlSendMessage (
+  IN  MTL_CHANNEL  *Channel,
+  IN  UINT32       MessageHeader,
+  OUT UINT32       PayloadLength
+  );
+
+/** Wait for a response on a channel.
+
+  If channel is free after sending message, it implies SCP responded
+  with a response on the channel.
+
+  @param[in] Channel               Pointer to a channel.
+
+  @retval EFI_SUCCESS              Message received successfully.
+  @retval EFI_TIMEOUT              Time out error.
+**/
+EFI_STATUS
+MtlReceiveMessage (
+  IN  MTL_CHANNEL  *Channel,
+  OUT UINT32       *MessageHeader,
+  OUT UINT32       *PayloadLength
+  );
+
+#endif  /* ARM_MTL_LIB_H_ */
+
diff --git a/ArmPkg/Library/ArmMtlNullLib/ArmMtlNullLib.c b/ArmPkg/Library/ArmMtlNullLib/ArmMtlNullLib.c
new file mode 100644
index 0000000000000000000000000000000000000000..f1862371113e342e4a4c8059be27884842210d08
--- /dev/null
+++ b/ArmPkg/Library/ArmMtlNullLib/ArmMtlNullLib.c
@@ -0,0 +1,108 @@
+/** @file
+
+  Copyright (c) 2017-2018, Arm Limited. All rights reserved.
+
+  This program and the accompanying materials
+  are licensed and made available under the terms and conditions of the BSD License
+  which accompanies this distribution.  The full text of the license may be found at
+  http://opensource.org/licenses/bsd-license.php
+
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+
+  System Control and Management Interface V1.0
+    http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/
+    DEN0056A_System_Control_and_Management_Interface.pdf
+**/
+
+#include <Library/ArmMtlLib.h>
+#include <Library/DebugLib.h>
+
+/** Wait until channel is free.
+
+  @param[in] Channel                Pointer to a channel.
+  @param[in] TimeOutInMicroSeconds  Timeout in micro seconds.
+
+  @retval EFI_UNSUPPORTED           Interface not implemented.
+**/
+EFI_STATUS
+MtlWaitUntilChannelFree (
+  IN MTL_CHANNEL  *Channel,
+  IN UINTN        TimeOutInMicroSeconds
+  )
+{
+  return EFI_UNSUPPORTED;
+}
+
+/** Return the address of the message payload.
+
+  @param[in] Channel   Pointer to a channel.
+
+  @retval UINT32*      Pointer to the payload.
+**/
+UINT32*
+MtlGetChannelPayload (
+  IN  MTL_CHANNEL  *Channel
+  )
+{
+  ASSERT (FALSE);
+  return NULL;
+}
+
+/** Return pointer to a channel for the requested channel type.
+
+  @param[in] ChannelType        ChannelType, Low or High priority channel.
+                                MTL_CHANNEL_TYPE_LOW or
+                                MTL_CHANNEL_TYPE_HIGH
+
+  @param[out] Channel           Holds pointer to the channel.
+
+  @retval EFI_UNSUPPORTED       Requested channel type not supported or
+                                interface not implemented.
+**/
+EFI_STATUS
+MtlGetChannel (
+  IN  MTL_CHANNEL_TYPE  ChannelType,
+  OUT MTL_CHANNEL       **Channel
+  )
+{
+  return EFI_UNSUPPORTED;
+}
+
+/** Mark the channel busy and ring the doorbell.
+
+  @param[in] Channel               Pointer to a channel.
+  @param[in] MessageHeader         Message header.
+
+  @param[out] PayloadLength        Message length.
+
+  @retval EFI_UNSUPPORTED          Interface not implemented.
+**/
+EFI_STATUS
+MtlSendMessage (
+  IN  MTL_CHANNEL  *Channel,
+  IN  UINT32       MessageHeader,
+  OUT UINT32       PayloadLength
+  )
+{
+  return EFI_UNSUPPORTED;
+}
+
+/** Wait for a response on a channel.
+
+  If channel is free after sending message, it implies SCP responded
+  with a response on the channel.
+
+  @param[in] Channel               Pointer to a channel.
+
+  @retval EFI_UNSUPPORTED          Interface not implemented.
+**/
+EFI_STATUS
+MtlReceiveMessage (
+  IN  MTL_CHANNEL  *Channel,
+  OUT UINT32       *MessageHeader,
+  OUT UINT32       *PayloadLength
+  )
+{
+  return EFI_UNSUPPORTED;
+}
diff --git a/ArmPkg/Library/ArmMtlNullLib/ArmMtlNullLib.inf b/ArmPkg/Library/ArmMtlNullLib/ArmMtlNullLib.inf
new file mode 100644
index 0000000000000000000000000000000000000000..9c0426b00e48e791dae9ad11e2f47d248d9c09ce
--- /dev/null
+++ b/ArmPkg/Library/ArmMtlNullLib/ArmMtlNullLib.inf
@@ -0,0 +1,26 @@
+#/** @file
+#  Copyright (c) 2017-2018, Arm Limited. All rights reserved.
+#
+#  This program and the accompanying materials
+#  are licensed and made available under the terms and conditions of the BSD License
+#  which accompanies this distribution.  The full text of the license may be found at
+#  http://opensource.org/licenses/bsd-license.php
+#
+#  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+#**/
+
+[Defines]
+  INF_VERSION                    = 0x00010019
+  BASE_NAME                      = ArmMtlNullLib
+  FILE_GUID                      = 05810525-FDEC-4006-9F1F-37609B3675FA
+  MODULE_TYPE                    = BASE
+  VERSION_STRING                 = 1.0
+  LIBRARY_CLASS                  = ArmMtlLib
+
+[Sources.common]
+  ArmMtlNullLib.c
+
+[Packages]
+  ArmPkg/ArmPkg.dec
+  MdePkg/MdePkg.dec
-- 
'Guid(CE165669-3EF3-493F-B85D-6190EE5B9759)'