xref: /openbmc/phosphor-dbus-interfaces/yaml/org/open_power/Logging/PEL.interface.yaml (revision 8da396ca4e24c1831d5d8fc9c9afc208002032c1) 
1description: >
2    Provides D-Bus access to OpenPower Platform Event Logs
3methods:
4    - name: GetPEL
5      description: >
6          Returns a file desciptor to a PEL.
7      parameters:
8          - name: pelID
9            type: uint32
10            description: >
11                The PEL log ID of the PEL to retrieve.
12      returns:
13          - name: data
14            type: unixfd
15            description: >
16                A file descriptor for a file that contains the PEL.
17      errors:
18          - xyz.openbmc_project.Common.Error.InternalFailure
19          - xyz.openbmc_project.Common.Error.InvalidArgument
20
21    - name: GetPELFromOBMCID
22      description: >
23          Returns PEL data based on the OpenBMC event log ID.
24      parameters:
25          - name: obmcLogID
26            type: uint32
27            description: >
28                The OpenBMC event log ID of the PEL to retrieve.
29      returns:
30          - name: data
31            type: array[byte]
32            description: >
33                The PEL data
34      errors:
35          - xyz.openbmc_project.Common.Error.InvalidArgument
36
37    - name: HostAck
38      description: >
39          Notifies the PEL handler that the host (usually the OS) acked a PEL.
40      parameters:
41          - name: pelID
42            type: uint32
43            description: >
44                The PEL log ID
45      errors:
46          - xyz.openbmc_project.Common.Error.InvalidArgument
47
48    - name: HostReject
49      description: >
50          Notifies the PEL handler that the host could not process a PEL.
51      parameters:
52          - name: pelID
53            type: uint32
54            description: >
55                The PEL log ID
56          - name: reason
57            type: enum[self.RejectionReason]
58            description: >
59                The reason the PEL was rejected
60      errors:
61          - xyz.openbmc_project.Common.Error.InvalidArgument
62
63    - name: CreatePELWithFFDCFiles
64      description: >
65          Creates an OpenBMC event log and a corresponding PEL. This method
66          returns the IDs of the created PEL and OpenBMC event log, unlike the
67          'xyz.openbmc_project.Logging.Create.CreateWithFFDCFiles' method which
68          doesn't return anything.
69      parameters:
70          - name: Message
71            type: string
72            description: >
73                The Message property of the OpenBMC event log entry.
74                This is also the key into the PEL message registry.
75          - name: Severity
76            type: enum[xyz.openbmc_project.Logging.Entry.Level]
77            description: >
78                The Severity property of the event entry.
79          - name: AdditionalData
80            type: dict[string, string]
81            description: >
82                The AdditionalData property of the event entry.
83                e.g.:
84                  {
85                    "key1": "value1",
86                    "key2": "value2"
87                  }
88                ends up in AdditionaData like:
89                  ["KEY1=value1", "KEY2=value2"]
90          - name: FFDC
91            type: array[struct[enum[xyz.openbmc_project.Logging.Create.FFDCFormat], byte, byte, unixfd]]
92            description: >
93                File descriptors for any files containing FFDC, along with metadata
94                about the contents:
95
96                  FFDCFormat- The format type of the contained data.
97                  subType - The format subtype, used for the 'Custom' type.
98                  version - The version of the data format, used for the 'Custom'
99                            type.
100                  unixfd - The file descriptor to the data file.
101
102                e.g.:
103                [
104                  {"xyz.openbmc_project.Logging.Create.FFDCFormat.JSON", 0, 0, 5},
105                  {"xyz.openbmc_project.Logging.Create.FFDCFormat.Custom", 1, 2, 6}
106                ]
107      returns:
108          - name: IDs
109            type: struct[uint32, uint32]
110            description: >
111                The IDs of the 2 created logs:
112                  - OpenBMC event log ID
113                  - PEL log ID: The unique ID of the PEL
114                Note that the PEL's platform log ID (PLID) field is always
115                equal to the PEL log ID for BMC created PELs.
116
117    - name: GetPELIdFromBMCLogId
118      description: >
119          Returns the PEL Id (aka Entry ID (EID)) based on the
120          given BMC event log id.
121      parameters:
122          - name: bmcLogId
123            type: uint32
124            description: >
125                The BMC event log id of the PEL to retrieve the PEL id.
126      returns:
127          - name: pelId
128            type: uint32
129            description: >
130                The Id of the PEL.
131      errors:
132          - xyz.openbmc_project.Common.Error.InvalidArgument
133
134    - name: GetBMCLogIdFromPELId
135      description: >
136          Returns the BMC event log id based on the given PEL id (aka
137          Entry ID (EID)).
138      parameters:
139          - name: pelId
140            type: uint32
141            description: >
142                The PEL id to retrieve the BMC event log id.
143      returns:
144          - name: bmcLogId
145            type: uint32
146            description: >
147                The BMC event log id of the PEL.
148      errors:
149          - xyz.openbmc_project.Common.Error.InvalidArgument
150
151enumerations:
152    - name: RejectionReason
153      description: >
154          The reason the PEL was rejected
155      values:
156          - name: BadPEL
157            description: >
158                The PEL was malformed.
159          - name: HostFull
160            description: >
161                The host does not have room for more PELs at this time.
162