Improve naming of common code and configuration for ADSP DSPs

[pamolloy]

At ADI, we are trying to mainline support for our DSP SoCs. Starting with the single Cortex-A55 ADSP-SC598. Note the SC* stands for SHARC Connect, where SHARC is the DSP core architecture.

Unfortunately, the SoC part naming is somewhat complicated:

https://analogdevicesinc.github.io/documentation/products/adsp/index.html#id1

For example, SC57x, SC58x, SC592 and SC594 are 32-bit, while SC596 and SC598 are 64-bit. An unreleased SoC will be very similar to the SC598, but does not follow the SC5xxx pattern as it uses a different digit instead of the 5.

We're considering the following options:

1. adsp-sc: A generic prefix representing the "SHARC Connect" family (e.g. drivers/clk/adi/clk-adsp-sc.c, compatible = "adi,adsp-sc-uart")
2. sc5xx: Sticking with the current prefix, even for the 8-series chips, as one would for a driver
3. scxxx: Using 'xxx' as a wildcard for the 3-digit model series
4. adsp-scxxx: Perhaps the most accurate option, but rather long for a prefix

Feel free to take a look at our tree, but note there is a lot of work to do before submission:

https://github.com/analogdevicesinc/linux/commits/adsp-6.12.0-y/

We already have support mainline in U-Boot.[1] And expect to have to update it accordingly. In U-Boot it is a bit easier because there isn't the same distinction between arm and arm64.

https://lore.kernel.org/linux-arch/Vz-23fFGsZWIiHL9un3f6bosyPElJf6hnyRM6QOsbT3p4xWpTcncCn9hIa_JmHSR47ZbJD8fTQGdhIermxH2GV4p1dxTdmt2CzKCCsuMbrE=@philipmolloy.com/

[sipraga]

I had a go at drafting some rules, just to get the ball rolling a bit on this. See below (sorry about the formatting).

I'm not 100% sure everything makes perfect sense but feel free to comment.

1 Naming drivers and their compatible strings
═════════════════════════════════════════════

  Axioms:

  • The family is called ADSP
  • The SoCs in the family generally have the same compatible
    peripherals


1.1 Driver names
────────────────

  Solution: Name drivers adsp-xxx, where xxx is the general
  function. Examples:

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   peripheral         driver name  
  ─────────────────────────────────
   PORT pinctrl+gpio  adsp-pinctrl 
   TRU                adsp-tru     
   SPORT              adsp-sport   
   SPI                adsp-spi     
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  etc. - with the caveat that some subsystems want naming to follow a
  slightly different convention. The point here is not to encode SCxxx
  at all. The family is ADSP. Even on the non-SC ADSP variants, the
  peripherals are the same.


2 Compatible strings
════════════════════

  Within each compatible family there are often a few SoC part names,
  e.g. SC596 and SC598. The driver doesn't *need* to have a compatible
  string for each of them if they truly are compatible.

  Solution: Pick *one* SoC part number which covers N compatible
  peripherals. Always use this one. The name doesn't matter, but it's
  helpful if it's always the same one. SC598 seems more common than
  SC596, so it's chosen for us. Now we proceed.

  Examples:

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   peripheral         compatible             
  ───────────────────────────────────────────
   PORT pinctrl+gpio  adi,adsp-sc598-pinctrl 
   TRU                adi,adsp-sc598-tru     
   SPORT              adi,adsp-sc598-sport   
   SPI                adi,adsp-sc598-spi     
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Question: Isn't it weird that now adsp-sc596 has compatible =
  "adi,adsp-sc598-tru"?

  Answer: No, why would it be? The hardware is compatible. There is no
  need for a second compatible string. You actually see this all the
  time.


2.1 Top-level compatible strings
────────────────────────────────

  Here we talk about / { compatible = "aaa", "bbb", "ccc"; }

  In this case, aaa should be as specific as possible. Basically
  matching the device tree filename below.

  Optionally "bbb", "ccc" can describe less specific things.

  Example:

  compatible = "adi,adsp-sc598-ezkit", "adi,adsp-sc598-som",
  "adi,adsp-sc598";

  Don't use "adi,adsp-sc5xx" or "adi,adsp-sc59x", as these aren't
  specific enough. If two sc59x's are compatible, then use one
  instance. See the general advice for compatible strings.


3 Device tree filenames
═══════════════════════

3.1 Naming SoC family-level device trees
────────────────────────────────────────

  Axioms:

  • The device tree name should refer to the family as informatively as
    possible
  • The device tree name should remain succinct
  • The device tree name should rely on disambiguation based on its file
    path in Linux

  SC596 and SC598 are essentially the same. Their device trees live in
  arch/arm64/boot/dts, so we already know it's the 64-bit variant. No
  need to disambiguate with SC59x SoCs with the A5 (32-bit).

  So what's different? Actually not much. Just the number of SHARC cores
  (1 or 2 respectively). SHARC core frequency also varies, but at a more
  granular level, and we don't care about it.

  Solution:

  adsp-sc59x.dtsi

  Inside it can set status = "disabled" for the 2nd SHARC core. For
  SC598 which has it, adsp-sc598.dtsi can #include and set status =
  "okay".


3.1.1 A new SoC has come out and it's basically an SC598 but with, say, a different CPU, and it's called SC999
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

  OK. You could split out the peripherals for SC59x into a file
  adsp-sc59x-peri.dtsi. Then include it in the SoC(-family) level device
  tree, define the CPU, and follow the rest of the rules
  here. adsp-sc999.dtsi including adsp-sc59x-peri.dtsi is fine, and
  actually quite informative. The reader can deduce that it's all the
  same except for what's not.


3.2 Naming SoC-level device trees
─────────────────────────────────

  Here it's pretty obvious.

  SC598 -> adsp-sc598.dtsi


3.3 Naming SoM-level device trees
─────────────────────────────────

  Axioms:

  • The device tree name should refer to the exact hardware it is
    running on
  • The device tree name should include reference to the SoC it uses

  Here it's simple.

  SCxxx-SOM -> adsp-scxxx-som.dtsi

  Where xxx is substituted for the actual number. e.g.

  SC598-SOM -> adsp-sc598-som.dtsi


3.4 Naming top-level device trees
─────────────────────────────────

  Axioms:

  • The device tree name should refer to the exact hardware it is
    running on
  • The device tree name should include reference to the SoM or SoC it
    uses
  • The device tree name should include reference to the carrier board
    it uses

  Since a carrier board takes a standard SoM type based on its
  connector, and since SoM-level device tree names include reference to
  the SoC used, it is sufficient to build a name from SoC + carrier
  board.

  Examples:

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   SoM \ carrier  SOMCRR-EZKIT          SOMCRR-EZLITE         
  ────────────────────────────────────────────────────────────
   SC598-SOM      adsp-sc598-ezkit.dts  adsp-sc598-ezlite.dts 
   SC594-SOM      adsp-sc594-ezkit.dts  adsp-sc594-ezlite.dts 
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Some evaluation boards don't consist of a SoM. Instead you get
  something like:

  SC584-EZLITE -> adsp-sc584-ezlite.dts

[pamolloy]

cc @gmalysa