Add documentation for TM16xx-compatible 7-segment LED display controllers
with keyscan.
Signed-off-by: Jean-François Lessard <jefflessard3@gmail.com>
---
Notes:
The 'segments' property is intentionally not vendor-prefixed as it
defines a generic hardware description concept applicable to any
7-segment display controller. The property describes the fundamental
grid/segment coordinate mapping that is controller-agnostic and could
be reused by other LED matrix display bindings. Similar to how 'gpios'
describes GPIO connections generically, 'segments' describes segment
connections in a standardized way using uint32-matrix format.
.../bindings/auxdisplay/titanmec,tm16xx.yaml | 477 ++++++++++++++++++
MAINTAINERS | 5 +
2 files changed, 482 insertions(+)
create mode 100644 Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml
diff --git a/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml b/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml
new file mode 100644
index 000000000..c94556d95
--- /dev/null
+++ b/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml
@@ -0,0 +1,477 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/auxdisplay/titanmec,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: |
+ LED matrix controllers used in auxiliary display devices that drive individual
+ LED icons and 7-segment digit groups through a grid/segment addressing scheme.
+ Controllers manage a matrix of LEDs organized as grids (columns/banks in
+ vendor datasheets) and segments (rows/bit positions in vendor datasheets).
+ Maximum grid and segment indices are controller-specific.
+
+ The controller is agnostic of the display layout. Board-specific LED wiring is
+ described through child nodes that specify grid/segment coordinates for
+ individual icons and segment mapping for 7-segment digits.
+
+ The bindings use separate 'leds' and 'digits' containers to accommodate
+ different addressing schemes:
+ - LEDs use 2-cell addressing (grid, segment) for matrix coordinates
+ - Digits use 1-cell addressing with explicit segment mapping
+
+ The controller node exposes a logical LED-like control for the aggregate
+ display brightness. Child nodes describe individual icons and 7-seg digits.
+ The top-level control supports only label and brightness-related properties
+ and does not support other common LED properties such as color or function.
+ Child LED nodes use the standard LED binding.
+
+ Optional keypad scanning is supported when both 'linux,keymap' and
+ 'poll-interval' properties are specified.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - fdhisi,fd628
+ - princeton,pt6964
+ - wxicore,aip1628
+ - const: titanmec,tm1628
+ - items:
+ - enum:
+ - wxicore,aip1618
+ - const: titanmec,tm1618
+ - items:
+ - enum:
+ - fdhisi,fd650
+ - wxicore,aip650
+ - const: titanmec,tm1650
+ - enum:
+ - fdhisi,fd620
+ - fdhisi,fd655
+ - fdhisi,fd6551
+ - titanmec,tm1618
+ - titanmec,tm1620
+ - titanmec,tm1628
+ - titanmec,tm1638
+ - titanmec,tm1650
+ - winrise,hbs658
+
+ reg:
+ maxItems: 1
+
+ label:
+ description:
+ The label for the top-level LED. If omitted, the label is taken from the
+ node name (excluding the unit address). It has to uniquely identify a
+ device, i.e. no other LED class device can be assigned the same label.
+ $ref: /schemas/leds/common.yaml#/properties/label
+
+ max-brightness:
+ description:
+ Normally the maximum brightness is determined by the hardware and this
+ property is not required. This property is used to put a software limit
+ on the brightness apart from what the driver says, as it could happen
+ that a LED can be made so bright that it gets damaged or causes damage
+ due to restrictions in a specific system, such as mounting conditions.
+ $ref: /schemas/leds/common.yaml#/properties/max-brightness
+
+ default-brightness:
+ description:
+ Brightness to be set if LED's default state is on. Used only during
+ initialization. If the option is not set then max brightness is used.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ digits:
+ type: object
+ description: Container for 7-segment digit group definitions
+ additionalProperties: false
+
+ properties:
+ "#address-cells":
+ const: 1
+ "#size-cells":
+ const: 0
+
+ patternProperties:
+ "^digit@[0-9]+$":
+ type: object
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description: Digit position identifier
+ maxItems: 1
+
+ segments:
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+ description: |
+ Array of grid/segment coordinate pairs for each 7-segment position.
+ Each entry is <grid segment> mapping to standard 7-segment positions
+ in order: a, b, c, d, e, f, g
+
+ Standard 7-segment layout:
+ aaa
+ f b
+ f b
+ ggg
+ e c
+ e c
+ ddd
+ items:
+ items:
+ - description: Grid index
+ - description: Segment index
+ minItems: 7
+ maxItems: 7
+
+ required:
+ - reg
+ - segments
+
+ leds:
+ type: object
+ description: Container for individual LED icon definitions
+ additionalProperties: false
+
+ properties:
+ "#address-cells":
+ const: 2
+ "#size-cells":
+ const: 0
+
+ patternProperties:
+ "^led@[0-9]+,[0-9]+$":
+ type: object
+ $ref: /schemas/leds/common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description:
+ Grid and segment indices as <grid segment> of this individual LED icon
+
+ required:
+ - reg
+
+allOf:
+ - $ref: /schemas/input/input.yaml#
+ - $ref: /schemas/input/matrix-keymap.yaml#
+
+dependencies:
+ poll-interval:
+ - linux,keymap
+ linux,keymap:
+ - poll-interval
+ autorepeat:
+ - linux,keymap
+ - poll-interval
+
+# SPI controllers require 3-wire (combined MISO/MOSI line)
+if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fdhisi,fd620
+ - fdhisi,fd628
+ - princeton,pt6964
+ - titanmec,tm1618
+ - titanmec,tm1620
+ - titanmec,tm1628
+ - titanmec,tm1638
+ - wxicore,aip1618
+ - wxicore,aip1628
+then:
+ allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ properties:
+ spi-3wire: true
+ required:
+ - spi-3wire
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ // I2C example: Magicsee N5 TV box with fd655 controller
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ display@24 {
+ reg = <0x24>;
+ compatible = "fdhisi,fd655";
+
+ digits {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ digit@0 {
+ reg = <0>;
+ segments = <4 3>, <4 4>, <4 5>, <4 0>, <4 1>, <4 2>, <4 6>;
+ };
+
+ digit@1 {
+ reg = <1>;
+ segments = <3 3>, <3 4>, <3 5>, <3 0>, <3 1>, <3 2>, <3 6>;
+ };
+
+ digit@2 {
+ reg = <2>;
+ segments = <2 3>, <2 4>, <2 5>, <2 0>, <2 1>, <2 2>, <2 6>;
+ };
+
+ digit@3 {
+ reg = <3>;
+ segments = <1 3>, <1 4>, <1 5>, <1 0>, <1 1>, <1 2>, <1 6>;
+ };
+ };
+
+ leds {
+ #address-cells = <2>;
+ #size-cells = <0>;
+
+ led@0,0 {
+ reg = <0 0>;
+ function = LED_FUNCTION_ALARM;
+ };
+
+ led@0,1 {
+ reg = <0 1>;
+ function = LED_FUNCTION_USB;
+ };
+
+ led@0,2 {
+ reg = <0 2>;
+ function = "play";
+ };
+
+ led@0,3 {
+ reg = <0 3>;
+ function = "pause";
+ };
+
+ led@0,4 {
+ reg = <0 4>;
+ function = "colon";
+ };
+
+ led@0,5 {
+ reg = <0 5>;
+ function = LED_FUNCTION_LAN;
+ };
+
+ led@0,6 {
+ reg = <0 6>;
+ function = LED_FUNCTION_WLAN;
+ };
+ };
+ };
+ };
+
+ - |
+ #include <dt-bindings/input/input.h>
+
+ // SPI example: TM1638 module with keypad support
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ display@0 {
+ reg = <0>;
+ compatible = "titanmec,tm1638";
+ spi-3wire;
+ spi-lsb-first;
+ spi-max-frequency = <500000>;
+
+ label = "tm1638";
+ default-brightness = <2>;
+ max-brightness = <4>;
+ poll-interval = <100>;
+ linux,keymap = <MATRIX_KEY(2, 0, KEY_F1)
+ MATRIX_KEY(2, 2, KEY_F2)
+ MATRIX_KEY(2, 4, KEY_F3)
+ MATRIX_KEY(2, 6, KEY_F4)
+ MATRIX_KEY(2, 1, KEY_F5)
+ MATRIX_KEY(2, 3, KEY_F6)
+ MATRIX_KEY(2, 5, KEY_F7)
+ MATRIX_KEY(2, 7, KEY_F8)>;
+
+ digits {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ digit@0 {
+ reg = <0>;
+ segments = <7 0>, <7 1>, <7 2>, <7 3>, <7 4>, <7 5>, <7 6>;
+ };
+
+ digit@1 {
+ reg = <1>;
+ segments = <6 0>, <6 1>, <6 2>, <6 3>, <6 4>, <6 5>, <6 6>;
+ };
+
+ digit@2 {
+ reg = <2>;
+ segments = <5 0>, <5 1>, <5 2>, <5 3>, <5 4>, <5 5>, <5 6>;
+ };
+
+ digit@3 {
+ reg = <3>;
+ segments = <4 0>, <4 1>, <4 2>, <4 3>, <4 4>, <4 5>, <4 6>;
+ };
+
+ digit@4 {
+ reg = <4>;
+ segments = <3 0>, <3 1>, <3 2>, <3 3>, <3 4>, <3 5>, <3 6>;
+ };
+
+ digit@5 {
+ reg = <5>;
+ segments = <2 0>, <2 1>, <2 2>, <2 3>, <2 4>, <2 5>, <2 6>;
+ };
+
+ digit@6 {
+ reg = <6>;
+ segments = <1 0>, <1 1>, <1 2>, <1 3>, <1 4>, <1 5>, <1 6>;
+ };
+
+ digit@7 {
+ reg = <7>;
+ segments = <0 0>, <0 1>, <0 2>, <0 3>, <0 4>, <0 5>, <0 6>;
+ };
+ };
+
+ leds {
+ #address-cells = <2>;
+ #size-cells = <0>;
+
+ led@0,7 {
+ reg = <0 7>;
+ };
+
+ led@1,7 {
+ reg = <1 7>;
+ };
+
+ led@2,7 {
+ reg = <2 7>;
+ };
+
+ led@3,7 {
+ reg = <3 7>;
+ };
+
+ led@4,7 {
+ reg = <4 7>;
+ };
+
+ led@5,7 {
+ reg = <5 7>;
+ };
+
+ led@6,7 {
+ reg = <6 7>;
+ };
+
+ led@7,7 {
+ reg = <7 7>;
+ };
+ };
+ };
+ };
+
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ // SPI example: X96 Max with transposed layout (fd628 with tm1628 fallback)
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ display@0 {
+ reg = <0>;
+ compatible = "fdhisi,fd628", "titanmec,tm1628";
+ spi-3wire;
+ spi-lsb-first;
+ spi-max-frequency = <500000>;
+
+ digits {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ digit@0 {
+ reg = <0>;
+ segments = <0 3>, <1 3>, <2 3>, <3 3>, <4 3>, <5 3>, <6 3>;
+ };
+
+ digit@1 {
+ reg = <1>;
+ segments = <0 2>, <1 2>, <2 2>, <3 2>, <4 2>, <5 2>, <6 2>;
+ };
+
+ digit@2 {
+ reg = <2>;
+ segments = <0 1>, <1 1>, <2 1>, <3 1>, <4 1>, <5 1>, <6 1>;
+ };
+
+ digit@3 {
+ reg = <3>;
+ segments = <0 0>, <1 0>, <2 0>, <3 0>, <4 0>, <5 0>, <6 0>;
+ };
+ };
+
+ leds {
+ #address-cells = <2>;
+ #size-cells = <0>;
+
+ led@0,4 {
+ reg = <0 4>;
+ function = "apps";
+ };
+
+ led@1,4 {
+ reg = <1 4>;
+ function = "setup";
+ };
+
+ led@2,4 {
+ reg = <2 4>;
+ function = LED_FUNCTION_USB;
+ };
+
+ led@3,4 {
+ reg = <3 4>;
+ function = LED_FUNCTION_SD;
+ };
+
+ led@4,4 {
+ reg = <4 4>;
+ function = "colon";
+ };
+
+ led@5,4 {
+ reg = <5 4>;
+ function = "hdmi";
+ };
+
+ led@6,4 {
+ reg = <6 4>;
+ function = "video";
+ };
+ };
+ };
+ };
diff --git a/MAINTAINERS b/MAINTAINERS
index daf520a13..4e5a7db6d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -25402,6 +25402,11 @@ W: http://sourceforge.net/projects/tlan/
F: Documentation/networking/device_drivers/ethernet/ti/tlan.rst
F: drivers/net/ethernet/ti/tlan.*
+TM16XX-COMPATIBLE LED CONTROLLERS DISPLAY DRIVER
+M: Jean-François Lessard <jefflessard3@gmail.com>
+S: Maintained
+F: Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml
+
TMIO/SDHI MMC DRIVER
M: Wolfram Sang <wsa+renesas@sang-engineering.com>
L: linux-mmc@vger.kernel.org
--
2.43.0
On Sun, 24 Aug 2025 23:32:28 -0400 Jean-François Lessard <jefflessard3@gmail.com> wrote: > + - Digits use 1-cell addressing with explicit segment mapping This new digits layout introduced in v3 implies that a different segment mapping can be used per digit by a single display/controller. Is that really a thing? Regards Per Larsson
Le 25 août 2025 15 h 08 min 36 s HAE, Per Larsson <per@palvencia.se> a écrit : >On Sun, 24 Aug 2025 23:32:28 -0400 >Jean-François Lessard <jefflessard3@gmail.com> wrote: > >> + - Digits use 1-cell addressing with explicit segment mapping > >This new digits layout introduced in v3 implies that a >different segment mapping can be used per digit by a >single display/controller. Is that really a thing? > Board manufacturers typically use consistent patterns across digits, but some use matrix-transposed layouts where grid/segment relationships are swapped system-wide. The explicit coordinate mapping handles both standard and transposed configurations. Bottom line: I am not aware of different per digit 7-segment mappings on a single display board. Best Regards Jean-François Lessard
On Sun, Aug 24, 2025 at 11:32:28PM -0400, Jean-François Lessard wrote:
> Add documentation for TM16xx-compatible 7-segment LED display controllers
> with keyscan.
>
> Signed-off-by: Jean-François Lessard <jefflessard3@gmail.com>
> ---
>
> Notes:
> The 'segments' property is intentionally not vendor-prefixed as it
> defines a generic hardware description concept applicable to any
> 7-segment display controller. The property describes the fundamental
> grid/segment coordinate mapping that is controller-agnostic and could
> be reused by other LED matrix display bindings. Similar to how 'gpios'
> describes GPIO connections generically, 'segments' describes segment
> connections in a standardized way using uint32-matrix format.
>
> .../bindings/auxdisplay/titanmec,tm16xx.yaml | 477 ++++++++++++++++++
> MAINTAINERS | 5 +
> 2 files changed, 482 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml
>
> diff --git a/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml b/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml
> new file mode 100644
> index 000000000..c94556d95
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml
> @@ -0,0 +1,477 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/auxdisplay/titanmec,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: |
> + LED matrix controllers used in auxiliary display devices that drive individual
> + LED icons and 7-segment digit groups through a grid/segment addressing scheme.
> + Controllers manage a matrix of LEDs organized as grids (columns/banks in
> + vendor datasheets) and segments (rows/bit positions in vendor datasheets).
> + Maximum grid and segment indices are controller-specific.
> +
> + The controller is agnostic of the display layout. Board-specific LED wiring is
> + described through child nodes that specify grid/segment coordinates for
> + individual icons and segment mapping for 7-segment digits.
> +
> + The bindings use separate 'leds' and 'digits' containers to accommodate
> + different addressing schemes:
> + - LEDs use 2-cell addressing (grid, segment) for matrix coordinates
> + - Digits use 1-cell addressing with explicit segment mapping
> +
> + The controller node exposes a logical LED-like control for the aggregate
> + display brightness. Child nodes describe individual icons and 7-seg digits.
> + The top-level control supports only label and brightness-related properties
> + and does not support other common LED properties such as color or function.
> + Child LED nodes use the standard LED binding.
> +
> + Optional keypad scanning is supported when both 'linux,keymap' and
> + 'poll-interval' properties are specified.
> +
> +properties:
> + compatible:
> + oneOf:
> + - items:
> + - enum:
> + - fdhisi,fd628
> + - princeton,pt6964
> + - wxicore,aip1628
> + - const: titanmec,tm1628
> + - items:
> + - enum:
> + - wxicore,aip1618
> + - const: titanmec,tm1618
> + - items:
> + - enum:
> + - fdhisi,fd650
> + - wxicore,aip650
> + - const: titanmec,tm1650
> + - enum:
> + - fdhisi,fd620
> + - fdhisi,fd655
> + - fdhisi,fd6551
> + - titanmec,tm1618
> + - titanmec,tm1620
> + - titanmec,tm1628
> + - titanmec,tm1638
> + - titanmec,tm1650
> + - winrise,hbs658
> +
> + reg:
> + maxItems: 1
> +
> + label:
> + description:
> + The label for the top-level LED. If omitted, the label is taken from the
> + node name (excluding the unit address). It has to uniquely identify a
> + device, i.e. no other LED class device can be assigned the same label.
> + $ref: /schemas/leds/common.yaml#/properties/label
> +
> + max-brightness:
> + description:
> + Normally the maximum brightness is determined by the hardware and this
> + property is not required. This property is used to put a software limit
> + on the brightness apart from what the driver says, as it could happen
> + that a LED can be made so bright that it gets damaged or causes damage
> + due to restrictions in a specific system, such as mounting conditions.
> + $ref: /schemas/leds/common.yaml#/properties/max-brightness
These 2 $ref's should be at the node level. The clue is you
copied-n-pasted the whole description.
What you need here is some constraints. What's the max value?
> +
> + default-brightness:
> + description:
> + Brightness to be set if LED's default state is on. Used only during
> + initialization. If the option is not set then max brightness is used.
> + $ref: /schemas/types.yaml#/definitions/uint32
This needs to first go into leds/common.yaml.
> +
> + digits:
> + type: object
> + description: Container for 7-segment digit group definitions
> + additionalProperties: false
> +
> + properties:
> + "#address-cells":
> + const: 1
> + "#size-cells":
> + const: 0
> +
> + patternProperties:
> + "^digit@[0-9]+$":
> + type: object
> + unevaluatedProperties: false
> +
> + properties:
> + reg:
> + description: Digit position identifier
Position is right to left (0 on right)? Please clarify.
> + maxItems: 1
> +
> + segments:
> + $ref: /schemas/types.yaml#/definitions/uint32-matrix
> + description: |
> + Array of grid/segment coordinate pairs for each 7-segment position.
> + Each entry is <grid segment> mapping to standard 7-segment positions
> + in order: a, b, c, d, e, f, g
> +
> + Standard 7-segment layout:
> + aaa
> + f b
> + f b
> + ggg
> + e c
> + e c
> + ddd
> + items:
> + items:
> + - description: Grid index
> + - description: Segment index
Can't you do an array instead and make the array index be the grid or
segment index?
> + minItems: 7
> + maxItems: 7
> +
> + required:
> + - reg
> + - segments
> +
> + leds:
> + type: object
> + description: Container for individual LED icon definitions
> + additionalProperties: false
> +
> + properties:
> + "#address-cells":
> + const: 2
> + "#size-cells":
> + const: 0
> +
> + patternProperties:
> + "^led@[0-9]+,[0-9]+$":
> + type: object
> + $ref: /schemas/leds/common.yaml#
> + unevaluatedProperties: false
> +
> + properties:
> + reg:
> + description:
> + Grid and segment indices as <grid segment> of this individual LED icon
> +
> + required:
> + - reg
> +
> +allOf:
> + - $ref: /schemas/input/input.yaml#
> + - $ref: /schemas/input/matrix-keymap.yaml#
> +
> +dependencies:
> + poll-interval:
> + - linux,keymap
> + linux,keymap:
> + - poll-interval
> + autorepeat:
> + - linux,keymap
> + - poll-interval
> +
> +# SPI controllers require 3-wire (combined MISO/MOSI line)
> +if:
Move this under the allOf.
> + properties:
> + compatible:
> + contains:
> + enum:
> + - fdhisi,fd620
> + - fdhisi,fd628
> + - princeton,pt6964
> + - titanmec,tm1618
> + - titanmec,tm1620
> + - titanmec,tm1628
> + - titanmec,tm1638
> + - wxicore,aip1618
> + - wxicore,aip1628
> +then:
> + allOf:
Drop allOf.
> + - $ref: /schemas/spi/spi-peripheral-props.yaml#
> + properties:
> + spi-3wire: true
Drop 'properties'
> + required:
> + - spi-3wire
> +
> +required:
Order should be 'dependencies', 'required', 'allOf'.
> + - compatible
> + - reg
> +
> +unevaluatedProperties: false
> +
> +examples:
> + - |
> + #include <dt-bindings/leds/common.h>
> +
> + // I2C example: Magicsee N5 TV box with fd655 controller
> + i2c {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + display@24 {
> + reg = <0x24>;
> + compatible = "fdhisi,fd655";
> +
> + digits {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + digit@0 {
> + reg = <0>;
> + segments = <4 3>, <4 4>, <4 5>, <4 0>, <4 1>, <4 2>, <4 6>;
> + };
> +
> + digit@1 {
> + reg = <1>;
> + segments = <3 3>, <3 4>, <3 5>, <3 0>, <3 1>, <3 2>, <3 6>;
> + };
> +
> + digit@2 {
> + reg = <2>;
> + segments = <2 3>, <2 4>, <2 5>, <2 0>, <2 1>, <2 2>, <2 6>;
> + };
> +
> + digit@3 {
> + reg = <3>;
> + segments = <1 3>, <1 4>, <1 5>, <1 0>, <1 1>, <1 2>, <1 6>;
> + };
> + };
> +
> + leds {
> + #address-cells = <2>;
> + #size-cells = <0>;
> +
> + led@0,0 {
> + reg = <0 0>;
> + function = LED_FUNCTION_ALARM;
> + };
> +
> + led@0,1 {
> + reg = <0 1>;
> + function = LED_FUNCTION_USB;
> + };
> +
> + led@0,2 {
> + reg = <0 2>;
> + function = "play";
> + };
> +
> + led@0,3 {
> + reg = <0 3>;
> + function = "pause";
> + };
> +
> + led@0,4 {
> + reg = <0 4>;
> + function = "colon";
> + };
> +
> + led@0,5 {
> + reg = <0 5>;
> + function = LED_FUNCTION_LAN;
> + };
> +
> + led@0,6 {
> + reg = <0 6>;
> + function = LED_FUNCTION_WLAN;
> + };
> + };
> + };
> + };
> +
> + - |
> + #include <dt-bindings/input/input.h>
> +
> + // SPI example: TM1638 module with keypad support
> + spi {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + display@0 {
> + reg = <0>;
> + compatible = "titanmec,tm1638";
> + spi-3wire;
> + spi-lsb-first;
> + spi-max-frequency = <500000>;
> +
> + label = "tm1638";
> + default-brightness = <2>;
> + max-brightness = <4>;
> + poll-interval = <100>;
> + linux,keymap = <MATRIX_KEY(2, 0, KEY_F1)
> + MATRIX_KEY(2, 2, KEY_F2)
> + MATRIX_KEY(2, 4, KEY_F3)
> + MATRIX_KEY(2, 6, KEY_F4)
> + MATRIX_KEY(2, 1, KEY_F5)
> + MATRIX_KEY(2, 3, KEY_F6)
> + MATRIX_KEY(2, 5, KEY_F7)
> + MATRIX_KEY(2, 7, KEY_F8)>;
> +
> + digits {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + digit@0 {
> + reg = <0>;
> + segments = <7 0>, <7 1>, <7 2>, <7 3>, <7 4>, <7 5>, <7 6>;
> + };
> +
> + digit@1 {
> + reg = <1>;
> + segments = <6 0>, <6 1>, <6 2>, <6 3>, <6 4>, <6 5>, <6 6>;
> + };
> +
> + digit@2 {
> + reg = <2>;
> + segments = <5 0>, <5 1>, <5 2>, <5 3>, <5 4>, <5 5>, <5 6>;
> + };
> +
> + digit@3 {
> + reg = <3>;
> + segments = <4 0>, <4 1>, <4 2>, <4 3>, <4 4>, <4 5>, <4 6>;
> + };
> +
> + digit@4 {
> + reg = <4>;
> + segments = <3 0>, <3 1>, <3 2>, <3 3>, <3 4>, <3 5>, <3 6>;
> + };
> +
> + digit@5 {
> + reg = <5>;
> + segments = <2 0>, <2 1>, <2 2>, <2 3>, <2 4>, <2 5>, <2 6>;
> + };
> +
> + digit@6 {
> + reg = <6>;
> + segments = <1 0>, <1 1>, <1 2>, <1 3>, <1 4>, <1 5>, <1 6>;
> + };
> +
> + digit@7 {
> + reg = <7>;
> + segments = <0 0>, <0 1>, <0 2>, <0 3>, <0 4>, <0 5>, <0 6>;
> + };
> + };
> +
> + leds {
> + #address-cells = <2>;
> + #size-cells = <0>;
> +
> + led@0,7 {
> + reg = <0 7>;
> + };
> +
> + led@1,7 {
> + reg = <1 7>;
> + };
> +
> + led@2,7 {
> + reg = <2 7>;
> + };
> +
> + led@3,7 {
> + reg = <3 7>;
> + };
> +
> + led@4,7 {
> + reg = <4 7>;
> + };
> +
> + led@5,7 {
> + reg = <5 7>;
> + };
> +
> + led@6,7 {
> + reg = <6 7>;
> + };
> +
> + led@7,7 {
> + reg = <7 7>;
> + };
> + };
> + };
> + };
> +
> + - |
> + #include <dt-bindings/leds/common.h>
> +
> + // SPI example: X96 Max with transposed layout (fd628 with tm1628 fallback)
> + spi {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + display@0 {
> + reg = <0>;
> + compatible = "fdhisi,fd628", "titanmec,tm1628";
> + spi-3wire;
> + spi-lsb-first;
> + spi-max-frequency = <500000>;
> +
> + digits {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + digit@0 {
> + reg = <0>;
> + segments = <0 3>, <1 3>, <2 3>, <3 3>, <4 3>, <5 3>, <6 3>;
> + };
> +
> + digit@1 {
> + reg = <1>;
> + segments = <0 2>, <1 2>, <2 2>, <3 2>, <4 2>, <5 2>, <6 2>;
> + };
> +
> + digit@2 {
> + reg = <2>;
> + segments = <0 1>, <1 1>, <2 1>, <3 1>, <4 1>, <5 1>, <6 1>;
> + };
> +
> + digit@3 {
> + reg = <3>;
> + segments = <0 0>, <1 0>, <2 0>, <3 0>, <4 0>, <5 0>, <6 0>;
> + };
> + };
> +
> + leds {
> + #address-cells = <2>;
> + #size-cells = <0>;
> +
> + led@0,4 {
> + reg = <0 4>;
> + function = "apps";
> + };
> +
> + led@1,4 {
> + reg = <1 4>;
> + function = "setup";
> + };
> +
> + led@2,4 {
> + reg = <2 4>;
> + function = LED_FUNCTION_USB;
> + };
> +
> + led@3,4 {
> + reg = <3 4>;
> + function = LED_FUNCTION_SD;
> + };
> +
> + led@4,4 {
> + reg = <4 4>;
> + function = "colon";
> + };
> +
> + led@5,4 {
> + reg = <5 4>;
> + function = "hdmi";
> + };
> +
> + led@6,4 {
> + reg = <6 4>;
> + function = "video";
> + };
> + };
> + };
> + };
> diff --git a/MAINTAINERS b/MAINTAINERS
> index daf520a13..4e5a7db6d 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -25402,6 +25402,11 @@ W: http://sourceforge.net/projects/tlan/
> F: Documentation/networking/device_drivers/ethernet/ti/tlan.rst
> F: drivers/net/ethernet/ti/tlan.*
>
> +TM16XX-COMPATIBLE LED CONTROLLERS DISPLAY DRIVER
> +M: Jean-François Lessard <jefflessard3@gmail.com>
> +S: Maintained
> +F: Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml
> +
> TMIO/SDHI MMC DRIVER
> M: Wolfram Sang <wsa+renesas@sang-engineering.com>
> L: linux-mmc@vger.kernel.org
> --
> 2.43.0
>
Le 25 août 2025 14 h 26 min 57 s HAE, Rob Herring <robh@kernel.org> a écrit : >On Sun, Aug 24, 2025 at 11:32:28PM -0400, Jean-François Lessard wrote: >> Add documentation for TM16xx-compatible 7-segment LED display controllers >> with keyscan. >> >> Signed-off-by: Jean-François Lessard <jefflessard3@gmail.com> >> --- >> >> Notes: >> The 'segments' property is intentionally not vendor-prefixed as it >> defines a generic hardware description concept applicable to any >> 7-segment display controller. The property describes the fundamental >> grid/segment coordinate mapping that is controller-agnostic and could >> be reused by other LED matrix display bindings. Similar to how 'gpios' >> describes GPIO connections generically, 'segments' describes segment >> connections in a standardized way using uint32-matrix format. >> >> .../bindings/auxdisplay/titanmec,tm16xx.yaml | 477 ++++++++++++++++++ >> MAINTAINERS | 5 + >> 2 files changed, 482 insertions(+) >> create mode 100644 Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml >> >> diff --git a/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml b/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml >> new file mode 100644 >> index 000000000..c94556d95 >> --- /dev/null >> +++ b/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml >> @@ -0,0 +1,477 @@ >> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) >> +%YAML 1.2 >> +--- >> +$id: http://devicetree.org/schemas/auxdisplay/titanmec,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: | >> + LED matrix controllers used in auxiliary display devices that drive individual >> + LED icons and 7-segment digit groups through a grid/segment addressing scheme. >> + Controllers manage a matrix of LEDs organized as grids (columns/banks in >> + vendor datasheets) and segments (rows/bit positions in vendor datasheets). >> + Maximum grid and segment indices are controller-specific. In reference to max-brightness, I'll replace with: Maximum brightness and grid/segment indices are controller-specific. Controller-specific maximum are validated in the driver. >> + >> + The controller is agnostic of the display layout. Board-specific LED wiring is >> + described through child nodes that specify grid/segment coordinates for >> + individual icons and segment mapping for 7-segment digits. >> + >> + The bindings use separate 'leds' and 'digits' containers to accommodate >> + different addressing schemes: >> + - LEDs use 2-cell addressing (grid, segment) for matrix coordinates >> + - Digits use 1-cell addressing with explicit segment mapping >> + >> + The controller node exposes a logical LED-like control for the aggregate >> + display brightness. Child nodes describe individual icons and 7-seg digits. >> + The top-level control supports only label and brightness-related properties >> + and does not support other common LED properties such as color or function. >> + Child LED nodes use the standard LED binding. >> + >> + Optional keypad scanning is supported when both 'linux,keymap' and >> + 'poll-interval' properties are specified. >> + >> +properties: >> + compatible: >> + oneOf: >> + - items: >> + - enum: >> + - fdhisi,fd628 >> + - princeton,pt6964 >> + - wxicore,aip1628 >> + - const: titanmec,tm1628 >> + - items: >> + - enum: >> + - wxicore,aip1618 >> + - const: titanmec,tm1618 >> + - items: >> + - enum: >> + - fdhisi,fd650 >> + - wxicore,aip650 >> + - const: titanmec,tm1650 >> + - enum: >> + - fdhisi,fd620 >> + - fdhisi,fd655 >> + - fdhisi,fd6551 >> + - titanmec,tm1618 >> + - titanmec,tm1620 >> + - titanmec,tm1628 >> + - titanmec,tm1638 >> + - titanmec,tm1650 >> + - winrise,hbs658 >> + >> + reg: >> + maxItems: 1 >> + >> + label: >> + description: >> + The label for the top-level LED. If omitted, the label is taken from the >> + node name (excluding the unit address). It has to uniquely identify a >> + device, i.e. no other LED class device can be assigned the same label. >> + $ref: /schemas/leds/common.yaml#/properties/label >> + >> + max-brightness: >> + description: >> + Normally the maximum brightness is determined by the hardware and this >> + property is not required. This property is used to put a software limit >> + on the brightness apart from what the driver says, as it could happen >> + that a LED can be made so bright that it gets damaged or causes damage >> + due to restrictions in a specific system, such as mounting conditions. >> + $ref: /schemas/leds/common.yaml#/properties/max-brightness > >These 2 $ref's should be at the node level. The clue is you >copied-n-pasted the whole description. > I'll add: allOf: - $ref: /schemas/leds/common.yaml# at the node level and constrain inapplicable LED properties (color, function) using properties: false since this auxdisplay device integrates with LED subsystem for brightness control. >What you need here is some constraints. What's the max value? > Maximum brightness varies by controller: - TM1618/TM1628/TM1638 support levels 0-8 - TM1650 supports levels 0-8 - TM1620 supports levels 0-3 I'll set the schema maximum to 8: max-brightness: maximum: 8 # Maximum across all TM16xx controllers with the top-level description note that actual limits are controller-dependent and are enforced by the driver. >> + >> + default-brightness: >> + description: >> + Brightness to be set if LED's default state is on. Used only during >> + initialization. If the option is not set then max brightness is used. >> + $ref: /schemas/types.yaml#/definitions/uint32 > >This needs to first go into leds/common.yaml. > Given its specific relevance to this auxdisplay use case rather than general LED behavior, I am not sure it's worth adding default-brightness to LEDs/common.yaml If broader LED subsystem adoption is wanted, I am willing to submit a separate patch to this series to add it. Otherwise, existing precedent in backlight/common.yaml and leds/leds-pwm.yaml would advocate for defining it locally. >> + >> + digits: >> + type: object >> + description: Container for 7-segment digit group definitions >> + additionalProperties: false >> + >> + properties: >> + "#address-cells": >> + const: 1 >> + "#size-cells": >> + const: 0 >> + >> + patternProperties: >> + "^digit@[0-9]+$": >> + type: object >> + unevaluatedProperties: false >> + >> + properties: >> + reg: >> + description: Digit position identifier > >Position is right to left (0 on right)? Please clarify. > I'll clarify: digit positions are numbered sequentially left-to-right, with reg=0 representing the leftmost digit position as displayed to the user. >> + maxItems: 1 >> + >> + segments: >> + $ref: /schemas/types.yaml#/definitions/uint32-matrix >> + description: | >> + Array of grid/segment coordinate pairs for each 7-segment position. >> + Each entry is <grid segment> mapping to standard 7-segment positions >> + in order: a, b, c, d, e, f, g >> + >> + Standard 7-segment layout: >> + aaa >> + f b >> + f b >> + ggg >> + e c >> + e c >> + ddd >> + items: >> + items: >> + - description: Grid index >> + - description: Segment index > >Can't you do an array instead and make the array index be the grid or >segment index? > Original design was array-based: - titanmec,digits: array of grid indices - titanmec,segment-mapping: array of segment indices for a,b,c,d,e,f,g - titanmec,transposed: boolean for matrix-transposed cases The current explicit coordinate approach was adopted based on v2 feedback and handles both standard and transposed wiring patterns effectively, where manufacturers swap grid/segment relationships: - Standard: digit segments use same grid, different segments - Transposed: digit segments use same segment, different grids It also future-proofs potential irregular wiring patterns where individual digits might have different grid/segment relationships. Unless you have strong objections, I prefer to keep this approach to avoid further churn, as it's proven to handle all the real-world board layouts encountered. See ttps://lore.kernel.org/linux-devicetree/9133F5BC-7F4E-4732-9649-178E5A698273@gmail.com/ >> + minItems: 7 >> + maxItems: 7 >> + >> + required: >> + - reg >> + - segments >> + >> + leds: >> + type: object >> + description: Container for individual LED icon definitions >> + additionalProperties: false >> + >> + properties: >> + "#address-cells": >> + const: 2 >> + "#size-cells": >> + const: 0 >> + >> + patternProperties: >> + "^led@[0-9]+,[0-9]+$": >> + type: object >> + $ref: /schemas/leds/common.yaml# >> + unevaluatedProperties: false >> + >> + properties: >> + reg: >> + description: >> + Grid and segment indices as <grid segment> of this individual LED icon >> + >> + required: >> + - reg >> + >> +allOf: >> + - $ref: /schemas/input/input.yaml# >> + - $ref: /schemas/input/matrix-keymap.yaml# >> + >> +dependencies: >> + poll-interval: >> + - linux,keymap >> + linux,keymap: >> + - poll-interval >> + autorepeat: >> + - linux,keymap >> + - poll-interval >> + >> +# SPI controllers require 3-wire (combined MISO/MOSI line) >> +if: > >Move this under the allOf. > Well received. >> + properties: >> + compatible: >> + contains: >> + enum: >> + - fdhisi,fd620 >> + - fdhisi,fd628 >> + - princeton,pt6964 >> + - titanmec,tm1618 >> + - titanmec,tm1620 >> + - titanmec,tm1628 >> + - titanmec,tm1638 >> + - wxicore,aip1618 >> + - wxicore,aip1628 >> +then: >> + allOf: > >Drop allOf. > Well received. >> + - $ref: /schemas/spi/spi-peripheral-props.yaml# >> + properties: >> + spi-3wire: true > >Drop 'properties' > Well received. >> + required: >> + - spi-3wire >> + >> +required: > >Order should be 'dependencies', 'required', 'allOf'. > I'll reorder the schema sections accordingly. >> + - compatible >> + - reg >> + >> +unevaluatedProperties: false >> + ... >> -- >> 2.43.0 >> Thanks for your time and your feedback, Best Regards Jean-François Lessard
On Mon, Aug 25, 2025 at 09:33:58PM -0400, Jean-François Lessard wrote: > Le 25 août 2025 14 h 26 min 57 s HAE, Rob Herring <robh@kernel.org> a écrit : > >On Sun, Aug 24, 2025 at 11:32:28PM -0400, Jean-François Lessard wrote: > >> Add documentation for TM16xx-compatible 7-segment LED display controllers > >> with keyscan. > >> > >> Signed-off-by: Jean-François Lessard <jefflessard3@gmail.com> > >> --- > >> > >> Notes: > >> The 'segments' property is intentionally not vendor-prefixed as it > >> defines a generic hardware description concept applicable to any > >> 7-segment display controller. The property describes the fundamental > >> grid/segment coordinate mapping that is controller-agnostic and could > >> be reused by other LED matrix display bindings. Similar to how 'gpios' > >> describes GPIO connections generically, 'segments' describes segment > >> connections in a standardized way using uint32-matrix format. > >> > >> .../bindings/auxdisplay/titanmec,tm16xx.yaml | 477 ++++++++++++++++++ > >> MAINTAINERS | 5 + > >> 2 files changed, 482 insertions(+) > >> create mode 100644 Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml > >> > >> diff --git a/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml b/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml > >> new file mode 100644 > >> index 000000000..c94556d95 > >> --- /dev/null > >> +++ b/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml > >> @@ -0,0 +1,477 @@ > >> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) > >> +%YAML 1.2 > >> +--- > >> +$id: http://devicetree.org/schemas/auxdisplay/titanmec,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: | > >> + LED matrix controllers used in auxiliary display devices that drive individual > >> + LED icons and 7-segment digit groups through a grid/segment addressing scheme. > >> + Controllers manage a matrix of LEDs organized as grids (columns/banks in > >> + vendor datasheets) and segments (rows/bit positions in vendor datasheets). > >> + Maximum grid and segment indices are controller-specific. > > In reference to max-brightness, I'll replace with: > > Maximum brightness and grid/segment indices are controller-specific. Controller-specific maximum are validated in the driver. > > >> + > >> + The controller is agnostic of the display layout. Board-specific LED wiring is > >> + described through child nodes that specify grid/segment coordinates for > >> + individual icons and segment mapping for 7-segment digits. > >> + > >> + The bindings use separate 'leds' and 'digits' containers to accommodate > >> + different addressing schemes: > >> + - LEDs use 2-cell addressing (grid, segment) for matrix coordinates > >> + - Digits use 1-cell addressing with explicit segment mapping > >> + > >> + The controller node exposes a logical LED-like control for the aggregate > >> + display brightness. Child nodes describe individual icons and 7-seg digits. > >> + The top-level control supports only label and brightness-related properties > >> + and does not support other common LED properties such as color or function. > >> + Child LED nodes use the standard LED binding. > >> + > >> + Optional keypad scanning is supported when both 'linux,keymap' and > >> + 'poll-interval' properties are specified. > >> + > >> +properties: > >> + compatible: > >> + oneOf: > >> + - items: > >> + - enum: > >> + - fdhisi,fd628 > >> + - princeton,pt6964 > >> + - wxicore,aip1628 > >> + - const: titanmec,tm1628 > >> + - items: > >> + - enum: > >> + - wxicore,aip1618 > >> + - const: titanmec,tm1618 > >> + - items: > >> + - enum: > >> + - fdhisi,fd650 > >> + - wxicore,aip650 > >> + - const: titanmec,tm1650 > >> + - enum: > >> + - fdhisi,fd620 > >> + - fdhisi,fd655 > >> + - fdhisi,fd6551 > >> + - titanmec,tm1618 > >> + - titanmec,tm1620 > >> + - titanmec,tm1628 > >> + - titanmec,tm1638 > >> + - titanmec,tm1650 > >> + - winrise,hbs658 > >> + > >> + reg: > >> + maxItems: 1 > >> + > >> + label: > >> + description: > >> + The label for the top-level LED. If omitted, the label is taken from the > >> + node name (excluding the unit address). It has to uniquely identify a > >> + device, i.e. no other LED class device can be assigned the same label. > >> + $ref: /schemas/leds/common.yaml#/properties/label > >> + > >> + max-brightness: > >> + description: > >> + Normally the maximum brightness is determined by the hardware and this > >> + property is not required. This property is used to put a software limit > >> + on the brightness apart from what the driver says, as it could happen > >> + that a LED can be made so bright that it gets damaged or causes damage > >> + due to restrictions in a specific system, such as mounting conditions. > >> + $ref: /schemas/leds/common.yaml#/properties/max-brightness > > > >These 2 $ref's should be at the node level. The clue is you > >copied-n-pasted the whole description. > > > > I'll add: > > allOf: > - $ref: /schemas/leds/common.yaml# > > at the node level and constrain inapplicable LED properties (color, function) > using properties: false since this auxdisplay device integrates with LED > subsystem for brightness control. > > >What you need here is some constraints. What's the max value? > > > > Maximum brightness varies by controller: > - TM1618/TM1628/TM1638 support levels 0-8 > - TM1650 supports levels 0-8 > - TM1620 supports levels 0-3 > I'll set the schema maximum to 8: > > max-brightness: > maximum: 8 # Maximum across all TM16xx controllers > > with the top-level description note that actual limits are controller-dependent > and are enforced by the driver. > > >> + > >> + default-brightness: > >> + description: > >> + Brightness to be set if LED's default state is on. Used only during > >> + initialization. If the option is not set then max brightness is used. > >> + $ref: /schemas/types.yaml#/definitions/uint32 > > > >This needs to first go into leds/common.yaml. > > > > Given its specific relevance to this auxdisplay use case rather than general LED > behavior, I am not sure it's worth adding default-brightness to LEDs/common.yaml > If broader LED subsystem adoption is wanted, I am willing to submit a separate > patch to this series to add it. > > Otherwise, existing precedent in backlight/common.yaml and leds/leds-pwm.yaml > would advocate for defining it locally. The type for a property should really only be set in 1 place. Otherwise, it is easy to define different types for the same property (which we have and have to deal with some). Given we now have 2 cases for LEDs, it should at least be in leds/common.yaml. Should there be 1 definition for both backlight and LEDs, yes. But I can live with 2 definitions in common bindings for now. > >> + > >> + digits: > >> + type: object > >> + description: Container for 7-segment digit group definitions > >> + additionalProperties: false > >> + > >> + properties: > >> + "#address-cells": > >> + const: 1 > >> + "#size-cells": > >> + const: 0 > >> + > >> + patternProperties: > >> + "^digit@[0-9]+$": > >> + type: object > >> + unevaluatedProperties: false > >> + > >> + properties: > >> + reg: > >> + description: Digit position identifier > > > >Position is right to left (0 on right)? Please clarify. > > > > I'll clarify: digit positions are numbered sequentially left-to-right, > with reg=0 representing the leftmost digit position as displayed to the user. > > >> + maxItems: 1 > >> + > >> + segments: > >> + $ref: /schemas/types.yaml#/definitions/uint32-matrix > >> + description: | > >> + Array of grid/segment coordinate pairs for each 7-segment position. > >> + Each entry is <grid segment> mapping to standard 7-segment positions > >> + in order: a, b, c, d, e, f, g > >> + > >> + Standard 7-segment layout: > >> + aaa > >> + f b > >> + f b > >> + ggg > >> + e c > >> + e c > >> + ddd > >> + items: > >> + items: > >> + - description: Grid index > >> + - description: Segment index > > > >Can't you do an array instead and make the array index be the grid or > >segment index? > > > > Original design was array-based: > - titanmec,digits: array of grid indices > - titanmec,segment-mapping: array of segment indices for a,b,c,d,e,f,g > - titanmec,transposed: boolean for matrix-transposed cases > > The current explicit coordinate approach was adopted based on v2 feedback and > handles both standard and transposed wiring patterns effectively, where > manufacturers swap grid/segment relationships: > - Standard: digit segments use same grid, different segments > - Transposed: digit segments use same segment, different grids > It also future-proofs potential irregular wiring patterns where individual > digits might have different grid/segment relationships. > > Unless you have strong objections, I prefer to keep this approach to avoid > further churn, as it's proven to handle all the real-world board layouts > encountered. 2 arrays would not be an improvement. So leave it as you have it. Rob
Le 29 août 2025 11 h 26 min 13 s HAE, Rob Herring <robh@kernel.org> a écrit : >On Mon, Aug 25, 2025 at 09:33:58PM -0400, Jean-François Lessard wrote: >> Le 25 août 2025 14 h 26 min 57 s HAE, Rob Herring <robh@kernel.org> a écrit : >> >On Sun, Aug 24, 2025 at 11:32:28PM -0400, Jean-François Lessard wrote: >> >> Add documentation for TM16xx-compatible 7-segment LED display controllers >> >> with keyscan. >> >> >> >> Signed-off-by: Jean-François Lessard <jefflessard3@gmail.com> >> >> --- >> >> >> >> Notes: >> >> The 'segments' property is intentionally not vendor-prefixed as it >> >> defines a generic hardware description concept applicable to any >> >> 7-segment display controller. The property describes the fundamental >> >> grid/segment coordinate mapping that is controller-agnostic and could >> >> be reused by other LED matrix display bindings. Similar to how 'gpios' >> >> describes GPIO connections generically, 'segments' describes segment >> >> connections in a standardized way using uint32-matrix format. >> >> >> >> .../bindings/auxdisplay/titanmec,tm16xx.yaml | 477 ++++++++++++++++++ >> >> MAINTAINERS | 5 + >> >> 2 files changed, 482 insertions(+) >> >> create mode 100644 Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml >> >> >> >> diff --git a/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml b/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml >> >> new file mode 100644 >> >> index 000000000..c94556d95 >> >> --- /dev/null >> >> +++ b/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml >> >> @@ -0,0 +1,477 @@ >> >> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) >> >> +%YAML 1.2 >> >> +--- >> >> +$id: http://devicetree.org/schemas/auxdisplay/titanmec,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: | >> >> + LED matrix controllers used in auxiliary display devices that drive individual >> >> + LED icons and 7-segment digit groups through a grid/segment addressing scheme. >> >> + Controllers manage a matrix of LEDs organized as grids (columns/banks in >> >> + vendor datasheets) and segments (rows/bit positions in vendor datasheets). >> >> + Maximum grid and segment indices are controller-specific. >> >> In reference to max-brightness, I'll replace with: >> >> Maximum brightness and grid/segment indices are controller-specific. Controller-specific maximum are validated in the driver. >> >> >> + >> >> + The controller is agnostic of the display layout. Board-specific LED wiring is >> >> + described through child nodes that specify grid/segment coordinates for >> >> + individual icons and segment mapping for 7-segment digits. >> >> + >> >> + The bindings use separate 'leds' and 'digits' containers to accommodate >> >> + different addressing schemes: >> >> + - LEDs use 2-cell addressing (grid, segment) for matrix coordinates >> >> + - Digits use 1-cell addressing with explicit segment mapping >> >> + >> >> + The controller node exposes a logical LED-like control for the aggregate >> >> + display brightness. Child nodes describe individual icons and 7-seg digits. >> >> + The top-level control supports only label and brightness-related properties >> >> + and does not support other common LED properties such as color or function. >> >> + Child LED nodes use the standard LED binding. >> >> + >> >> + Optional keypad scanning is supported when both 'linux,keymap' and >> >> + 'poll-interval' properties are specified. >> >> + >> >> +properties: >> >> + compatible: >> >> + oneOf: >> >> + - items: >> >> + - enum: >> >> + - fdhisi,fd628 >> >> + - princeton,pt6964 >> >> + - wxicore,aip1628 >> >> + - const: titanmec,tm1628 >> >> + - items: >> >> + - enum: >> >> + - wxicore,aip1618 >> >> + - const: titanmec,tm1618 >> >> + - items: >> >> + - enum: >> >> + - fdhisi,fd650 >> >> + - wxicore,aip650 >> >> + - const: titanmec,tm1650 >> >> + - enum: >> >> + - fdhisi,fd620 >> >> + - fdhisi,fd655 >> >> + - fdhisi,fd6551 >> >> + - titanmec,tm1618 >> >> + - titanmec,tm1620 >> >> + - titanmec,tm1628 >> >> + - titanmec,tm1638 >> >> + - titanmec,tm1650 >> >> + - winrise,hbs658 >> >> + >> >> + reg: >> >> + maxItems: 1 >> >> + >> >> + label: >> >> + description: >> >> + The label for the top-level LED. If omitted, the label is taken from the >> >> + node name (excluding the unit address). It has to uniquely identify a >> >> + device, i.e. no other LED class device can be assigned the same label. >> >> + $ref: /schemas/leds/common.yaml#/properties/label >> >> + >> >> + max-brightness: >> >> + description: >> >> + Normally the maximum brightness is determined by the hardware and this >> >> + property is not required. This property is used to put a software limit >> >> + on the brightness apart from what the driver says, as it could happen >> >> + that a LED can be made so bright that it gets damaged or causes damage >> >> + due to restrictions in a specific system, such as mounting conditions. >> >> + $ref: /schemas/leds/common.yaml#/properties/max-brightness >> > >> >These 2 $ref's should be at the node level. The clue is you >> >copied-n-pasted the whole description. >> > >> >> I'll add: >> >> allOf: >> - $ref: /schemas/leds/common.yaml# >> >> at the node level and constrain inapplicable LED properties (color, function) >> using properties: false since this auxdisplay device integrates with LED >> subsystem for brightness control. >> >> >What you need here is some constraints. What's the max value? >> > >> >> Maximum brightness varies by controller: >> - TM1618/TM1628/TM1638 support levels 0-8 >> - TM1650 supports levels 0-8 >> - TM1620 supports levels 0-3 >> I'll set the schema maximum to 8: >> >> max-brightness: >> maximum: 8 # Maximum across all TM16xx controllers >> >> with the top-level description note that actual limits are controller-dependent >> and are enforced by the driver. >> >> >> + >> >> + default-brightness: >> >> + description: >> >> + Brightness to be set if LED's default state is on. Used only during >> >> + initialization. If the option is not set then max brightness is used. >> >> + $ref: /schemas/types.yaml#/definitions/uint32 >> > >> >This needs to first go into leds/common.yaml. >> > >> >> Given its specific relevance to this auxdisplay use case rather than general LED >> behavior, I am not sure it's worth adding default-brightness to LEDs/common.yaml >> If broader LED subsystem adoption is wanted, I am willing to submit a separate >> patch to this series to add it. >> >> Otherwise, existing precedent in backlight/common.yaml and leds/leds-pwm.yaml >> would advocate for defining it locally. > >The type for a property should really only be set in 1 place. Otherwise, >it is easy to define different types for the same property (which we >have and have to deal with some). > >Given we now have 2 cases for LEDs, it should at least be in >leds/common.yaml. Should there be 1 definition for both backlight and >LEDs, yes. But I can live with 2 definitions in common bindings for now. > Understood. I'll add default-brightness definition to leds/common.yaml. >> >> + >> >> + digits: >> >> + type: object >> >> + description: Container for 7-segment digit group definitions >> >> + additionalProperties: false >> >> + >> >> + properties: >> >> + "#address-cells": >> >> + const: 1 >> >> + "#size-cells": >> >> + const: 0 >> >> + >> >> + patternProperties: >> >> + "^digit@[0-9]+$": >> >> + type: object >> >> + unevaluatedProperties: false >> >> + >> >> + properties: >> >> + reg: >> >> + description: Digit position identifier >> > >> >Position is right to left (0 on right)? Please clarify. >> > >> >> I'll clarify: digit positions are numbered sequentially left-to-right, >> with reg=0 representing the leftmost digit position as displayed to the user. >> >> >> + maxItems: 1 >> >> + >> >> + segments: >> >> + $ref: /schemas/types.yaml#/definitions/uint32-matrix >> >> + description: | >> >> + Array of grid/segment coordinate pairs for each 7-segment position. >> >> + Each entry is <grid segment> mapping to standard 7-segment positions >> >> + in order: a, b, c, d, e, f, g >> >> + >> >> + Standard 7-segment layout: >> >> + aaa >> >> + f b >> >> + f b >> >> + ggg >> >> + e c >> >> + e c >> >> + ddd >> >> + items: >> >> + items: >> >> + - description: Grid index >> >> + - description: Segment index >> > >> >Can't you do an array instead and make the array index be the grid or >> >segment index? >> > >> >> Original design was array-based: >> - titanmec,digits: array of grid indices >> - titanmec,segment-mapping: array of segment indices for a,b,c,d,e,f,g >> - titanmec,transposed: boolean for matrix-transposed cases >> >> The current explicit coordinate approach was adopted based on v2 feedback and >> handles both standard and transposed wiring patterns effectively, where >> manufacturers swap grid/segment relationships: >> - Standard: digit segments use same grid, different segments >> - Transposed: digit segments use same segment, different grids >> It also future-proofs potential irregular wiring patterns where individual >> digits might have different grid/segment relationships. >> >> Unless you have strong objections, I prefer to keep this approach to avoid >> further churn, as it's proven to handle all the real-world board layouts >> encountered. > >2 arrays would not be an improvement. So leave it as you have it. > Acknowledged. I'll keep segments as uint32-matrix. Thank you, Jean-François Lessard
Le 25 août 2025 21 h 33 min 58 s HAE, "Jean-François Lessard" <jefflessard3@gmail.com> a écrit :
>Le 25 août 2025 14 h 26 min 57 s HAE, Rob Herring <robh@kernel.org> a écrit :
>>On Sun, Aug 24, 2025 at 11:32:28PM -0400, Jean-François Lessard wrote:
>>> Add documentation for TM16xx-compatible 7-segment LED display controllers
>>> with keyscan.
>>>
>>> Signed-off-by: Jean-François Lessard <jefflessard3@gmail.com>
>>> ---
>>>
...
>>> .../bindings/auxdisplay/titanmec,tm16xx.yaml | 477 ++++++++++++++++++
>>> MAINTAINERS | 5 +
>>> 2 files changed, 482 insertions(+)
>>> create mode 100644 Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml
>>>
>>> diff --git a/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml b/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml
>>> new file mode 100644
>>> index 000000000..c94556d95
>>> --- /dev/null
>>> +++ b/Documentation/devicetree/bindings/auxdisplay/titanmec,tm16xx.yaml
>>> @@ -0,0 +1,477 @@
>>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>>> +%YAML 1.2
>>> +---
>>> +$id: http://devicetree.org/schemas/auxdisplay/titanmec,tm16xx.yaml#
>>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>>> +
>>> +title: Auxiliary displays based on TM16xx and compatible LED controllers
>>> +
...
>>> +
>>> + digits:
>>> + type: object
>>> + description: Container for 7-segment digit group definitions
>>> + additionalProperties: false
>>> +
>>> + properties:
>>> + "#address-cells":
>>> + const: 1
>>> + "#size-cells":
>>> + const: 0
>>> +
>>> + patternProperties:
>>> + "^digit@[0-9]+$":
>>> + type: object
>>> + unevaluatedProperties: false
>>> +
>>> + properties:
>>> + reg:
>>> + description: Digit position identifier
>>
>>Position is right to left (0 on right)? Please clarify.
>>
>
>I'll clarify: digit positions are numbered sequentially left-to-right,
>with reg=0 representing the leftmost digit position as displayed to the user.
>
>>> + maxItems: 1
>>> +
>>> + segments:
>>> + $ref: /schemas/types.yaml#/definitions/uint32-matrix
>>> + description: |
>>> + Array of grid/segment coordinate pairs for each 7-segment position.
>>> + Each entry is <grid segment> mapping to standard 7-segment positions
>>> + in order: a, b, c, d, e, f, g
>>> +
>>> + Standard 7-segment layout:
>>> + aaa
>>> + f b
>>> + f b
>>> + ggg
>>> + e c
>>> + e c
>>> + ddd
>>> + items:
>>> + items:
>>> + - description: Grid index
>>> + - description: Segment index
>>
>>Can't you do an array instead and make the array index be the grid or
>>segment index?
>>
>
>Original design was array-based:
>- titanmec,digits: array of grid indices
>- titanmec,segment-mapping: array of segment indices for a,b,c,d,e,f,g
>- titanmec,transposed: boolean for matrix-transposed cases
>
>The current explicit coordinate approach was adopted based on v2 feedback and
>handles both standard and transposed wiring patterns effectively, where
>manufacturers swap grid/segment relationships:
>- Standard: digit segments use same grid, different segments
>- Transposed: digit segments use same segment, different grids
>It also future-proofs potential irregular wiring patterns where individual
>digits might have different grid/segment relationships.
>
>Unless you have strong objections, I prefer to keep this approach to avoid
>further churn, as it's proven to handle all the real-world board layouts
>encountered.
>
>See
>ttps://lore.kernel.org/linux-devicetree/9133F5BC-7F4E-4732-9649-178E5A698273@gmail.com/
>
Diving deeper on your suggestion of using arrays, would this revised design be
acceptable?
properties:
digits:
patternProperties:
"^digit@[0-9]+$":
properties:
reg:
maxItems: 1
grids:
$ref: /schemas/types.yaml#/definitions/uint32-array
description: Grid indices for segments a,b,c,d,e,f,g in order
minItems: 7
maxItems: 7
segments:
$ref: /schemas/types.yaml#/definitions/uint32-array
description: Segment indices for segments a,b,c,d,e,f,g in order
minItems: 7
maxItems: 7
This approach:
- Uses arrays as you suggested, indexed by segment position
- Maintains flexibility for both standard and transpose layouts
- Keeps the semantic clarity that Krzysztof requested
Example usage would be:
digit@0 {
reg = <0>;
grids = <4 4 4 4 4 4 4>; // Standard: all segments use same grid
segments = <3 4 5 0 1 2 6>; // Different segment indices
};
// vs transpose case:
digit@0 {
reg = <0>;
grids = <0 1 2 3 4 5 6>; // Transpose: different grids
segments = <3 3 3 3 3 3 3>; // Same segment index
};
Would this better align with your preference for array-based approaches?
If so, the remaining question is if these needs to be vendor prefixed
or if they are still generic enough hardware description concept
applicable to any 7-segment display controller.
>>> + minItems: 7
>>> + maxItems: 7
>>> +
>>> + required:
>>> + - reg
>>> + - segments
>>> +
...
Best Regards
Jean-François Lessard
© 2016 - 2025 Red Hat, Inc.