ArmPkg: MTL Library interface and Null library implementation

[mirror_edk2.git] / ArmPkg / Include / Library / ArmMtlLib.h

diff --git a/ArmPkg/Include/Library/ArmMtlLib.h b/ArmPkg/Include/Library/ArmMtlLib.h
new file mode 100644 (file)
index 0000000..4218a74
--- /dev/null
+++ b/ArmPkg/Include/Library/ArmMtlLib.h
@@ -0,0 +1,137 @@
+/** @file\r
+\r
+  Copyright (c) 2017-2018, Arm Limited. All rights reserved.\r
+\r
+  This program and the accompanying materials\r
+  are licensed and made available under the terms and conditions of the BSD License\r
+  which accompanies this distribution.  The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php\r
+\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+  System Control and Management Interface V1.0\r
+    http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/\r
+    DEN0056A_System_Control_and_Management_Interface.pdf\r
+**/\r
+\r
+#ifndef ARM_MTL_LIB_H_\r
+#define ARM_MTL_LIB_H_\r
+\r
+#include <Uefi/UefiBaseType.h>\r
+\r
+// Ideally we don't need packed struct. However we can't rely on compilers.\r
+#pragma pack(1)\r
+\r
+typedef struct {\r
+  UINT32 Reserved1;\r
+  UINT32 ChannelStatus;\r
+  UINT64 Reserved2;\r
+  UINT32 Flags;\r
+  UINT32 Length;\r
+  UINT32 MessageHeader;\r
+\r
+  // NOTE: Since EDK2 does not allow flexible array member [] we declare\r
+  // here array of 1 element length. However below is used as a variable\r
+  // length array.\r
+  UINT32 Payload[1];    // size less object gives offset to payload.\r
+} MTL_MAILBOX;\r
+\r
+#pragma pack()\r
+\r
+// Channel Type, Low-priority, and High-priority\r
+typedef enum {\r
+  MTL_CHANNEL_TYPE_LOW = 0,\r
+  MTL_CHANNEL_TYPE_HIGH = 1\r
+} MTL_CHANNEL_TYPE;\r
+\r
+typedef struct {\r
+  UINT64 PhysicalAddress;\r
+  UINT32 ModifyMask;\r
+  UINT32 PreserveMask;\r
+} MTL_DOORBELL;\r
+\r
+typedef struct {\r
+  MTL_CHANNEL_TYPE ChannelType;\r
+  MTL_MAILBOX      * CONST MailBox;\r
+  MTL_DOORBELL     DoorBell;\r
+} MTL_CHANNEL;\r
+\r
+/** Wait until channel is free.\r
+\r
+  @param[in] Channel                Pointer to a channel.\r
+  @param[in] TimeOutInMicroSeconds  Time out in micro seconds.\r
+\r
+  @retval EFI_SUCCESS               Channel is free.\r
+  @retval EFI_TIMEOUT               Time out error.\r
+**/\r
+EFI_STATUS\r
+MtlWaitUntilChannelFree (\r
+  IN MTL_CHANNEL  *Channel,\r
+  IN UINT64       TimeOutInMicroSeconds\r
+  );\r
+\r
+/** Return the address of the message payload.\r
+\r
+  @param[in] Channel   Pointer to a channel.\r
+\r
+  @retval UINT32*      Pointer to the payload.\r
+**/\r
+UINT32*\r
+MtlGetChannelPayload (\r
+  IN MTL_CHANNEL  *Channel\r
+  );\r
+\r
+/** Return pointer to a channel for the requested channel type.\r
+\r
+  @param[in] ChannelType        ChannelType, Low or High priority channel.\r
+                                MTL_CHANNEL_TYPE_LOW or\r
+                                MTL_CHANNEL_TYPE_HIGH\r
+\r
+  @param[out] Channel           Holds pointer to the channel.\r
+\r
+  @retval EFI_SUCCESS           Pointer to channel is returned.\r
+  @retval EFI_UNSUPPORTED       Requested channel type not supported.\r
+**/\r
+EFI_STATUS\r
+MtlGetChannel (\r
+  IN  MTL_CHANNEL_TYPE  ChannelType,\r
+  OUT MTL_CHANNEL       **Channel\r
+  );\r
+\r
+/** Mark the channel busy and ring the doorbell.\r
+\r
+  @param[in] Channel               Pointer to a channel.\r
+  @param[in] MessageHeader         Message header.\r
+\r
+  @param[out] PayloadLength        Message length.\r
+\r
+  @retval EFI_SUCCESS              Message sent successfully.\r
+  @retval EFI_DEVICE_ERROR         Channel is busy.\r
+**/\r
+EFI_STATUS\r
+MtlSendMessage (\r
+  IN  MTL_CHANNEL  *Channel,\r
+  IN  UINT32       MessageHeader,\r
+  OUT UINT32       PayloadLength\r
+  );\r
+\r
+/** Wait for a response on a channel.\r
+\r
+  If channel is free after sending message, it implies SCP responded\r
+  with a response on the channel.\r
+\r
+  @param[in] Channel               Pointer to a channel.\r
+\r
+  @retval EFI_SUCCESS              Message received successfully.\r
+  @retval EFI_TIMEOUT              Time out error.\r
+**/\r
+EFI_STATUS\r
+MtlReceiveMessage (\r
+  IN  MTL_CHANNEL  *Channel,\r
+  OUT UINT32       *MessageHeader,\r
+  OUT UINT32       *PayloadLength\r
+  );\r
+\r
+#endif  /* ARM_MTL_LIB_H_ */\r
+\r