Keil Logo

Technical Support

On-Line Manuals

Compiler Reference Guide

Preface armclang Command-line Options Support level definitions Summary of armclang command-line options -C -c -D -E -e -fbare-metal-pie -fbracket-depth=N -fcommon, -fno-common -fdata-sections, -fno-data-sections -ffast-math, -fno-fast-math -ffixed-rN -ffp-mode -ffunction-sections, -fno-function-sections -fident, -fno-ident @file -fldm-stm, -fno-ldm-stm -fno-builtin -fno-inline-functions -flto, -fno-lto -fexceptions, -fno-exceptions -fomit-frame-pointer, -fno-omit-frame-pointer -fropi, -fno-ropi -fropi-lowering, -fno-ropi-lowering -frwpi, -fno-rwpi -frwpi-lowering, -fno-rwpi-lowering -fshort-enums, -fno-short-enums -fshort-wchar, -fno-short-wchar -fstack-protector, -fstack-protector-all, -fstack- -fstrict-aliasing, -fno-strict-aliasing -ftrapv -fvectorize, -fno-vectorize -fvisibility -fwrapv -g, -gdwarf-2, -gdwarf-3, -gdwarf-4 -I -include -L -l -M, -MM -MD, -MMD -MF -MG -MP -MT -march -marm -masm -mbig-endian -mbranch-protection -mcmse -mcpu -mexecute-only -mfloat-abi -mfpu -mimplicit-it -mlittle-endian -mmemtag-stack, -mno-memtag-stack -mno-neg-immediates -moutline, -mno-outline -mpixolib -munaligned-access, -mno-unaligned-access -mthumb -nostdlib -nostdlibinc -o -O -pedantic -pedantic-errors -Rpass -S -save-temps -std --target -U -u -v --version --version_number --vsn -W -Wl -Xlinker -x -### Compiler-specific Keywords and Operators Compiler-specific Function, Variable, and Type Att Compiler-specific Intrinsics Compiler-specific Pragmas Other Compiler-specific Features Standard C Implementation Definition Standard C++ Implementation Definition armclang Integrated Assembler armclang Inline Assembler

-mbranch-protection

1.51 -mbranch-protection

Protects branches using Pointer Authentication and Branch Target Identification.

Default

The default is -mbranch-protection=none.

Syntax

-mbranch-protection=protection

Parameters

protection can specify the level or type of protection.

When specifying the level of protection, it can be one of:

none
This disables all types of branch protection.
standard
This enables all types of branch protection to their standard values. The standard protection is equivalent to -mbranch-protection=bti+pac-ret.

When specifying the type of protection, you can enable one or more types of protection by using the + separator:

bti
This enables branch protection using Branch Target Identification.
pac-ret

This enables branch protection using Pointer Authentication using key A. This protects functions that save the Link Register (LR) on the stack. This does not generate branch protection code for leaf functions that do not save the LR on the stack.

If you use the pac-ret type of protection, you can specify additional parameters to modify the pointer authentication protection using the + separator:

leaf
This enables pointer authentication on all leaf functions, including the leaf functions that do not save the Link Register on the stack.
b-key
This enables pointer authentication with Key B, rather than Key A.
Key A and Key B refer to secret values that are used for generating a signature for authenticating the return addresses.

Operation

Use -mbranch-protection to enable or disable branch protection for your code. Branch protection protects your code from Return Oriented Programming (ROP) and Jump Oriented Programming (JOP) attacks. To protect your code from ROP attacks, enable protection using Pointer Authentication. To protect your code from JOP attacks, you must enable protection using Pointer Authentication and Branch Target Identification.

When compiling with pac-ret, for Armv8.3-A or later architectures, the compiler uses pointer authentication instructions that are not available for earlier architectures. The resulting code cannot be run on earlier architectures. However, when compiling with pac-ret for architectures before Armv8.3-A, the compiler uses pointer authentication instructions from the hint space. These instructions do not provide the branch protection in architectures before Armv8.3-A, but these instructions do provide branch protection when run on Armv8.3-A or later. This is useful when creating libraries, with branch protection, that you want to run on any Armv8-A architecture.

When compiling with bti, the compiler generates BTI instructions. These BTI instructions provide branch protection on Armv8.5-A or later architectures. However, on earlier architectures, these instructions are part of the hint space, and therefore these instructions are effectively NOP instructions that do not provide the BTI branch protection.

If you enable branch protection armlink automatically selects the library with branch protection. You can override the selected library by using the armlink --library_security option to specify the library that you want to use.

Branch protection using pointer authentication and branch target identification are only available in AArch64.

For more information on pointer authentication, see Pointer authentication in AArch64 state in the Arm Architecture Reference Manual for Armv8-A architecture profile.

For more information on branch target identification, see BTI in the A64 Instruction Set Architecture: Armv8, for Armv8-A architecture profile.

Examples

This enables the standard branch protection using Branch Target Identification and Pointer Authentication:

armclang --target=aarch64-arm-none-eabi -march=armv8.5-a -mbranch-protection=standard -c foo.c

This enables the branch protection using pointer authentication, but does not use branch target identification:

armclang --target=aarch64-arm-none-eabi -march=armv8.5-a -mbranch-protection=pac-ret -c foo.c

This enables the branch protection using pointer authentication using Key B, but does not use branch target identification:

armclang --target=aarch64-arm-none-eabi -march=armv8.5-a -mbranch-protection=pac-ret+b-key -c foo.c

This enables the branch protection using pointer authentication, including protection for all leaf functions, and also uses branch target identification:

armclang --target=aarch64-arm-none-eabi -march=armv8.5-a -mbranch-protection=bti+pac-ret+leaf -c foo.c

This enables branch protection using pointer authentication. However, since the specified architecture is Armv8-A, the compiler generates pointer authentication instructions that are from the encoding space of hint instructions. These instructions are effectively NOP instructions and do not provide branch protection on architectures before Armv8.3-A. However these instructions do provide branch protection when run on Armv8.3-A or later architectures.

armclang --target=aarch64-arm-none-eabi -march=armv8-a -mbranch-protection=pac-ret -c foo.c

This enables branch protection using branch target identification. The compiler generates BTI instructions that are effectively NOP instructions and do not provide branch protection on architectures before Armv8.5-A. However these instructions do provide branch protection when run on Armv8.5-A or later architectures.

armclang --target=aarch64-arm-none-eabi -march=armv8-a -mbranch-protection=bti -c foo.c
Non-ConfidentialPDF file icon PDF version100067_0612_00_en
Copyright © 2014–2019 Arm Limited or its affiliates. All rights reserved. 
  Arm logo
Important information

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies.

Change Settings

Privacy Policy Update

Arm’s Privacy Policy has been updated. By continuing to use our site, you consent to Arm’s Privacy Policy. Please review our Privacy Policy to learn more about our collection, use and transfers
of your data.