Add architecture management functions to TensileCreateLibrary

[bstefanuk]

Objectives:

• Refactor code section in TensileCreateLibrary main responsible for verifying support architectures to a function.
• Add unit testing for the function.
• Add inline documentation for the function.
• Integrate the inline documentation into the documentation pipeline.

Outcomes:

• A new function has been added named parseGfxArchitectures.
• A new function has been added named mapGfxArchitectures.
• Automated API documentation and unit tests have been added.
• The help string has been updated for improved clarity and expected architecture input style.

Testing:

Unit testing:

• New tests include failure cases for unsupported architectures and malformed inputs.
• New tests include success cases for all and separately provided architectures, this includes both CMake and CLI argument styles.
• Command to run unit tests (from Tensile/Tensile/Tests):

  $ pytest unit/test_TensileCreateLibrary.py

Integration testing:

• Build rocBLAS via ./install.sh -c for both the source and destination branches (see Docker environment info below)
• Compare generated Tensile manifests (build/release/Tensile/library/TensileManifest.txt) with diff; no changes.

Notable changes:

• parseArchitectures raises a ValueError if an unrecognized architecture is found or incorrect delimiters are used. Previously, if an error was encountered, printExit was called.

Docker environment info:

$ cat /etc/os-release | head -1
PRETTY_NAME="Ubuntu 22.04.3 LTS"

$ apt show rocm-libs -a | head -2 | tail +2
Version: 6.1.2.60102-119~22.04

$ uname -r
5.15.0-86-generic

[cgmb]

• supportedArchitectures raises a ValueError if an unsupported architecture or malformed input is found.

My question is perhaps beyond the scope of this PR, but is this necessary? There are source kernels to fall back to, right? It is useful to be able to build Tensile for unsupported architectures, even if the performance is poor. It's much easier to get started with a new GPU architecture if you can build every library with a new target id without having to patch the library. That gets you through the first step of, "Make it work. Make it right. Make it fast," using only build flags.

[ellosel]

• supportedArchitectures raises a ValueError if an unsupported architecture or malformed input is found.

My question is perhaps beyond the scope of this PR, but is this necessary? There are source kernels to fall back to, right? It is useful to be able to build Tensile for unsupported architectures, even if the performance is poor. It's much easier to get started with a new GPU architecture if you can build every library with a new target id without having to patch the library. That gets you through the first step of, "Make it work. Make it right. Make it fast," using only build flags.

Previously we would call printExit if an architecture was unsupported. This attempts to more idiomatically support that behavior and give users the opportunity to recover but you are suggesting maybe we don't want that behavior at all. @yoichiyoshida thoughts?

[bstefanuk]

Great point @cgmb. As @ellosel mentioned, this behaviour replaces a hard program exit, so the effective behaviour is unchanged, see L1212.

Perhaps the confusion here is actually in the usage of the term "supported architecture" which may be better replaced by "unrecognized architecture". These functions search a dictionary defined in Common.py which maps Gfx names to architecture names, e.g., aldebaran. The exception is thus only raised if a Gfx architecture is passed that isn't in the map, e.g., gfxXYZ.

I have updated the wording of the PR description.

[cgmb]

Previously we would call printExit if an architecture was unsupported. This attempts to more idiomatically support that behavior and give users the opportunity to recover but you are suggesting maybe we don't want that behavior at all.

That is correct.

These functions search a dictionary defined in Common.py which maps Gfx names to architecture names, e.g., aldebaran. The exception is thus only raised if a Gfx architecture is passed that isn't in the map, e.g., gfxXYZ.

Is gfxXYZ the gfxip or the ISA? While they've usually been the same over the past few years, these can be different and the distinction may be important.

The mapping seems a bit weird at a conceptual level, since there has never been a 1-to-1 mapping between GFX names and architecture names. On a practical level, I also wonder if it could just map gfxXYZ to gfxXYZ in the case that there's no architecture name hardcoded for that input.

this behaviour replaces a hard program exit, so the effective behaviour is unchanged

I understand this is not a regression, but I'd thought we could improve the behaviour if we're changing it anyway. Although, upon further reflection, it is perhaps out-of-scope for this PR as it is not really changing.

[bstefanuk]

The mapping seems a bit weird at a conceptual level, since there has never been a 1-to-1 mapping between GFX names and architecture names.

I see what you mean and think it will be important to continue to discuss these decisions. In terms of scope, our focus at the moment is to refactor TensileCreateLibrary so that we can form a holistic view of its design and make changes of the sort you propose, in the future, while understanding how these changes will impact the project.

From a programmatic view, the Gfx architectures used here are mapped to their arch names, which are then interpreted as substring matchers for filtering which logic files are included in the generated library. I see a potential future solution where we scrap the Gfx archs as CLI parameters and just use the intended names directly, e.g., aldebaran.

[bstefanuk]

@cgmb I have created a ticket to review the usage of the --architecture option for TensileCreateLibrary, and in Tensile at-large.