xref: /openbmc/pldm/requester/README.md (revision b3dbb6e8)
1## Overview
2
3PLDM requester infrastructure enables the requester code in PLDM daemon to
4meet the requirements of PLDM requesters. It provides the following features:
5
6- Register a PLDM request and the response handler to be invoked on receiving
7  the response.
8- The handling of the request and response is asynchronous. This means the PLDM
9  daemon is not blocked till the response is received for a request.
10- Multiple outstanding requests are supported.
11- Request retries based on the time-out waiting for a response.
12- Instance ID expiration and marking the instance ID free after expiration.
13
14Future enhancements:
15
16- A mechanism to queue multiple outstanding requests to the same responder.
17- Handle ERROR_NOT_READY completion code and retry the PLDM request after 250ms
18  interval.
19
20The requester code needs to use the `registerRequest` API to register the PLDM
21request. The destination endpoint ID, instance ID, PLDM type, PLDM command code,
22PLDM request message (PLDM header and payload) and response function handler are
23passed as parameters to the registerRequest API.
24
25```
26    int registerRequest(mctp_eid_t eid, uint8_t instanceId, uint8_t type,
27                        uint8_t command, pldm::Request&& requestMsg,
28                        ResponseHandler&& responseHandler)
29```
30
31The signature of the response function handler:
32```
33void handler(mctp_eid_t eid, const pldm_msg* response, size_t respMsgLen)
34```
35
36- If the response is received before instance ID expiration:
37  - If the response matches with an outstanding request then the response
38    handler is invoked.
39  - If the response does not match with the PLDM instance ID, PLDM type and PLDM
40    command code of an outstanding request, then no action is taken on the
41    response.
42- Once the instance ID is expired, then the response handler is invoked with
43  empty response, so that further action can be taken.
44