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
151    - name: GetPELJSON
152      description: >
153          Returns a string containing the JSON representation
154          of the PEL.
155      parameters:
156          - name: bmcLogId
157            type: uint32
158            description: >
159                The BMC event log id of the PEL to retrieve JSON for
160      returns:
161          - name: json
162            type: string
163            description: >
164                The PEL in JSON format
165      errors:
166          - xyz.openbmc_project.Common.Error.InvalidArgument
167          - xyz.openbmc_project.Common.Error.InternalFailure
168
169enumerations:
170    - name: RejectionReason
171      description: >
172          The reason the PEL was rejected
173      values:
174          - name: BadPEL
175            description: >
176                The PEL was malformed.
177          - name: HostFull
178            description: >
179                The host does not have room for more PELs at this time.
180