=====================
Smaller Vector Tables
=====================
.. warning::
Migrated from:
https://cwiki.apache.org/confluence/display/NUTTX/Smaller+Vector+Tables
One of the largest OS data structures is the vector table,
``g_irqvector[]``. This is the table that holds the vector
information when ``irq_attach()`` is called and used to
dispatch interrupts by ``irq_dispatch()``. Recent changes
have made that table even larger, for 32-bit arm the
size of that table is given by:
.. code-block:: c
nbytes = number_of_interrupts * (2 * sizeof(void *))
We will focus on the STM32 for this discussion to keep
things simple. However, this discussion applies to all
architectures.
The number of (physical) interrupt vectors supported by
the MCU hardwared given by the definition ``NR_IRQ`` which
is provided in a header file in ``arch/arm/include/stm32``.
This is, by default, the value of ``number_of_interrupts``
in the above equation.
For a 32-bit ARM like the STM32 with, say, 100 interrupt
vectors, this size would be 800 bytes of memory. That is
not a lot for high-end MCUs with a lot of RAM memory,
but could be a show stopper for MCUs with minimal RAM.
Two approaches for reducing the size of the vector tables
are described below. Both depend on the fact that not all
interrupts are used on a given MCU. Most of the time,
the majority of entries in ``g_irqvector[]`` are zero because
only a small number of interrupts are actually attached
and enabled by the application. If you know that certain
IRQ numbers are not going to be used, then it is possible
to filter those out and reduce the size to the number of
supported interrupts.
For example, if the actual number of interrupts used were
20, the the above requirement would go from 800 bytes to
160 bytes.
Software IRQ Remapping
======================
`[On March 3, 2017, support for this "Software IRQ Remapping"
as included in the NuttX repository.]`
One of the simplest way of reducing the size of
``g_irqvector[]`` would be to remap the large set of physical
interrupt vectors into a much small set of interrupts that
are actually used. For the sake of discussion, let's
imagine two new configuration settings:
* ``CONFIG_ARCH_MINIMAL_VECTORTABLE``: Enables IRQ mapping
* ``CONFIG_ARCH_NUSER_INTERRUPTS``: The number of IRQs after mapping.
Then it could allocate the interrupt vector table to be
size ``CONFIG_IRQ_NMAPPED_IRQ`` instead of the much bigger
``NR_IRQS``:
.. code-block:: c
#ifdef CONFIG_ARCH_MINIMAL_VECTORTABLE
struct irq_info_s g_irqvector[CONFIG_ARCH_NUSER_INTERRUPTS];
#else
struct irq_info_s g_irqvector[NR_IRQS];
#endif
The ``g_irqvector[]`` table is accessed in only three places:
``irq_attach()``
----------------
``irq_attach()`` receives the physical vector number along
with the information needed later to dispatch interrupts:
.. code-block:: c
int irq_attach(int irq, xcpt_t isr, FAR void *arg);
Logic in ``irq_attach()`` would map the incoming physical
vector number to a table index like:
.. code-block:: c
#ifdef CONFIG_ARCH_MINIMAL_VECTORTABLE
int ndx = g_irqmap[irq];
#else
int ndx = irq;
#endif
where ``up_mapirq[]`` is an array indexed by the physical
interrupt vector number and contains the new, mapped
interrupt vector table index. This array must be
provided by platform-specific code.
``irq_attach()`` would this use this index to set the ``g_irqvector[]``.
.. code-block:: c
g_irqvector[ndx].handler = isr;
g_irqvector[ndx].arg = arg;
``irq_dispatch()``
------------------
``irq_dispatch()`` is called by MCU logic when an interrupt is received:
.. code-block:: c
void irq_dispatch(int irq, FAR void *context);
Where, again irq is the physical interrupt vector number.
``irq_dispatch()`` would do essentially the same thing as
``irq_attach()``. First it would map the irq number to
a table index:
.. code-block:: c
#ifdef CONFIG_ARCH_MINIMAL_VECTORTABLE
int ndx = g_irqmap[irq];
#else
int ndx = irq;
#endif
Then dispatch the interrupt handling to the attached
interrupt handler. NOTE that the physical vector
number is passed to the handler so it is completely
unaware of the underlying `shell` game:
.. code-block:: c
vector = g_irqvector[ndx].handler;
arg = g_irqvector[ndx].arg;
vector(irq, context, arg);
``irq_initialize()``
--------------------
``irq_initialize()``: simply set the ``g_irqvector[]`` table
a known state on power-up. It would only have to distinguish
the difference in sizes.
.. code-block:: c
#ifdef CONFIG_ARCH_MINIMAL_VECTORTABLE
# define TAB_SIZE CONFIG_ARCH_NUSER_INTERRUPTS
#else
# define TAB_SIZE NR_IRQS
#endif
for (i = 0; i < TAB_SIZE; i++)
``g_mapirq[]``
--------------
An implementation of ``up_mapirq()`` might be something like:
.. code-block:: c
#include <nuttx/irq.h>
const irq_mapped_t g_irqmap[NR_IRQS] =
{
... IRQ to index mapping values ...
};
``g_irqmap[]`` is a array of mapped irq table indices. It
contains the mapped index value and is itself indexed
by the physical interrupt vector number. It provides
an ``irq_mapped_t`` value in the range of 0 to
``CONFIG_ARCH_NUSER_INTERRUPTS`` that is the new, mapped
index into the vector table. Unsupported IRQs would
simply map to an out of range value like ``IRQMAPPED_MAX``.
So, for example, if ``g_irqmap[37] == 24``, then the hardware
interrupt vector 37 will be mapped to the interrupt vector
table at index 24. if ``g_irqmap[42] == IRQMAPPED_MAX``, then
hardware interrupt vector 42 is not used and if it occurs
will result in an unexpected interrupt crash.
Hardware Vector Remapping
=========================
`[This technical approach is discussed here but is
discouraged because of technical "Complications" and
"Dubious Performance Improvements" discussed at the
end of this section.]`
Most ARMv7-M architectures support two mechanism for handling interrupts:
* The so-called `common` vector handler logic enabled with
``CONFIG_ARMV7M_CMNVECTOR=y`` that can be found in
``arch/arm/src/armv7-m/``, and
* MCU-specific interrupt handling logic. For the
STM32, this logic can be found at ``arch/arm/src/stm32/gnu/stm32_vectors.S``.
The `common` vector logic is slightly more efficient,
the MCU-specific logic is slightly more flexible.
If we don't use the `common` vector logic enabled with
``CONFIG_ARMV7M_CMNVECTOR=y``, but instead the more
flexible MCU-specific implementation, then we can
also use this to map the large set of hardware
interrupt vector numbers to a smaller set of software
interrupt numbers. This involves minimal changes to
the OS and does not require any magic software lookup
table. But is considerably more complex to implement.
This technical approach requires changes to three files:
* A new header file at ``arch/arm/include/stm32``, say
``xyz_irq.h`` for the purposes of this discussion.
This new header file is like the other IRQ definition
header files in that directory except that it
defines only the IRQ number of the interrupts after
remapping. So, instead of having the 100 IRQ number
definitions of the original IRQ header file based on
the physical vector numbers, this header file would
define ``only`` the small set of 20 ``mapped`` IRQ numbers in
the range from 0 through 19. It would also set ``NR_IRQS``
to the value 20.
* A new header file at ``arch/arm/src/stm32/hardware``, say
``xyz_vector.h``. It would be similar to the other vector
definitions files in that directory: It will consist
of a sequence of 100 ``VECTOR`` and ``UNUSED`` macros. It will
define ``VECTOR`` entries for the 20 valid interrupts and
80 ``UNUSED`` entries for the unused interrupt vector numbers.
More about this below.
* Modification of the ``stm32_vectors.S`` file. These changes
are trivial and involve only the conditional inclusion
of the new, special ``xyz_vectors.h`` header file.
**REVISIT**: This needs to be updated. Neither the ``xyz_vector.h``
files nor the ``stm32_vectors.S`` exist in the current realization.
This has all been replaced with the common vector handling at
``arch/arm/src/armv7-m``.
Vector Definitions
==================
In ``arch/arm/src/stm32/gnu/stm32_vector.S``, notice that the
``xyz_vector.h`` file will be included twice. Before each
inclusion, the macros ``VECTOR`` and ``UNUSED`` are defined.
The first time that ``xyz_vector.h`` included, it defines the
hardware vector table. The hardware vector table consists
of ``NR_IRQS`` 32-bit addresses in an array. This is
accomplished by setting:
.. code-block:: c
#undef VECTOR
#define VECTOR(l,i) .word l
#undef UNUSED
#define UNUSED(i) .word stm32_reserved
Then including ``xyz_vector.h``. So consider the following
definitions in the original file:
.. code-block:: c
...
VECTOR(stm32_usart1, STM32_IRQ_USART1) /* Vector 16+37: USART1 global interrupt */
VECTOR(stm32_usart2, STM32_IRQ_USART2) /* Vector 16+38: USART2 global interrupt */
VECTOR(stm32_usart3, STM32_IRQ_USART3) /* Vector 16+39: USART3 global interrupt */
...
Suppose that we wanted to support only USART1 and that
we wanted to have the IRQ number for USART1 to be 12.
That would be accomplished in the ``xyz_vector.h`` header
file like this:
.. code-block:: c
...
VECTOR(stm32_usart1, STM32_IRQ_USART1) /* Vector 16+37: USART1 global interrupt */
UNUSED(0) /* Vector 16+38: USART2 global interrupt */
UNUSED(0) /* Vector 16+39: USART3 global interrupt */
...
Where the value of ``STM32_IRQ_USART1`` was defined to
be 12 in the ``arch/arm/include/stm32/xyz_irq.h`` header
file. When ``xyz_vector.h`` is included by ``stm32_vectors.S``
with the above definitions for ``VECTOR`` and ``UNUSED``, the
following would result:
.. code-block:: c
...
.word stm32_usart1
.word stm32_reserved
.word stm32_reserved
...
These are the settings for vector 53, 54, and 55,
respectively. The entire vector table would be populated
in this way. ``stm32_reserved``, if called would result in
an "unexpected ISR" crash. ``stm32_usart1``, if called will
process the USART1 interrupt normally as we will see below.
Interrupt Handler Definitions
-----------------------------
in the vector table, all of the valid vectors are set to
the address of a `handler` function. All unused vectors
are force to vector to ``stm32_reserved``. Currently, only
vectors that are not supported by the hardware are
marked ``UNUSED``, but you can mark any vector ``UNUSED`` in
order to eliminate it.
The second time that ``xyz_vector.h`` is included by
``stm32_vector.S``, the `handler` functions are generated.
Each of the valid vectors point to the matching handler
function. In this case, you do NOT have to provide
handlers for the ``UNUSED`` vectors, only for the used
``VECTOR`` vectors. All of the unused vectors will go
to the common ``stm32_reserved`` handler. The remaining
set of handlers is very sparse.
These are the values of ``UNUSED`` and ``VECTOR`` macros on the
second time the ``xzy_vector.h`` is included by ``stm32_vectors.S``:
.. code-block:: asm
.macro HANDLER, label, irqno
.thumb_func
label:
mov r0, #\irqno
b exception_common
.endm
#undef VECTOR
#define VECTOR(l,i) HANDLER l, i
#undef UNUSED
#define UNUSED(i)
In the above USART1 example, a single handler would be
generated that will provide the IRQ number 12. Remember
that 12 is the expansion of the macro ``STM32_IRQ_USART1``
that is provided in the ``arch/arm/include/stm32/xyz_irq.h``
header file:
.. code-block:: asm
.thumb_func
stm32_usart1:
mov r0, #12
b exception_common
Now, when vector 16+37 occurs it is mapped to IRQ 12
with no significant software overhead.
A Complication
--------------
A complication in the above logic has been noted by David Sidrane:
When we access the NVIC in ``stm32_irq.c`` in order to enable
and disable interrupts, the logic requires the physical
vector number in order to select the NVIC register and
the bit(s) the modify in the NVIC register.
This could be handled with another small IRQ lookup table
(20 ``uint8_t`` entries in our example situation above). But
then this approach is not so much better than the `Software
Vector Mapping` described about which does not suffer from
this problem. Certainly enabling/disabling interrupts in a
much lower rate operation and at least does not put the
lookup in the critical interrupt path.
Another option suggested by David Sidrane is equally ugly:
* Don't change the ``arch/arm/include/stm32`` IRQ definition file.
* Instead, encode the IRQ number so that it has both
the index and physical vector number:
.. code-block:: c
...
VECTOR(stm32_usart1, STM32_IRQ_USART1 << 8 | STM32_INDEX_USART1)
UNUSED(0)
UNUSED(0)
...
The STM32_INDEX_USART1 would have the value 12 and
STM32_IRQ_USART1 would be as before (53). This encoded
value would be received by ``irq_dispatch()`` and it would
decode both the index and the physical vector number.
It would use the index to look up in the ``g_irqvector[]``
table but would pass the physical vector number to the
interrupt handler as the IRQ number.
A lookup would still be required in ``irq_attach()`` in
order to convert the physical vector number back to
an index (100 ``uint8_t`` entries in our example). So
some lookup is unavoidable.
Based upon these analysis, my recommendation is that
we do not consider the second option any further. The
first option is cleaner, more portable, and generally
preferable.is well worth that.
Dubious Performance Improvements
--------------------------------
The intent of this second option was to provide a higher
performance mapping of physical interrupt vectors to IRQ
numbers compared to the pure software mapping of option 1. However,
in order to implement this approach, we had
to use the less efficient, non-common vector handling
logic. That logic is not terribly less efficient, the
cost is probably only a 16 bit load immediate instruction
and branch to another location in FLASH (which will cause
the CPU pipeline to be flushed).
The variant of option 2 where both the physical vector number
and vector table index are encoded would require even more
processing in ``irq_dispatch()`` in order to decode the
physical vector number and vector table index.
Possible just AND and SHIFT instructions.
However, the minimal cost of the first pure software
mapping approach was possibly as small as a single
indexed byte fetch from FLASH in ``irq_attach()``.
Indexing is, of course, essentially `free` in the ARM
ISA, the primary cost would be the FLASH memory access.
So my first assessment is that the performance of both
approaches is the essentially the same. If anything, the
first approach is possibly the more performant if
implemented efficiently.
Both options would require some minor range checking in
``irq_attach()`` as well.
Because of this and because of the simplicity of the
first option, I see no reason to support or consider
this second option any further.
Complexity and Generalizability
-------------------------------
Option 2 is overly complex; it depends on a deep understanding
on how the MCU interrupt logic works and on a high level of
Thumb assembly language skills.
Another problem with option 2 is that really only applies to
the Cortex-M family of processors and perhaps others that
support interrupt vectored interrupts in a similar fashion.
It is not a general solution that can be used with any CPU
architectures.
And even worse, the MCU-specific interrupt handling logic
that this support depends upon is is very limited. As soon
as the common interrupt handler logic was added, I stopped
implementing the MCU specific logic in all newer ARMv7-M
ports. So that MCU specific interrupt handler logic is
only present for EFM32, Kinetis, LPC17, SAM3/4, STM32,
Tiva, and nothing else. Very limited!
These are further reasons why option 2 is no recommended and
will not be supported explicitly.