shields: doc: allow to indicate supported hw features

Shield authors can now indicate an optional list of hardware features
that the shield supports, in the form of the same kind of "binding type"
already used for boards.

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This commit is contained in:
Benjamin Cabé 2025-05-26 11:57:25 +02:00 committed by Benjamin Cabé
commit 804915841a
5 changed files with 26 additions and 2 deletions

View file

@ -13,7 +13,15 @@
aria-label="Open the documentation page for {{ shield.full_name }}"
data-name="{{ shield.full_name}}"
data-vendor="{{ shield.vendor }}"
tabindex="0">
data-supported-features="
{%- set feature_types = [] -%}
{%- for feature in shield.supported_features -%}
{%- if feature not in feature_types -%}
{%- set _ = feature_types.append(feature) -%}
{%- endif -%}
{%- endfor -%}
{{- feature_types|join(' ') -}}
" tabindex="0">
<div class="vendor">{{ vendors[shield.vendor] }}</div>
{% if shield.image -%}
<img alt="A picture of the {{ shield.full_name }} shield"

View file

@ -416,6 +416,7 @@ def get_catalog(generate_hw_features=False, hw_features_vendor_filter=None):
"vendor": shield.vendor or "others",
"doc_page": doc_page_path,
"image": guess_image(shield),
"supported_features": shield.supported_features or [],
}
return {

View file

@ -33,6 +33,11 @@ These files provides shield configuration as follows:
* ``name``: Name of the shield used in Kconfig and build system (required)
* ``full_name``: Full commercial name of the shield (required)
* ``vendor``: Manufacturer/vendor of the shield (required)
* ``supported_features``: List of hardware features the shield supports (optional). In order to
help users identify the features a shield supports without having to dig into its overlay file,
the ``supported_features`` field can be used to list the types of features the shield supports.
The values should be the same as the ones defined in the
:zephyr_file:`dts/bindings/binding-types.txt` file.
Example:
@ -41,6 +46,9 @@ These files provides shield configuration as follows:
name: foo_shield
full_name: Foo Shield for Arduino
vendor: acme
supported_features:
- display
- input
* **<shield>.overlay**: This file provides a shield description in devicetree
format that is merged with the board's :ref:`devicetree <dt-guide>`

View file

@ -39,6 +39,7 @@ class Shield:
dir: Path
full_name: str | None = None
vendor: str | None = None
supported_features: list[str] | None = None
def shield_key(shield):
return shield.name
@ -49,7 +50,8 @@ def process_shield_data(shield_data, shield_dir):
name=shield_data['name'],
dir=shield_dir,
full_name=shield_data.get('full_name'),
vendor=shield_data.get('vendor')
vendor=shield_data.get('vendor'),
supported_features=shield_data.get('supported_features', []),
)
def find_shields(args):

View file

@ -21,6 +21,11 @@ schema;shield-schema:
required: true
type: str
desc: Manufacturer/vendor of the shield
supported_features:
required: false
sequence:
- type: str
desc: A hardware feature the shield supports (see dts/bindings/binding-types.txt)
type: map
range: