[PATCH] D78565: [clang][doc] Clang ARM CPU command line argument reference

[Sjoerd Meijer via Phabricator via cfe-commits]

SjoerdMeijer added a comment.

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.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D78565/new/

https://reviews.llvm.org/D78565



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D78565: [clang][doc] Clang ARM CPU command line argument reference

[David Greene via Phabricator via cfe-commits]

greened added a comment.

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.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D78565/new/

https://reviews.llvm.org/D78565



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D78565: [clang][doc] Clang ARM CPU command line argument reference

[David Greene via Phabricator via cfe-commits]

greened added a comment.

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.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D78565/new/

https://reviews.llvm.org/D78565



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D78565: [clang][doc] Clang ARM CPU command line argument reference

[Sjoerd Meijer via Phabricator via cfe-commits]

SjoerdMeijer abandoned this revision.
SjoerdMeijer added a comment.

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.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D78565/new/

https://reviews.llvm.org/D78565



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D78565: [clang][doc] Clang ARM CPU command line argument reference

[Sjoerd Meijer via Phabricator via cfe-commits]

SjoerdMeijer added a comment.

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.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D78565/new/

https://reviews.llvm.org/D78565



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D78565: [clang][doc] Clang ARM CPU command line argument reference

[Peter Smith via Phabricator via cfe-commits]

psmith added a comment.

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.




Comment at: clang/docs/ClangARMCPUsCLI.rst:27
+
+.. option:: --target=arm-arm-none-eabi -mcpu=cortex-m33 -mfpu=fp-armv8-sp-d16 
-mfloat-abi=hard -mthumb
+

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


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D78565/new/

https://reviews.llvm.org/D78565



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D78565: [clang][doc] Clang ARM CPU command line argument reference

[Sjoerd Meijer via Phabricator via cfe-commits]

SjoerdMeijer created this revision.
SjoerdMeijer added reviewers: psmith, ostannard, kristof.beyls, chill.
Herald added subscribers: danielkiss, arphaman.

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.


https://reviews.llvm.org/D78565

Files:
  clang/docs/ClangARMCPUsCLI.rst
  clang/docs/index.rst


Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -20,6 +20,7 @@
Toolchain
LanguageExtensions
ClangCommandLineReference
+   ClangARMCPUsCLI
AttributeReference
DiagnosticsReference
CrossCompilation
Index: clang/docs/ClangARMCPUsCLI.rst
===
--- /dev/null
+++ clang/docs/ClangARMCPUsCLI.rst
@@ -0,0 +1,77 @@
+=
+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


Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -20,6 +20,7 @@
Toolchain
LanguageExtensions
ClangCommandLineReference
+   ClangARMCPUsCLI
AttributeReference
DiagnosticsReference
CrossCompilation
Index: clang/docs/ClangARMCPUsCLI.rst
===
--- /dev/null
+++ clang/docs/ClangARMCPUsCLI.rst
@@ -0,0 +1,77 @@
+=
+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