6.3 Assembly List Files

The assembler will produce an assembly list file if instructed. The xc8-cc driver option -Wa,-a is typically used to request generation of such a file (see 4.6.10 Mapped Assembler Options).

The assembly list file shows the assembly output produced by the compiler for both C and assembly source code. If the assembler optimizers are enabled, the assembly output can be different than assembly source code. It is still useful for assembly programming.

The list file is in a human-readable form and cannot be used by the assembly as a source file. It differs from an assembly output file in that it contains address and op-code data.

The assembler optimizer simplifies some expressions and removes some assembler directives from the listing file for clarity, although these directives are included in the true assembly output files. If you are using the assembly list file to look at the code produced by the compiler, you might wish to turn off the assembler optimizer so that all the compiler-generated directives are shown in the list file. Re-enable the optimizer when continuing development. 4.6.6 Options for Controlling Optimization gives more information on controlling the optimizers.

Provided that the link stage has successfully concluded, the listing file is updated by the linker so that it contains absolute addresses and symbol values. Thus, you can use the assembler list file to determine the position and exact op codes of instructions.

Tick marks “'” in the assembly listing, next to addresses or opcodes, indicate that the linker did not update the list file, most likely due to a compiler error, or a compiler option that stopped compilation before the link stage. For example, in the following listing:

85  000A' 027F                      subwf   127,w
86  000B' 1D03                      skipz
87  000C' 2800'                     goto    u15

These marks indicate that addresses are just address offsets into their enclosing psect, and that opcodes have not been fixed up. Any address field in the opcode that has not been fixed up is shown with a value of 0.

There is a single assembly list file produced by the assembler for each assembly file passed to it. So, there is a single file produced for all the C source code in a project, including p-code based library code. The file also contains some of the C initialization that forms part of the runtime startup code. There is also a single file produced for each assembly source file. Typically, there is at least one assembly file in each project. It contains some of the runtime startup file and is typically named startup.s.