/* **********************************************************
 * Copyright 2004 - 2009 VMware, Inc.  All rights reserved.
 * **********************************************************/

/*
 * @VMKAPIMOD_LICENSE@
 */

/*
 ***********************************************************************
 * Assertions                                                     */ /**
 * \defgroup Assert Assertions
 *
 * Assertions and related interfaces.
 *
 * @{
 ***********************************************************************
 */

#ifndef _VMKAPI_ASSERT_H_
#define _VMKAPI_ASSERT_H_

/** \cond never */
#ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H
#error This vmkapi file should never be included directly but only via vmkapi.h
#endif
/** \endcond never */

#include "base/vmkapi_compiler.h"
#include "base/vmkapi_types.h"

#include <stdarg.h>

/*
 ***********************************************************************
 * vmk_vPanic --                                                  */ /**
 *
 * \ingroup Assert
 * \brief Panics the system.
 *
 * Used in unrecoverable error conditions.\n
 * A system dump is generated if a dump device has been configured.
 *
 ***********************************************************************
 */
void vmk_vPanic(
   const char *fmt,
   va_list ap);

/*
 ***********************************************************************
 * vmk_Panic --                                                   */ /**
 *
 * \ingroup Assert
 * \brief Panics the system.
 *
 * Used in unrecoverable error conditions.\n
 * A system dump is generated if a dump device has been configured.
 *
 ***********************************************************************
 */
void
vmk_Panic(
   const char *fmt,
   ...)
VMK_ATTRIBUTE_PRINTF(1,2);

/*
 ***********************************************************************
 * VMK_ASSERT_BUG --                                              */ /**
 *
 * \ingroup Assert
 * \brief Panics the system if a runtime expression evalutes to false
 *        regardless of debug build status.
 *
 * \param[in] _cond_    Expression to check.
 *
 ***********************************************************************
 */
#define VMK_ASSERT_BUG(_cond_)                                    \
   do {                                                           \
      if (VMK_UNLIKELY(!(_cond_))) {                              \
         vmk_Panic("Failed at %s:%d -- VMK_ASSERT(%s)\n",         \
                   __FILE__, __LINE__, #_cond_);                  \
         /* Ensure that we don't lose warnings in condition */    \
         if (0) { if (_cond_) {;} } (void)0;                      \
      }                                                           \
   } while(0)

/*
 ***********************************************************************
 * VMK_ASSERT --                                                  */ /**
 *
 * \ingroup Assert
 * \brief Panics the system if a runtime expression evalutes to false
 *        only in debug builds.
 *
 * \param[in] _cond_    Expression to check.
 *
 ***********************************************************************
 */
#if defined(VMX86_DEBUG)
#define VMK_ASSERT(_cond_) VMK_ASSERT_BUG(_cond_)
#else
#define VMK_ASSERT(_cond_)
#endif


/*
 ***********************************************************************
 * VMK_ASSERT_ON_COMPILE --                                       */ /**
 *
 * \ingroup Assert
 * \brief Fail compilation if a condition does not hold true
 *
 * \note This macro must be used inside the context of a function.
 *
 * \param[in] _cond_    Expression to check.
 *
 ***********************************************************************
 */
#define VMK_ASSERT_ON_COMPILE(_cond_)                    \
   do {                                                  \
      switch(0) {                                        \
         case 0:                                         \
         case (_cond_):                                  \
            ;                                            \
      }                                                  \
   } while(0)                                            \

/*
 ***********************************************************************
 * VMK_ASSERT_LIST --                                             */ /**
 *
 * \ingroup Assert
 * \brief  To put a VMK_ASSERT_ON_COMPILE() outside a function, wrap it
 *         in VMK_ASSERT_LIST(). The first parameter must be unique in
 *         each .c file where it appears
 *
 * \par Example usage with VMK_ASSERT_ON_COMPILE:
 *
 * \code
 * VMK_ASSERT_LIST(fs_assertions,
 *    VMK_ASSERT_ON_COMPILE(sizeof(fs_diskLock) == 128);
 *    VMK_ASSERT_ON_COMPILE(sizeof(fs_LockRes) == DISK_BLK_SIZE);
 * )
 * \endcode
 *
 * \param[in] _name_          Unique name of the list of assertions.
 * \param[in] _assertions_    Individual assert-on-compile statements.
 *
 ***********************************************************************
 */
#define VMK_ASSERT_LIST(_name_, _assertions_)      \
   static inline void _name_(void) {               \
      _assertions_                                 \
   }

/*
 ***********************************************************************
 * VMK_DEBUG_ONLY --                                              */ /**
 *
 * \ingroup Assert
 * \brief Compile code only for debug builds.
 *
 * \par Example usage:
 *
 * \code
 * VMK_DEBUG_ONLY(
 *    myFunc();
 *    x = 1;
 *    y = 3;
 * )
 * \endcode
 *
 ***********************************************************************
 */
#if defined(VMX86_DEBUG)
#define VMK_DEBUG_ONLY(x) x
#else
#define VMK_DEBUG_ONLY(x)
#endif

/*
 ***********************************************************************
 * VMK_NOT_REACHED --                                             */ /**
 *
 * \ingroup Assert
 * \brief Panic if code reaches this call
 *
 ***********************************************************************
 */
#define VMK_NOT_REACHED() \
   vmk_Panic("Failed at %s:%d -- NOT REACHED\n", __FILE__, __LINE__)

#endif /* _VMKAPI_ASSERT_H_ */
/** @} */