Understanding Variables like ${BSP_INCLUDEDIR} and Include File Organization in RTEMS YAML Files

Tools Tools
1

Hi! I’m working on a Board Support Package (BSP) for the arm/at32f4 target in RTEMS, and I have some questions about the variables used in YAML configuration files and how include files are organized.

Background

In my YAML file, I use variables like ${BSP_INCLUDEDIR} and ${BSP_LIBDIR} in the install section to specify where header files and other resources should be installed. For example:

install:
- destination: ${BSP_INCLUDEDIR}
  source:
  - bsps/arm/at32f4/include/bsp.h
  - bsps/arm/at32f4/include/at32f435_437_clock.h
  - bsps/arm/at32f4/include/bsp/at32f435_437.h
- destination: ${BSP_INCLUDEDIR}/bsp
  source:
  - bsps/arm/at32f4/include/bsp/irq.h

This results in header files being installed in (e.g.) prefix/arm-rtems7/include/ and prefix/arm-rtems7/include/bsp/, which aligns with the expected #include directives like #include <bsp.h> and #include <bsp/irq.h>.

However, I find the need to explicitly specify directories in the #include directives (e.g., bsp/irq.h) and the YAML file cumbersome, especially for peripheral header files that often don’t have nested #include directives. I’m considering simplifying the include structure, but I want to understand the rationale behind the current organization and the available variables.

Questions

  1. What variables are available in RTEMS YAML files?

    • I know about ${BSP_INCLUDEDIR}, ${BSP_LIBDIR}, and ${PREFIX}. Are there other variables (e.g., for architecture, BSP-specific paths, or other installation directories) that I can use in the install or other sections of the YAML file?
    • How can I discover the full list of these variables and their values?

  2. Why is the include file organization structured this way?

    • Why does RTEMS use a structure where some header files are installed in ${BSP_INCLUDEDIR} (e.g., bsp.h) and others in ${BSP_INCLUDEDIR}/bsp (e.g., irq.h)? What are the benefits of this organization for BSP development and application compilation?
    • Is the bsp/ subdirectory a strict requirement for certain files (like irq.h) due to expectations in the core RTEMS code, or is it just a convention?
    • Are there best practices for organizing header files to minimize the need to specify subdirectories in #include directives while maintaining compatibility with RTEMS?

  3. Can I simplify the include structure?

    • Ideally, I’d like to specify header files in the YAML install section without needing to account for their directory structure (e.g., just list bsp.h, irq.h without paths) and have them found by the compiler without explicit subdirectories in #include (e.g., #include <irq.h> instead of #include <bsp/irq.h>). Is this feasible without breaking RTEMS expectations?

Context

I’m trying to streamline the development process for my BSP, especially for peripheral header files that don’t typically include other headers. The current structure requires me to carefully manage paths in both the YAML file and #include directives, which feels redundant. Understanding the full set of variables and the reasoning behind the include file organization will help me decide whether to adapt to the current system or explore simplifications like a unified header file.

Any insights, documentation pointers, or examples of how other BSPs handle this would be greatly appreciated!

UPD:
Encountering ValueError: could not find ['bsps', 'arm', 'at32f4', 'rtt', 'SEGGER_RTT.h'] when building with new RTEMS YAML system. SEGGER_RTT.h exists in C:/msys64/home/SimTech/rtems/bsps/arm/at32f4/rtt, -Ibsps/arm/at32f4/rtt is set, and the file is listed in the install section of YAML. Waf still fails to locate it. Suspect issue with dependency scanning or path handling in Windows/MSYS2. Relevant YAML snippet:

includes:
- bsps/arm/at32f4/rtt
install:
- destination: ${BSP_INCLUDEDIR}
  source:
  - bsps/arm/at32f4/rtt/SEGGER_RTT.h
  - bsps/arm/at32f4/include/bsp.h
  - bsps/arm/at32f4/include/at32f435_437_clock.h
  - bsps/arm/at32f4/include/at32f435_437.h
source:
- bsps/arm/at32f4/rtt/SEGGER_RTT.c
- bsps/arm/at32f4/rtt/SEGGER_RTT_printf.c
- bsps/arm/at32f4/rtt/SEGGER_RTT_ASM_ARMv7M.S`

SEGGER_RTT_printf.c includes #include “SEGGER_RTT.h”. Any insights in RTEMS YAML/Waf setup?