DynamicTablesPkg/Library/Acpi/Arm/AcpiDbg2LibArm/Dbg2Generator.c

   1 /** @file
   2   DBG2 Table Generator
   3
   4   Copyright (c) 2017 - 2019, ARM Limited. All rights reserved.
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   @par Reference(s):
  14   - Microsoft Debug Port Table 2 (DBG2) Specification - December 10, 2015.
  15
  16 **/
  17
  18 #include <IndustryStandard/DebugPort2Table.h>
  19 #include <Library/AcpiLib.h>
  20 #include <Library/DebugLib.h>
  21 #include <Library/PL011UartLib.h>
  22 #include <Protocol/AcpiTable.h>
  23 #include <Protocol/SerialIo.h>
  24
  25 // Module specific include files.
  26 #include <AcpiTableGenerator.h>
  27 #include <ConfigurationManagerObject.h>
  28 #include <ConfigurationManagerHelper.h>
  29 #include <Library/TableHelperLib.h>
  30 #include <Protocol/ConfigurationManagerProtocol.h>
  31
  32 /** ARM standard DBG2 Table Generator
  33
  34   Constructs the DBG2 table for PL011 or SBSA UART peripherals.
  35
  36 Requirements:
  37   The following Configuration Manager Object(s) are required by
  38   this Generator:
  39   - EArmObjSerialDebugPortInfo
  40 */
  41
  42 #pragma pack(1)
  43
  44 /** The number of debug ports represented by the Table.
  45 */
  46 #define DBG2_NUM_DEBUG_PORTS                       1
  47
  48 /** The number of Generic Address Registers
  49     presented in the debug device information.
  50 */
  51 #define DBG2_NUMBER_OF_GENERIC_ADDRESS_REGISTERS   1
  52
  53 /** The index for the debug port 1 in the Debug port information list.
  54 */
  55 #define DBG_PORT_INDEX_PORT1                       0
  56
  57 /** A string representing the name of the debug port 1.
  58 */
  59 #define NAME_STR_PORT1                            "COM1"
  60
  61 /** The length of the namespace string.
  62 */
  63 #define DBG2_NAMESPACESTRING_FIELD_SIZE            sizeof (NAME_STR_PORT1)
  64
  65 /** The PL011 UART address range length.
  66 */
  67 #define PL011_UART_LENGTH                          0x1000
  68
  69 /** A structure that provides the OS with the required information
  70     for initializing a debugger connection.
  71 */
  72 typedef struct {
  73   /// The debug device information for the platform
  74   EFI_ACPI_DBG2_DEBUG_DEVICE_INFORMATION_STRUCT Dbg2Device;
  75
  76   /// The base address register for the serial port
  77   EFI_ACPI_6_2_GENERIC_ADDRESS_STRUCTURE        BaseAddressRegister;
  78
  79   /// The address size
  80   UINT32 AddressSize;
  81
  82   /// The debug port name string
  83   UINT8  NameSpaceString[DBG2_NAMESPACESTRING_FIELD_SIZE];
  84 } DBG2_DEBUG_DEVICE_INFORMATION;
  85
  86 /** A structure representing the information about the debug port(s)
  87     available on the platform.
  88 */
  89 typedef struct {
  90   /// The DBG2 table header
  91   EFI_ACPI_DEBUG_PORT_2_DESCRIPTION_TABLE Description;
  92
  93   /// Debug port information list
  94   DBG2_DEBUG_DEVICE_INFORMATION       Dbg2DeviceInfo[DBG2_NUM_DEBUG_PORTS];
  95 } DBG2_TABLE;
  96
  97 /** A helper macro used for initializing the debug port device
  98     information structure.
  99
 100   @param [in]  SubType      The DBG Port SubType.
 101   @param [in]  UartBase     The UART port base address.
 102   @param [in]  UartAddrLen  The UART port address range length.
 103   @param [in]  UartNameStr  The UART port name string.
 104 **/
 105 #define DBG2_DEBUG_PORT_DDI(                                          \
 106           SubType,                                                    \
 107           UartBase,                                                   \
 108           UartAddrLen,                                                \
 109           UartNameStr                                                 \
 110           ) {                                                         \
 111     {                                                                 \
 112       /* UINT8     Revision */                                        \
 113       EFI_ACPI_DBG2_DEBUG_DEVICE_INFORMATION_STRUCT_REVISION,         \
 114       /* UINT16    Length */                                          \
 115       sizeof (DBG2_DEBUG_DEVICE_INFORMATION),                         \
 116       /* UINT8     NumberofGenericAddressRegisters */                 \
 117       DBG2_NUMBER_OF_GENERIC_ADDRESS_REGISTERS,                       \
 118       /* UINT16    NameSpaceStringLength */                           \
 119       DBG2_NAMESPACESTRING_FIELD_SIZE,                                \
 120       /* UINT16    NameSpaceStringOffset */                           \
 121       OFFSET_OF (DBG2_DEBUG_DEVICE_INFORMATION, NameSpaceString),     \
 122       /* UINT16    OemDataLength */                                   \
 123       0,                                                              \
 124       /* UINT16    OemDataOffset */                                   \
 125       0,                                                              \
 126       /* UINT16    Port Type */                                       \
 127       EFI_ACPI_DBG2_PORT_TYPE_SERIAL,                                 \
 128       /* UINT16    Port Subtype */                                    \
 129       SubType,                                                        \
 130       /* UINT8     Reserved[2] */                                     \
 131       {EFI_ACPI_RESERVED_BYTE, EFI_ACPI_RESERVED_BYTE},               \
 132       /* UINT16    BaseAddressRegister Offset */                      \
 133       OFFSET_OF (DBG2_DEBUG_DEVICE_INFORMATION, BaseAddressRegister), \
 134       /* UINT16    AddressSize Offset */                              \
 135       OFFSET_OF (DBG2_DEBUG_DEVICE_INFORMATION, AddressSize)          \
 136     },                                                                \
 137     /* EFI_ACPI_6_2_GENERIC_ADDRESS_STRUCTURE BaseAddressRegister */  \
 138     ARM_GAS32 (UartBase),                                             \
 139     /* UINT32  AddressSize */                                         \
 140     UartAddrLen,                                                      \
 141     /* UINT8   NameSpaceString[MAX_DBG2_NAME_LEN] */                  \
 142     UartNameStr                                                       \
 143   }
 144
 145 /** The DBG2 Table template definition.
 146
 147   Note: fields marked with "{Template}" will be set dynamically
 148 */
 149 STATIC
 150 DBG2_TABLE AcpiDbg2 = {
 151   {
 152     ACPI_HEADER (
 153       EFI_ACPI_6_2_DEBUG_PORT_2_TABLE_SIGNATURE,
 154       DBG2_TABLE,
 155       EFI_ACPI_DBG2_DEBUG_DEVICE_INFORMATION_STRUCT_REVISION
 156       ),
 157     OFFSET_OF (DBG2_TABLE, Dbg2DeviceInfo),
 158     DBG2_NUM_DEBUG_PORTS
 159   },
 160   {
 161     /*
 162      * Debug port 1
 163      */
 164     DBG2_DEBUG_PORT_DDI (
 165       0,                    // {Template}: Serial Port Subtype
 166       0,                    // {Template}: Serial Port Base Address
 167       PL011_UART_LENGTH,
 168       NAME_STR_PORT1
 169       )
 170   }
 171 };
 172
 173 #pragma pack()
 174
 175 /** This macro expands to a function that retrieves the Serial
 176     debug port information from the Configuration Manager
 177 */
 178 GET_OBJECT_LIST (
 179   EObjNameSpaceArm,
 180   EArmObjSerialDebugPortInfo,
 181   CM_ARM_SERIAL_PORT_INFO
 182   );
 183
 184 /** Initialize the PL011 UART with the parameters obtained from
 185     the Configuration Manager.
 186
 187   @param [in]  SerialPortInfo Pointer to the Serial Port Information.
 188
 189   @retval EFI_SUCCESS           Success.
 190   @retval EFI_INVALID_PARAMETER The parameters for serial port initialization
 191                                 are invalid.
 192 **/
 193 STATIC
 194 EFI_STATUS
 195 SetupDebugUart (
 196   IN  CONST CM_ARM_SERIAL_PORT_INFO  * CONST SerialPortInfo
 197   )
 198 {
 199   EFI_STATUS          Status;
 200   UINT64              BaudRate;
 201   UINT32              ReceiveFifoDepth;
 202   EFI_PARITY_TYPE     Parity;
 203   UINT8               DataBits;
 204   EFI_STOP_BITS_TYPE  StopBits;
 205
 206   ASSERT (SerialPortInfo != NULL);
 207
 208   // Initialize the Serial Debug UART
 209   DEBUG ((DEBUG_INFO, "Initializing Serial Debug UART...\n"));
 210   ReceiveFifoDepth = 0; // Use the default value for FIFO depth
 211   Parity = (EFI_PARITY_TYPE)FixedPcdGet8 (PcdUartDefaultParity);
 212   DataBits = FixedPcdGet8 (PcdUartDefaultDataBits);
 213   StopBits = (EFI_STOP_BITS_TYPE)FixedPcdGet8 (PcdUartDefaultStopBits);
 214
 215   BaudRate = SerialPortInfo->BaudRate;
 216   Status = PL011UartInitializePort (
 217              (UINTN)SerialPortInfo->BaseAddress,
 218              SerialPortInfo->Clock,
 219              &BaudRate,
 220              &ReceiveFifoDepth,
 221              &Parity,
 222              &DataBits,
 223              &StopBits
 224              );
 225
 226   DEBUG ((DEBUG_INFO, "Debug UART Configuration:\n"));
 227   DEBUG ((DEBUG_INFO, "UART Base  = 0x%lx\n", SerialPortInfo->BaseAddress));
 228   DEBUG ((DEBUG_INFO, "Clock      = %d\n", SerialPortInfo->Clock));
 229   DEBUG ((DEBUG_INFO, "Baudrate   = %ld\n", BaudRate));
 230   DEBUG ((DEBUG_INFO, "Configuring Debug UART. Status = %r\n", Status));
 231
 232   ASSERT_EFI_ERROR (Status);
 233   return Status;
 234 }
 235
 236 /** Construct the DBG2 ACPI table
 237
 238     The BuildDbg2Table function is called by the Dynamic Table Manager
 239     to construct the DBG2 ACPI table.
 240
 241   This function invokes the Configuration Manager protocol interface
 242   to get the required hardware information for generating the ACPI
 243   table.
 244
 245   If this function allocates any resources then they must be freed
 246   in the FreeXXXXTableResources function.
 247
 248   @param [in]  This           Pointer to the table generator.
 249   @param [in]  AcpiTableInfo  Pointer to the ACPI Table Info.
 250   @param [in]  CfgMgrProtocol Pointer to the Configuration Manager
 251                               Protocol Interface.
 252   @param [out] Table          Pointer to the constructed ACPI Table.
 253
 254   @retval EFI_SUCCESS           Table generated successfully.
 255   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 256   @retval EFI_NOT_FOUND         The required object was not found.
 257   @retval EFI_BAD_BUFFER_SIZE   The size returned by the Configuration
 258                                 Manager is less than the Object size for the
 259                                 requested object.
 260 **/
 261 STATIC
 262 EFI_STATUS
 263 EFIAPI
 264 BuildDbg2Table (
 265   IN  CONST ACPI_TABLE_GENERATOR                  * CONST This,
 266   IN  CONST CM_STD_OBJ_ACPI_TABLE_INFO            * CONST AcpiTableInfo,
 267   IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL  * CONST CfgMgrProtocol,
 268   OUT       EFI_ACPI_DESCRIPTION_HEADER          ** CONST Table
 269   )
 270 {
 271   EFI_STATUS                 Status;
 272   CM_ARM_SERIAL_PORT_INFO  * SerialPortInfo;
 273
 274   ASSERT (This != NULL);
 275   ASSERT (AcpiTableInfo != NULL);
 276   ASSERT (CfgMgrProtocol != NULL);
 277   ASSERT (Table != NULL);
 278   ASSERT (AcpiTableInfo->TableGeneratorId == This->GeneratorID);
 279   ASSERT (AcpiTableInfo->AcpiTableSignature == This->AcpiTableSignature);
 280
 281   if ((AcpiTableInfo->AcpiTableRevision < This->MinAcpiTableRevision) ||
 282       (AcpiTableInfo->AcpiTableRevision > This->AcpiTableRevision)) {
 283     DEBUG ((
 284       DEBUG_ERROR,
 285       "ERROR: DBG2: Requested table revision = %d, is not supported."
 286       "Supported table revision: Minimum = %d, Maximum = %d\n",
 287       AcpiTableInfo->AcpiTableRevision,
 288       This->MinAcpiTableRevision,
 289       This->AcpiTableRevision
 290       ));
 291     return EFI_INVALID_PARAMETER;
 292   }
 293
 294   *Table = NULL;
 295
 296   Status = GetEArmObjSerialDebugPortInfo (
 297              CfgMgrProtocol,
 298              CM_NULL_TOKEN,
 299              &SerialPortInfo,
 300              NULL
 301              );
 302   if (EFI_ERROR (Status)) {
 303     DEBUG ((
 304       DEBUG_ERROR,
 305       "ERROR: DBG2: Failed to get serial port information. Status = %r\n",
 306       Status
 307       ));
 308     goto error_handler;
 309   }
 310
 311   if (SerialPortInfo->BaseAddress == 0) {
 312     Status = EFI_INVALID_PARAMETER;
 313     DEBUG ((
 314       DEBUG_ERROR,
 315       "ERROR: DBG2: Uart port base address is invalid. BaseAddress = 0x%lx\n",
 316       SerialPortInfo->BaseAddress
 317       ));
 318     goto error_handler;
 319   }
 320
 321   if ((SerialPortInfo->PortSubtype !=
 322       EFI_ACPI_DBG2_PORT_SUBTYPE_SERIAL_ARM_PL011_UART) &&
 323       (SerialPortInfo->PortSubtype !=
 324       EFI_ACPI_DBG2_PORT_SUBTYPE_SERIAL_ARM_SBSA_GENERIC_UART_2X) &&
 325       (SerialPortInfo->PortSubtype !=
 326       EFI_ACPI_DBG2_PORT_SUBTYPE_SERIAL_ARM_SBSA_GENERIC_UART) &&
 327       (SerialPortInfo->PortSubtype !=
 328       EFI_ACPI_DBG2_PORT_SUBTYPE_SERIAL_DCC)) {
 329     Status = EFI_INVALID_PARAMETER;
 330     DEBUG ((
 331       DEBUG_ERROR,
 332       "ERROR: DBG2: Uart port sybtype is invalid. PortSubtype = 0x%x\n",
 333       SerialPortInfo->PortSubtype
 334       ));
 335     goto error_handler;
 336   }
 337
 338   Status = AddAcpiHeader (
 339              CfgMgrProtocol,
 340              This,
 341              (EFI_ACPI_DESCRIPTION_HEADER*)&AcpiDbg2,
 342              AcpiTableInfo,
 343              sizeof (DBG2_TABLE)
 344              );
 345   if (EFI_ERROR (Status)) {
 346     DEBUG ((
 347       DEBUG_ERROR,
 348       "ERROR: DBG2: Failed to add ACPI header. Status = %r\n",
 349       Status
 350       ));
 351     goto error_handler;
 352   }
 353
 354   // Update the base address
 355   AcpiDbg2.Dbg2DeviceInfo[DBG_PORT_INDEX_PORT1].BaseAddressRegister.Address =
 356     SerialPortInfo->BaseAddress;
 357
 358   // Update the serial port subtype
 359   AcpiDbg2.Dbg2DeviceInfo[DBG_PORT_INDEX_PORT1].Dbg2Device.PortSubtype =
 360     SerialPortInfo->PortSubtype;
 361
 362   // Initialize the serial port
 363   Status = SetupDebugUart (SerialPortInfo);
 364   if (EFI_ERROR (Status)) {
 365     DEBUG ((
 366       DEBUG_ERROR,
 367       "ERROR: DBG2: Failed to configure debug serial port. Status = %r\n",
 368       Status
 369       ));
 370     goto error_handler;
 371   }
 372
 373   *Table = (EFI_ACPI_DESCRIPTION_HEADER*)&AcpiDbg2;
 374
 375 error_handler:
 376   return Status;
 377 }
 378
 379 /** This macro defines the DBG2 Table Generator revision.
 380 */
 381 #define DBG2_GENERATOR_REVISION CREATE_REVISION (1, 0)
 382
 383 /** The interface for the DBG2 Table Generator.
 384 */
 385 STATIC
 386 CONST
 387 ACPI_TABLE_GENERATOR Dbg2Generator = {
 388   // Generator ID
 389   CREATE_STD_ACPI_TABLE_GEN_ID (EStdAcpiTableIdDbg2),
 390   // Generator Description
 391   L"ACPI.STD.DBG2.GENERATOR",
 392   // ACPI Table Signature
 393   EFI_ACPI_6_2_DEBUG_PORT_2_TABLE_SIGNATURE,
 394   // ACPI Table Revision supported by this Generator
 395   EFI_ACPI_DBG2_DEBUG_DEVICE_INFORMATION_STRUCT_REVISION,
 396   // Minimum supported ACPI Table Revision
 397   EFI_ACPI_DBG2_DEBUG_DEVICE_INFORMATION_STRUCT_REVISION,
 398   // Creator ID
 399   TABLE_GENERATOR_CREATOR_ID_ARM,
 400   // Creator Revision
 401   DBG2_GENERATOR_REVISION,
 402   // Build Table function
 403   BuildDbg2Table,
 404   // No additional resources are allocated by the generator.
 405   // Hence the Free Resource function is not required.
 406   NULL,
 407   // Extended build function not needed
 408   NULL,
 409   // Extended build function not implemented by the generator.
 410   // Hence extended free resource function is not required.
 411   NULL
 412 };
 413
 414 /** Register the Generator with the ACPI Table Factory.
 415
 416   @param [in]  ImageHandle  The handle to the image.
 417   @param [in]  SystemTable  Pointer to the System Table.
 418
 419   @retval EFI_SUCCESS           The Generator is registered.
 420   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 421   @retval EFI_ALREADY_STARTED   The Generator for the Table ID
 422                                 is already registered.
 423 **/
 424 EFI_STATUS
 425 EFIAPI
 426 AcpiDbg2LibConstructor (
 427   IN CONST EFI_HANDLE                ImageHandle,
 428   IN       EFI_SYSTEM_TABLE  * CONST SystemTable
 429   )
 430 {
 431   EFI_STATUS  Status;
 432   Status = RegisterAcpiTableGenerator (&Dbg2Generator);
 433   DEBUG ((DEBUG_INFO, "DBG2: Register Generator. Status = %r\n", Status));
 434   ASSERT_EFI_ERROR (Status);
 435
 436   return Status;
 437 }
 438
 439 /** Deregister the Generator from the ACPI Table Factory.
 440
 441   @param [in]  ImageHandle  The handle to the image.
 442   @param [in]  SystemTable  Pointer to the System Table.
 443
 444   @retval EFI_SUCCESS           The Generator is deregistered.
 445   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 446   @retval EFI_NOT_FOUND         The Generator is not registered.
 447 **/
 448 EFI_STATUS
 449 EFIAPI
 450 AcpiDbg2LibDestructor (
 451   IN CONST EFI_HANDLE                ImageHandle,
 452   IN       EFI_SYSTEM_TABLE  * CONST SystemTable
 453   )
 454 {
 455   EFI_STATUS  Status;
 456   Status = DeregisterAcpiTableGenerator (&Dbg2Generator);
 457   DEBUG ((DEBUG_INFO, "DBG2: Deregister Generator. Status = %r\n", Status));
 458   ASSERT_EFI_ERROR (Status);
 459   return Status;
 460 }