requester: Add new APIs for instance ID allocation and freeing
This patch starts the move of instance id handling into libpldm.
Currently pldmd allocates instance ids, and exposes a DBus call for
external apps to get instance ids. It relies on exploiting a behaviour
of mctp-demux to reclaim used ids by monitoring all incoming PLDM
responses. When moving to AF_MCTP, PLDM messages are not broadcast to
all PLDM sockets, and so this method of reclaiming ids won't work
automatically.
As instance id handling is moving into libpldm eventually, we may as
well do that now rather than adding an additional step to address this
issue. So an allocate and free function for instance ids is added in
this patch. As this implementation uses file locking, we have the
feature of any ids belonging to a process that dies being automatically
reclaimed into the id pool.
Some context behind the file based range locking design for instance IDs
can be found here:
https://amboar.github.io/notes/2023/03/28/motivating-a-new-scheme-for-pldm-instance-id-management-in-openbmc.html
and
https://amboar.github.io/notes/2023/03/29/a-global-pldm-instance-id-allocator-for-libpldm.html
Change-Id: Ia19870b1bcae9e614bda6e475b290faa0b327a73
Signed-off-by: Rashmica Gupta <rashmica@linux.ibm.com>
diff --git a/include/libpldm/requester/instance-id.h b/include/libpldm/requester/instance-id.h
new file mode 100644
index 0000000..eebaecb
--- /dev/null
+++ b/include/libpldm/requester/instance-id.h
@@ -0,0 +1,92 @@
+#ifndef INSTANCE_ID_H
+#define INSTANCE_ID_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "libpldm/base.h"
+#include <stdint.h>
+
+typedef uint8_t pldm_instance_id_t;
+struct pldm_instance_db;
+
+#ifdef __STDC_HOSTED__
+/**
+ * @brief Instantiates an instance ID database object for a given database path
+ *
+ * @param[out] ctx - *ctx must be NULL, and will point to a PLDM instance ID
+ * database object on success.
+ * @param[in] dbpath - the path to the instance ID database file to use
+ *
+ * @return int - Returns 0 on success. Returns -EINVAL if ctx is NULL or *ctx
+ * is not NULL. Returns -ENOMEM if memory couldn't be allocated.
+ * Returns the errno if the database couldn't be opened.
+ * */
+int pldm_instance_db_init(struct pldm_instance_db **ctx, const char *dbpath);
+
+/**
+ * @brief Instantiates an instance ID database object for the default database
+ * path
+ *
+ * @param[out] ctx - *ctx will point to a PLDM instance ID database object on
+ * success.
+ *
+ * @return int - Returns 0 on success. Returns -EINVAL if ctx is NULL or *ctx
+ * is not NULL. Returns -ENOMEM if memory couldn't be allocated.
+ * Returns the errno if the database couldn't be opened.
+ * */
+int pldm_instance_db_init_default(struct pldm_instance_db **ctx);
+
+/**
+ * @brief Destroys an instance ID database object
+ *
+ * @param[in] ctx - PLDM instance ID database object
+ *
+ * @return int - Returns 0 on success or if *ctx is NULL. No specific errors are
+ * specified.
+ * */
+int pldm_instance_db_destroy(struct pldm_instance_db *ctx);
+
+/**
+ * @brief Allocates an instance ID for a destination TID from the instance ID
+ * database
+ *
+ * @param[in] ctx - PLDM instance ID database object
+ * @param[in] tid - PLDM TID
+ * @param[in] iid - caller owned pointer to a PLDM instance ID object. On
+ * success, this points to an instance ID to use for a PLDM request
+ * message.
+ *
+ * @return int - Returns 0 on success if we were able to allocate an instance
+ * ID. Returns -EINVAL if the iid pointer is NULL. Returns -EAGAIN
+ * if a successive call may succeed. Returns -EPROTO if the
+ * operation has entered an undefined state.
+ */
+int pldm_instance_id_alloc(struct pldm_instance_db *ctx, pldm_tid_t tid,
+ pldm_instance_id_t *iid);
+
+/**
+ * @brief Frees an instance ID previously allocated by pldm_instance_id_alloc
+ *
+ * @param[in] ctx - PLDM instance ID database object
+ * @param[in] tid - PLDM TID
+ * @param[in] iid - If this instance ID was not previously allocated by
+ * pldm_instance_id_alloc then EINVAL is returned.
+ *
+ * @return int - Returns 0 on success. Returns -EINVAL if the iid supplied was
+ * not previously allocated by pldm_instance_id_alloc or it has
+ * previously been freed. Returns -EAGAIN if a successive call may
+ * succeed. Returns -EPROTO if the operation has entered an
+ * undefined state.
+ */
+int pldm_instance_id_free(struct pldm_instance_db *ctx, pldm_tid_t tid,
+ pldm_instance_id_t iid);
+
+#endif /* __STDC_HOSTED__*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* INSTANCE_ID_H */