123 lines
5.1 KiB
ReStructuredText
123 lines
5.1 KiB
ReStructuredText
===========
|
|
LED Support
|
|
===========
|
|
|
|
A board architecture may or may not have LEDs. If the board does
|
|
have LEDs, then most architectures provide similar LED support
|
|
that is enabled when ``CONFIG_ARCH_LEDS`` is selected in the NuttX
|
|
configuration file. This LED support is part of
|
|
architecture-specific logic and is not managed by the core NuttX
|
|
logic. However, the support provided by each architecture is
|
|
sufficiently similar that it can be documented here.
|
|
|
|
Header Files
|
|
============
|
|
|
|
LED-related definitions are provided in two header files:
|
|
|
|
- LED definitions are provided for each board in the ``board.h``
|
|
that resides in the ``<board-name>/include/board.h`` file
|
|
(which is also linked to ``include/arch/board/board.h`` when
|
|
the RTOS is configured). Those definitions are discussed
|
|
`below <#leddefinitions>`__.
|
|
- The board-specific logic provides unique instances of the LED
|
|
interfaces. This is because the implementation of LED support
|
|
may be very different on different boards. Prototypes for these
|
|
board-specific implementations are, however, provided in
|
|
architecture-common header files. That header file is usually
|
|
at ``<arch-name>/src/common/up_internal.h``, but could be at
|
|
other locations in particular architectures. These prototypes
|
|
are discussed `below <#ledapis>`__.
|
|
|
|
LED Definitions
|
|
===============
|
|
|
|
The implementation of LED support is very specific to a board
|
|
architecture. Some boards have several LEDS, others have only one
|
|
or two. Some have none. Others LED matrices and show alphanumeric
|
|
data, etc. The NuttX logic does not refer to specific LEDS,
|
|
rather, it refers to an event to be shown on the LEDS in whatever
|
|
manner is appropriate for the board; the way that this event is
|
|
presented depends upon the hardware available on the board.
|
|
|
|
The model used by NuttX is that the board can show 8 events
|
|
defined as follows in ``<board-name>/include/board.h``:
|
|
|
|
.. code-block:: c
|
|
|
|
#define LED_STARTED ??
|
|
#define LED_HEAPALLOCATE ??
|
|
#define LED_IRQSENABLED ??
|
|
#define LED_STACKCREATED ??
|
|
#define LED_INIRQ ??
|
|
#define LED_SIGNAL ??
|
|
#define LED_ASSERTION ??
|
|
#define LED_PANIC ??
|
|
|
|
The specific value assigned to each pre-processor variable can be
|
|
whatever makes the implementation easiest for the board logic. The
|
|
*meaning* associated with each definition is as follows:
|
|
|
|
- ``LED_STARTED`` is the value that describes the setting of the
|
|
LEDs when the LED logic is first initialized. This LED value is
|
|
set but never cleared.
|
|
- ``LED_HEAPALLOCATE`` indicates that the NuttX heap has been
|
|
configured. This is an important place in the boot sequence
|
|
because if the memory is configured wrong, it will probably
|
|
crash leaving this LED setting. This LED value is set but never
|
|
cleared.
|
|
- ``LED_IRQSENABLED`` indicates that interrupts have been
|
|
enabled. Again, during bring-up (or if there are hardware
|
|
problems), it is very likely that the system may crash just
|
|
when interrupts are enabled, leaving this setting on the LEDs.
|
|
This LED value is set but never cleared.
|
|
- ``LED_STACKCREATED`` is set each time a new stack is created.
|
|
If set, it means that the system attempted to start at least
|
|
one new thread. This LED value is set but never cleared.
|
|
- ``LED_INIRQ`` is set and cleared on entry and exit from each
|
|
interrupt. If interrupts are working okay, this LED will have a
|
|
dull glow.
|
|
- ``LED_SIGNAL`` is set and cleared on entry and exit from a
|
|
signal handler. Signal handlers are tricky so this is
|
|
especially useful during bring-up or a new architecture.
|
|
- ``LED_ASSERTION`` is set if an assertion occurs.
|
|
- ``LED_PANIC`` will blink at around 1Hz if the system panics and
|
|
hangs.
|
|
|
|
Common LED interfaces
|
|
=====================
|
|
|
|
The ``include/nuttx/board.h`` includes the following declarations:
|
|
|
|
.. c:function:: void board_autoled_initialize(void)
|
|
|
|
Called early in power-up initialization to initialize the LED hardware.
|
|
|
|
.. note:: In most architectures,
|
|
``board_autoled_initialize()`` is called from board-specific
|
|
initialization logic. But there are a few architectures
|
|
where this initialization function is still called from
|
|
common chip architecture logic. This interface is not,
|
|
however, a common board interface in any event.
|
|
|
|
.. warning:: This interface name will eventually be removed;
|
|
do not use it in new board ports. New implementations should
|
|
not use the naming convention for common board interfaces,
|
|
but should instead use the naming conventions for
|
|
microprocessor-specific interfaces or the board-specific
|
|
interfaces (such as ``stm32_led_initialize()``).
|
|
|
|
.. c:function:: void board_autoled_on(int led)
|
|
|
|
Called to instantiate the LED
|
|
presentation of the event. The ``led`` argument is one of the
|
|
definitions provided in ``<board-name>/include/board.h``.
|
|
|
|
.. c:function:: void board_autoled_off(int led)
|
|
|
|
Called to terminate the LED
|
|
presentation of the event. The ``led`` argument is one of the
|
|
definitions provided in ``<board-name>/include/board.h``. Note
|
|
that only ``LED_INIRQ``, ``LED_SIGNAL``, ``LED_ASSERTION``, and
|
|
``LED_PANIC`` indications are terminated.
|