/
acle.md
12367 lines (9514 loc) · 600 KB
/
acle.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: Arm C Language Extensions
version: 2023Q2
date-of-issue: 04 August 2023
# LaTeX specific variables
copyright-text: "Copyright: see section \\texorpdfstring{\\nameref{copyright}}{Copyright}."
draftversion: true
# Jekyll specific variables
header_counter: true
toc: true
---
<!--
SPDX-FileCopyrightText: Copyright 2011-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
SPDX-FileCopyrightText: Copyright 2022 Google LLC.
CC-BY-SA-4.0 AND Apache-Patent-License
See LICENSE.md file for details
-->
<!---
**** Do not remove! ****
The two lines following this comments are necessary
to generate the Table of Contents via Jekyll.
They are automatically removed by the scripts that generates the pdfs.
-->
* TOC
{:toc}
# Preface
## Abstract
This document specifies the Arm C Language Extensions to enable C/C++
programmers to exploit the Arm architecture with minimal restrictions on
source code portability.
## Keywords
ACLE, ABI, C, C++, compiler, armcc, gcc, intrinsic, macro, attribute,
Neon, SIMD, SVE, SVE2, atomic
## Latest release and defects report
For the latest release of this document, see the [ACLE project on
GitHub](https://github.com/ARM-software/acle).
Please report defects in this specification to the [issue tracker page
on GitHub](https://github.com/ARM-software/acle/issues).
## License
This work is licensed under the Creative Commons
Attribution-ShareAlike 4.0 International License. To view a copy of
this license, visit <http://creativecommons.org/licenses/by-sa/4.0/> or
send a letter to Creative Commons, PO Box 1866, Mountain View, CA
94042, USA.
Grant of Patent License. Subject to the terms and conditions of this
license (both the Public License and this Patent License), each
Licensor hereby grants to You a perpetual, worldwide, non-exclusive,
no-charge, royalty-free, irrevocable (except as stated in this
section) patent license to make, have made, use, offer to sell, sell,
import, and otherwise transfer the Licensed Material, where such
license applies only to those patent claims licensable by such
Licensor that are necessarily infringed by their contribution(s) alone
or by combination of their contribution(s) with the Licensed Material
to which such contribution(s) was submitted. If You institute patent
litigation against any entity (including a cross-claim or counterclaim
in a lawsuit) alleging that the Licensed Material or a contribution
incorporated within the Licensed Material constitutes direct or
contributory patent infringement, then any licenses granted to You
under this license for that Licensed Material shall terminate as of
the date such litigation is filed.
## About the license
As identified more fully in the [License](#license) section, this project
is licensed under CC-BY-SA-4.0 along with an additional patent
license. The language in the additional patent license is largely
identical to that in Apache-2.0 (specifically, Section 3 of Apache-2.0
as reflected at <https://www.apache.org/licenses/LICENSE-2.0>) with two
exceptions.
First, several changes were made related to the defined terms so as to
reflect the fact that such defined terms need to align with the
terminology in CC-BY-SA-4.0 rather than Apache-2.0 (e.g., changing
“Work” to “Licensed Material”).
Second, the defensive termination clause was changed such that the
scope of defensive termination applies to “any licenses granted to
You” (rather than “any patent licenses granted to You”). This change
is intended to help maintain a healthy ecosystem by providing
additional protection to the community against patent litigation
claims.
## Contributions
Contributions to this project are licensed under an inbound=outbound
model such that any such contributions are licensed by the contributor
under the same terms as those in the LICENSE file.
We do not require copyright assignment. The original contributor will
retain the copyright.
## Trademark notice
The text of and illustrations in this document are licensed by Arm
under a Creative Commons Attribution–Share Alike 4.0 International
license ("CC-BY-SA-4.0”), with an additional clause on patents.
The Arm trademarks featured here are registered trademarks or
trademarks of Arm Limited (or its subsidiaries) in the US and/or
elsewhere. All rights reserved. Please visit
<https://www.arm.com/company/policies/trademarks> for more information
about Arm’s trademarks.
## Copyright
* Copyright 2011-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>.
* Copyright 2022 Google LLC.
## About this document
### Change control
#### Current Status and Anticipated Changes
The following support level definitions are used by the ACLE
specifications:
**Release**
Arm considers this specification to have enough implementations,
which have received sufficient testing, to verify that it is
correct. The details of these criteria are dependent on the scale
and complexity of the change over previous versions: small, simple
changes might only require one implementation, but more complex
changes require multiple independent implementations, which have
been rigorously tested for cross-compatibility. Arm anticipates that
future changes to this specification will be limited to
typographical corrections, clarifications and compatible extensions.
**Beta**
Arm considers this specification to be complete, but existing
implementations do not meet the requirements for confidence in its
release quality. Arm might need to make incompatible changes if issues
emerge from its implementation.
**Alpha**
The content of this specification is a draft, and Arm considers the
likelihood of future incompatible changes to be significant.
All content in this document is at the **Release** quality level,
unless a different support level is specified in the text.
#### Change history
| **Issue** | **Date** | **By** | **Change** |
| ------------ | ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| A | 11/11/11 | AG | First release |
| B | 13/11/13 | AG | Version 1.1. Editorial changes. Corrections and completions to intrinsics as detailed in 3.3. Updated for C11/C++11. |
| C | 09/05/14 | TB | Version 2.0. Updated for Armv8 AArch32 and AArch64. |
| D | 24/03/16 | TB | Version 2.1. Updated for Armv8.1 AArch32 and AArch64. |
| E | 02/06/17 | Arm | Version ACLE Q2 2017. Updated for Armv8.2-A and Armv8.3-A. |
| F | 30/04/18 | Arm | Version ACLE Q2 2018. Updated for Armv8.4-A. |
| G | 30/03/19 | Arm | Version ACLE Q1 2019. Updated for Armv8.5-A and MVE. Various bugfixes. |
| H | 30/06/19 | Arm | Version ACLE Q2 2019. Updated for TME and more Armv8.5-A intrinsics. Various bugfixes. |
| ACLE Q3 2019 | 30/09/19 | Arm | Version ACLE Q3 2019. |
| ACLE Q4 2019 | 31/12/19 | Arm | Version ACLE Q4 2019. |
| ACLE Q2 2020 | 31/05/20 | Arm | Version ACLE Q2 2020. |
| ACLE Q3 2020 | 31/10/20 | Arm | Version ACLE Q3 2020. |
| 2021Q2 | 02 July 2021 | Arm | Version ACLE Q2 2021. Open source version. NFCI. |
| 2021Q3 | 30 September 2021 | Arm | Minor re-wording. NFCI. |
| 2021Q4 | 11 January 2022 | Arm | See [Changes between ACLE Q3 2021 and ACLE Q4 2021](#changes-between-acle-q3-2021-and-acle-q4-2021) |
| 2022Q1 | 06 April 2022 | Arm | See [Changes between ACLE Q4 2021 and ACLE Q1 2022](#changes-between-acle-q4-2021-and-acle-q1-2022) |
| 2022Q2 | 01 Jul 2022 | Arm | See [Changes between ACLE Q1 2021 and ACLE Q2 2022](#changes-between-acle-q1-2022-and-acle-q2-2022) |
| 2022Q4 | 23 November 2022 | Arm | See [Changes between ACLE Q2 2022 and ACLE Q4 2022](#changes-between-acle-q2-2022-and-acle-q4-2022) |
| 2023Q2 | 04 August 2023 | Arm | See [Changes between ACLE Q4 2022 and ACLE Q2 2023](#changes-between-acle-q4-2022-and-acle-q2-2023) |
#### Changes between ACLE Q2 2017 and ACLE Q2 2018
Most changes in ACLE Q2 2018 are updates to support features introduced in
Armv8.3-A [[ARMARMv83]](#ARMARMv83). Support is added for the Complex addition and Complex MLA intrinsics.
Armv8.4-A [[ARMARMv84]](#ARMARMv84). Support is added for the Dot Product intrinsics.
#### Changes between ACLE Q2 2018 and ACLE Q1 2019
* Support added for features introduced in Armv8.5-A [[ARMARMv85]](#ARMARMv85) (including the MTE extension).
* Support added for MVE [[MVE-spec]](#MVE-spec) from the Armv8.1-M architecture.
* Support added for Armv8.4-A half-precision extensions through Neon intrinsics.
* Added feature detection macro for LSE atomic operations.
* Added floating-point versions of intrinsics to access coprocessor registers.
#### Changes between ACLE Q1 2019 and ACLE Q2 2019
* Support added for TME features.
* Support added for rounding intrinsics from Armv8.5-A [[ARMARMv85]](#ARMARMv85).
#### Changes between ACLE Q2 2019 and ACLE Q3 2019
* Support added for Armv8.6-A features.
* Support added for random number instruction intrinsics from Armv8.5-A [[ARMARMv85]](#ARMARMv85).
#### Changes between ACLE Q3 2019 and ACLE Q4 2019
* BETA support for the Custom Datapath Extension.
* MVE intrinsics updates and fixes.
* Feature macros for Pointer Authentication and Branch Target Identification.
#### Changes between ACLE Q4 2019 and ACLE Q2 2020
* Updates to CDE intrinsics.
* Allow some Neon intrinsics previously available in A64 only in A32 as well.
#### Changes between ACLE Q2 2020 and ACLE Q3 2020
* Add support for features introduced in the Armv8.7-a architecture update.
* Fix allowed values for __ARM_FEATURE_CDE_COPROC macro.
#### Changes between ACLE Q2 2021 and ACLE Q3 2021
* Fixed FP16 format description at [Half-precision
floating-point](#half-precision-floating-point).
* Fixed the description of `vmul_lane_u16` at
[Concepts](#neon-intrinsics-concepts).
#### Changes between ACLE Q3 2021 and ACLE Q4 2021
* Updated copyright statement in section [Copyright](#copyright).
* Introduced `__ARM_FEATURE_PAUTH` and `__ARM_FEATURE_BTI` in sections
[Pointer Authentication](#pointer-authentication) and [Branch Target
Identification](#branch-target-identification) respectively.
* Fixed the changelog of 2021Q3, as is was missing the mentioning of
the intrinsic `vmul_lane_u16` in the second item.
* Fixed item lists rendering in [M-profile Vector
Extension](#m-profile-vector-extension-mve-intrinsics).
* Fixed superfluous and broken backticks in code examples throughout.
* Added reference to the *Cortex-M Security Extension (CMSE)*
specifications in [Cortex-M Security Extension
(CMSE)](#cortex-m-security-extension-cmse).
* Added specification for [NEON-SVE Bridge](#neon-sve-bridge) and
[NEON-SVE Bridge macros](#neon-sve-bridge-macros).
* Added feature detection macro for the memcpy family of memory
operations (MOPS) at [memcpy family of memory operations
standarization instructions -
MOPS](#memcpy-family-of-memory-operations-standarization-instructions---mops)
* Added intrinsic for the memcpy family of memory operations (MOPS) at
[memcpy family of operations intrinsics -
MOPS](#memcpy-family-of-operations-intrinsics---mops)
* Converted document sources from reStructuredText (`.rst`) to
Markdown (`.md`). The tool [`pandoc`](https://pandoc.org/) is now
used to render the PDF of the specs. The PDF is rendered using the
standard layout used in Arm specifications.
* Updated the section links in [Changes between ACLE Q2 2021 and ACLE
Q3 2021](#changes-between-acle-q2-2021-and-acle-q3-2021) by using
the actual section title.
#### Changes between ACLE Q4 2021 and ACLE Q1 2022
* Updated the description of the `__arm_mops_memset_tag` intrinsic in [memcpy
family of operations intrinsics - MOPS](#memcpy-family-of-operations-intrinsics---mops)
to require both the `__ARM_FEATURE_MOPS` and `__ARM_FEATURE_MEMORY_TAGGING`
feature macros.
* Fixed minor formatting errors throughout.
* Replaced link text such as “sec-…” and “ssec-…” with section titles.
* Reorganized the presentation of [Feature test macros](#feature-test-macros).
Also:
* Generalized some AArch32-specific text to AArch64.
* Added more cross-references to the descriptions of the macros.
* Used embedded links for the [list of predefined macros](#summary-of-predefined-macros)
and fixed some misdirected links. Resorted the list into alphabetical
order.
* Reorganized the [Intrinsics](#intrinsics) and
[Header files](#header-files) sections.
* Added a description of [`<arm_neon_sve_bridge.h>`](#arm_neon_sve_bridge.h)
to the [Header files](#header-files) section.
* In [Data types](#data-types), clarified that `__fp16` and `__bf16` are
predefined types whereas vector types like `int32x4_t` are not.
* Moved the [Future directions](#future-directions) chapter to the end.
* Added a description of support levels in [Current Status and
Anticipated Changes](#current-status-and-anticipated-changes).
* Support added for [Function Multi Versioning](#function-multi-versioning).
* The sections [AES extension](#aes-extension), [SHA2
extension](#sha2-extension) and [SHA512
extension](#sha512-extension) have been reworded for clarity, by
specifying the `FEAT_*` tag they refer to from the Arm Architectural
Reference Manual.
* Sorted the items in [References](#references).
* Changed the wording of **Beta** in [Current Status and Anticipated
Changes](#current-status-and-anticipated-changes).
* Sorted the table in [Terms and abbreviations](#terms-and-abbreviations).
* Formatted `memcpy`, `memmove` and `memset` with fixed-width font all
throughout the document.
* Minor rewording for:
* [Introduction](#introduction) section of [memcpy family of
operations intrinsics -
MOPS](#memcpy-family-of-operations-intrinsics---mops).
* [Procedure calls and the Q / GE bits](#procedure-calls-and-the-q-ge-bits).
* [Custom calling conventions](#custom-calling-conventions) - use a
bulleted list for the examples.
No functional change intended.
* Reordered the sections in [Change history](#change-history) in
chronological order.
#### Changes between ACLE Q1 2022 and ACLE Q2 2022
* Added [support for SVE and SVE2](#arm_sve.h). This incorporates the final
00bet6 version of the separate beta document [Arm C Language Extensions for
SVE](https://developer.arm.com/architectures/system-architectures/software-standards/acle),
except that the optional feature `__ARM_FEATURE_SVE_NONMEMBER_OPERATORS`
has been removed. The SVE and SVE2 support is now at “release” rather than
beta quality and the separate beta document is no longer maintained.
* Added section [Scalable Vector Extension procedure call standard attribute](#scalable-vector-extension-procedure-call-standard-attribute)
* Fixes for [Function Multi Versioning](#function-multi-versioning):
* typo in `FEAT_DPB2`.
* added `FEAT_LS64*`.
#### Changes between ACLE Q2 2022 and ACLE Q4 2022
* Added [**Alpha**](#current-status-and-anticipated-changes)
[support for SME](#arm_sme.h).
* Added feature detection macro `__ARM_FEATURE_RCPC` for RCpc (Release Consistent processor consistent) model at [RCpc](#rcpc).
* Added two new valid values to the
[SVE feature macros](#scalable-vector-extension-sve):
* `__ARM_FEATURE_SVE_VECTOR_OPERATORS=2`
* `__ARM_FEATURE_SVE_PREDICATE_OPERATORS=2`
* Fixes for [Function Multi Versioning](#function-multi-versioning):
* Added missing features of `ID_AA64ISAR1_EL1` and `ID_AA64ISAR2_EL1`.
* Renamed the feature macro to `__HAVE_FUNCTION_MULTI_VERSIONING`
* Added some clarifications.
#### Changes between ACLE Q4 2022 and ACLE Q2 2023
* Added SLC as a valid Cache Level for the Memory prefetch intrinsics.
* Added [support for 128-bit system registers](#special-register-intrinsics),
including two intrinsics for accessing them (`__rsr128` and `__wsr128`), and a
feature macro to detect if they are available (`__ARM_FEATURE_SYSREG128`).
* Added support for FEAT_LRCPC3 LDAP1/STL1 intrinsics and `__ARM_FEATURE_RCPC`.
* Corrected the mandatory architecture versions for FEAT_LRCPC and FEAT_LRCPC2.
* Corrected references to `-pedantic` flag.
* Fixed typos.
* Fixes for [Function Multi Versioning](#function-multi-versioning):
* Renamed features to `sme-f64f64` and `sme-i16i64`
* Corrected register name to `ID_AA64SMFR0_EL1.I16I64`
* Removed incorrect optimisation remark in [CMSE](#CMSE-ACLE)'s floating-point
register clearing.
* Removed incorrect information about the floating-point ABI used in
[CMSE](#CMSE-ACLE)'s Arguments on the stack and floating point handling.
* Corrected description and example in [CMSE](#CMSE-ACLE)'s section about
non-secure function pointers.
* Added a requirement on [`arm_new_za`](#arm_new_za) to set the initial
contents of ZA to zero.
#### Changes for next release
* Combined the SME `slice_base` and `slice_offset` arguments into a
single `slice` argument.
* Added the [Keyword attributes](#keyword-attributes) section.
* Changed the [SME language extensions](#sme-language-extensions-and-intrinsics)
to use keyword attributes instead of GNU-style attributes.
* Added missing word to Function Multi Versioning's [Name mangling](#name-mangling).
* Added description of SVE reinterpret intrinsics.
### References
This document refers to the following documents.
<!-- Please the list of references in alphabetical order -->
* <span id="AAPCS" class="citation-label">AAPCS</span> Arm,
[Application Binary Interface for the Arm
Architecture](https://developer.arm.com/products/architecture/system-architectures/software-standards/abi)
* <span id="AAPCS64" class="citation-label">AAPCS64</span> Arm,
[Application Binary Interface for the Arm
Architecture](https://developer.arm.com/products/architecture/system-architectures/software-standards/abi)
* <span id="ARMARM" class="citation-label">ARMARM</span> Arm, Arm
Architecture Reference Manual (7-A / 7-R), Arm DDI 0406C
* <span id="ARMARMv8" class="citation-label">ARMARMv8</span> Arm,
Armv8-A Reference Manual (Issue A.b), Arm DDI0487A.B
* <span id="ARMARMv81" class="citation-label">ARMARMv81</span> Arm,
Armv8.1 Extension, [The ARMv8-A architecture and its ongoing
development](http://community.arm.com/groups/processors/blog/2014/12/02/the-armv8-a-architecture-and-its-ongoing-development)
* <span id="ARMARMv82" class="citation-label">ARMARMv82</span> Arm,
Armv8.2 Extension, [Armv8-A architecture
evolution](https://community.arm.com/groups/processors/blog/2016/01/05/armv8-a-architecture-evolution)
* <span id="ARMARMv83" class="citation-label">ARMARMv83</span> Arm,
Armv8.3 Extension, [Armv8-A architecture: 2016
additions](https://community.arm.com/processors/b/blog/posts/armv8-a-architecture-2016-additions)
* <span id="ARMARMv84" class="citation-label">ARMARMv84</span> Arm,
Armv8.4 Extension, [Introducing 2017’s extensions to the Arm
Architecture](https://community.arm.com/processors/b/blog/posts/introducing-2017s-extensions-to-the-arm-architecture)
* <span id="ARMARMv85" class="citation-label">ARMARMv85</span> Arm,
Armv8.5 Extension, [Arm A-Profile Architecture Developments 2018:
Armv8.5-A](https://community.arm.com/developer/ip-products/processors/b/processors-ip-blog/posts/arm-a-profile-architecture-2018-developments-armv85a)
* <span id="ARMv7M" class="citation-label">ARMv7M</span> Arm, Arm
Architecture Reference Manual (7-M), Arm DDI 0403C
* <span id="BA" class="citation-label">BA</span> Arm, EABI Addenda and
Errata Build Attributes, Arm IHI 0045C
* <span id="Bfloat16" class="citation-label">Bfloat16</span> Arm,
[BFloat16 processing for Neural Networks on
Armv8-A](https://community.arm.com/developer/ip-products/processors/b/ml-ip-blog/posts/bfloat16-processing-for-neural-networks-on-armv8_2d00_a)
* <span id="C11" class="citation-label">C11</span> ISO, Standard C
(based on draft N1570), ISO/IEC 9899:2011
* <span id="C99" class="citation-label">C99</span> ISO, Standard C
(C99), ISO 9899:1999
* <span id="CFP15" class="citation-label">CFP15</span> ISO/IEC,
Floating point extensions for C, ISO/IEC TS 18661-3
* <span id="CMSE-ACLE" class="citation-label">CMSE-ACLE</span> Arm,
[Arm®v8-M Security Extensions: Requirements on Development
Tools](https://developer.arm.com/documentation/ecm0359818/latest)
* <span id="CPP11" class="citation-label">CPP11</span> ISO, Standard
C++ (based on draft N3337), ISO/IEC 14882:2011
* <span id="CPP14" class="citation-label">CPP14</span> ISO, Standard C++
(based on draft N3797), ISO/IEC 14882:2014
* <span id="G.191" class="citation-label">G.191</span> ITU-T, Software
Tool Library 2005 User's Manual, T-REC-G.191-200508-I
* <span id="GCC" class="citation-label">GCC</span> GNU/FSF, [GNU C
Compiler Collection](http://gcc.gnu.org/onlinedocs)
* <span id="IA-64" class="citation-label">IA-64</span> Intel, Intel
Itanium Processor-Specific ABI, 245370-003
* <span id="IEEE-FP" class="citation-label">IEEE-FP</span> IEEE, IEEE
Floating Point, IEEE 754-2008
* <span id="MVE" class="citation-label">MVE</span> Arm, [MVE
Intrinsics](https://developer.arm.com/architectures/instruction-sets/simd-isas/helium/mve-intrinsics)
* <span id="MVE-spec" class="citation-label">MVE-spec</span> Arm, Arm
v8-M Architecture Reference Manual, Arm DDI0553B.F
* <span id="Neon" class="citation-label">Neon</span> Arm, [Neon
Intrinsics](https://developer.arm.com/technologies/neon/intrinsics)
* <span id="POSIX" class="citation-label">POSIX</span> IEEE / TOG, The
Open Group Base Specifications, IEEE 1003.1
* <span id="Warren" class="citation-label">Warren</span> 8. Warren, Hacker's Delight, pub. Addison-Wesley 2003
* <span id="cxxabi" class="citation-label">cxxabi</span> [Itanium C++
ABI](https://itanium-cxx-abi.github.io/cxx-abi/)
### Terms and abbreviations
This document uses the following terms and abbreviations.
<!-- Please keep the rows of the table in alphabetical order by the column "Term" -->
| **Term** | **Meaning** |
| ---------------- | -------------------------------------------------------------------------------------------- |
| AAPCS | Arm Procedure Call Standard, part of the ABI, defined in [[AAPCS]](#AAPCS). |
| ABI | Arm Application Binary Interface. |
| ACLE | Arm C Language Extensions, as defined in this document. |
| Advanced SIMD | A 64-bit/128-bit SIMD instruction set defined as part of the Arm architecture. |
| FFR | The SVE first-fault register. |
| FFRT | The SVE “first-fault register token”. This is a conceptual construct that forms part of the ACLE model of first-faulting and non-faulting loads; see [First-faulting and non-faulting loads](#first-faulting-and-non-faulting-loads) for details. |
| ILP32 | A 32-bit address mode where long is a 32-bit type. |
| LLP64 | A 64-bit address mode where long is a 32-bit type. |
| LP64 | A 64-bit address mode where long is a 64-bit type. |
| Neon | An implementation of the Arm Advanced SIMD extensions. |
| SIMD | Any instruction set that operates simultaneously on multiple elements of a vector data type. |
| sizeless type | A C and C++ type that can be used to create objects, but that has no measurable size; see [Sizeless types](#sizeless-types) for details. |
| SVE | The Armv8-A Scalable Vector Extension. Also used more generally to include SVE2 and other SVE extensions. |
| SVE2 | An Armv9-A extension of SVE. |
| SVL | Streaming Vector Length; that is, the number of bits in an SVE vector type like ``svint32_t`` when the processor is in [streaming mode](#streaming-mode) |
| SVL.B | As for SVL, but measured in bytes rather than bits |
| Thumb | The Thumb instruction set extension to Arm. |
| VG | The number of 64-bit elements (“vector granules”) in an SVE vector. |
| VFP | The original Arm non-SIMD floating-point instruction set. |
| build attributes | Object build attributes indicating configuration, as defined in [[BA]](#BA). |
| word | A 32-bit quantity, in memory or a register. |
### Terms used to specify C and C++ semantics
The following terms are used to specify C and C++ semantics:
<!-- Do not remove the following `span`, it is needed to create an
anchor that can be referred via an internal hyperlink to the paragraph
following it. --><span id="abstract-machine"></span>
**abstract machine**
> The conceptual machine that the C and C++ language standards use to define
> the behavior of programs.
<!-- Do not remove the following `span`, it is needed to create an
anchor that can be referred via an internal hyperlink to the paragraph
following it. --><span id="evaluated-call"></span>
**evaluated call**
> A call that does not occur in an “unevaluated operand”;
> see section `[expr.context]` in the C++ standard for details.
>
> For example, any calls that occur in the operand of a `sizeof`
> expression are not evaluated.
<!-- Do not remove the following `span`, it is needed to create an
anchor that can be referred via an internal hyperlink to the paragraph
following it. --><span id="external-linkage"></span>
**external linkage**
> A function has “external linkage” if there is a single definition that can be
> referenced by name from more than one translation unit. See `[basic.link]`
> in the C++ standard for more details.
>
> As noted in [Intrinsics](#intrinsics), it is unspecified whether ACLE
> intrinsics are functions and, if so, what linkage they have. However,
> certain ACLE support functions are defined to have external linkage.
<!-- Do not remove the following `span`, it is needed to create an
anchor that can be referred via an internal hyperlink to the paragraph
2following it. --><span id="ill-formed"></span>
**ill-formed** programs or pieces of programs
> Programs or pieces of programs that violate a rule due to their static
> construction rather than due to their runtime behavior.
>
> Ill-formed programs should usually be rejected with at least one
> diagnostic. However, there are some ill-formed C++ constructs for which
> “no diagnostic is required”; see the `[intro]` section of the C++
> standard for details. Many of these constructs could in principle
> use ACLE features.
>
> In order to cope with such cases, ACLE does not say when
> ill-formed programs should be rejected. However, from a
> quality-of-implementation perspective, it is better to reject
> ill-formed programs wherever possible.
<!-- Do not remove the following `span`, it is needed to create an
anchor that can be referred via an internal hyperlink to the paragraph
2following it. --><span id="unprototyped-function"></span>
**unprototyped functions**
> In early versions of C, it was possible to call a function without
> declaring it first. The function was then assumed to return an `int`.
> For example, this was a valid complete translation unit:
>
> ``` c
> int x() { return some_func(1, 2.0, "apples"); }
> ```
>
> It was also possible to declare a function's return type without specifying
> its argument types. For example:
>
> ``` c
> double another_func();
> double f() { return another_func(1.0, 2, "oranges"); }
> ```
>
> Functions such as `some_func` and `another_func` are referred to as
> (K&R-style) “unprototyped” functions. The first C standard categorized
> these functions as an obsolescent feature and C18 removed all remaining
> support for them.
## Conventions
Most SVE ACLE intrinsics have two names: a longer unique name and a
shorter overloaded alias. The convention adopted in this document is to
enclose characters in square brackets if they are only present in the
longer name. For example:
``` c
svclz[_u16]_m
```
refers to an intrinsic whose full name is `svclz_u16_m` and whose
overloaded alias is `svclz_m`.
## Scope
The Arm C Language Extensions (ACLE) specification specifies source
language extensions and implementation choices that C/C++ compilers can
implement in order to allow programmers to better exploit the Arm
architecture.
The extensions include:
* Predefined macros that provide information about the functionality of
the target architecture.
* Intrinsic functions.
* Attributes that can be applied to functions, data and other entities.
This specification does not standardize command-line options,
diagnostics or other external behavior of compilers.
The intended users of this specification are:
* Application programmers wishing to adapt or hand-optimize
applications and libraries for Arm targets.
* System programmers needing low-level access to Arm targets beyond
what C/C++ provides for.
* Compiler implementors, who will implement this specification.
* Implementors of IDEs, static analysis and other similar tools who wish to
deal with the C/C++ source language extensions when encountered in
source code.
ACLE is not a hardware abstraction layer (HAL), and does not specify a
library component but it may make it easier to write a HAL or other
low-level library in C rather than assembler.
## Cortex-M Security Extension (CMSE)
ACLE support for the Cortex-M Security Extension (CMSE) is defined in
*Arm®v8-M Security Extensions: Requirements on Development Tools*
document [CMSE-ACLE](#CMSE-ACLE).
# Introduction
The Arm architecture includes features that go beyond the set of operations
available to C/C++ programmers. The intention of the Arm C Language
Extensions (ACLE) is to allow the creation of applications and middleware
code that is portable across compilers, and across Arm architecture
variants, while exploiting the advanced features of the Arm architecture.
The design principles for ACLE can be summarized as:
* Be implementable in (or as an addition to) current C/C++
implementations.
* Build on and standardize existing practice where possible.
ACLE incorporates some language extensions introduced in the GCC C
compiler. Current GCC documentation [[GCC]](#GCC) can be found at
<http://gcc.gnu.org/onlinedocs/gcc>.
Formally it should be assumed that ACLE refers to the documentation for
GCC 4.5.1: <http://gcc.gnu.org/onlinedocs/gcc-4.5.1/gcc/>.
Some of the ACLE extensions are not specific to the Arm architecture but
have proven to be of particular benefit in low-level and systems
programming; examples include features for controlling the alignment and
packing of data, and some common operations such as word rotation and
reversal. As and when features become available in international
standards (and implementations), Arm recommends that you use these in
preference to ACLE. When implementations are widely available, any
ACLE-specific features can be expected to be deprecated.
## Portable binary objects
In AArch32, the *ABI for the Arm Architecture* defines a set of build
attributes [[BA]](#BA). These attributes are intended to facilitate generating
cross-platform portable binary object files by providing a mechanism to
determine the compatibility of object files. In AArch64, the ABI does
not define a standard set of build attributes and takes the approach
that binaries are, in general, not portable across platforms. References
to build attributes in this document should be interpreted as applying
only to AArch32.
# C language extensions
## Data types
This section overlaps with the specification of the Arm Procedure Call
Standard, particularly [[AAPCS]](#AAPCS) (4.1). ACLE extends some of the guarantees
of C, allowing assumptions to be made in source code beyond those
permitted by Standard C.
* Plain char is unsigned, as specified in the ABI [[AAPCS]](#AAPCS) and
[[AAPCS64]](#AAPCS64) (7.1.1).
* When pointers are 32 bits, the long type is 32 bits (ILP32 model).
* When pointers are 64 bits, the long type may be either 64 bits
(LP64 model) or 32 bits (LLP64 model).
ACLE extends C by providing some types not present in Standard C and
defining how they are dealt with by the AAPCS. These types fall into
two groups:
* types that are defined by [header files](#header-files)
* types that are predefined by the implementation, so that
no header file needs to be included to make use of them
The former group includes things like [vector data types](#vector-data-types),
which are defined by the header file [`<arm_neon.h>`](#arm_neon.h).
The predefined types are:
* The `__fp16` type for 16-bit floating-point values (see
[Half-precision floating-point](#half-precision-floating-point)).
* The `__bf16` type for 16-bit brain floating-point values (see
[Half-precision brain floating-point](#half-precision-brain-floating-point)).
### Implementation-defined type properties
ACLE and the Arm ABI allow implementations some freedom in order to
conform to long-standing conventions in various environments. It is
suggested that implementations set suitable defaults for their
environment but allow the default to be overridden.
The signedness of a plain int bit-field is implementation-defined.
Whether the underlying type of an enumeration is minimal or at least
32-bit, is implementation-defined. The predefined macro
`__ARM_SIZEOF_MINIMAL_ENUM` should be defined as 1 or 4 according to
the size of a minimal enumeration type such as `enum { X=0 }`. An
implementation that conforms to the Arm ABI must reflect its choice in
the `Tag_ABI_enum_size build` attribute.
`wchar_t` may be 2 or 4 bytes. The predefined macro
`__ARM_SIZEOF_WCHAR_T` should be defined as the same number. An
implementation that conforms to the Arm ABI must reflect its choice in
the `Tag_ABI_PCS_wchar_t` build attribute.
## Predefined macros
Several predefined macros are defined. Generally these define features
of the Arm architecture being targeted, or how the C/C++ implementation
uses the architecture. These macros are detailed in
[Feature test macros](#feature-test-macros). All ACLE predefined macros
start with the prefix `__ARM`.
## Keyword attributes
This section is in
[**Alpha** state](#current-status-and-anticipated-changes) and may change or be
extended in the future.
ACLE adds several non-standard keywords to C and C++. These keywords
all start with the prefix `__arm_`. (However, not everything that
starts with `__arm_` is a keyword.)
The keywords are modeled after standard `[[…]]` attributes and
fulfill a similar role to them. However, the C++ standard says that
“any [non-standard attribute] that is not recognized by the
implementation is ignored” `[dcl.attr.grammar]`. It is therefore not
appropriate to use standard attributes for properties that affect the
type system, that affect the binary interface of the generated code, or
that must be honored for other reasons. ACLE uses keywords for some of
these properties instead. The keywords are therefore known as
“keyword attributes”.
A keyword attribute can appear wherever a standard `[[…]]` attribute
can appear. Following the terminology of the C++ standard, a keyword
attribute “appertains” to whatever a standard attribute would appertain
to. For example, consider the placeholders A, B, C and D in the
following function declaration:
``` c
/*A*/ void /*B*/ f /*C*/ (void) /*D*/;
```
Here:
* Attributes in position A appertain to the function declaration `f`.
* Attributes in position B appertain to the return type (`void`).
* Attributes in position C appertain to the function declaration `f`,
as for A.
* Attributes in position D appertain to the type of `f` (`void ()(void)`).
Position A is preferred over position C for ACLE code. This is because
position A can also be used for GNU-style attributes, whereas position C
cannot.
The table below lists all the ACLE keyword attributes. The “Target” column
says what the keyword is allowed to appertain to. For example, a function
type keyword can appear in position D above, but it cannot appear in
positions A, B or C.
Keyword attributes are only guaranteed to be supported by compilers that
predefine the associated macro to a nonzero value.
<!-- Please keep this table sorted alphabetically. -->
| **Name** | **Target** | **Predefined macro** |
| ----------------------------------------------------------- | --------------------- | --------------------------------- |
| [`__arm_locally_streaming`](#arm_locally_streaming) | function declaration | `__ARM_FEATURE_LOCALLY_STREAMING` |
| [`__arm_new_za`](#arm_new_za) | function declaration | `__ARM_FEATURE_SME` |
| [`__arm_preserves_za`](#arm_preserves_za) | function type | `__ARM_FEATURE_SME` |
| [`__arm_shared_za`](#arm_shared_za) | function type | `__ARM_FEATURE_SME` |
| [`__arm_streaming`](#arm_streaming) | function type | `__ARM_FEATURE_SME` |
| [`__arm_streaming_compatible`](#arm_streaming_compatible) | function type | `__ARM_FEATURE_SME` |
Using a keyword attribute multiple times is equivalent to using it once.
## Intrinsics
ACLE standardizes intrinsics to access various features of the
Arm ® architecture. It also standardizes a set of [header
files](#header-files) that provide access to these intrinsics.
Whether intrinsics are macros, functions or built-in operators is
unspecified. For example:
* It is unspecified whether applying #undef to an intrinsic
removes the name from visibility
* It is unspecified whether it is possible to take the address
of an intrinsic
However, each argument must be evaluated at most once. So this
definition is acceptable:
``` c
#define __rev(x) __builtin_bswap32(x)
```
but this is not:
``` c
#define __rev(x) ((((x) & 0xff) << 24) | (((x) & 0xff00) << 8) | \
(((x) & 0xff0000) >> 8) | ((x) >> 24))
```
### Constant arguments to intrinsics
Some intrinsics may require arguments that are constant at compile-time,
to supply data that is encoded into the immediate fields of an
instruction. Typically, these intrinsics require an
integral-constant-expression in a specified range, or sometimes a string
literal. An implementation should produce a diagnostic if the argument
does not meet the requirements.
## Header files
ACLE standardizes various header files that provide access to
[intrinsics](#intrinsics) and their associated data types.
It also standardizes [feature test macros](#feature-test-macros)
that indicate which header files are available.
Some architecture features have a dedicated header file;
for example, [`<arm_neon.h>`](#arm_neon.h) provides access to the
[Advanced SIMD (Neon) intrinsics](#advanced-simd-neon-intrinsics).
[`arm_acle.h`](#arm_acle.h) provides a catch-all for intrinsics that
do not belong to a more specific header file.
These headers behave as standard library headers; repeated inclusion has
no effect beyond the first include.
Except where noted otherwise, it is unspecified whether the ACLE headers
include the standard headers `<assert.h>`, `<stdint.h>` or
`<inttypes.h>`. However, the ACLE headers will not define the standard
type names (for example `uint32_t`) except by inclusion of the standard
headers. Arm recommends that you include the standard headers explicitly
if the associated types and macros are needed.
In C++, the following source code fragments are expected to work
correctly:
``` c
#include <stdint.h>
// UINT64_C not defined here since we did not set __STDC_FORMAT_MACROS
...
#include <arm_neon.h>
```
and:
``` c
#include <arm_neon.h>
...
#define __STDC_FORMAT_MACROS
#include <stdint.h>
// ... UINT64_C is now defined
```
### `<arm_acle.h>`
`<arm_acle.h>` provides access to intrinsics that do not belong
to the more specific header files below. These intrinsics are in the
C implementation namespace and begin with double underscores. It is
unspecified whether they are available without the header being
included. The `__ARM_ACLE` macro should be tested before including the
header:
``` c
#ifdef __ARM_ACLE
#include <arm_acle.h>
#endif /* __ARM_ACLE */
```
### `<arm_fp16.h>`
`<arm_fp16.h>` is provided to define the scalar 16-bit floating point
arithmetic intrinsics. As these intrinsics are in the user namespace,
an implementation would not normally define them until the header is
included. The `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC` feature macro
should be tested before including the header:
``` c
#ifdef __ARM_FEATURE_FP16_SCALAR_ARITHMETIC
#include <arm_fp16.h>
#endif /* __ARM_FEATURE_FP16_SCALAR_ARITHMETIC */
```
### `<arm_bf16.h>`
`<arm_bf16.h>` is provided to define the 16-bit brain floating point
arithmetic intrinsics. As these intrinsics are in the user namespace,
an implementation would not normally define them until the header is
included. The `__ARM_FEATURE_BF16` feature macro
should be tested before including the header:
``` c
#ifdef __ARM_FEATURE_BF16
#include <arm_bf16.h>
#endif /* __ARM_FEATURE_BF16 */
```
When `__ARM_BF16_FORMAT_ALTERNATIVE` is defined to `1` the only scalar
instructions available are conversion intrinsics between `bfloat16_t` and
`float32_t`. These instructions are:
* `vcvth_bf16_f32` (convert float32_t to bfloat16_t)
* `vcvtah_f32_bf16` (convert bfloat16_t to float32_t)
### `<arm_neon.h>`
`<arm_neon.h>` is provided to define the [Advanced SIMD (Neon)
intrinsics](#advanced-simd-neon-intrinsics) and associated
[data types](#vector-data-types). As these intrinsics and data types are
in the user namespace, an implementation would not normally define them
until the header is included. The `__ARM_NEON` macro should be tested
before including the header:
``` c
#ifdef __ARM_NEON
#include <arm_neon.h>
#endif /* __ARM_NEON */
```
Including `<arm_neon.h>` will also cause the following header files
to be included, if the header files are available:
* [`<arm_fp16.h>`](#arm_fp16.h)
* [`<arm_bf16.h>`](#arm_bf16.h)
<!-- Do not remove the following `span`, it is needed to create an
anchor that can be referred via an internal hyperlink to the section
following it. --><span id="arm_sve.h"></span>
### `<arm_sve.h>`
`<arm_sve.h>` defines data types and intrinsics for SVE and its
extensions; see [SVE language extensions and
intrinsics](#sve-language-extensions-and-intrinsics) for details.
You should test the `__ARM_FEATURE_SVE` macro before including the
header:
``` c
#ifdef __ARM_FEATURE_SVE
#include <arm_sve.h>
#endif /* __ARM_FEATURE_SVE */
```
Including `<arm_sve.h>` also includes the following header files:
* `<stdint.h>`
* `<stdbool.h>` (for C only)
* [`<arm_fp16.h>`](#arm_fp16.h)
* [`<arm_bf16.h>`](#arm_bf16.h) (if available)
### `<arm_neon_sve_bridge.h>`
`<arm_neon_sve_bridge.h>` defines intrinsics for moving data between
Neon and SVE vector types; see [NEON-SVE Bridge](#neon-sve-bridge)
for details. The `__ARM_NEON_SVE_BRIDGE` macro should be tested
before including the header:
``` c
#ifdef __ARM_NEON_SVE_BRIDGE
#include <arm_neon_sve_bridge.h>
#endif /* __ARM_NEON_SVE_BRIDGE */
```
Including `<arm_neon_sve_bridge.h>` will also include
[`<arm_neon.h>`](#arm_neon.h) and [`<arm_sve.h>`](#arm_sve.h).
### `<arm_mve.h>`