Q: I wonder about the purpose of the two chip.h files in each arm chip.

  $ find arch/arm -name chip.h | grep stm32
  arch/arm/include/stm32/chip.h
  arch/arm/src/stm32/chip.h

A: The arch/arm/src/stm32/chip.h file was a bad idea that happened a long time ago.
Right now, I believe that its only required when CONFIG_ARMV7M_CMNVECTOR is selected in the configuration.
In that case, arch/arm/src/stm32/chip.h is included by arch/arm/src/armv7-m/up_vectors.c in order provide the number of interrupt vectors.
In stm32, arch/arm/src/stm32/chip.h provides the number of vectors indirectly by including the correct, chip-specific vectors.h file.
This function is a little more obvious in arch/arm/srch/lpc43xx/chip.h.

This arch/arm/src/xyz/chip.h is also a good way to export awkward internal header files in a cleaner way. But that use is optional and not required outside of the chip- and board-related directories.

For the arch/include/stm32/chip.h file, only set of definitions is required there: The NVIC priorities:

  • NVIC_SYSH_PRIORITY_MIN provides the lowest interrupt priority supported by the system. This is the highest numeric value; but the lowest interrupt priority.
  • NVIC_SYSH_PRIORITY_DEFAULT provides the default priority of all interrupts. Since truly nested interrupts are not supported, this is the priority of all interrupts except for the SVCall interrupt.
  • NVIC_SYSH_PRIORITY_MAX provides the maximum interrupt priority. For all ARMv7-M's, this will be the value zero.
  • NVIC_SYSH_PRIORITY_STEP is the value need to increment from one priority level to next, lower priority level.

If CONFIG_ARMV7M_USEBASEPRI is selected, then interrupts will be disabled by setting the BASEPRI register to NVIC_SYSH_DISABLE_PRIORITY so that most interrupts will not have execution priority.
SVCall must have execution priority in all cases.

In the normal cases, interrupts are not nest-able and all interrupts run at an execution priority between NVIC_SYSH_PRIORITY_MIN and NVIC_SYSH_PRIORITY_MAX (with NVIC_SYSH_PRIORITY_MAX reserved for SVCall).

If, in addition, CONFIG_ARCH_HIPRI_INTERRUPT is defined, then special high priority interrupts are supported.
These are not "nested" in the normal sense of the word.
These high priority interrupts can interrupt normal interrupt processing but execute outside of OS (although they can "get back into the game" via a PendSV interrupt).

In the normal course of things, interrupts must occasionally be disabled using the up_irq_save() inline function to prevent contention in use of resources that may be shared between interrupt level and non-interrupt level logic. Now the question arises, if we are using the BASEPRI to disable interrupts and have high priority interrupts enabled (CONFIG_ARCH_HIPRI_INTERRUPT=y), do we disable all interrupts except SVCall (we cannot disable SVCall interrupts)? Or do we only disable the "normal" interrupts?

If we are using the BASEPRI register to disable interrupts, then the answer is that we must disable ONLY the normal interrupts. That is because we cannot disable SVCALL interrupts and we cannot permit SVCAll interrupts running at a higher priority than the high priority interrupts. Otherwise, they will introduce jitter in the high priority interrupt response time.

Hence, if you need to disable the high priority interrupt, you will have to disable the interrupt either at the peripheral that generates the interrupt or at the interrupt controller (e.g., NVIC). Disabling global interrupts via the BASEPRI register cannot effect high priority interrupts.

  • NVIC_SYSH_MAXNORMAL_PRIORITY is the maximum priority of "normal" interrupts. Interrupt are disabled at the level NVIC_SYSH_MAXNORMAL_PRIORITY, disabling all "normal" interrupt but leaving the high priority and SVCALL interrupts enabled.
  • NVIC_SYSH_HIGH_PRIORITY is the priority of the high priority interrupt.
  • NVIC_SYSH_DISABLE_PRIORITY is the level at which interrupts will be disabled. This will be equal to NVIC_SYSH_MAXNORMAL_PRIORITY.
  • NVIC_SYSH_SVCALL_PRIORITY }} is the priority of the SVCall interrupt. This must be higher priority than {{NVIC_SYSH_DISABLE_PRIORITY so that it is never disabled, but lower in priority than NVIC_SYSH_DISABLE_PRIORITY so that SVCall handling cannot interfere with high priority interrupt handling.

These definitions only have to be here because NVIC implementations may differ in the number of priority levels.

Now, by convention, the arch/xyz/include/chip/abc/chip.h file is also used to provide all of the definitions that discriminate the features of the different members of the chip family.
It is not technically necessary that those chip feature definitions exist in this header file, but it is a good convention to follow so that it is easier for people who have to work across the differ architectures.

There is another really big difference between the two chip header files: They also different in scope:

  • Code in the arch/arm/src/xyz and in boards/arm/xyz/abc/src directories can both include the arch/arm/src/xyz/chip.h header file, but nothing else can (only because nothing else is provided the header file path in the build system). So that chip.h file is intended to be used only in low-level boar/chip logic.
  • The chip.h header file at arch/arm/include/xyz/chip.h, on the other hand, will be linked at include/arch/chip and, hence, can be included anywhere in the system, even from applications. It can be included like:
  #include <arch/chip/chip.h>

So the arch/arm/include/xyz/chip.h header file is a place where you would want to put chip-related stuff that can be made visible to application code.
Chip capabilities is a good example of the kind of knowledge that applications might care about.

  • No labels