// Copyright 2020 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
// =============================================================================
//
// This file describes Pigweed's public user-facing assert API.
//
// THIS API IS NOT STABLE OR COMPLETE! NEITHER FACADE NOR BACKEND API!
//
#pragma once

#include "pw_preprocessor/macro_arg_count.h"

// The pw_assert public API:
//
//   Trigger a crash with a message. Replaces LOG_FATAL() in other systems.
//   PW_CRASH(msg, ...)
//
//   In all below cases, the message argument is optional:
//   PW_CHECK_INT_LE(x, y) or
//   PW_CHECK_INT_LE(x, y, "Was booting %s subsystem", subsystem_name)
//
//   Asserts the condition, crashes on failure. Equivalent to assert.
//   PW_CHECK(condition) or
//   PW_CHECK(condition, msg, ...)
//
//   Some common typed checks.
//   PW_CHECK_OK(status, msg, ...)  Asserts status == PW_STATUS_OK
//   PW_CHECK_NOTNULL(ptr, msg, ...)  Asserts ptr != NULL
//
//   In many cases an assert is a binary comparison. In those cases, using the
//   special binary assert macros below for <, <=, >, >=, == enables reporting
//   the values of the operands in addition to the string of the condition.
//
//   Binary comparison asserts for 'int' type ("%d" in format strings):
//   PW_CHECK_INT_LE(a, b, msg, ...)  Asserts a <= b
//   PW_CHECK_INT_LT(a, b, msg, ...)  Asserts a <  b
//   PW_CHECK_INT_GE(a, b, msg, ...)  Asserts a >= b
//   PW_CHECK_INT_GT(a, b, msg, ...)  Asserts a >  b
//   PW_CHECK_INT_EQ(a, b, msg, ...)  Asserts a == b
//   PW_CHECK_INT_NE(a, b, msg, ...)  Asserts a != b
//
//   Binary comparison asserts for 'unsigned int' type ("%u" in format strings):
//   PW_CHECK_UINT_LE(a, b, msg, ...)  Asserts a <= b
//   PW_CHECK_UINT_LT(a, b, msg, ...)  Asserts a <  b
//   PW_CHECK_UINT_GE(a, b, msg, ...)  Asserts a >= b
//   PW_CHECK_UINT_GT(a, b, msg, ...)  Asserts a >  b
//   PW_CHECK_UINT_EQ(a, b, msg, ...)  Asserts a == b
//   PW_CHECK_UINT_NE(a, b, msg, ...)  Asserts a != b
//
//   Binary comparison asserts for 'void*' type ("%p" in format strings):
//   PW_CHECK_PTR_LE(a, b, msg, ...)  Asserts a <= b
//   PW_CHECK_PTR_LT(a, b, msg, ...)  Asserts a <  b
//   PW_CHECK_PTR_GE(a, b, msg, ...)  Asserts a >= b
//   PW_CHECK_PTR_GT(a, b, msg, ...)  Asserts a >  b
//   PW_CHECK_PTR_EQ(a, b, msg, ...)  Asserts a == b
//   PW_CHECK_PTR_NE(a, b, msg, ...)  Asserts a != b
//
//   Binary comparison asserts for 'float' type ("%f" in format strings):
//   PW_CHECK_FLOAT_NEAR(a, b, abs_tolerance, msg, ...)
//     Asserts (a >= (b - abs_tolerance)) && (a <= (b + abs_tolerance))
//   PW_CHECK_FLOAT_EXACT_LE(a, b, msg, ...)  Asserts a <= b
//   PW_CHECK_FLOAT_EXACT_LT(a, b, msg, ...)  Asserts a <  b
//   PW_CHECK_FLOAT_EXACT_GE(a, b, msg, ...)  Asserts a >= b
//   PW_CHECK_FLOAT_EXACT_GT(a, b, msg, ...)  Asserts a >  b
//   PW_CHECK_FLOAT_EXACT_EQ(a, b, msg, ...)  Asserts a == b
//   PW_CHECK_FLOAT_EXACT_NE(a, b, msg, ...)  Asserts a != b
//
//   The above CHECK_*_*() are also available in DCHECK variants, which will
//   only evaluate their arguments and trigger if the NDEBUG macro is defined.
//
//   Note: For float, proper comparator checks which take floating point
//   precision and ergo error accumulation into account are not provided on
//   purpose as this comes with some complexity and requires application
//   specific tolerances in terms of Units of Least Precision (ULP). Instead,
//   we recommend developers carefully consider how floating point precision and
//   error impact the data they are bounding and whether CHECKs are appropriate.
//
//   Note: PW_CRASH is the equivalent of LOG_FATAL in other systems, where a
//   device crash is triggered with a message. In Pigweed, logging and
//   crashing/asserting are separated. There is a LOG_CRITICAL level in the
//   logging module, but it does not have side effects; for LOG_FATAL, instead
//   use this macro (PW_CRASH).
//
// The public macro definitions are split out into an impl file to facilitate
// testing the facade logic directly, without going through the facade/backend
// build facilities.
#include "pw_assert/internal/assert_impl.h"

// The pw_assert_backend must provide these macros:
//
//   PW_HANDLE_CRASH(msg, ...)
//   PW_HANDLE_ASSERT_FAILURE(condition, msg, ...)
//   PW_HANDLE_ASSERT_BINARY_COMPARE_FAILURE(a, op, b, type_fmt, msg, ...)
//
//   The low level functionality of triggering a crash, rebooting a device,
//   collecting information, or hanging out in a while(1) loop, must be
//   provided by the underlying assert backend as part of the crash or assert
//   failure handling.
//
//   Note that for the assert failures, the handler should assume the assert
//   has already failed (the facade checks the condition before delegating).
//
#include "pw_assert_backend/assert_backend.h"