|
1 | 1 | --- |
2 | 2 | title: "ARM Assembler command-line reference" |
3 | 3 | description: "Reference guide to the Microsoft ARM assembler command-line options." |
4 | | -ms.date: "02/09/2020" |
| 4 | +ms.date: 05/09/2022 |
5 | 5 | ms.assetid: f7b89478-1ab5-4995-8cde-a805f0462c45 |
6 | 6 | --- |
7 | 7 | # ARM Assembler command-line reference |
8 | 8 |
|
9 | | -This article provides command-line information about the Microsoft ARM assembler, **armasm**. **armasm** assembles ARMv7 Thumb assembly language into the Microsoft implementation of the Common Object File Format (COFF). The linker can link COFF code objects produced by both the ARM assembler and the C compiler. It can link either together with object libraries created by the librarian. |
| 9 | +The Microsoft ARM assemblers, **armasm** and **armasm64**, support several command-line options. By default, **armasm** assembles ARMv7 Thumb assembly language into the Microsoft implementation of the Common Object File Format (COFF). The **armasm64** assembler creates COFF object code for ARM64 and ARM64EC targets. The linker can link COFF code objects produced by both the ARM assembler and the C/C++ compiler. It can link either together with object libraries created by the librarian. |
10 | 10 |
|
11 | 11 | ## Syntax |
12 | 12 |
|
13 | 13 | > **`armasm`** [*options*] *source_file* *object_file*\ |
14 | | -> **`armasm`** [*options*] **`-o`** *object_file* *source_file* |
| 14 | +> **`armasm`** [*options*] *source_file* |
| 15 | +
|
| 16 | +> **`armasm64`** [*options*] *source_file* *object_file*\ |
| 17 | +> **`armasm64`** [*options*] *source_file* |
15 | 18 |
|
16 | 19 | ### Parameters |
17 | 20 |
|
18 | 21 | *options*\ |
19 | 22 | A combination of zero or more of the following options: |
20 | 23 |
|
| 24 | +- **`-16`**\ |
| 25 | + Available only in **armasm**. Assemble source as 16-bit Thumb instructions. This option is the default. |
| 26 | + |
| 27 | +- **`-32`**\ |
| 28 | + Available only in **armasm**. Assemble source as 32-bit ARM instructions. |
| 29 | + |
| 30 | +- **`-coff_thumb2_only`**\ |
| 31 | + Available only in **armasm**. Allow only Thumb-2 code. |
| 32 | + |
| 33 | +- **`-errorReport:`** *option*\ |
| 34 | + This option is deprecated. In Windows Vista and later, error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. |
| 35 | + |
21 | 36 | - **`-errors`** *filename*\ |
22 | | - Redirect error and warning messages to *filename*. |
| 37 | + **`-e`** *filename*\ |
| 38 | + Redirect error and warning messages to *filename*. By default, these messages are sent to `stdout`. |
23 | 39 |
|
24 | | -- **`-i`** *dir*[**`;`**<em>dir</em>]\ |
25 | | - Add the specified directories to the include search path. |
| 40 | +- **`-funcOverride:`** *function_name*\ |
| 41 | + Available only in **armasm64**. Emit function overriding support for *function_name*. |
26 | 42 |
|
27 | | -- **`-predefine`** *directive*\ |
28 | | - Specify a SETA, SETL, or SETS directive to predefine a symbol.\ |
29 | | - Example: `armasm.exe -predefine "COUNT SETA 150" source.asm`\ |
30 | | - For more information, see the [ARM Compiler armasm Reference Guide](https://developer.arm.com/documentation/dui0802/latest/). |
| 43 | +- **`-g`**\ |
| 44 | + Generate debugging information. |
31 | 45 |
|
32 | | -- **`-nowarn`**\ |
33 | | - Disable all warning messages. |
| 46 | +- **`-gh:SHA1`**\ |
| 47 | + Use the SHA-1 cryptographic hash algorithm to generate a checksum of each source file in debug info. Overrides **`-gh:SHA256`**. |
34 | 48 |
|
35 | | -- **`-ignore`** *warning*\ |
36 | | - Disable the specified warning. For possible values, see the section about warnings. |
| 49 | +- **`-gh:SHA256`**\ |
| 50 | + Use the SHA-256 cryptographic hash algorithm to generate a checksum of each source file in debug info. This option is on by default in Visual Studio 2022 version 17.0 and later. |
| 51 | + |
| 52 | +- **`-guard:ehcont`**[**`-`**]\ |
| 53 | + Generate a sorted list of the relative virtual addresses (RVA) of all the valid exception handling continuation targets for a binary. It's used at runtime for `NtContinue` and `SetThreadContext` instruction pointer validation. By default, **`-guard:ehcont`** is off and must be explicitly enabled. To explicitly disable this option, use **`-guard:ehcont-`**. This option is available in Visual Studio 2019 version 16.7 and later. The feature is supported for 64-bit processes on a 64-bit OS. |
37 | 54 |
|
38 | 55 | - **`-help`**\ |
39 | | - Print the command-line help message. |
| 56 | + **`-h`**\ |
| 57 | + Print the command-line help message. |
| 58 | + |
| 59 | +- **`-i`** *dir*[**`;`** *dir*]\ |
| 60 | + Add one or more specified directories to the include search path. Separate directories by using a semi-colon (`;`). |
| 61 | + |
| 62 | +- **`-ignore`** *warning_number*\ |
| 63 | + Disable the specified warning number. For possible values, see [ARM Assembler diagnostic messages](arm-assembler-diagnostic-messages.md). |
| 64 | + |
| 65 | +- **`-list`** *list_file*\ |
| 66 | + Create a detailed listing of the generated assembly language to *list_file*. The *list_file* parameter is optional. If it's omitted, the assembler appends *`.lst`* to the base name of *source_file* to create the listing file. |
40 | 67 |
|
41 | 68 | - **`-machine`** *machine*\ |
42 | | - Specify the machine type to set in the PE header. Possible values for *machine* are:\ |
43 | | - **ARM**—Sets the machine type to IMAGE_FILE_MACHINE_ARMNT. This option is the default.\ |
44 | | - **THUMB**—Sets the machine type to IMAGE_FILE_MACHINE_THUMB. |
| 69 | + Specify the machine type to set in the PE header. In **armasm**, possible values for *machine* are: |
| 70 | + - **ARM**—Sets the machine type to `IMAGE_FILE_MACHINE_ARMNT`. This option is the default. |
| 71 | + - **THUMB**—Sets the machine type to `IMAGE_FILE_MACHINE_THUMB`. |
45 | 72 |
|
46 | | -- **`-oldit`**\ |
47 | | - Generate ARMv7-style IT blocks. By default, ARMv8-compatible IT blocks are generated. |
| 73 | + In **armasm64**, possible values are: |
| 74 | + - **ARM64**—Sets the machine type to `IMAGE_FILE_MACHINE_ARM64`. This option is the default. |
| 75 | + - **ARM64EC**—Sets the machine type to `IMAGE_FILE_MACHINE_ARM64EC`. |
48 | 76 |
|
49 | | -- **`-via`** *filename*\ |
50 | | - Read additional command-line arguments from *filename*. |
| 77 | +- **`-noesc`**\ |
| 78 | + **`-noe`**\ |
| 79 | + Ignore C-style escaped special characters, such as `\n` or `\t`. |
51 | 80 |
|
52 | | -- **`-16`**\ |
53 | | - Assemble source as 16-bit Thumb instructions. This option is the default. |
| 81 | +- **`-nologo`**\ |
| 82 | + Suppress the copyright banner. |
54 | 83 |
|
55 | | -- **`-32`**\ |
56 | | - Assemble source as 32-bit ARM instructions. |
| 84 | +- **`-nowarn`**\ |
| 85 | + **`-now`**\ |
| 86 | + Disable all warning messages. |
57 | 87 |
|
58 | | -- **`-g`**\ |
59 | | - Generate debugging information. |
| 88 | +- **`-o`** *object_file*\ |
| 89 | + Specify the name of the object (output) file. The **`-o`** option is optional; you can instead specify an object file name as the last element of the command line. |
60 | 90 |
|
61 | | -- **`-errorReport:`** *option*\ |
62 | | - This option is deprecated. Starting in Windows Vista, error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. |
| 91 | +- **`-oldit`**\ |
| 92 | + Available only in **armasm**. Generate ARMv7-style IT blocks. By default, ARMv8-compatible IT blocks are generated. |
| 93 | + |
| 94 | +- **`-predefine`** *directive*\ |
| 95 | + **`-pd`** *directive*\ |
| 96 | + Specify a SETA, SETL, or SETS directive to predefine a symbol.\ |
| 97 | + Example: `armasm.exe -predefine "COUNT SETA 150" source.asm`\ |
| 98 | + For more information, see the [ARM Compiler armasm Reference Guide](https://developer.arm.com/documentation/dui0802/latest/). |
| 99 | + |
| 100 | +- **`-sourcelink:`** *sourcelink_filename*\ |
| 101 | + *sourcelink_filename* specifies a JSON-formatted configuration file that contains a simple mapping of local file paths to URLs for source files to display in the debugger. For more information on the format of this file, see [Source Link JSON Schema](https://github.com/dotnet/designs/blob/master/accepted/2020/diagnostics/source-link.md#source-link-json-schema). Source Link is a language- and source-control agnostic system for providing source debugging for binaries. Source Link is supported for native binaries starting in Visual Studio 2017 version 15.8. For an overview of Source Link, see [Source Link](https://github.com/dotnet/designs/blob/master/accepted/2020/diagnostics/source-link.md). For information on how to use Source Link in your projects, and how to generate the SourceLink file as part of your project, see [Using Source Link](https://github.com/dotnet/sourcelink#using-source-link-in-c-projects). |
| 102 | + |
| 103 | +- **`-via`** *filename*\ |
| 104 | + Read extra command-line arguments from *filename*. |
63 | 105 |
|
64 | 106 | *source_file*\ |
65 | 107 | The name of the source file. |
66 | 108 |
|
67 | 109 | *object_file*\ |
68 | | -The name of the object (output) file. |
| 110 | +The last element of the command line can specify the name of the object (output) file. If it's omitted, and no **`-o`** option is specified, the assembler appends *`.obj`* to the base name of *source_file* to create the object file. |
69 | 111 |
|
70 | 112 | ## Remarks |
71 | 113 |
|
72 | 114 | The following example demonstrates how to use armasm in a typical scenario. First, use armasm to build an assembly language source (.asm) file to an object (.obj) file. Then, use the CL command-line C compiler to compile a source (.c) file, and also specify the linker option to link the ARM object file. |
73 | 115 |
|
74 | 116 | ```cmd |
75 | | -armasm myasmcode.asm -o myasmcode.obj |
| 117 | +armasm -o myasmcode.obj myasmcode.asm |
76 | 118 | cl myccode.c /link myasmcode.obj |
77 | 119 | ``` |
78 | 120 |
|
|
0 commit comments