yaml/org/open_power/Logging/PEL.interface.yaml

description: >
  Provides D-Bus access to OpenPower Platform Event Logs
methods:
  - name: GetPEL
    description: >
      Returns a file desciptor to a PEL.
    parameters:
      - name: pelID
        type: uint32
        description: >
          The PEL log ID of the PEL to retrieve.
    returns:
      - name: data
        type: unixfd
        description: >
          A file descriptor for a file that contains the PEL.
    errors:
       - xyz.openbmc_project.Common.Error.InternalFailure
       - xyz.openbmc_project.Common.Error.InvalidArgument

  - name: GetPELFromOBMCID
    description: >
      Returns PEL data based on the OpenBMC event log ID.
    parameters:
      - name: obmcLogID
        type: uint32
        description: >
          The OpenBMC event log ID of the PEL to retrieve.
    returns:
      - name: data
        type: array[byte]
        description: >
          The PEL data
    errors:
       - xyz.openbmc_project.Common.Error.InvalidArgument

  - name: HostAck
    description: >
      Notifies the PEL handler that the host (usually the OS) acked a PEL.
    parameters:
      - name: pelID
        type: uint32
        description: >
          The PEL log ID
    errors:
       - xyz.openbmc_project.Common.Error.InvalidArgument

  - name: HostReject
    description: >
      Notifies the PEL handler that the host could not process a PEL.
    parameters:
      - name: pelID
        type: uint32
        description: >
          The PEL log ID
      - name: reason
        type: enum[self.RejectionReason]
        description: >
          The reason the PEL was rejected
    errors:
       - xyz.openbmc_project.Common.Error.InvalidArgument

  - name: CreatePELWithFFDCFiles
    description: >
      Creates an OpenBMC event log and a corresponding PEL. This method
      returns the IDs of the created PEL and OpenBMC event log, unlike the
      'xyz.openbmc_project.Logging.Create.CreateWithFFDCFiles' method which
      doesn't return anything.
    parameters:
      - name: Message
        type: string
        description: >
          The Message property of the OpenBMC event log entry.
          This is also the key into the PEL message registry.
      - name: Severity
        type: enum[xyz.openbmc_project.Logging.Entry.Level]
        description: >
          The Severity property of the event entry.
      - name: AdditionalData
        type: dict[string, string]
        description: >
          The AdditionalData property of the event entry.
          e.g.:
            {
              "key1": "value1",
              "key2": "value2"
            }
          ends up in AdditionaData like:
            ["KEY1=value1", "KEY2=value2"]
      - name: FFDC
        type: array[struct[enum[xyz.openbmc_project.Logging.Create.FFDCFormat], byte, byte, unixfd]]
        description: >
          File descriptors for any files containing FFDC, along with metadata
          about the contents:

            FFDCFormat- The format type of the contained data.
            subType - The format subtype, used for the 'Custom' type.
            version - The version of the data format, used for the 'Custom'
                      type.
            unixfd - The file descriptor to the data file.

          e.g.:
          [
            {"xyz.openbmc_project.Logging.Create.FFDCFormat.JSON", 0, 0, 5},
            {"xyz.openbmc_project.Logging.Create.FFDCFormat.Custom", 1, 2, 6}
          ]
    returns:
      - name: IDs
        type: struct[uint32, uint32]
        description: >
          The IDs of the 2 created logs:
            - OpenBMC event log ID
            - PEL log ID: The unique ID of the PEL
          Note that the PEL's platform log ID (PLID) field is always
          equal to the PEL log ID for BMC created PELs.

  - name: GetPELIdFromBMCLogId
    description: >
        Returns the PEL Id (aka Entry ID (EID)) based on the
        given BMC event log id.
    parameters:
      - name: bmcLogId
        type: uint32
        description: >
          The BMC event log id of the PEL to retrieve the PEL id.
    returns:
      - name: pelId
        type: uint32
        description: >
            The Id of the PEL.
    errors:
       - xyz.openbmc_project.Common.Error.InvalidArgument

enumerations:
  - name: RejectionReason
    description: >
      The reason the PEL was rejected
    values:
      - name: BadPEL
        description: >
          The PEL was malformed.
      - name: HostFull
        description: >
          The host does not have room for more PELs at this time.