blob: 928f7b8792a6bb01cd671e1dba78731d43b78a92 [file] [log] [blame]
Deepak Kodihallif9684792019-11-08 08:45:45 -06001description: >
2 Implement to provide features needed to build a PLDM Request message. This
3 API would be used by PLDM requester apps on the BMC.
4
5 Any OpenBMC implementation must provide exactly one implementation of
6 xyz.openbmc_project.PLDM.Requester on /xyz/openbmc_project/pldm.
7
8 PLDM stands for Platform Level Data Model. More information about PLDM (and
9 MCTP) can be found at https://www.dmtf.org/standards/pmci.
10
11methods:
12 - name: GetInstanceId
13 description: >
14 Obtain a new PLDM instance id, for the input MCTP EID, to be used in a
15 PLDM request message. Instance ids help distinguish PLDM response
16 messages when a PLDM requester sends out multiple request messages,
17 without waiting for a response message. Refer the PLDM specification
18 DSP0240 version 1.0.0. Also refer
19 https://github.com/openbmc/docs/blob/master/designs/pldm-stack.md#Requester.
20
21 The instance id starts at 0 and can go upto 31 (5 bits), for each MCTP
22 EID that a PLDM requester is communicating with. An implementation of
23 this API should track instance ids in terms of whether they're in use
24 (request message with that instance id has been sent out, and the
25 corresponding response message hasn't been received yet) or not, and
26 grant unused ids via this method. An implementation may also
27 optionally implement the instance id expiry, as per the spec DSP0240
28 v1.0.0. The spec recommends implementing the same.
29
30 If there's a call to this method when all 32 ids have already been
31 granted to the input eid, then the
32 xyz.openbmc_project.Common.Error.TooManyResources exception will be
33 thrown. The recommendation for the caller upon receiving this
Patrick Williamsa1347412022-12-06 10:56:22 -060034 exception is to retry calling this method, at least once, after a time
35 period equal to the maximum instance id expiration interval, which is
36 6 seconds as per DSP0240 v1.0.0. If the exception persists post this
37 interval, the way of handling the same (further retries, report an
38 error, etc) is left to the user.
Deepak Kodihallif9684792019-11-08 08:45:45 -060039 parameters:
Patrick Williams8da396c2022-03-14 14:21:02 -050040 - name: eid
41 type: byte
42 description: >
Patrick Williamsa1347412022-12-06 10:56:22 -060043 The MCTP endpoint, specified by 'eid' (endpoint id), for which
44 the new PLDM instance id needs to be generated.
Deepak Kodihallif9684792019-11-08 08:45:45 -060045 returns:
Patrick Williams8da396c2022-03-14 14:21:02 -050046 - name: instanceid
47 type: byte
48 description: >
49 PLDM instance id.
Deepak Kodihallif9684792019-11-08 08:45:45 -060050 errors:
Patrick Williams8da396c2022-03-14 14:21:02 -050051 - xyz.openbmc_project.Common.Error.TooManyResources