Add documentation for TM16XX and compatible LED display controllers.
This patch is inspired by previous work from Andreas Färber and Heiner Kallweit.
Co-developed-by: Andreas Färber <afaerber@suse.de>
Co-developed-by: Heiner Kallweit <hkallweit1@gmail.com>
Signed-off-by: Jean-François Lessard <jefflessard3@gmail.com>
---
.../bindings/auxdisplay/tm16xx.yaml | 153 ++++++++++++++++++
1 file changed, 153 insertions(+)
create mode 100644 Documentation/devicetree/bindings/auxdisplay/tm16xx.yaml
diff --git a/Documentation/devicetree/bindings/auxdisplay/tm16xx.yaml b/Documentation/devicetree/bindings/auxdisplay/tm16xx.yaml
new file mode 100644
index 0000000000..eba3d3f3f7
--- /dev/null
+++ b/Documentation/devicetree/bindings/auxdisplay/tm16xx.yaml
@@ -0,0 +1,153 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/auxdisplay/tm16xx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Auxiliary displays based on TM16xx and compatible LED controllers
+
+maintainers:
+ - Jean-François Lessard <jefflessard3@gmail.com>
+
+description: |
+ TM16xx controllers manage a matrix of LEDs organized in grids (rows) and segments (columns).
+ Each grid or segment can be wired to drive either a digit or individual icons, depending on the
+ board design.
+
+ Typical display example:
+
+ --- --- --- ---
+ WIFI | | | | - | | | | USB PLAY
+ --- --- --- ---
+ LAN | | | | - | | | | BT PAUSE
+ --- --- --- ---
+
+ The controller itself is agnostic of the display layout. The specific arrangement
+ (which grids and segments drive which digits or icons) is determined by the board-level
+ wiring. Therefore, these bindings describe hardware configuration at the PCB level
+ to enable support of multiple display implementations using these LED controllers.
+
+properties:
+ compatible:
+ enum:
+ - titanmec,tm1618
+ - titanmec,tm1620
+ - titanmec,tm1628
+ - titanmec,tm1650
+ - fdhisi,fd620
+ - fdhisi,fd628
+ - fdhisi,fd650
+ - fdhisi,fd6551
+ - fdhisi,fd655
+ - icore,aip650
+ - icore,aip1618
+ - icore,aip1628
+ - princeton,pt6964
+ - winrise,hbs658
+
+ reg:
+ maxItems: 1
+
+ tm16xx,digits:
+ description: |
+ Array of grid (row) indexes corresponding to specific wiring of digits in the display matrix.
+ Defines which grid lines are connected to digit elements.
+ $ref: /schemas/types.yaml#/definitions/uint8-array
+ items:
+ minimum: 0
+ maximum: 7
+ minItems: 1
+ maxItems: 8
+
+ tm16xx,segment-mapping:
+ description: |
+ Array of segment (column) indexes specifying the hardware layout mapping used for digit display.
+ Each entry gives the segment index corresponding to a standard 7-segment element (a-g).
+ $ref: /schemas/types.yaml#/definitions/uint8-array
+ items:
+ minimum: 0
+ maximum: 7
+ minItems: 7
+ maxItems: 7
+
+ tm16xx,transposed:
+ description: |
+ Optional flag indicating if grids and segments are swapped compared to standard matrix orientation.
+ This accommodates devices where segments are wired to rows and grids to columns.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ "#address-cells":
+ const: 2
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^led@[0-7],[0-7]$":
+ $ref: /schemas/leds/common.yaml#
+ properties:
+ reg:
+ description: Grid (row) and segment (column) index in the matrix of this individual LED icon
+ required:
+ - reg
+
+required:
+ - compatible
+ - reg
+ - tm16xx,digits
+ - tm16xx,segment-mapping
+
+additionalProperties: true
+
+examples:
+ - |
+ display_client: i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ display@24 {
+ compatible = "titanmec,tm1650";
+ reg = <0x24>;
+ tm16xx,digits = /bits/ 8 <0 1 2 3>;
+ tm16xx,segment-mapping = /bits/ 8 <0 1 2 3 4 5 6>;
+
+ #address-cells = <2>;
+ #size-cells = <0>;
+
+ led@4,0 {
+ reg = <4 0>;
+ function = "lan";
+ };
+
+ led@4,1 {
+ reg = <4 1>;
+ function = "wlan";
+ };
+ };
+ };
+ - |
+ display_client: spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ display@0 {
+ compatible = "titanmec,tm1628";
+ reg = <0>;
+ tm16xx,transposed;
+ tm16xx,digits = /bits/ 8 <1 2 3 4>;
+ tm16xx,segment-mapping = /bits/ 8 <0 1 2 3 4 5 6>;
+
+ #address-cells = <2>;
+ #size-cells = <0>;
+
+ led@0,2 {
+ reg = <0 2>;
+ function = "usb";
+ };
+
+ led@0,3 {
+ reg = <0 3>;
+ function = "power";
+ };
+ };
+ };
--
2.43.0
On Sat, 28 Jun 2025 12:18:43 -0400, Jean-François Lessard wrote: > Add documentation for TM16XX and compatible LED display controllers. > > This patch is inspired by previous work from Andreas Färber and Heiner Kallweit. > > Co-developed-by: Andreas Färber <afaerber@suse.de> > Co-developed-by: Heiner Kallweit <hkallweit1@gmail.com> > Signed-off-by: Jean-François Lessard <jefflessard3@gmail.com> > --- > .../bindings/auxdisplay/tm16xx.yaml | 153 ++++++++++++++++++ > 1 file changed, 153 insertions(+) > create mode 100644 Documentation/devicetree/bindings/auxdisplay/tm16xx.yaml > My bot found errors running 'make dt_binding_check' on your patch: yamllint warnings/errors: dtschema/dtc warnings/errors: Documentation/devicetree/bindings/auxdisplay/tm16xx.example.dts:59.29-83.11: ERROR (duplicate_label): /example-1/spi: Duplicate label 'display_client' on /example-1/spi and /example-0/i2c ERROR: Input tree has errors, aborting (use -f to force output) make[2]: *** [scripts/Makefile.dtbs:131: Documentation/devicetree/bindings/auxdisplay/tm16xx.example.dtb] Error 2 make[2]: *** Waiting for unfinished jobs.... make[1]: *** [/builds/robherring/dt-review-ci/linux/Makefile:1519: dt_binding_check] Error 2 make: *** [Makefile:248: __sub-make] Error 2 doc reference errors (make refcheckdocs): See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20250628161850.38865-7-jefflessard3@gmail.com The base for the series is generally the latest rc1. A different dependency should be noted in *this* patch. If you already ran 'make dt_binding_check' and didn't see the above error(s), then make sure 'yamllint' is installed and dt-schema is up to date: pip3 install dtschema --upgrade Please check and re-submit after running the above command yourself. Note that DT_SCHEMA_FILES can be set to your schema file to speed up checking your schema. However, it must be unset to test all examples with your schema.
On Sat, Jun 28, 2025 at 1:55 PM Rob Herring (Arm) <robh@kernel.org> wrote: > > > On Sat, 28 Jun 2025 12:18:43 -0400, Jean-François Lessard wrote: > > Add documentation for TM16XX and compatible LED display controllers. > > > > This patch is inspired by previous work from Andreas Färber and Heiner Kallweit. > > > > Co-developed-by: Andreas Färber <afaerber@suse.de> > > Co-developed-by: Heiner Kallweit <hkallweit1@gmail.com> > > Signed-off-by: Jean-François Lessard <jefflessard3@gmail.com> > > --- > > .../bindings/auxdisplay/tm16xx.yaml | 153 ++++++++++++++++++ > > 1 file changed, 153 insertions(+) > > create mode 100644 Documentation/devicetree/bindings/auxdisplay/tm16xx.yaml > > > > My bot found errors running 'make dt_binding_check' on your patch: > > yamllint warnings/errors: > > dtschema/dtc warnings/errors: > Documentation/devicetree/bindings/auxdisplay/tm16xx.example.dts:59.29-83.11: ERROR (duplicate_label): /example-1/spi: Duplicate label 'display_client' on /example-1/spi and /example-0/i2c > ERROR: Input tree has errors, aborting (use -f to force output) > make[2]: *** [scripts/Makefile.dtbs:131: Documentation/devicetree/bindings/auxdisplay/tm16xx.example.dtb] Error 2 > make[2]: *** Waiting for unfinished jobs.... > make[1]: *** [/builds/robherring/dt-review-ci/linux/Makefile:1519: dt_binding_check] Error 2 > make: *** [Makefile:248: __sub-make] Error 2 > Thank you for the dt_binding_check feedback – I’ll prepare v2 shortly fixing the duplicate label issue. > doc reference errors (make refcheckdocs): > > See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20250628161850.38865-7-jefflessard3@gmail.com > > The base for the series is generally the latest rc1. A different dependency > should be noted in *this* patch. > > If you already ran 'make dt_binding_check' and didn't see the above > error(s), then make sure 'yamllint' is installed and dt-schema is up to > date: > > pip3 install dtschema --upgrade > > Please check and re-submit after running the above command yourself. Note > that DT_SCHEMA_FILES can be set to your schema file to speed up checking > your schema. However, it must be unset to test all examples with your schema. > Before I send v2, I’d like your guidance on one specific design question: Currently, the binding uses a 'tm16xx,' prefix for properties describing hardware layout (e.g. tm16xx,digits). TM16xx being the family name for these compatible controllers (Titanmec, Fuda Hisi, Princeton, Winrise, i-Core). 1. Is using 'tm16xx,' as a class prefix appropriate here, or should I instead use a vendor-specific prefix (e.g. 'titanmec,') despite multiple vendors implementing this hardware design? 2. Should 'tm16xx' also be formally added to vendor-prefixes.yaml or handled differently? Your advice will ensure the next revision aligns with DT conventions. Thanks again for your review and guidance.
© 2016 - 2025 Red Hat, Inc.