From 2c62fec96e3201ef51a41427465dbcf97ad5ecdf Mon Sep 17 00:00:00 2001 From: chrysn Date: Wed, 12 Dec 2018 20:19:07 +0100 Subject: [PATCH] saul/doc: Warn about and deprecate saul_reg_rm saul_reg_rm can not be used safely unless in tight coordination with the application. This points out the issue, puts the onus of making sure nobody calls vanishing registrations on the device driver and deprecates the call (as the requirements for correct usage are practically impossible to fulfull for a generic driver). --- sys/include/saul_reg.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/sys/include/saul_reg.h b/sys/include/saul_reg.h index 624e1db1b3..ec2ae81588 100644 --- a/sys/include/saul_reg.h +++ b/sys/include/saul_reg.h @@ -72,6 +72,16 @@ int saul_reg_add(saul_reg_t *dev); /** * @brief Unregister a device from the SAUL registry * + * @warning Removing the device at runtime can send applications that have + * looked up that device into invalid states, and should thus be + * avoided. + * + * @warning This function must only be used by drivers that advise developers + * using them on how to prevent race conditions when using SAUL. + * + * @deprecated This function will be removed soon as it is practically unusable + * for the above reasons. + * * @param[in] dev pointer to a registry entry * * @return 0 on success