dsp: fru: Rename get_fru_record_by_option_check()
We drop the `_check` suffix so that it is now
`get_fru_record_by_option()`.
To do so, introduce some infrastructure that makes renaming APIs
easier and scripts the migration for users. The renaming process comes
in several parts, which are captured in the addition to the changes
checklist.
The coccinelle script based off the insight at [1].
[1]: https://stackoverflow.com/questions/42776220/coccinelle-help-to-replace-a-function-with-variable-args
Change-Id: I730b76c3e3c92dcc046fecbee76cd6b040f11d21
Signed-off-by: Andrew Jeffery <andrew@codeconstruct.com.au>
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5f094c0..6c2cb1b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,23 @@
1. base: Define macros for reserved TIDs
+### Deprecated
+
+1. fru: Deprecate `get_fru_record_by_option_check()`
+
+ Users should switch to `get_fru_record_by_option()`. Migration can be
+ performed using the [Coccinelle semantic patch][coccinelle]
+ `get_fru_record_by_option_check.cocci`:
+
+ ```
+ $ spatch \
+ --sp-file=${LIBPLDM_DIR}/evolutions/current/get_fru_record_by_option_check.cocci \
+ --in-place \
+ $(git ls-files | grep -E '\.[ch](pp)?')
+ ```
+
+[coccinelle]: https://coccinelle.gitlabpages.inria.fr/website/
+
## [0.8.0] - 2024-05-23
### Added
diff --git a/docs/checklists/changes.md b/docs/checklists/changes.md
index 7d00e65..c28f9bb 100644
--- a/docs/checklists/changes.md
+++ b/docs/checklists/changes.md
@@ -176,6 +176,28 @@
- [ ] There has been at least one tagged release of `libpldm` subsequent to
the API being marked deprecated
+## Renaming an API
+
+A change to an API is a pure rename only if there are no additional behavioural
+changes. Renaming an API with no other behavioural changes is really two
+actions:
+
+1. Introducing the new API name
+2. Deprecating the old API name
+
+- [ ] Only the name of the function has changed. None of its behaviour has
+ changed.
+
+- [ ] Both the new and the old functions are declared in the public headers
+
+- [ ] I've aliased the old function name to the new function name via the
+ `libpldm_deprecated_aliases` list in `meson.build`
+
+- [ ] I've added a [semantic patch][coccinelle] to migrate users from the old
+ name to the new name
+
+[coccinelle]: https://coccinelle.gitlabpages.inria.fr/website/
+
## Testing my changes
Each of the following must succeed when executed in order. Note that to avoid
diff --git a/evolutions/current/get_fru_record_by_option_check.cocci b/evolutions/current/get_fru_record_by_option_check.cocci
new file mode 100644
index 0000000..5682f88
--- /dev/null
+++ b/evolutions/current/get_fru_record_by_option_check.cocci
@@ -0,0 +1,6 @@
+@@
+@@
+- get_fru_record_by_option_check(
++ get_fru_record_by_option(
+ ...
+ )
diff --git a/include/libpldm/fru.h b/include/libpldm/fru.h
index 1563cb7..f337c43 100644
--- a/include/libpldm/fru.h
+++ b/include/libpldm/fru.h
@@ -465,9 +465,13 @@
* @return PLDM_SUCCESS if no error occurs. PLDM_ERROR_INVALID_LENGTH if record_size lacks capacity
* to encode the relevant records.
*/
+int get_fru_record_by_option(const uint8_t *table, size_t table_size,
+ uint8_t *record_table, size_t *record_size,
+ uint16_t rsi, uint8_t rt, uint8_t ft);
int get_fru_record_by_option_check(const uint8_t *table, size_t table_size,
uint8_t *record_table, size_t *record_size,
uint16_t rsi, uint8_t rt, uint8_t ft);
+
/* SetFruRecordTable */
/** @brief Decode SetFruRecordTable request data
diff --git a/meson.build b/meson.build
index f9c943b..0a2cc04 100644
--- a/meson.build
+++ b/meson.build
@@ -27,9 +27,13 @@
# ABI control
visible = '__attribute__((visibility("default")))'
+libpldm_deprecated_aliases = []
if get_option('abi').contains('deprecated')
conf.set('LIBPLDM_ABI_DEPRECATED', visible)
add_project_arguments('-DLIBPLDM_API_DEPRECATED', language: ['c', 'cpp'])
+ libpldm_deprecated_aliases += [
+ ['get_fru_record_by_option_check', 'get_fru_record_by_option'],
+ ]
else
conf.set('LIBPLDM_ABI_DEPRECATED', '')
endif
diff --git a/src/dsp/fru.c b/src/dsp/fru.c
index fd6120e..b7fa2b6 100644
--- a/src/dsp/fru.c
+++ b/src/dsp/fru.c
@@ -213,9 +213,9 @@
}
LIBPLDM_ABI_STABLE
-int get_fru_record_by_option_check(const uint8_t *table, size_t table_size,
- uint8_t *record_table, size_t *record_size,
- uint16_t rsi, uint8_t rt, uint8_t ft)
+int get_fru_record_by_option(const uint8_t *table, size_t table_size,
+ uint8_t *record_table, size_t *record_size,
+ uint16_t rsi, uint8_t rt, uint8_t ft)
{
const struct pldm_fru_record_data_format *record_data_src =
(const struct pldm_fru_record_data_format *)table;
diff --git a/src/meson.build b/src/meson.build
index 525463f..5242eed 100644
--- a/src/meson.build
+++ b/src/meson.build
@@ -15,6 +15,11 @@
subdir('oem/meta')
endif
+libpldm_link_args = []
+foreach alias : libpldm_deprecated_aliases
+ libpldm_link_args += '-Wl,--defsym=@0@=@1@'.format(alias[0], alias[1])
+endforeach
+
libpldm = library(
'pldm',
libpldm_sources,
@@ -23,6 +28,7 @@
libpldm_include_dir,
include_directories('.')
],
+ link_args: libpldm_link_args,
version: meson.project_version(),
gnu_symbol_visibility: 'hidden',
install: true