1description: >
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
34          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.
39      parameters:
40          - name: eid
41            type: byte
42            description: >
43                The MCTP endpoint, specified by 'eid' (endpoint id), for which
44                the new PLDM instance id needs to be generated.
45      returns:
46          - name: instanceid
47            type: byte
48            description: >
49                PLDM instance id.
50      errors:
51          - xyz.openbmc_project.Common.Error.TooManyResources
52