Re: [RFC][DT] Guidance on device tree property prefix for TM16XX-class LED display controllers

Re: [RFC][DT] Guidance on device tree property prefix for TM16XX-class LED display controllers

[Andy Shevchenko]

On Mon, Jun 16, 2025 at 12:05:11PM -0400, Jean-Francois Lessard wrote:
> Hi all,
> 
> I’m working on preparing a new driver and device tree binding for auxiliary
> LED display controllers of the TM16XX class, and I’d like to request
> guidance on property naming conventions before submitting a formal patch
> series.

> The driver (tentatively named tm16xx) supports LED controller chips that
> share a common hardware design and programming model, produced by multiple
> vendors, including:
> 
> Titan Micro Electronics: TM1618, TM1620, TM1628, TM1650
> 
> FUDA HISI Microelectronics: FD620, FD628, FD650, FD655, FD6551
> 
> Princeton Technology Corp: PT6964
> 
> HBS: HBS658
> 
> tm16xx,digits = /bits/ 8 <0 1 2 3>;
> tm16xx,segment-mapping = /bits/ 8 <0 1 2 3 4 5 6>;
> tm16xx,transposed;

I'm not sure I got what the controller is. Is it for 7-segment like display or
is it something else?

Because it might be that LED subsystem is not the best for it to begin with.

-- 
With Best Regards,
Andy Shevchenko

[RFC][DT] Guidance on device tree property prefix for TM16XX-class LED display controllers

[Jean-Francois Lessard]

Hi all,

I’m working on preparing a new driver and device tree binding for
auxiliary LED display controllers of the TM16XX class, and I’d like to
request guidance on property naming conventions before submitting a
formal patch series.

The driver (tentatively named tm16xx) supports LED controller chips
that share a common hardware design and programming model, produced by
multiple vendors, including:
- Titan Micro Electronics: TM1618, TM1620, TM1628, TM1650
- FUDA HISI Microelectronics: FD620, FD628, FD650, FD655, FD6551
- Princeton Technology Corp: PT6964
- HBS: HBS658

These devices are functionally compatible and appear in various
consumer and embedded hardware (e.g., Android TV boxes) to control
both 7-segment displays and custom icons that may look like this:

          ---    ---       ---    ---
 [WIFI]  |   |  |   |  -  |   |  |   |  [USB]  [PLAY]
          ---    ---       ---    ---
 [LAN]   |   |  |   |  -  |   |  |   |  [BT]   [PAUSE]
          ---    ---       ---    ---

My current binding defines properties describing hardware layout, for example:

    tm16xx,digits = /bits/ 8 <0 1 2 3>;
    tm16xx,segment-mapping = /bits/ 8 <0 1 2 3 4 5 6>;
    tm16xx,transposed;

These describe hardware characteristics (grid/digit arrangement,
segment mapping, transposed display output) that apply to this class
of compatible hardware, regardless of vendor.

My question: Given that these properties describe a common hardware
class (rather than a specific vendor design or generic LED display
behavior), what is the preferred naming convention?

1. Should I retain a prefix like tm16xx, to represent this hardware
class (as it is the most recognized functional family name)?

2. Should I instead pick an original vendor’s prefix (e.g., titanmec,)
even though other vendors produce compatible chips?

3. Is there another convention recommended for hardware classes
produced by multiple vendors with compatible designs?

I want to ensure that the binding follows the preferred conventions
for upstream acceptance and clean DT design.

Any guidance or suggestions would be greatly appreciated!

Best regards,
Jean-François Lessard
jefflessard3@gmail.com

Re: [RFC][DT] Guidance on device tree property prefix for TM16XX-class LED display controllers

[Andy Shevchenko]

On Mon, Jun 16, 2025 at 11:06 PM Jean-Francois Lessard
<jefflessard3@gmail.com> wrote:
>
> Hi all,
>
> I’m working on preparing a new driver and device tree binding for
> auxiliary LED display controllers of the TM16XX class, and I’d like to
> request guidance on property naming conventions before submitting a
> formal patch series.
>
> The driver (tentatively named tm16xx) supports LED controller chips
> that share a common hardware design and programming model, produced by
> multiple vendors, including:
> - Titan Micro Electronics: TM1618, TM1620, TM1628, TM1650
> - FUDA HISI Microelectronics: FD620, FD628, FD650, FD655, FD6551
> - Princeton Technology Corp: PT6964
> - HBS: HBS658
>
> These devices are functionally compatible and appear in various
> consumer and embedded hardware (e.g., Android TV boxes) to control
> both 7-segment displays and custom icons that may look like this:
>
>           ---    ---       ---    ---
>  [WIFI]  |   |  |   |  -  |   |  |   |  [USB]  [PLAY]
>           ---    ---       ---    ---
>  [LAN]   |   |  |   |  -  |   |  |   |  [BT]   [PAUSE]
>           ---    ---       ---    ---

So, have you looked at auxdisplay subsystem? It's mostly for 7-segment
displays and has some common libraries (and interfaces) for that.

> My current binding defines properties describing hardware layout, for example:
>
>     tm16xx,digits = /bits/ 8 <0 1 2 3>;
>     tm16xx,segment-mapping = /bits/ 8 <0 1 2 3 4 5 6>;
>     tm16xx,transposed;
>
> These describe hardware characteristics (grid/digit arrangement,
> segment mapping, transposed display output) that apply to this class
> of compatible hardware, regardless of vendor.
>
> My question: Given that these properties describe a common hardware
> class (rather than a specific vendor design or generic LED display
> behavior), what is the preferred naming convention?

Naming for the vendor or for the properties? With applying it to
auxdisplay, some of the properties will be available without vendor
prefix.

> 1. Should I retain a prefix like tm16xx, to represent this hardware
> class (as it is the most recognized functional family name)?
>
> 2. Should I instead pick an original vendor’s prefix (e.g., titanmec,)
> even though other vendors produce compatible chips?
>
> 3. Is there another convention recommended for hardware classes
> produced by multiple vendors with compatible designs?
>
> I want to ensure that the binding follows the preferred conventions
> for upstream acceptance and clean DT design.
>
> Any guidance or suggestions would be greatly appreciated!

The rest we can discuss when we see patches, I think.

-- 
With Best Regards,
Andy Shevchenko

Re: [RFC][DT] Guidance on device tree property prefix for TM16XX-class LED display controllers

[Jean-Francois Lessard]

> So, have you looked at auxdisplay subsystem? It's mostly for 7-segment
> displays and has some common libraries (and interfaces) for that.

Yes, I’ve looked at the auxdisplay subsystem; that’s what I’m
targeting. While these chips are LED controllers, in practice they’re
used by device manufacturers as auxiliary displays. I’ve implemented
7-segment mapping using map_to_7segment.h as recommended, including
exposing map_seg7 via DEVICE_ATTR.

> Naming for the vendor or for the properties? With applying it to
> auxdisplay, some of the properties will be available without vendor
> prefix.

Regarding the property prefix: I meant the prefix for the properties.
I didn’t find any existing auxdisplay properties that apply directly.
The closest is segment-gpios, which doesn’t match this hardware. My
understanding was that only generic properties (e.g., segment-gpios)
go without a prefix, and that hardware-specific ones should have a
vendor or class prefix. Is the preference within auxdisplay to drop
prefixes even for properties that describe specific hardware
characteristics (like digit grid or segment indices)?

> The rest we can discuss when we see patches, I think.

Any guidance on this before I prepare patches would be very helpful.

FYI you can find the current draft of the driver and binding at:
https://github.com/jefflessard/tm16xx-display
(README.md, tm16xx.c, and
Documentation/devicetree/bindings/auxdisplay/tm16xx.yaml)
I’ll be happy to send proper patches once I know the direction for the
property naming.

Thanks again for your time.

Le lun. 16 juin 2025, 16 h 27, Andy Shevchenko
<andy.shevchenko@gmail.com> a écrit :
>
> On Mon, Jun 16, 2025 at 11:06 PM Jean-Francois Lessard
> <jefflessard3@gmail.com> wrote:
> >
> > Hi all,
> >
> > I’m working on preparing a new driver and device tree binding for
> > auxiliary LED display controllers of the TM16XX class, and I’d like to
> > request guidance on property naming conventions before submitting a
> > formal patch series.
> >
> > The driver (tentatively named tm16xx) supports LED controller chips
> > that share a common hardware design and programming model, produced by
> > multiple vendors, including:
> > - Titan Micro Electronics: TM1618, TM1620, TM1628, TM1650
> > - FUDA HISI Microelectronics: FD620, FD628, FD650, FD655, FD6551
> > - Princeton Technology Corp: PT6964
> > - HBS: HBS658
> >
> > These devices are functionally compatible and appear in various
> > consumer and embedded hardware (e.g., Android TV boxes) to control
> > both 7-segment displays and custom icons that may look like this:
> >
> >           ---    ---       ---    ---
> >  [WIFI]  |   |  |   |  -  |   |  |   |  [USB]  [PLAY]
> >           ---    ---       ---    ---
> >  [LAN]   |   |  |   |  -  |   |  |   |  [BT]   [PAUSE]
> >           ---    ---       ---    ---
>
> So, have you looked at auxdisplay subsystem? It's mostly for 7-segment
> displays and has some common libraries (and interfaces) for that.
>
> > My current binding defines properties describing hardware layout, for example:
> >
> >     tm16xx,digits = /bits/ 8 <0 1 2 3>;
> >     tm16xx,segment-mapping = /bits/ 8 <0 1 2 3 4 5 6>;
> >     tm16xx,transposed;
> >
> > These describe hardware characteristics (grid/digit arrangement,
> > segment mapping, transposed display output) that apply to this class
> > of compatible hardware, regardless of vendor.
> >
> > My question: Given that these properties describe a common hardware
> > class (rather than a specific vendor design or generic LED display
> > behavior), what is the preferred naming convention?
>
> Naming for the vendor or for the properties? With applying it to
> auxdisplay, some of the properties will be available without vendor
> prefix.
>
> > 1. Should I retain a prefix like tm16xx, to represent this hardware
> > class (as it is the most recognized functional family name)?
> >
> > 2. Should I instead pick an original vendor’s prefix (e.g., titanmec,)
> > even though other vendors produce compatible chips?
> >
> > 3. Is there another convention recommended for hardware classes
> > produced by multiple vendors with compatible designs?
> >
> > I want to ensure that the binding follows the preferred conventions
> > for upstream acceptance and clean DT design.
> >
> > Any guidance or suggestions would be greatly appreciated!
>
> The rest we can discuss when we see patches, I think.
>
> --
> With Best Regards,
> Andy Shevchenko

Re: [RFC][DT] Guidance on device tree property prefix for TM16XX-class LED display controllers

[Geert Uytterhoeven]

Hi Jean-Francois,

On Mon, 16 Jun 2025 at 22:06, Jean-Francois Lessard
<jefflessard3@gmail.com> wrote:
> I’m working on preparing a new driver and device tree binding for
> auxiliary LED display controllers of the TM16XX class, and I’d like to
> request guidance on property naming conventions before submitting a
> formal patch series.
>
> The driver (tentatively named tm16xx) supports LED controller chips
> that share a common hardware design and programming model, produced by
> multiple vendors, including:
> - Titan Micro Electronics: TM1618, TM1620, TM1628, TM1650
> - FUDA HISI Microelectronics: FD620, FD628, FD650, FD655, FD6551
> - Princeton Technology Corp: PT6964
> - HBS: HBS658
>
> These devices are functionally compatible and appear in various
> consumer and embedded hardware (e.g., Android TV boxes) to control
> both 7-segment displays and custom icons that may look like this:
>
>           ---    ---       ---    ---
>  [WIFI]  |   |  |   |  -  |   |  |   |  [USB]  [PLAY]
>           ---    ---       ---    ---
>  [LAN]   |   |  |   |  -  |   |  |   |  [BT]   [PAUSE]
>           ---    ---       ---    ---
>
> My current binding defines properties describing hardware layout, for example:
>
>     tm16xx,digits = /bits/ 8 <0 1 2 3>;
>     tm16xx,segment-mapping = /bits/ 8 <0 1 2 3 4 5 6>;
>     tm16xx,transposed;
>
> These describe hardware characteristics (grid/digit arrangement,
> segment mapping, transposed display output) that apply to this class
> of compatible hardware, regardless of vendor.

Personally, I am a bit reluctant to try to describe the segment mapping
in DT, as it can become rather cumbersome.  The alternative is to use
a device-specific compatible value, and put the mapping in the driver,
like I did for the Adafruit 7 and 14 segment Featherwing displays in
drivers/auxdisplay/ht16k33.c.

Gr{oetje,eeting}s,

                        Geert

-- 
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [RFC][DT] Guidance on device tree property prefix for TM16XX-class LED display controllers

[Andy Shevchenko]

On Tue, Jun 17, 2025 at 12:43 PM Geert Uytterhoeven
<geert@linux-m68k.org> wrote:
> On Mon, 16 Jun 2025 at 22:06, Jean-Francois Lessard
> <jefflessard3@gmail.com> wrote:

> > I’m working on preparing a new driver and device tree binding for
> > auxiliary LED display controllers of the TM16XX class, and I’d like to
> > request guidance on property naming conventions before submitting a
> > formal patch series.
> >
> > The driver (tentatively named tm16xx) supports LED controller chips
> > that share a common hardware design and programming model, produced by
> > multiple vendors, including:
> > - Titan Micro Electronics: TM1618, TM1620, TM1628, TM1650
> > - FUDA HISI Microelectronics: FD620, FD628, FD650, FD655, FD6551
> > - Princeton Technology Corp: PT6964
> > - HBS: HBS658
> >
> > These devices are functionally compatible and appear in various
> > consumer and embedded hardware (e.g., Android TV boxes) to control
> > both 7-segment displays and custom icons that may look like this:
> >
> >           ---    ---       ---    ---
> >  [WIFI]  |   |  |   |  -  |   |  |   |  [USB]  [PLAY]
> >           ---    ---       ---    ---
> >  [LAN]   |   |  |   |  -  |   |  |   |  [BT]   [PAUSE]
> >           ---    ---       ---    ---
> >
> > My current binding defines properties describing hardware layout, for example:
> >
> >     tm16xx,digits = /bits/ 8 <0 1 2 3>;
> >     tm16xx,segment-mapping = /bits/ 8 <0 1 2 3 4 5 6>;
> >     tm16xx,transposed;
> >
> > These describe hardware characteristics (grid/digit arrangement,
> > segment mapping, transposed display output) that apply to this class
> > of compatible hardware, regardless of vendor.
>
> Personally, I am a bit reluctant to try to describe the segment mapping
> in DT, as it can become rather cumbersome.

Yes, the segment mapping is implied already by the mapping table for
the characters and...

> The alternative is to use
> a device-specific compatible value, and put the mapping in the driver,
> like I did for the Adafruit 7 and 14 segment Featherwing displays in
> drivers/auxdisplay/ht16k33.c.

...as Geert said, if required, can be bound to the compatible string
and hardcoded in the driver.

The problem is, that often segment mapping is PCB level of the wiring
and to be honest I dunno how to distinguish such a scenario easily as
one would need to check compatible string for the component _and_ for
the board.

-- 
With Best Regards,
Andy Shevchenko

Re: [RFC][DT] Guidance on device tree property prefix for TM16XX-class LED display controllers

[Jean-Francois Lessard]

Hi Andy, hi Geert,

Thank you both for your feedback, it’s much appreciated. I’d like to
clarify a few points that I hope will help explain the design choice
behind the proposed DT properties.

While these LED controllers are related to traditional 7-segment
displays, what I’m trying to describe in DT is somewhat distinct. The
controllers manage a grid (matrix) of outputs, where “grids” represent
rows and “segments” represent columns. This follows the terminology
used in the controller datasheets. The 'segment-mapping' property is
not about logical digit-to-segment mappings (which the driver handles
through 'map_to_7segment.h' and similar helpers), but about the
physical wiring between the controller’s matrix outputs and the actual
display elements on a specific board.

In other words, these properties describe board-specific hardware
wiring: how the controller’s generic matrix connects to the
manufacturer’s particular display layout. This varies significantly
between devices. Some boards wire grids to digits and segments to
segments; others wire grids or segments to icons. Some even transpose
the matrix so that grids drive segments and segments drive digits.
That’s why I proposed the optional 'transposed' property to switch the
matrix rows and columns in software to match the board’s wiring.

Importantly, the 'compatible' string already maps to the specific
controller type and its protocol, but it can’t capture the board-level
wiring configuration. The same controller model is reused in many
different boards with different wiring. For example, across 74 display
configurations I’ve looked at, there are 39 distinct combinations of
controller type, digit grids, segment mappings, and icon assignments.
There’s no standard wiring for a given controller chip that the driver
could infer from 'compatible' alone.

That’s why I felt it was appropriate to describe this board-specific
wiring in DT, keeping the driver generic and agnostic of any
particular board layout, while letting each board describe its wiring
explicitly.

I hope this clarifies the motivation. I want to make sure this
approach aligns with upstream expectations before preparing formal
patches. Please let me know if this seems like a reasonable direction
or if you’d recommend a different solution.

Thanks again for your time and guidance.

Best regards,
Jean-François

On Tue, Jun 17, 2025 at 7:58 AM Andy Shevchenko
<andy.shevchenko@gmail.com> wrote:
>
> On Tue, Jun 17, 2025 at 12:43 PM Geert Uytterhoeven
> <geert@linux-m68k.org> wrote:
> > On Mon, 16 Jun 2025 at 22:06, Jean-Francois Lessard
> > <jefflessard3@gmail.com> wrote:
>
> > > I’m working on preparing a new driver and device tree binding for
> > > auxiliary LED display controllers of the TM16XX class, and I’d like to
> > > request guidance on property naming conventions before submitting a
> > > formal patch series.
> > >
> > > The driver (tentatively named tm16xx) supports LED controller chips
> > > that share a common hardware design and programming model, produced by
> > > multiple vendors, including:
> > > - Titan Micro Electronics: TM1618, TM1620, TM1628, TM1650
> > > - FUDA HISI Microelectronics: FD620, FD628, FD650, FD655, FD6551
> > > - Princeton Technology Corp: PT6964
> > > - HBS: HBS658
> > >
> > > These devices are functionally compatible and appear in various
> > > consumer and embedded hardware (e.g., Android TV boxes) to control
> > > both 7-segment displays and custom icons that may look like this:
> > >
> > >           ---    ---       ---    ---
> > >  [WIFI]  |   |  |   |  -  |   |  |   |  [USB]  [PLAY]
> > >           ---    ---       ---    ---
> > >  [LAN]   |   |  |   |  -  |   |  |   |  [BT]   [PAUSE]
> > >           ---    ---       ---    ---
> > >
> > > My current binding defines properties describing hardware layout, for example:
> > >
> > >     tm16xx,digits = /bits/ 8 <0 1 2 3>;
> > >     tm16xx,segment-mapping = /bits/ 8 <0 1 2 3 4 5 6>;
> > >     tm16xx,transposed;
> > >
> > > These describe hardware characteristics (grid/digit arrangement,
> > > segment mapping, transposed display output) that apply to this class
> > > of compatible hardware, regardless of vendor.
> >
> > Personally, I am a bit reluctant to try to describe the segment mapping
> > in DT, as it can become rather cumbersome.
>
> Yes, the segment mapping is implied already by the mapping table for
> the characters and...
>
> > The alternative is to use
> > a device-specific compatible value, and put the mapping in the driver,
> > like I did for the Adafruit 7 and 14 segment Featherwing displays in
> > drivers/auxdisplay/ht16k33.c.
>
> ...as Geert said, if required, can be bound to the compatible string
> and hardcoded in the driver.
>
> The problem is, that often segment mapping is PCB level of the wiring
> and to be honest I dunno how to distinguish such a scenario easily as
> one would need to check compatible string for the component _and_ for
> the board.
>
> --
> With Best Regards,
> Andy Shevchenko

Re: [RFC][DT] Guidance on device tree property prefix for TM16XX-class LED display controllers

[Andy Shevchenko]

On Tue, Jun 17, 2025 at 4:39 PM Jean-Francois Lessard
<jefflessard3@gmail.com> wrote:

Please, stop top-posting!

> Thank you both for your feedback, it’s much appreciated. I’d like to
> clarify a few points that I hope will help explain the design choice
> behind the proposed DT properties.
>
> While these LED controllers are related to traditional 7-segment
> displays, what I’m trying to describe in DT is somewhat distinct. The
> controllers manage a grid (matrix) of outputs, where “grids” represent
> rows and “segments” represent columns. This follows the terminology
> used in the controller datasheets. The 'segment-mapping' property is
> not about logical digit-to-segment mappings (which the driver handles
> through 'map_to_7segment.h' and similar helpers), but about the
> physical wiring between the controller’s matrix outputs and the actual
> display elements on a specific board.
>
> In other words, these properties describe board-specific hardware
> wiring: how the controller’s generic matrix connects to the
> manufacturer’s particular display layout. This varies significantly
> between devices. Some boards wire grids to digits and segments to
> segments; others wire grids or segments to icons. Some even transpose
> the matrix so that grids drive segments and segments drive digits.
> That’s why I proposed the optional 'transposed' property to switch the
> matrix rows and columns in software to match the board’s wiring.
>
> Importantly, the 'compatible' string already maps to the specific
> controller type and its protocol, but it can’t capture the board-level
> wiring configuration. The same controller model is reused in many
> different boards with different wiring. For example, across 74 display
> configurations I’ve looked at, there are 39 distinct combinations of
> controller type, digit grids, segment mappings, and icon assignments.
> There’s no standard wiring for a given controller chip that the driver
> could infer from 'compatible' alone.
>
> That’s why I felt it was appropriate to describe this board-specific
> wiring in DT, keeping the driver generic and agnostic of any
> particular board layout, while letting each board describe its wiring
> explicitly.
>
> I hope this clarifies the motivation. I want to make sure this
> approach aligns with upstream expectations before preparing formal
> patches. Please let me know if this seems like a reasonable direction
> or if you’d recommend a different solution.
>
> Thanks again for your time and guidance.

You need to talk to the DT people for this. I'm not an expert, but as
I said it feels (and you confirmed it) as PCB level of the
description. I believe it may be part of DT, but I can't tell you how.

> On Tue, Jun 17, 2025 at 7:58 AM Andy Shevchenko
> <andy.shevchenko@gmail.com> wrote:
> >
> > On Tue, Jun 17, 2025 at 12:43 PM Geert Uytterhoeven
> > <geert@linux-m68k.org> wrote:
> > > On Mon, 16 Jun 2025 at 22:06, Jean-Francois Lessard
> > > <jefflessard3@gmail.com> wrote:
> >
> > > > I’m working on preparing a new driver and device tree binding for
> > > > auxiliary LED display controllers of the TM16XX class, and I’d like to
> > > > request guidance on property naming conventions before submitting a
> > > > formal patch series.
> > > >
> > > > The driver (tentatively named tm16xx) supports LED controller chips
> > > > that share a common hardware design and programming model, produced by
> > > > multiple vendors, including:
> > > > - Titan Micro Electronics: TM1618, TM1620, TM1628, TM1650
> > > > - FUDA HISI Microelectronics: FD620, FD628, FD650, FD655, FD6551
> > > > - Princeton Technology Corp: PT6964
> > > > - HBS: HBS658
> > > >
> > > > These devices are functionally compatible and appear in various
> > > > consumer and embedded hardware (e.g., Android TV boxes) to control
> > > > both 7-segment displays and custom icons that may look like this:
> > > >
> > > >           ---    ---       ---    ---
> > > >  [WIFI]  |   |  |   |  -  |   |  |   |  [USB]  [PLAY]
> > > >           ---    ---       ---    ---
> > > >  [LAN]   |   |  |   |  -  |   |  |   |  [BT]   [PAUSE]
> > > >           ---    ---       ---    ---
> > > >
> > > > My current binding defines properties describing hardware layout, for example:
> > > >
> > > >     tm16xx,digits = /bits/ 8 <0 1 2 3>;
> > > >     tm16xx,segment-mapping = /bits/ 8 <0 1 2 3 4 5 6>;
> > > >     tm16xx,transposed;
> > > >
> > > > These describe hardware characteristics (grid/digit arrangement,
> > > > segment mapping, transposed display output) that apply to this class
> > > > of compatible hardware, regardless of vendor.
> > >
> > > Personally, I am a bit reluctant to try to describe the segment mapping
> > > in DT, as it can become rather cumbersome.
> >
> > Yes, the segment mapping is implied already by the mapping table for
> > the characters and...
> >
> > > The alternative is to use
> > > a device-specific compatible value, and put the mapping in the driver,
> > > like I did for the Adafruit 7 and 14 segment Featherwing displays in
> > > drivers/auxdisplay/ht16k33.c.
> >
> > ...as Geert said, if required, can be bound to the compatible string
> > and hardcoded in the driver.
> >
> > The problem is, that often segment mapping is PCB level of the wiring
> > and to be honest I dunno how to distinguish such a scenario easily as
> > one would need to check compatible string for the component _and_ for
> > the board.

-- 
With Best Regards,
Andy Shevchenko

Re: [RFC][DT] Guidance on device tree property prefix for TM16XX-class LED display controllers

[Jean-Francois Lessard]

On Tue, Jun 17, 2025 at 2:41 PM Andy Shevchenko
<andy.shevchenko@gmail.com> wrote:
>
> On Tue, Jun 17, 2025 at 4:39 PM Jean-Francois Lessard
> <jefflessard3@gmail.com> wrote:
>
> Please, stop top-posting!

Well received!

>
> > Thank you both for your feedback, it’s much appreciated. I’d like to
> > clarify a few points that I hope will help explain the design choice
> > behind the proposed DT properties.
> >
> > While these LED controllers are related to traditional 7-segment
> > displays, what I’m trying to describe in DT is somewhat distinct. The
> > controllers manage a grid (matrix) of outputs, where “grids” represent
> > rows and “segments” represent columns. This follows the terminology
> > used in the controller datasheets. The 'segment-mapping' property is
> > not about logical digit-to-segment mappings (which the driver handles
> > through 'map_to_7segment.h' and similar helpers), but about the
> > physical wiring between the controller’s matrix outputs and the actual
> > display elements on a specific board.
> >
> > In other words, these properties describe board-specific hardware
> > wiring: how the controller’s generic matrix connects to the
> > manufacturer’s particular display layout. This varies significantly
> > between devices. Some boards wire grids to digits and segments to
> > segments; others wire grids or segments to icons. Some even transpose
> > the matrix so that grids drive segments and segments drive digits.
> > That’s why I proposed the optional 'transposed' property to switch the
> > matrix rows and columns in software to match the board’s wiring.
> >
> > Importantly, the 'compatible' string already maps to the specific
> > controller type and its protocol, but it can’t capture the board-level
> > wiring configuration. The same controller model is reused in many
> > different boards with different wiring. For example, across 74 display
> > configurations I’ve looked at, there are 39 distinct combinations of
> > controller type, digit grids, segment mappings, and icon assignments.
> > There’s no standard wiring for a given controller chip that the driver
> > could infer from 'compatible' alone.
> >
> > That’s why I felt it was appropriate to describe this board-specific
> > wiring in DT, keeping the driver generic and agnostic of any
> > particular board layout, while letting each board describe its wiring
> > explicitly.
> >
> > I hope this clarifies the motivation. I want to make sure this
> > approach aligns with upstream expectations before preparing formal
> > patches. Please let me know if this seems like a reasonable direction
> > or if you’d recommend a different solution.
> >
> > Thanks again for your time and guidance.
>
> You need to talk to the DT people for this. I'm not an expert, but as
> I said it feels (and you confirmed it) as PCB level of the
> description. I believe it may be part of DT, but I can't tell you how.
>

Thank you Andy for clarifying. Since this question was originally sent
to the devicetree list (with [DT] marker in subject and DT maintainers
subscribed), I’d like to kindly follow up to ask if any DT maintainers
could provide guidance.

Patch for guidance below:
[PATCH] dt-bindings: auxdisplay: Add TM16xx family LED controller bindings

Signed-off-by: Jean-François Lessard <jefflessard3@gmail.com>
---
 .../bindings/auxdisplay/tm16xx.yaml           | 150 ++++++++++++++++++
 1 file changed, 150 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 0000000..f3d411f
--- /dev/null
+++ b/Documentation/devicetree/bindings/auxdisplay/tm16xx.yaml
@@ -0,0 +1,150 @@
+# 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
+      - princeton,pt6964
+      - hbs,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 Tue, Jun 17, 2025 at 7:58 AM Andy Shevchenko
> > <andy.shevchenko@gmail.com> wrote:
> > >
> > > On Tue, Jun 17, 2025 at 12:43 PM Geert Uytterhoeven
> > > <geert@linux-m68k.org> wrote:
> > > > On Mon, 16 Jun 2025 at 22:06, Jean-Francois Lessard
> > > > <jefflessard3@gmail.com> wrote:
> > >
> > > > > I’m working on preparing a new driver and device tree binding for
> > > > > auxiliary LED display controllers of the TM16XX class, and I’d like to
> > > > > request guidance on property naming conventions before submitting a
> > > > > formal patch series.
> > > > >
> > > > > The driver (tentatively named tm16xx) supports LED controller chips
> > > > > that share a common hardware design and programming model, produced by
> > > > > multiple vendors, including:
> > > > > - Titan Micro Electronics: TM1618, TM1620, TM1628, TM1650
> > > > > - FUDA HISI Microelectronics: FD620, FD628, FD650, FD655, FD6551
> > > > > - Princeton Technology Corp: PT6964
> > > > > - HBS: HBS658
> > > > >
> > > > > These devices are functionally compatible and appear in various
> > > > > consumer and embedded hardware (e.g., Android TV boxes) to control
> > > > > both 7-segment displays and custom icons that may look like this:
> > > > >
> > > > >           ---    ---       ---    ---
> > > > >  [WIFI]  |   |  |   |  -  |   |  |   |  [USB]  [PLAY]
> > > > >           ---    ---       ---    ---
> > > > >  [LAN]   |   |  |   |  -  |   |  |   |  [BT]   [PAUSE]
> > > > >           ---    ---       ---    ---
> > > > >
> > > > > My current binding defines properties describing hardware layout, for example:
> > > > >
> > > > >     tm16xx,digits = /bits/ 8 <0 1 2 3>;
> > > > >     tm16xx,segment-mapping = /bits/ 8 <0 1 2 3 4 5 6>;
> > > > >     tm16xx,transposed;
> > > > >
> > > > > These describe hardware characteristics (grid/digit arrangement,
> > > > > segment mapping, transposed display output) that apply to this class
> > > > > of compatible hardware, regardless of vendor.
> > > >
> > > > Personally, I am a bit reluctant to try to describe the segment mapping
> > > > in DT, as it can become rather cumbersome.
> > >
> > > Yes, the segment mapping is implied already by the mapping table for
> > > the characters and...
> > >
> > > > The alternative is to use
> > > > a device-specific compatible value, and put the mapping in the driver,
> > > > like I did for the Adafruit 7 and 14 segment Featherwing displays in
> > > > drivers/auxdisplay/ht16k33.c.
> > >
> > > ...as Geert said, if required, can be bound to the compatible string
> > > and hardcoded in the driver.
> > >
> > > The problem is, that often segment mapping is PCB level of the wiring
> > > and to be honest I dunno how to distinguish such a scenario easily as
> > > one would need to check compatible string for the component _and_ for
> > > the board.
>
> --
> With Best Regards,
> Andy Shevchenko