libpldm: Explicit deprecated, stable and testing ABI classes
Experimenting with new APIs is important, but ABI stability of the
library is also important. We wish to have the freedom to add APIs
without being burdened by them being immediately set in stone.
We implement this wish by introducing three classes of ABI:
1. deprecated
2. stable
3. testing
These are enforced by corresponding function attributes:
1. LIBPLDM_ABI_DEPRECATED
2. LIBPLDM_ABI_STABLE
3. LIBPLDM_ABI_TESTING
Symbol visibility in the library is flipped to 'hidden' by default, so
one of these annotations must be used for the symbol to be exposed.
With these classes in place there are now clear points in time at which
we update the ABI dumps captured under the abi/ directory: When an API
is migrated from the 'testing' class to the 'stable' class, or when
removed from the 'deprecated' class.
Which classes of functions are exposed by the build is controlled by the
new 'abi' meson option. The option is of array type which contains the
list of ABI classes the build should consider. It defaults to enabling
all classes to provide test coverage in CI. The classes used should be
constrained to deprecated and stable (and not test) in any dependent
projects.
Signed-off-by: Andrew Jeffery <andrew@aj.id.au>
Change-Id: I25402e20c7be9c9f264f9ccd7ac36b384823734c
diff --git a/src/platform.c b/src/platform.c
index c6f3cf6..775b181 100644
--- a/src/platform.c
+++ b/src/platform.c
@@ -1,3 +1,4 @@
+#include "config.h"
#include "msgbuf/platform.h"
#include "base.h"
#include "msgbuf.h"
@@ -22,6 +23,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int encode_state_effecter_pdr(
struct pldm_state_effecter_pdr *const effecter,
const size_t allocation_size,
@@ -92,6 +94,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int encode_state_sensor_pdr(
struct pldm_state_sensor_pdr *const sensor,
const size_t allocation_size,
@@ -159,6 +162,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int encode_set_state_effecter_states_resp(uint8_t instance_id,
uint8_t completion_code,
struct pldm_msg *msg)
@@ -183,6 +187,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int encode_set_state_effecter_states_req(uint8_t instance_id,
uint16_t effecter_id,
uint8_t comp_effecter_count,
@@ -220,6 +225,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_set_state_effecter_states_resp(const struct pldm_msg *msg,
size_t payload_length,
uint8_t *completion_code)
@@ -241,6 +247,7 @@
}
#define PLDM_SET_STATE_EFFECTER_STATES_MIN_SIZE 3
+LIBPLDM_ABI_STABLE
int decode_set_state_effecter_states_req(const struct pldm_msg *msg,
size_t payload_length,
uint16_t *effecter_id,
@@ -282,6 +289,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int decode_get_pdr_req(const struct pldm_msg *msg, size_t payload_length,
uint32_t *record_hndl, uint32_t *data_transfer_hndl,
uint8_t *transfer_op_flag, uint16_t *request_cnt,
@@ -316,6 +324,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int encode_get_pdr_resp(uint8_t instance_id, uint8_t completion_code,
uint32_t next_record_hndl,
uint32_t next_data_transfer_hndl, uint8_t transfer_flag,
@@ -361,6 +370,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int encode_get_pdr_repository_info_resp(
uint8_t instance_id, uint8_t completion_code, uint8_t repository_state,
const uint8_t *update_time, const uint8_t *oem_update_time,
@@ -407,6 +417,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_get_pdr_repository_info_resp(
const struct pldm_msg *msg, size_t payload_length,
uint8_t *completion_code, uint8_t *repository_state,
@@ -452,6 +463,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int encode_get_pdr_req(uint8_t instance_id, uint32_t record_hndl,
uint32_t data_transfer_hndl, uint8_t transfer_op_flag,
uint16_t request_cnt, uint16_t record_chg_num,
@@ -487,6 +499,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_get_pdr_resp(const struct pldm_msg *msg, size_t payload_length,
uint8_t *completion_code, uint32_t *next_record_hndl,
uint32_t *next_data_transfer_hndl,
@@ -537,6 +550,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int decode_set_numeric_effecter_value_req(const struct pldm_msg *msg,
size_t payload_length,
uint16_t *effecter_id,
@@ -575,6 +589,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int encode_set_numeric_effecter_value_resp(uint8_t instance_id,
uint8_t completion_code,
struct pldm_msg *msg,
@@ -604,6 +619,7 @@
return rc;
}
+LIBPLDM_ABI_STABLE
int encode_set_numeric_effecter_value_req(uint8_t instance_id,
uint16_t effecter_id,
uint8_t effecter_data_size,
@@ -668,6 +684,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_set_numeric_effecter_value_resp(const struct pldm_msg *msg,
size_t payload_length,
uint8_t *completion_code)
@@ -685,6 +702,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int encode_get_state_sensor_readings_resp(uint8_t instance_id,
uint8_t completion_code,
uint8_t comp_sensor_count,
@@ -721,6 +739,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int encode_get_state_sensor_readings_req(uint8_t instance_id,
uint16_t sensor_id,
bitfield8_t sensor_rearm,
@@ -751,6 +770,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_get_state_sensor_readings_resp(const struct pldm_msg *msg,
size_t payload_length,
uint8_t *completion_code,
@@ -802,6 +822,7 @@
return pldm_msgbuf_destroy_consumed(buf);
}
+LIBPLDM_ABI_STABLE
int decode_get_state_sensor_readings_req(const struct pldm_msg *msg,
size_t payload_length,
uint16_t *sensor_id,
@@ -829,6 +850,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int encode_sensor_event_data(
struct pldm_sensor_event_data *const event_data,
const size_t event_data_size, const uint16_t sensor_id,
@@ -864,6 +886,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_platform_event_message_req(const struct pldm_msg *msg,
size_t payload_length,
uint8_t *format_version, uint8_t *tid,
@@ -894,6 +917,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int decode_poll_for_platform_event_message_req(
const struct pldm_msg *msg, size_t payload_length,
uint8_t *format_version, uint8_t *transfer_operation_flag,
@@ -940,6 +964,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int encode_platform_event_message_resp(uint8_t instance_id,
uint8_t completion_code,
uint8_t platform_event_status,
@@ -972,6 +997,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int encode_poll_for_platform_event_message_resp(
uint8_t instance_id, uint8_t completion_code, uint8_t tid,
uint16_t event_id, uint32_t next_data_transfer_handle,
@@ -1037,6 +1063,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int encode_platform_event_message_req(
uint8_t instance_id, uint8_t format_version, uint8_t tid,
uint8_t event_class, const uint8_t *event_data,
@@ -1086,6 +1113,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_platform_event_message_resp(const struct pldm_msg *msg,
size_t payload_length,
uint8_t *completion_code,
@@ -1127,6 +1155,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int encode_event_message_buffer_size_req(uint8_t instance_id,
uint16_t event_receiver_max_buffer_size,
struct pldm_msg *msg)
@@ -1150,6 +1179,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_event_message_buffer_size_resp(const struct pldm_msg *msg,
size_t payload_length,
uint8_t *completion_code,
@@ -1184,6 +1214,7 @@
return pldm_msgbuf_destroy_consumed(buf);
}
+LIBPLDM_ABI_STABLE
int encode_event_message_supported_req(uint8_t instance_id,
uint8_t format_version,
struct pldm_msg *msg)
@@ -1214,6 +1245,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_event_message_supported_resp(const struct pldm_msg *msg,
size_t payload_length,
uint8_t *completion_code,
@@ -1280,6 +1312,7 @@
return pldm_msgbuf_destroy_consumed(buf);
}
+LIBPLDM_ABI_STABLE
int decode_sensor_event_data(const uint8_t *event_data,
size_t event_data_length, uint16_t *sensor_id,
uint8_t *sensor_event_class_type,
@@ -1331,6 +1364,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int decode_sensor_op_data(const uint8_t *sensor_data, size_t sensor_data_length,
uint8_t *present_op_state, uint8_t *previous_op_state)
{
@@ -1355,6 +1389,7 @@
return pldm_msgbuf_destroy_consumed(buf);
}
+LIBPLDM_ABI_STABLE
int decode_state_sensor_data(const uint8_t *sensor_data,
size_t sensor_data_length, uint8_t *sensor_offset,
uint8_t *event_state,
@@ -1383,6 +1418,7 @@
return pldm_msgbuf_destroy_consumed(buf);
}
+LIBPLDM_ABI_STABLE
int decode_numeric_sensor_data(const uint8_t *sensor_data,
size_t sensor_data_length, uint8_t *event_state,
uint8_t *previous_event_state,
@@ -1473,6 +1509,7 @@
}
#define PLDM_NUMERIC_SENSOR_VALUE_PDR_MIN_SIZE 69
+LIBPLDM_ABI_STABLE
int decode_numeric_sensor_pdr_data(
const void *pdr_data, size_t pdr_data_length,
struct pldm_numeric_sensor_value_pdr *pdr_value)
@@ -1573,6 +1610,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int encode_get_numeric_effecter_value_req(uint8_t instance_id,
uint16_t effecter_id,
struct pldm_msg *msg)
@@ -1599,6 +1637,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int encode_get_numeric_effecter_value_resp(
uint8_t instance_id, uint8_t completion_code,
uint8_t effecter_data_size, uint8_t effecter_oper_state,
@@ -1679,6 +1718,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_get_numeric_effecter_value_req(const struct pldm_msg *msg,
size_t payload_length,
uint16_t *effecter_id)
@@ -1702,6 +1742,7 @@
return pldm_msgbuf_destroy_consumed(buf);
}
+LIBPLDM_ABI_STABLE
int decode_get_numeric_effecter_value_resp(const struct pldm_msg *msg,
size_t payload_length,
uint8_t *completion_code,
@@ -1762,6 +1803,7 @@
return pldm_msgbuf_destroy_consumed(buf);
}
+LIBPLDM_ABI_STABLE
int encode_pldm_pdr_repository_chg_event_data(
uint8_t event_data_format, uint8_t number_of_change_records,
const uint8_t *event_data_operations,
@@ -1825,6 +1867,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_pldm_pdr_repository_chg_event_data(const uint8_t *event_data,
size_t event_data_size,
uint8_t *event_data_format,
@@ -1855,6 +1898,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_TESTING
int decode_pldm_message_poll_event_data(const uint8_t *event_data,
size_t event_data_length,
uint8_t *format_version,
@@ -1891,6 +1935,7 @@
return pldm_msgbuf_destroy_consumed(buf);
}
+LIBPLDM_ABI_TESTING
int encode_pldm_message_poll_event_data(uint8_t format_version,
uint16_t event_id,
uint32_t data_transfer_handle,
@@ -1920,6 +1965,8 @@
return pldm_msgbuf_destroy(buf);
}
+
+LIBPLDM_ABI_STABLE
int decode_pldm_pdr_repository_change_record_data(
const uint8_t *change_record_data, size_t change_record_data_size,
uint8_t *event_data_operation, uint8_t *number_of_change_entries,
@@ -1949,6 +1996,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int encode_get_sensor_reading_req(uint8_t instance_id, uint16_t sensor_id,
uint8_t rearm_event_state,
struct pldm_msg *msg)
@@ -1977,6 +2025,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_get_sensor_reading_resp(
const struct pldm_msg *msg, size_t payload_length,
uint8_t *completion_code, uint8_t *sensor_data_size,
@@ -2032,6 +2081,7 @@
return pldm_msgbuf_destroy_consumed(buf);
}
+LIBPLDM_ABI_STABLE
int encode_get_sensor_reading_resp(uint8_t instance_id, uint8_t completion_code,
uint8_t sensor_data_size,
uint8_t sensor_operational_state,
@@ -2102,6 +2152,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_get_sensor_reading_req(const struct pldm_msg *msg,
size_t payload_length, uint16_t *sensor_id,
uint8_t *rearm_event_state)
@@ -2126,6 +2177,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int encode_set_event_receiver_req(uint8_t instance_id,
uint8_t event_message_global_enable,
uint8_t transport_protocol_type,
@@ -2170,6 +2222,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int decode_set_event_receiver_resp(const struct pldm_msg *msg,
size_t payload_length,
uint8_t *completion_code)
@@ -2193,6 +2246,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int decode_set_event_receiver_req(const struct pldm_msg *msg,
size_t payload_length,
uint8_t *event_message_global_enable,
@@ -2236,6 +2290,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int encode_set_event_receiver_resp(uint8_t instance_id, uint8_t completion_code,
struct pldm_msg *msg)
@@ -2260,6 +2315,7 @@
return PLDM_SUCCESS;
}
+LIBPLDM_ABI_STABLE
int encode_poll_for_platform_event_message_req(uint8_t instance_id,
uint8_t format_version,
uint8_t transfer_operation_flag,
@@ -2302,6 +2358,7 @@
return pldm_msgbuf_destroy(buf);
}
+LIBPLDM_ABI_STABLE
int decode_poll_for_platform_event_message_resp(
const struct pldm_msg *msg, size_t payload_length,
uint8_t *completion_code, uint8_t *tid, uint16_t *event_id,