// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0

#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_WARN_UNUSED_RESULT_H_
#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_WARN_UNUSED_RESULT_H_

/**
 * @file
 * @brief Unused Result Warning Macro for DIFs.
 */

// Header Extern Guard (so header can be used from C and C++)
#ifdef __cplusplus
extern "C" {
#endif  // __cplusplus

/**
 * Attribute for functions which return errors that must be acknowledged.
 *
 * This attribute must be used to mark all DIFs which return an error value of
 * some kind, to ensure that callers do not accidentally drop the error on the
 * ground.
 *
 * Normally, the standard way to drop such a value on the ground explicitly is
 * with the syntax `(void)expr;`, in analogy with the behavior of C++'s
 * `[[nodiscard]]` attribute.
 * However, GCC does not implement this, so the idiom `if (expr) {}` should be
 * used instead, for the time being.
 * See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=25509.
 */
#define DIF_WARN_UNUSED_RESULT __attribute__((warn_unused_result))

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_WARN_UNUSED_RESULT_H_

// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0

#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_WARN_UNUSED_RESULT_H_
#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_WARN_UNUSED_RESULT_H_

/**
 * @file
 * @brief Unused Result Warning Macro for DIFs.
 */

// Header Extern Guard (so header can be used from C and C++)
#ifdef __cplusplus
extern "C" {
#endif  // __cplusplus

/**
 * Attribute for functions which return errors that must be acknowledged.
 *
 * This attribute must be used to mark all DIFs which return an error value of
 * some kind, to ensure that callers do not accidentally drop the error on the
 * ground.
 */
#define DIF_WARN_UNUSED_RESULT __attribute__((warn_unused_result))

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_WARN_UNUSED_RESULT_H_

--- 
+++ 
@@ -21,6 +21,13 @@
  * This attribute must be used to mark all DIFs which return an error value of
  * some kind, to ensure that callers do not accidentally drop the error on the
  * ground.
+ *
+ * Normally, the standard way to drop such a value on the ground explicitly is
+ * with the syntax `(void)expr;`, in analogy with the behavior of C++'s
+ * `[[nodiscard]]` attribute.
+ * However, GCC does not implement this, so the idiom `if (expr) {}` should be
+ * used instead, for the time being.
+ * See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=25509.
  */
 #define DIF_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
 
[dif] Add a comment explaining how to drop an error on the ground

See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=25509, which
necessitates doing this in a non-standard, but still portable, manner.

Signed-off-by: Miguel Young de la Sota <71b8e7f4945fd97b98544cf897992af89646547a@google.com>
