aboutsummaryrefslogtreecommitdiff
path: root/include/libopencm3/cm3
diff options
context:
space:
mode:
Diffstat (limited to 'include/libopencm3/cm3')
-rw-r--r--include/libopencm3/cm3/assert.h136
-rw-r--r--include/libopencm3/cm3/common.h10
-rw-r--r--include/libopencm3/cm3/doc-cm3.h22
-rw-r--r--include/libopencm3/cm3/docmain.h70
4 files changed, 168 insertions, 70 deletions
diff --git a/include/libopencm3/cm3/assert.h b/include/libopencm3/cm3/assert.h
new file mode 100644
index 0000000..0ccb0f7
--- /dev/null
+++ b/include/libopencm3/cm3/assert.h
@@ -0,0 +1,136 @@
+/** @defgroup debugging Debugging
+
+@brief Macros and functions to aid in debugging
+
+@version 1.0.0
+
+@date 25 September 2012
+
+Two preprocessor defines control the behavior of assertion check macros in
+this module. They allow the choice between generated code size and ease of
+debugging.
+
+If NDEBUG is defined, all assertion checks are disabled and macros do not
+generate any code.
+
+If CM3_ASSERT_VERBOSE is defined, information regarding the position of
+assertion checks will be stored in the binary, allowing for more
+informative error messages, but also significantly increased code size. As
+default assertion checks do not use this information it is only useful if
+the application linked with libopencm3 defines its own
+cm3_assert_failed_verbose() implementation.
+
+LGPL License Terms @ref lgpl_license
+*/
+
+/*
+ * This file is part of the libopencm3 project.
+ *
+ * Copyright (C) 2012 Tomaz Solc <tomaz.solc@tablix.org>
+ *
+ * This library is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/**@{*/
+
+#ifndef LIBOPENCM3_CM3_ASSERT_H
+#define LIBOPENCM3_CM3_ASSERT_H
+
+#include <libopencm3/cm3/common.h>
+
+#define CM3_LIKELY(expr) (__builtin_expect (!!(expr), 1))
+
+#ifdef NDEBUG
+# define cm3_assert(expr) do { (void)0; } while(0)
+# define cm3_assert_not_reached() while(1)
+#else
+# ifdef CM3_ASSERT_VERBOSE
+# define cm3_assert(expr) do { \
+ if(CM3_LIKELY(expr)) { (void)0; } else { \
+ cm3_assert_failed_verbose( \
+ __FILE__, __LINE__, \
+ __func__, #expr); \
+ } \
+ } while(0)
+# define cm3_assert_not_reached() do { \
+ cm3_assert_failed_verbose( \
+ __FILE__, __LINE__, \
+ __func__, 0); \
+ } while(0)
+# else
+/** @brief Check if assertion is true.
+ *
+ * If NDEBUG macro is defined, this macro generates no code. Otherwise
+ * cm3_assert_failed() or cm3_assert_failed_verbose() is called if assertion
+ * is false.
+ *
+ * The purpose of this macro is to aid in debugging libopencm3 and
+ * applications using it. It can be used for example to check if function
+ * arguments are within expected ranges and stop execution in case an
+ * unexpected state is reached.
+ *
+ * @param expr expression to check */
+# define cm3_assert(expr) do { \
+ if(CM3_LIKELY(expr)) { (void)0; } else { \
+ cm3_assert_failed(); \
+ } \
+ } while(0)
+/** @brief Check if unreachable code is reached.
+ *
+ * If NDEBUG macro is defined, this macro generates code for an infinite loop.
+ * Otherwise cm3_assert_failed() or cm3_assert_failed_verbose() is called if
+ * the macro is ever reached.
+ *
+ * The purpose of this macro is to aid in debugging libopencm3 and
+ * applications using it. It can be used for example to stop execution if an
+ * unreachable portion of code is reached. */
+# define cm3_assert_not_reached() do { \
+ cm3_assert_failed(); \
+ } while(0)
+# endif
+#endif
+
+BEGIN_DECLS
+
+/** @brief Called on a failed assertion.
+ *
+ * Halts execution in an infinite loop. This function never returns.
+ *
+ * Defined as a weak symbol, so applications can define their own
+ * implementation. Usually, a custom implementation of this function should
+ * report an error in some way (print a message to a debug console, display,
+ * LED, ...) and halt execution or reboot the device. */
+void cm3_assert_failed(void) __attribute__ ((__noreturn__));
+
+/** @brief Called on a failed assertion with verbose messages enabled.
+ *
+ * Halts execution in an infinite loop. This function never returns.
+ *
+ * Defined as a weak symbol, so applications can define their own
+ * implementation. Usually, a custom implementation of this function should
+ * report an error in some way (print a message to a debug console, display,
+ * LED, ...) and halt execution or reboot the device.
+ *
+ * @param file File name where the failed assertion occurred
+ * @param line Line number where the failed assertion occurred
+ * @param func Name of the function where the failed assertion occurred
+ * @param assert_expr Expression that evaluated to false (can be NULL) */
+void cm3_assert_failed_verbose(const char *file, int line, const char *func,
+ const char *assert_expr) __attribute__ ((__noreturn__));
+
+END_DECLS
+
+#endif
+
+/**@}*/
diff --git a/include/libopencm3/cm3/common.h b/include/libopencm3/cm3/common.h
index 54cd2e4..7ef18fe 100644
--- a/include/libopencm3/cm3/common.h
+++ b/include/libopencm3/cm3/common.h
@@ -32,6 +32,16 @@ typedef uint16_t u16;
typedef uint32_t u32;
typedef uint64_t u64;
+/* This must be placed around external function declaration for C++
+ * support. */
+#ifdef __cplusplus
+# define BEGIN_DECLS extern "C" {
+# define END_DECLS }
+#else
+# define BEGIN_DECLS
+# define END_DECLS
+#endif
+
/* Generic memory-mapped I/O accessor functions */
#define MMIO8(addr) (*(volatile u8 *)(addr))
#define MMIO16(addr) (*(volatile u16 *)(addr))
diff --git a/include/libopencm3/cm3/doc-cm3.h b/include/libopencm3/cm3/doc-cm3.h
new file mode 100644
index 0000000..0f76370
--- /dev/null
+++ b/include/libopencm3/cm3/doc-cm3.h
@@ -0,0 +1,22 @@
+/** @mainpage libopencm3 Core CM3
+
+@version 1.0.0
+
+@date 14 September 2012
+
+API documentation for Cortex M3 core features.
+
+LGPL License Terms @ref lgpl_license
+*/
+
+/** @defgroup CM3_defines CM3 Defines
+
+@brief Defined Constants and Types for Cortex M3 core features
+
+@version 1.0.0
+
+@date 14 September 2012
+
+LGPL License Terms @ref lgpl_license
+*/
+
diff --git a/include/libopencm3/cm3/docmain.h b/include/libopencm3/cm3/docmain.h
deleted file mode 100644
index 9407ceb..0000000
--- a/include/libopencm3/cm3/docmain.h
+++ /dev/null
@@ -1,70 +0,0 @@
-/**
- * @mainpage libopencm3 Developer Documentation
-
-@version 1.0.0
-
-@author @htmlonly &copy; @endhtmlonly 2012 Ken Sarkies ksarkies@internode.on.net
-
-@date 18 August 2012
-
- * The libopencm3 project (previously known as libopenstm32) aims to create
- * a free/libre/open-source (GPL v3, or later) firmware library for various
- * ARM Cortex-M3 microcontrollers, including ST STM32, Toshiba TX03,
- * Atmel SAM3U, NXP LPC1000 and others.
- *
- * @par ""
- *
- * See the <a href="http://www.libopencm3.org">libopencm3 wiki</a> for
- * more information.
-
-LGPL License Terms @ref lgpl_license
-
-*/
-
-/** @page lgpl_license libopencm3 License
-
-libopencm3 is free software: you can redistribute it and/or modify
-it under the terms of the GNU Lesser General Public License as published by the Free
-Software Foundation, either version 3 of the License, or (at your option) any
-later version.
-
-libopencm3 is distributed in the hope that it will be useful, but WITHOUT ANY
-WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-
-You should have received a copy of the GNU Lesser General Public License along with this
-program. If not, see <http://www.gnu.org/licenses/>.
-
-*/
-
-/** @defgroup LM3S LM3S
-Libraries for Texas instruments LM3S series.
-*/
-
-/** @defgroup LPC13xx LPC13xx
-Libraries for NXP Semiconductor LPC13xx series.
-*/
-
-/** @defgroup LPC17xx LPC17xx
-Libraries for NXP Semiconductor LPC17xx series.
-*/
-
-/** @defgroup STM32F STM32F
-Libraries for ST Microelectronics STM32F series.
-*/
-
-/** @defgroup STM32F1xx STM32F1xx
-@ingroup STM32F
-Libraries for ST Microelectronics STM32F1xx series.
-*/
-
-/** @defgroup STM32F2xx STM32F2xx
-@ingroup STM32F
-Libraries for ST Microelectronics STM32F2xx series.
-*/
-
-/** @defgroup STM32F4xx STM32F4xx
-@ingroup STM32F
-Libraries for ST Microelectronics STM32F4xx series.
-*/
-