DynamicTablesPkg/Library/Common/SmbiosStringTableLib/SmbiosStringTableLib.c

/** @file
  SMBIOS String Table Helper

  Copyright (c) 2022, Arm Limited. All rights reserved.<BR>

  SPDX-License-Identifier: BSD-2-Clause-Patent

  @par Reference(s):
  - DSP0134 - SMBIOS Specification Version 3.6.0, 2022-06-17
**/

#include <Library/BaseLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/DebugLib.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/SmbiosStringTableLib.h>

/** Add a string to the string table.

  @param[in]   StrTable  Pointer to the string table
  @param[in]   Str       Pointer to the string
  @param[out]  StrRef    Optional pointer to retrieve the string field
                         reference of the string in the string table

  @return EFI_SUCCESS            Success
  @return EFI_INVALID_PARAMETER  Invalid string table pointer
  @return EFI_BUFFER_TOO_SMALL   Insufficient space to add string
**/
EFI_STATUS
EFIAPI
StringTableAddString (
  IN        STRING_TABLE *CONST  StrTable,
  IN  CONST CHAR8                *Str,
  OUT       UINT8                *StrRef      OPTIONAL
  )
{
  UINTN           StrLength;
  STRING_ELEMENT  *StrElement;

  if ((StrTable == NULL) || (Str == NULL)) {
    return EFI_INVALID_PARAMETER;
  }

  if (StrTable->StrCount >= StrTable->MaxStringElements) {
    return EFI_BUFFER_TOO_SMALL;
  }

  StrLength = AsciiStrLen (Str);
  if (StrLength == 0) {
    return EFI_INVALID_PARAMETER;
  }

  // Update the string element
  StrElement            = &StrTable->Elements[StrTable->StrCount];
  StrElement->StringLen = StrLength;
  StrElement->String    = Str;

  // Update String table information
  StrTable->TotalStrLen += StrLength;
  StrTable->StrCount++;

  // Return the index of the string in the string table if requested
  if (StrRef != NULL) {
    // Note: SMBIOS string field references start at 1. So, return the
    // StrCount as the string reference after it is updated.
    *StrRef = StrTable->StrCount;
  }

  return EFI_SUCCESS;
}

/** Returns the total size required to publish the strings to the SMBIOS
    string area.

  @param[in] StrTable              Pointer to the string table

  @return Total size required to publish the strings in the SMBIOS string area.
**/
UINTN
EFIAPI
StringTableGetStringSetSize (
  IN  STRING_TABLE *CONST  StrTable
  )
{
  if (StrTable == NULL) {
    ASSERT (0);
    return 0;
  }

  // See Section 6.1.3 Text strings, SMBIOS Specification Version 3.6.0
  // - If the formatted portion of the structure contains string-reference
  //   fields and all the string fields are set to 0 (no string references),
  //   the formatted section of the structure is followed by two null (00h)
  //   BYTES.
  // - Each string is terminated with a null (00h) BYTE
  // - and the set of strings is terminated with an additional null (00h) BYTE.

  // Therefore, if string count = 0, return 2
  // if string count > 0, the string set size =
  // StrTable->TotalStrLen (total length of the strings in the string table)
  // + StrTable->StrCount (add string count to include '\0' for each string)
  // +1 (an additional '\0' is required at the end of the string set).
  return (StrTable->StrCount == 0) ? 2 :
         (StrTable->TotalStrLen + StrTable->StrCount + 1);
}

/** Iterate through the string table and publish the strings in the SMBIOS
    string area.

  @param[in] StrTable              Pointer to the string table
  @param[in] SmbiosStringAreaStart Start address of the SMBIOS string area.
  @param[in] SmbiosStringAreaSize  Size of the SMBIOS string area.

  @return EFI_SUCCESS            Success
  @return EFI_INVALID_PARAMETER  Invalid string table pointer
  @return EFI_BUFFER_TOO_SMALL   Insufficient space to publish strings
**/
EFI_STATUS
EFIAPI
StringTablePublishStringSet (
  IN        STRING_TABLE  *CONST  StrTable,
  IN        CHAR8         *CONST  SmbiosStringAreaStart,
  IN  CONST UINTN                 SmbiosStringAreaSize
  )
{
  UINT8           Index;
  STRING_ELEMENT  *StrElement;
  CHAR8           *SmbiosString;
  UINTN           BytesRemaining;
  UINTN           BytesCopied;

  if ((StrTable == NULL) || (SmbiosStringAreaStart == NULL)) {
    return EFI_INVALID_PARAMETER;
  }

  if (SmbiosStringAreaSize < StringTableGetStringSetSize (StrTable)) {
    return EFI_BUFFER_TOO_SMALL;
  }

  SmbiosString   = SmbiosStringAreaStart;
  BytesRemaining = SmbiosStringAreaSize;

  if (StrTable->StrCount == 0) {
    // See Section 6.1.3 Text strings, SMBIOS Specification Version 3.6.0
    // If the formatted portion of the structure contains string-reference
    // fields and all the string fields are set to 0 (no string references),
    // the formatted section of the structure is followed by two null (00h)
    // BYTES.
    *SmbiosString++ = '\0';
  } else {
    for (Index = 0; Index < StrTable->StrCount; Index++) {
      StrElement = &StrTable->Elements[Index];
      AsciiStrCpyS (SmbiosString, BytesRemaining, StrElement->String);

      // See Section 6.1.3 Text strings, SMBIOS Specification Version 3.6.0
      // - Each string is terminated with a null (00h) BYTE
      // Bytes Copied = String length + 1 for the string NULL terminator.
      BytesCopied     = StrElement->StringLen + 1;
      BytesRemaining -= BytesCopied;
      SmbiosString   += BytesCopied;
    }
  }

  // See Section 6.1.3 Text strings, SMBIOS Specification Version 3.6.0
  // - the set of strings is terminated with an additional null (00h) BYTE.
  *SmbiosString = '\0';
  return EFI_SUCCESS;
}

/** Initialise the string table and allocate memory for the string elements.

  @param[in] StrTable           Pointer to the string table
  @param[in] MaxStringElements  Maximum number of strings that the string
                                table can hold.

  @return EFI_SUCCESS            Success
  @return EFI_INVALID_PARAMETER  Invalid string table pointer
  @return EFI_OUT_OF_RESOURCES   Failed to allocate memory for string elements
**/
EFI_STATUS
EFIAPI
StringTableInitialize (
  IN STRING_TABLE *CONST  StrTable,
  IN UINTN                MaxStringElements
  )
{
  STRING_ELEMENT  *Elements;

  if ((StrTable == NULL) || (MaxStringElements > MAX_UINT8)) {
    return EFI_INVALID_PARAMETER;
  }

  ZeroMem (StrTable, sizeof (STRING_TABLE));

  Elements = (STRING_ELEMENT *)AllocateZeroPool (
                                 sizeof (STRING_ELEMENT) * MaxStringElements
                                 );
  if (Elements == NULL) {
    return EFI_OUT_OF_RESOURCES;
  }

  StrTable->Elements          = Elements;
  StrTable->MaxStringElements = (UINT8)MaxStringElements;
  return EFI_SUCCESS;
}

/** Free memory allocated for the string elements in the string table.

  @param[in] StrTable           Pointer to the string table

  @return EFI_SUCCESS            Success
  @return EFI_INVALID_PARAMETER  Invalid string table pointer or string elements
**/
EFI_STATUS
EFIAPI
StringTableFree (
  IN STRING_TABLE *CONST  StrTable
  )
{
  if ((StrTable == NULL) || (StrTable->Elements == NULL)) {
    return EFI_INVALID_PARAMETER;
  }

  FreePool (StrTable->Elements);
  ZeroMem (StrTable, sizeof (STRING_TABLE));
  return EFI_SUCCESS;
}

/** Allocate a zeroed buffer for a SMBIOS record, including the string area.

  Per SMBIOS Specification Section 6.1.3, if the structure has no strings the
  formatted section is followed by two null (00h) bytes.  If strings are
  present each string is null-terminated and the set is terminated by an
  additional null byte.  This function encapsulates that rule so callers do
  not need to account for the terminator explicitly.

  @param[in]  StructSize  Size of the fixed-size part of the SMBIOS structure.
  @param[in]  StrTable    Optional pointer to a populated string table.
                          If NULL, the allocation includes only the two-byte
                          double-NULL terminator.
                          If non-NULL, the allocation includes the full string
                          area as returned by StringTableGetStringSetSize().

  @return  Pointer to the allocated SMBIOS record buffer, or NULL on failure.
**/
VOID *
EFIAPI
AllocateSmbiosRecord (
  IN        UINTN   StructSize,
  IN  STRING_TABLE  *StrTable    OPTIONAL
  )
{
  UINTN  StringAreaSize;

  // Per SMBIOS spec Section 6.1.3: two null bytes when no strings are present;
  // StringTableGetStringSetSize() already encodes this rule for non-empty tables.
  StringAreaSize = (StrTable == NULL) ? 2 : StringTableGetStringSetSize (StrTable);
  return AllocateZeroPool (StructSize + StringAreaSize);
}