[clang][doc] Clang ARM CPU command line argument reference

[SjoerdMeijer]

Summary

Following the discussion about -mtune on the cfe dev list, I thought it would be good to make a start with documenting common command line arguments to target different ARM CPU and architecture combinations. This list is not yet complete, is work in progress, but I have just taken 2 recent M-cores as an example.

[psmith]

One question I can't answer and I think would need wider review, is whether this is type of material (common options for specific CPUs) is suited for the Clang Documentation or whether it would be better hosted by Arm itself, for example on developer.arm.com? I think that a more reference like Arm CPU options like https://gcc.gnu.org/onlinedocs/gcc/ARM-Options.html would work better in the Clang documentation.

I think the material is useful, especially for people new to these CPUs.

clang/docs/ClangARMCPUsCLI.rst

27

I think you mean arm-arm-none-eabi for an upstream triple selecting the bare-metal driver?

[SjoerdMeijer]

Hi Peter,
Thanks for reviewing again! I thought these examples to be relevant here, because it shows usage and examples of this tool (i.e. open-source clang/llvm). Additional benefits is that source and documentation is in one place, and it allows others, non-Arm people, to edit and review this document too. But I will take this question to the list, to see what people think about this.

[SjoerdMeijer]

Fair enough, perhaps the audience is too small here on llvm.org for this and this is too niche. In A-profile we have the same problem, so could the exercise for an A-core here, but can't spend time on that now, so will abandon this.

[greened]

In D78565#1996297, @SjoerdMeijer wrote:

Fair enough, perhaps the audience is too small here on llvm.org for this and this is too niche. In A-profile we have the same problem, so could the exercise for an A-core here, but can't spend time on that now, so will abandon this.

I would find this extremely valuable in the clang documentation. Not sure why this should be put on developer.arm.com as it is compiler-specific as wel as (sub-)target-specific.

[greened]

In D78565#1997372, @greened wrote:

In D78565#1996297, @SjoerdMeijer wrote:

Fair enough, perhaps the audience is too small here on llvm.org for this and this is too niche. In A-profile we have the same problem, so could the exercise for an A-core here, but can't spend time on that now, so will abandon this.

I would find this extremely valuable in the clang documentation. Not sure why this should be put on developer.arm.com as it is compiler-specific as wel as (sub-)target-specific.

To be clear, I also like Peter's suggestion of documenting all -m options as gcc does. There's room for both-and here.

[SjoerdMeijer]

To be completely open about this, I had an offline chat with @psmith and @kristof.beyls about this. The reasoning is that this is probably related to my relatively poor choice of the 2 first cores that I describe here. They are microcontrollers, and Clang/LLVM doesn't provide a full embedded toolchain (linker, libraries, etc.), which is e.g. what we add downstream. So, if you're creating an embedded toolchain, you probably know what you're doing, and this is not one of the first problems that you have.

While I agree with that, I also mentioned that there are many issues orthogonal to this. Yes, we need a full toolchain, but I don't understand how improving things step-by-step can be a bad thing, or why we should wait for another thing to appear first before this becomes more valuable. And yes, also -m option documentation needs to be improved, but again, for me that is orthogonal to this doc change. And what I also mentioned, is that absolutely nothing changes about the whole story here if you take an A-core application processor instead of an M-core, for which the toolchain probably looks simpler.

I agree with all your updates and replies on the cfe dev list. You mentioned "complete overhaul", and yes, I think option handling is inconsistent, undocumented, and so in general quite broken. Problem is that I didn't get a lot of buy in here and on the mailing list. So, I was happy to abandon this as I didn't feel like spending more time on this at this point. But my idea was to step-by-step add more cores to this doc, also A-cores.

clang/docs/ClangARMCPUsCLI.rst

+=============================================
+Clang ARM CPU command line argument reference
+=============================================
+
+This page lists common command line arguments to target different ARM CPU
+and architecture combinations. This list is not yet complete, and is work in
+progress.
+
+Cortex-M33
+==========
+
+Architecture: Armv8-M
+
+Technical Reference Manual:
+`http://infocenter.arm.com/help/topic/com.arm.doc.100230_0002_00_en/cortex_m33_trm_100230_0002_00_en.pdf`
+
+Optional architecture extensions:
+- single precision floating-point (FP),
+- DSP,
+- ARMv8-M Security Extension (CMSE),
+- Custom Datapath Extension (CDE).
+
+Example architecture configurations and corresponding CLI options:
+
+All extensions enabled, except CMSE and CDE, with DSP implied by -mcpu=cortex-m33:
+
+.. option:: --target=arm-arm-none-eabi -mcpu=cortex-m33 -mfpu=fp-armv8-sp-d16 -mfloat-abi=hard -mthumb
+
+All extensions enabled:
+
+.. option:: --target=arm-arm-none-eabi -mcpu=cortex-m33 -mfpu=fp-armv8-sp-d16 -mfloat-abi=hard -mthumb -mcmse
+
+Without single precision float support:
+
+.. option:: --target=arm-arm-none-eabi -mcpu=cortex-m33 -mfpu=none -mthumb
+
+Without single precision float and DSP support:
+
+.. option:: --target=arm-arm-none-eabi -mcpu=cortex-m33+nodsp -mfpu=none -mthumb
+
+Cortex-M55
+==========
+
+Architecture: Armv8.1-M Main
+
+Technical Reference Manual: not yet available.
+
+Optional architecture extensions:
+- M-Profile Vector Extension (MVE), integer-only, or also floating-point.
+- Scalar half, single, and double precision floating-point,
+- ARMv8-M Security Extension (CMSE),
+- Custom Datapath Extension (CDE).
+
+Mandatory architecture extensions (thus implied in the examples below):
+- DSP
+
+Example architecture configurations and corresponding CLI options:
+
+Integer and float MVE (INT, F16, F32), and float support (F16, F32, F64):
+
+.. option:: --target=arm-arm-none-eabi -mcpu=cortex-m55 -mfloat-abi=hard -mthumb
+
+Integer-only MVE, with float support (F16, F32, F64):
+
+.. option:: --target=arm-arm-none-eabi -mcpu=cortex-m55+nomve.fp -mfloat-abi=hard -mthumb
+
+Integer-only MVE, no float support:
+
+.. option:: --target=arm-arm-none-eabi -mcpu=cortex-m55+nofp -mfloat-abi=hard -mthumb
+
+No MVE, only float support (F16, F32, F64):
+
+.. option:: --target=arm-arm-none-eabi -mcpu=cortex-m55+nomve -mfloat-abi=hard -mthumb
+
+Basic Armv8.1-M Main support, no extensions:
+
+.. option:: --target=arm-arm-none-eabi -mcpu=cortex-m55+nofp+nomve

clang/docs/index.rst

 
 .. toctree::
    :maxdepth: 1
 
    UsersManual
    Toolchain
    LanguageExtensions
    ClangCommandLineReference
+   ClangARMCPUsCLI
    AttributeReference
    DiagnosticsReference
    CrossCompilation
    ClangStaticAnalyzer
    ThreadSafetyAnalysis
    AddressSanitizer
    ThreadSanitizer
    MemorySanitizer