[FER] Separating combined board and shield directories

[rexut]

Is your enhancement proposal related to a problem? Please describe.

Whenever possible, Bridle follows the architectural concept of the “single point of truth”. Over the years, however, this has led to two fundamental challenges regarding board descriptions and their accompanying documentation related to maintenance and/or extraction and contribution to Zephyr upstream:

1. In contrast to the conventions of Zephyr upstream, Bridle groups similar boards from a single manufacturer into a sort of board family within a single directory and organizes the designs as hierarchical DTS include files with the respective intersections at various nested levels. This inevitably leads to a situation where only a single set of many boards can be maintained as a cohesive whole. Direct extraction and submission to Zephyr upstream is therefore not possible without the expectation of rejection, since a whole bundle of multiple boards would never pass the Zephyr upstream review process.
2. In terms of accompanying documentation, it was inevitable that many similar boards would have to be grouped together as a cohesive board family. This, too, resulted in a steadily growing number of RST include files containing either board-specific content or general statements (intersections) at varying levels of nesting. However, to ensure the still-required one-to-one referencing of an individual board in the documentation, reference points in RST syntax were assigned on the respective entry pages for the board families; yet, due to the parallel use of “dynamic tabs,” these remain impractical to use even today. For example, the link https://bridle.tiac-systems.net/doc/latest/bridle/boards/cytron/maker_rp2040/doc/index.html#cytron-maker-pi-rp2040 does lead to the correct board family, but it does not open the exact tabs for the “Cytron Maker Pi RP2040” board. Furthermore, in the current documentation structure, the long-standing Zephyr-specific RST directive .. zephyr:board:: cannot be used, as it requires a separate RST file for each individual board. This RST directive cannot be used multiple times in a single RST file for any number of boards within a family.

Both issues apply to combined board and shield families. The following are affected:

• Boards:
  • Cytron Maker RP2040
  • Cytron MOTION 2350
  • The PicoBoy (Color)
  • VccGND BluePill
  • Waveshare RP2040
  • Waveshare RP2350
  • WeAct BluePill+
• Shields:
  • Raspberry Pi Pico Breadboard Shields
  • Raspberry Pi Pico Clock Shields
  • Raspberry Pi Pico LCD Shields
  • Raspberry Pi Pico LED Shields
  • Raspberry Pi Pico TEST Shields
  • Waveshare LCD Modules

Describe the solution you'd like

For almost all board families available in Bridle, support for individual (but not all) boards already exists in Zephyr upstream. As a first step, the Bridle board families must be restructured exactly as they were defined in Zephyr upstream. For example:

Bridle knows the RP2040-Plus as part of the family Waveshare RP2040 with:

• … full qualified HVMv2 name waveshare_rp2040_plus@4mb/rp2040 or waveshare_rp2040_plus@16mb/rp2040

• bridle/boards/waveshare/rp2040/board.yml

  Lines 32 to 42 in cac877d

  	- name: waveshare_rp2040_plus
  	full_name: Waveshare RP2040-Plus
  	vendor: waveshare
  	socs:
  	- name: rp2040
  	revision:
  	format: "custom"
  	default: "4mb"
  	revisions:
  	- name: "4mb"
  	- name: "16mb"

• in folder: bridle/boards/waveshare/rp2040

Zephyr knows the RP2040-Plus

• … full qualified HVMv2 name rp2040_plus/rp2040 (no revisions, thus no 16mb flash support)
• zephyr/boards/waveshare/rp2040_plus/board.yml Lines 1 to 6 in bc460fe

  board:
    name: rp2040_plus
    full_name: RP2040-Plus
    vendor: waveshare
    socs:
    - name: rp2040

• in folder: zephyr/boards/waveshare/rp2040_plus

This means that for each name entry in the board.yaml file of a Bridle board family, a new, standalone board directory — including the associated documentation — must be created. Continuing with the Waveshare RP2040 example, this results in the following structure:

board name	board folder / documentation folder
bridle/boards/waveshare/rp2040/board.yml Lines 2 to 6 in cac877d - name: waveshare_rp2040_one full_name: Waveshare RP2040-One vendor: waveshare socs: - name: rp2040	bridle/boards/waveshare/rp2040_one bridle/boards/waveshare/rp2040_one/doc
bridle/boards/waveshare/rp2040/board.yml Lines 7 to 11 in cac877d - name: waveshare_rp2040_zero full_name: Waveshare RP2040-Zero vendor: waveshare socs: - name: rp2040	bridle/boards/waveshare/rp2040_zero bridle/boards/waveshare/rp2040_zero/doc
bridle/boards/waveshare/rp2040/board.yml Lines 12 to 16 in cac877d - name: waveshare_rp2040_matrix full_name: Waveshare RP2040-Matrix vendor: waveshare socs: - name: rp2040	bridle/boards/waveshare/rp2040_matrix bridle/boards/waveshare/rp2040_matrix/doc
bridle/boards/waveshare/rp2040/board.yml Lines 17 to 21 in cac877d - name: waveshare_rp2040_tiny full_name: Waveshare RP2040-Tiny vendor: waveshare socs: - name: rp2040	bridle/boards/waveshare/rp2040_tiny bridle/boards/waveshare/rp2040_tiny/doc
bridle/boards/waveshare/rp2040/board.yml Lines 22 to 26 in cac877d - name: waveshare_rp2040_eth full_name: Waveshare RP2040-ETH vendor: waveshare socs: - name: rp2040	bridle/boards/waveshare/rp2040_eth bridle/boards/waveshare/rp2040_eth/doc
bridle/boards/waveshare/rp2040/board.yml Lines 27 to 31 in cac877d - name: waveshare_rp2040_lcd_0_96 full_name: Waveshare RP2040-LCD-0.96 vendor: waveshare socs: - name: rp2040	bridle/boards/waveshare/rp2040_lcd_0_96 bridle/boards/waveshare/rp2040_lcd_0_96/doc
bridle/boards/waveshare/rp2040/board.yml Lines 32 to 42 in cac877d - name: waveshare_rp2040_plus full_name: Waveshare RP2040-Plus vendor: waveshare socs: - name: rp2040 revision: format: "custom" default: "4mb" revisions: - name: "4mb" - name: "16mb"	bridle/boards/waveshare/rp2040_plus bridle/boards/waveshare/rp2040_plus/doc
bridle/boards/waveshare/rp2040/board.yml Lines 43 to 47 in cac877d - name: waveshare_rp2040_geek full_name: Waveshare RP2040-Geek vendor: waveshare socs: - name: rp2040	bridle/boards/waveshare/rp2040_geek bridle/boards/waveshare/rp2040_geek/doc

Describe alternatives you've considered

There is essentially no alternative to the refactoring in Bridle. However, there are affected board families that will not be migrated upstream to Zephyr in the foreseeable future—or perhaps never at all—and therefore should not be considered here and, consequently, should not be refactored:

• VccGND BluePill
• WeAct BluePill+

Additional context

• The namespace used by Bridle, with the respective vendor prefix in the board name, must be retained in order to continue ensuring that Bridle's own boards can be uniquely distinguished from their equivalents in Zephyr upstream.
• Only in a subsequent change process can either boards be moved from Bridle to Zephyr upstream and/or the definitions missing for Bridle be reimplemented for existing Zephyr upstream boards in the form of newly created Bridle Board Extensions (BBE).
• Zephyr Board Porting Guide
• Zephyr Shield porting and configuration