include/rtems/status-checks.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @brief Header File for Status Checks
0007  *
0008  * @warning Do not include this file in other header files.  Use it only in
0009  * source files.
0010  */
0011
0012 /*
0013  * Copyright (c) 2008 embedded brains GmbH & Co. KG
0014  * Redistribution and use in source and binary forms, with or without
0015  * modification, are permitted provided that the following conditions
0016  * are met:
0017  * 1. Redistributions of source code must retain the above copyright
0018  *    notice, this list of conditions and the following disclaimer.
0019  * 2. Redistributions in binary form must reproduce the above copyright
0020  *    notice, this list of conditions and the following disclaimer in the
0021  *    documentation and/or other materials provided with the distribution.
0022  *
0023  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0024  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0025  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0026  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0027  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0028  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0029  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0030  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0031  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0032  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0033  * POSSIBILITY OF SUCH DAMAGE.
0034  */
0035
0036 #ifndef RTEMS_STATUS_CHECKS_H
0037 #define RTEMS_STATUS_CHECKS_H
0038
0039 #include <rtems/bspIo.h>
0040
0041 #ifdef __cplusplus
0042 extern "C" {
0043 #endif /* __cplusplus */
0044
0045 /**
0046  * @defgroup rtems_status_checks Status Checks
0047  *
0048  * @ingroup RTEMSAPI
0049  */
0050 /**@{**/
0051
0052 /**
0053  * @name Print Macros
0054  */
0055 /**@{**/
0056
0057 /**
0058  * @brief General purpose debug print macro.
0059  */
0060 #ifdef DEBUG
0061   #ifndef RTEMS_DEBUG_PRINT
0062     #ifdef RTEMS_STATUS_CHECKS_USE_PRINTK
0063       #define RTEMS_DEBUG_PRINT( fmt, ...) \
0064         printk( "%s: " fmt, __func__, ##__VA_ARGS__)
0065     #else /* RTEMS_STATUS_CHECKS_USE_PRINTK */
0066       #include <stdio.h>
0067       #define RTEMS_DEBUG_PRINT( fmt, ...) \
0068         printf( "%s: " fmt, __func__, ##__VA_ARGS__)
0069     #endif /* RTEMS_STATUS_CHECKS_USE_PRINTK */
0070   #endif /* RTEMS_DEBUG_PRINT */
0071 #else /* DEBUG */
0072   #ifdef RTEMS_DEBUG_PRINT
0073     #warning RTEMS_DEBUG_PRINT was defined, but DEBUG was undefined
0074     #undef RTEMS_DEBUG_PRINT
0075   #endif /* RTEMS_DEBUG_PRINT */
0076   #define RTEMS_DEBUG_PRINT( fmt, ...)
0077 #endif /* DEBUG */
0078
0079 /**
0080  * @brief Macro to print debug messages for successful operations.
0081  */
0082 #define RTEMS_DEBUG_OK( msg) \
0083   RTEMS_DEBUG_PRINT( "Ok: %s\n", msg)
0084
0085 /**
0086  * @brief General purpose system log print macro.
0087  */
0088 #ifndef RTEMS_SYSLOG_PRINT
0089   #ifdef RTEMS_STATUS_CHECKS_USE_PRINTK
0090     #define RTEMS_SYSLOG_PRINT( fmt, ...) \
0091       printk( fmt, ##__VA_ARGS__)
0092   #else /* RTEMS_STATUS_CHECKS_USE_PRINTK */
0093     #include <stdio.h>
0094     #define RTEMS_SYSLOG_PRINT( fmt, ...) \
0095       printf( fmt, ##__VA_ARGS__)
0096   #endif /* RTEMS_STATUS_CHECKS_USE_PRINTK */
0097 #endif /* RTEMS_SYSLOG_PRINT */
0098
0099 /**
0100  * @brief General purpose system log macro.
0101  */
0102 #define RTEMS_SYSLOG( fmt, ...) \
0103   RTEMS_SYSLOG_PRINT( "%s: " fmt, __func__, ##__VA_ARGS__)
0104
0105 /**
0106  * @brief General purpose system log macro for warnings.
0107  */
0108 #define RTEMS_SYSLOG_WARNING( fmt, ...) \
0109   RTEMS_SYSLOG( "Warning: " fmt, ##__VA_ARGS__)
0110
0111 /**
0112  * @brief Macro to generate a system log warning message if the status code @a
0113  * sc is not equal to @ref RTEMS_SUCCESSFUL.
0114  */
0115 #define RTEMS_SYSLOG_WARNING_SC( sc, msg) \
0116   if ((rtems_status_code) (sc) != RTEMS_SUCCESSFUL) { \
0117     RTEMS_SYSLOG_WARNING( "SC = %i: %s\n", (int) sc, msg); \
0118   }
0119
0120 /**
0121  * @brief General purpose system log macro for errors.
0122  */
0123 #define RTEMS_SYSLOG_ERROR( fmt, ...) \
0124   RTEMS_SYSLOG( "Error: " fmt, ##__VA_ARGS__)
0125
0126 /**
0127  * @brief Macro for system log error messages with status code.
0128  */
0129 #define RTEMS_SYSLOG_ERROR_WITH_SC( sc, msg) \
0130   RTEMS_SYSLOG_ERROR( "SC = %i: %s\n", (int) sc, msg);
0131
0132 /**
0133  * @brief Macro for system log error messages with return value.
0134  */
0135 #define RTEMS_SYSLOG_ERROR_WITH_RV( rv, msg) \
0136   RTEMS_SYSLOG_ERROR( "RV = %i: %s\n", (int) rv, msg);
0137
0138 /**
0139  * @brief Macro to generate a system log error message if the status code @a
0140  * sc is not equal to @ref RTEMS_SUCCESSFUL.
0141  */
0142 #define RTEMS_SYSLOG_ERROR_SC( sc, msg) \
0143   if ((rtems_status_code) (sc) != RTEMS_SUCCESSFUL) { \
0144     RTEMS_SYSLOG_ERROR_WITH_SC( sc, msg); \
0145   }
0146
0147 /**
0148  * @brief Macro to generate a system log error message if the return value @a
0149  * rv is less than zero.
0150  */
0151 #define RTEMS_SYSLOG_ERROR_RV( rv, msg) \
0152   if ((int) (rv) < 0) { \
0153     RTEMS_SYSLOG_ERROR_WITH_RV( rv, msg); \
0154   }
0155
0156 /** @} */
0157
0158 /**
0159  * @name Check Macros
0160  */
0161 /**@{**/
0162
0163 /**
0164  * @brief Prints message @a msg and returns with status code @a sc if the status
0165  * code @a sc is not equal to @ref RTEMS_SUCCESSFUL.
0166  */
0167 #define RTEMS_CHECK_SC( sc, msg) \
0168   if ((rtems_status_code) (sc) != RTEMS_SUCCESSFUL) { \
0169     RTEMS_SYSLOG_ERROR_WITH_SC( sc, msg); \
0170     return (rtems_status_code) sc; \
0171   } else { \
0172     RTEMS_DEBUG_OK( msg); \
0173   }
0174
0175 /**
0176  * @brief Prints message @a msg and returns with a return value of negative @a sc
0177  * if the status code @a sc is not equal to @ref RTEMS_SUCCESSFUL.
0178  */
0179 #define RTEMS_CHECK_SC_RV( sc, msg) \
0180   if ((rtems_status_code) (sc) != RTEMS_SUCCESSFUL) { \
0181     RTEMS_SYSLOG_ERROR_WITH_SC( sc, msg); \
0182     return -((int) (sc)); \
0183   } else { \
0184     RTEMS_DEBUG_OK( msg); \
0185   }
0186
0187 /**
0188  * @brief Prints message @a msg and returns if the status code @a sc is not equal
0189  * to @ref RTEMS_SUCCESSFUL.
0190  */
0191 #define RTEMS_CHECK_SC_VOID( sc, msg) \
0192   if ((rtems_status_code) (sc) != RTEMS_SUCCESSFUL) { \
0193     RTEMS_SYSLOG_ERROR_WITH_SC( sc, msg); \
0194     return; \
0195   } else { \
0196     RTEMS_DEBUG_OK( msg); \
0197   }
0198
0199 /**
0200  * @brief Prints message @a msg and delete the current task if the status code
0201  * @a sc is not equal to @ref RTEMS_SUCCESSFUL.
0202  */
0203 #define RTEMS_CHECK_SC_TASK( sc, msg) \
0204   if ((rtems_status_code) (sc) != RTEMS_SUCCESSFUL) { \
0205     RTEMS_SYSLOG_ERROR_WITH_SC( sc, msg); \
0206     rtems_task_exit(); \
0207     return; \
0208   } else { \
0209     RTEMS_DEBUG_OK( msg); \
0210   }
0211
0212 /**
0213  * @brief Prints message @a msg and returns with a return value @a rv if the
0214  * return value @a rv is less than zero.
0215  */
0216 #define RTEMS_CHECK_RV( rv, msg) \
0217   if ((int) (rv) < 0) { \
0218     RTEMS_SYSLOG_ERROR_WITH_RV( rv, msg); \
0219     return (int) rv; \
0220   } else { \
0221     RTEMS_DEBUG_OK( msg); \
0222   }
0223
0224 /**
0225  * @brief Prints message @a msg and returns with status code @ref RTEMS_IO_ERROR
0226  * if the return value @a rv is less than zero.
0227  */
0228 #define RTEMS_CHECK_RV_SC( rv, msg) \
0229   if ((int) (rv) < 0) { \
0230     RTEMS_SYSLOG_ERROR_WITH_RV( rv, msg); \
0231     return RTEMS_IO_ERROR; \
0232   } else { \
0233     RTEMS_DEBUG_OK( msg); \
0234   }
0235
0236 /**
0237  * @brief Prints message @a msg and returns if the return value @a rv is less
0238  * than zero.
0239  */
0240 #define RTEMS_CHECK_RV_VOID( rv, msg) \
0241   if ((int) (rv) < 0) { \
0242     RTEMS_SYSLOG_ERROR_WITH_RV( rv, msg); \
0243     return; \
0244   } else { \
0245     RTEMS_DEBUG_OK( msg); \
0246   }
0247
0248 /**
0249  * @brief Prints message @a msg and delete the current task if the return value
0250  * @a rv is less than zero.
0251  */
0252 #define RTEMS_CHECK_RV_TASK( rv, msg) \
0253   if ((int) (rv) < 0) { \
0254     RTEMS_SYSLOG_ERROR_WITH_RV( rv, msg); \
0255     rtems_task_exit(); \
0256     return; \
0257   } else { \
0258     RTEMS_DEBUG_OK( msg); \
0259   }
0260
0261 /** @} */
0262
0263 /**
0264  * @name Cleanup Macros
0265  */
0266 /**@{**/
0267
0268 /**
0269  * @brief Prints message @a msg and jumps to @a label if the status code @a sc
0270  * is not equal to @ref RTEMS_SUCCESSFUL.
0271  */
0272 #define RTEMS_CLEANUP_SC( sc, label, msg) \
0273   if ((rtems_status_code) (sc) != RTEMS_SUCCESSFUL) { \
0274     RTEMS_SYSLOG_ERROR_WITH_SC( sc, msg); \
0275     goto label; \
0276   } else { \
0277     RTEMS_DEBUG_OK( msg); \
0278   }
0279
0280 /**
0281  * @brief Prints message @a msg and jumps to @a label if the status code @a sc
0282  * is not equal to @ref RTEMS_SUCCESSFUL.  The return value variable @a rv will
0283  * be set to a negative @a sc in this case.
0284  */
0285 #define RTEMS_CLEANUP_SC_RV( sc, rv, label, msg) \
0286   if ((rtems_status_code) (sc) != RTEMS_SUCCESSFUL) { \
0287     RTEMS_SYSLOG_ERROR_WITH_SC( sc, msg); \
0288     rv = -((int) (sc)); \
0289     goto label; \
0290   } else { \
0291     RTEMS_DEBUG_OK( msg); \
0292   }
0293
0294 /**
0295  * @brief Prints message @a msg and jumps to @a label if the return value @a rv
0296  * is less than zero.
0297  */
0298 #define RTEMS_CLEANUP_RV( rv, label, msg) \
0299   if ((int) (rv) < 0) { \
0300     RTEMS_SYSLOG_ERROR_WITH_RV( rv, msg); \
0301     goto label; \
0302   } else { \
0303     RTEMS_DEBUG_OK( msg); \
0304   }
0305
0306 /**
0307  * @brief Prints message @a msg and jumps to @a label if the return value @a rv
0308  * is less than zero.  The status code variable @a sc will be set to @ref
0309  * RTEMS_IO_ERROR in this case.
0310  */
0311 #define RTEMS_CLEANUP_RV_SC( rv, sc, label, msg) \
0312   if ((int) (rv) < 0) { \
0313     RTEMS_SYSLOG_ERROR_WITH_RV( rv, msg); \
0314     sc = RTEMS_IO_ERROR; \
0315     goto label; \
0316   } else { \
0317     RTEMS_DEBUG_OK( msg); \
0318   }
0319
0320 /**
0321  * @brief Prints message @a msg and jumps to @a label.
0322  */
0323 #define RTEMS_DO_CLEANUP( label, msg) \
0324   do { \
0325     RTEMS_SYSLOG_ERROR( msg); \
0326     goto label; \
0327   } while (0)
0328
0329 /**
0330  * @brief Prints message @a msg, sets the status code variable @a sc to @a val
0331  * and jumps to @a label.
0332  */
0333 #define RTEMS_DO_CLEANUP_SC( val, sc, label, msg) \
0334   do { \
0335     sc = (rtems_status_code) val; \
0336     RTEMS_SYSLOG_ERROR_WITH_SC( sc, msg); \
0337     goto label; \
0338   } while (0)
0339
0340 /**
0341  * @brief Prints message @a msg, sets the return value variable @a rv to @a val
0342  * and jumps to @a label.
0343  */
0344 #define RTEMS_DO_CLEANUP_RV( val, rv, label, msg) \
0345   do { \
0346     rv = (int) val; \
0347     RTEMS_SYSLOG_ERROR_WITH_RV( rv, msg); \
0348     goto label; \
0349   } while (0)
0350
0351 /** @} */
0352
0353 /** @} */
0354
0355 #ifdef __cplusplus
0356 }
0357 #endif /* __cplusplus */
0358
0359 #endif /* RTEMS_STATUS_CHECKS_H */