| Deepak Kodihalli | f968479 | 2019-11-08 08:45:45 -0600 | [diff] [blame] | 1 | description: > |
| 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 | |
| 11 | methods: |
| 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 Williams | a134741 | 2022-12-06 10:56:22 -0600 | [diff] [blame] | 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. |
| Deepak Kodihalli | f968479 | 2019-11-08 08:45:45 -0600 | [diff] [blame] | 39 | parameters: |
| Patrick Williams | 8da396c | 2022-03-14 14:21:02 -0500 | [diff] [blame] | 40 | - name: eid |
| 41 | type: byte |
| 42 | description: > |
| Patrick Williams | a134741 | 2022-12-06 10:56:22 -0600 | [diff] [blame] | 43 | The MCTP endpoint, specified by 'eid' (endpoint id), for which |
| 44 | the new PLDM instance id needs to be generated. |
| Deepak Kodihalli | f968479 | 2019-11-08 08:45:45 -0600 | [diff] [blame] | 45 | returns: |
| Patrick Williams | 8da396c | 2022-03-14 14:21:02 -0500 | [diff] [blame] | 46 | - name: instanceid |
| 47 | type: byte |
| 48 | description: > |
| 49 | PLDM instance id. |
| Deepak Kodihalli | f968479 | 2019-11-08 08:45:45 -0600 | [diff] [blame] | 50 | errors: |
| Patrick Williams | 8da396c | 2022-03-14 14:21:02 -0500 | [diff] [blame] | 51 | - xyz.openbmc_project.Common.Error.TooManyResources |