feat(misc): add lv_check_arg macros (#9905)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Vandra-Meyer Ákos <akos@lvgl.io>

docs/src/contributing/assertions.rst

@@ -0,0 +1,215 @@
+.. _assertions_check_arg:
+
+=================================
+Assertions and Argument Checking
+=================================
+
+LVGL provides two sets of macros for validating conditions at runtime:
+**assertions** and **argument checking**. This page explains when and how to use
+each within LVGL's codebase.
+
+
+
+Overview
+********
+
++---------------------------+---------------------------+---------------------------+
+| Feature                   | LV_ASSERT                 | LV_CHECK_ARG              |
++===========================+===========================+===========================+
+| Purpose                   | Catch programming errors  | Validate runtime input    |
++---------------------------+---------------------------+---------------------------+
+| On failure                | Halts (LV_ASSERT_HANDLER) | Configurable action       |
++---------------------------+---------------------------+---------------------------+
+| Log level                 | Error                     | Warning                   |
++---------------------------+---------------------------+---------------------------+
+| Recovery possible         | No                        | Yes / Maybe               |
++---------------------------+---------------------------+---------------------------+
+| Typical use               | Internal invariants       | API input validation      |
++---------------------------+---------------------------+---------------------------+
+
+**Use assertions** for conditions that indicate bugs in the code—situations
+that should never happen if the code is correct.
+
+**Use argument checking** for conditions that might legitimately fail at runtime
+(e.g., user-provided input, resource availability) and require graceful handling.
+
+
+
+Assertions
+**********
+
+Assertions check for programming errors and halt the program when they fail.
+They are typically enabled only in debug builds and may be disabled in release builds.
+
+
+Configuration
+-------------
+
+Enable assertions in ``lv_conf.h``:
+
+- :c:macro:`LV_USE_ASSERT_NULL` - Check for NULL pointers
+- :c:macro:`LV_USE_ASSERT_MALLOC` - Check for failed memory allocations
+- :c:macro:`LV_USE_ASSERT_MEM_INTEGRITY` - Check memory integrity
+
+Configure the assert handler with :c:macro:`LV_ASSERT_HANDLER`. The default
+behavior is ``while(1);`` which halts the program.
+
+
+Usage
+-----
+
+:c:macro:`LV_ASSERT`
+   Basic assertion with the condition stringified in the log message:
+
+   .. code-block:: c
+
+      LV_ASSERT(pi > 0);
+
+:c:macro:`LV_ASSERT_MSG`
+   Assertion with a plain string message:
+
+   .. code-block:: c
+
+      LV_ASSERT_MSG(pi > 0, "pi should be positive");
+
+:c:macro:`LV_ASSERT_FORMAT_MSG`
+   Assertion with a printf-style format message:
+
+   .. code-block:: c
+
+      LV_ASSERT_FORMAT_MSG(pi > 0, ": was %f", pi);
+
+
+Specialized Assertions
+----------------------
+
+:c:macro:`LV_ASSERT_NULL`
+   Check that a pointer is not NULL:
+
+   .. code-block:: c
+
+      LV_ASSERT_NULL(obj);
+
+:c:macro:`LV_ASSERT_MALLOC`
+   Check that a memory allocation succeeded:
+
+   .. code-block:: c
+
+      void * buf = lv_malloc(size);
+      LV_ASSERT_MALLOC(buf);
+
+:c:macro:`LV_ASSERT_MEM_INTEGRITY`
+   Check that LVGL's memory pool is not corrupted:
+
+   .. code-block:: c
+
+      LV_ASSERT_MEM_INTEGRITY();
+
+
+
+Argument Checking
+*****************
+
+The :c:macro:`LV_CHECK_ARG` macro provides a flexible approach for validating
+function arguments at runtime: it logs a warning and allows you to specify a
+recovery action (such as returning from a function or continuing with a fallback).
+
+This macro is useful for:
+
+- Input validation at the start of functions
+- Checking preconditions without halting the program
+- Defensive programming with graceful error handling
+- Logging invariant violations that may not be critical but should be noted
+
+
+Configuration
+-------------
+
+In ``lv_conf.h``:
+
+- :c:macro:`LV_USE_CHECK_ARG` - Set to ``1`` to enable, ``0`` to disable.
+  When disabled, all ``LV_CHECK_ARG`` calls compile to nothing.
+- :c:macro:`LV_CHECK_ARG_ASSERT_ON_FAIL` - Set to ``1`` to also call
+  ``LV_ASSERT_HANDLER`` on failure (before the action is executed).
+
+The macro uses the :ref:`logging` system to output warnings.
+Make sure logging is enabled by setting :c:macro:`LV_USE_LOG` to ``1``.
+
+
+Usage
+-----
+
+:c:macro:`LV_CHECK_ARG`
+   Takes a condition, an action to execute on failure, and optional printf-style
+   arguments for the log message:
+
+   .. code-block:: c
+
+      void draw_to_display(lv_obj_t * display, int len)
+      {
+          /* Return early if display is NULL */
+          LV_CHECK_ARG(display != NULL, return, ": display must be provided");
+
+          /* Return -1 if len is invalid, logging the actual value */
+          LV_CHECK_ARG(len % 2 == 0, return, ": need even data points, but got %d", (int)len);
+      }
+
+      int get_width(lv_obj_t * obj)
+      {
+          /* Return -1 if obj is NULL */
+          LV_CHECK_ARG(obj != NULL, return -1, "tried to get width of NULL object");
+          /* ... */
+      }
+
+   The condition is stringified and included in the log message, so you can see
+   exactly what check failed. Only supply a format string and arguments if you
+   want to include additional context beyond the condition itself.
+
+   Using ``break`` as the action in a loop:
+
+   .. code-block:: c
+
+      for(int i = 0; i < count; i++) {
+          LV_CHECK_ARG(data[i] != NULL, break, ": NULL at index %d", i);
+          /* ... */
+      }
+
+
+
+Macros Reference
+****************
+
+Assertions
+----------
+
+.. list-table::
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Macro
+     - Description
+   * - :c:macro:`LV_ASSERT`
+     - Assert condition; on failure log and halt
+   * - :c:macro:`LV_ASSERT_MSG`
+     - Assert with plain string message
+   * - :c:macro:`LV_ASSERT_FORMAT_MSG`
+     - Assert with printf-style format message
+   * - :c:macro:`LV_ASSERT_NULL`
+     - Assert pointer is not NULL (if enabled)
+   * - :c:macro:`LV_ASSERT_MALLOC`
+     - Assert allocation succeeded (if enabled)
+   * - :c:macro:`LV_ASSERT_MEM_INTEGRITY`
+     - Assert memory pool integrity (if enabled)
+
+
+Argument Checking
+-----------------
+
+.. list-table::
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Macro
+     - Description
+   * - :c:macro:`LV_CHECK_ARG`
+     - Check condition; on failure log and execute action

docs/src/contributing/index.rst

@@ -12,3 +12,4 @@ Contributing
     pull_requests
     dco
     coding_style
+    assertions