List File In C (.LST)

Question

After compiling some code, the compiler generates a bunch of files. I have statistics, symbols, call tree, errors, list, debug and exe. I have figured out what each means, except for the list file. What is the function of the list file. Is it for the user or the computer/embedded system itself?

Answer 1

A list file (.LST) contains a block of C code [commented out by a sequence of period characters] followed by the assembly code for that block.

---

For example:

....................     return FALSE; 
0046:  MOVLW  00
0047:  MOVWF  21
0048:  GOTO   049

Answer 2

The exact contents of the list file varies slightly by tool and chip being used.

The major part of the file will be the translation of the C source code into assembly instructions that has been performed by the compiler. This is useful for debugging the code and to check on the efficiency of the compiler when translating certain source code constructs. In the example below each Cline is given a line number and the assembler listed after. (this example is for the AVR32 processor).

171                  /**********************************************************
172                  *   Test for a receive interrupt
173                  **********************************************************/
174              if ( USART_CHANNEL[ Channel ] -> CSR.rxrdy )
  000008 F8051502      LSL       R5,R12,0x2
  00000C ........      MOV       R7,LWRD(USART_CHANNEL)
  000010 EA17....      ORH       R7,HWRD(USART_CHANNEL)
  000014 EE0C0027      ADD       R7,R7,R12<<0x2
  000018 6E0C          LD.w      R12,R7[0x0]
  00001A ........      MOV       R6,LWRD(Serial_Receive_Queue)
  00001E EA16....      ORH       R6,HWRD(Serial_Receive_Queue)
  000022 785B          LD.w      R11,R12[0x14]
  000024 A19B          LSR       R11,0x1
  000026 C0B2          BRCC      ??USART_Process_Interrupt_1:C

The HEX values that are shown as "...." above are addresses that are not known at compile time, they are symbols that will be resolved at link time.

The list file will also typically give some statistics regarding the code size, RAM requirements and the stack usage for the module being compiled. Again IAR toolset for the AVR32

Maximum stack usage in bytes:

 Function                      CSTACK
 --------                      ------
 Serial_Ports_Initialise          36
   -> gpio_enable_module          36
   -> usart_init_rs232            36
   ->   Indirect call             36
   ->   Indirect call             36
   ->   Indirect call             36
   ->   Indirect call             36
 Serial_Transmit_With_Length      20
   -> xQueueGenericSend           20
   -> vTaskDelay                  20
 USART0_INT_Handler                0
   -> USART_Process_Interrupt      0
 USART1_INT_Handler                0
   -> USART_Process_Interrupt      0
 USART2_INT_Handler                0
   -> USART_Process_Interrupt      0
 USART_Process_Interrupt          32
   -> xQueueGenericSendFromISR    32
   -> xQueueReceiveFromISR        32


   Segment part sizes:

     Function/Label                   Bytes
     --------------                   -----
     Serial_Receive_Queue               24
     Serial_Transmit_Queue
     USART_CHANNEL                      12
     USART0_INT_Handler                  8
     USART1_INT_Handler                  8
     USART2_INT_Handler                 12
     USART_Process_Interrupt           112
     Serial_Ports_Initialise           172
     USART_Channel_In_Use               56
     USART_GPIO_MAP
     USART_OPTIONS
     Serial_Transmit_With_Length       116
     ?<Initializer for USART_CHANNEL>   12
     ??USART1_INT_Handler??handle        4
      Others                            24



 400 bytes in segment CODE32
  56 bytes in segment DATA32_C
  12 bytes in segment DATA32_I
  12 bytes in segment DATA32_ID
  24 bytes in segment DATA32_Z
  28 bytes in segment EVSEG
   4 bytes in segment HTAB
  24 bytes in segment INITTAB

 400 bytes of CODE  memory
 100 bytes of CONST memory (+ 24 bytes shared)
  36 bytes of DATA  memory

Errors: none
Warnings: 1

There will also be any error messages or warnings generated inserted at the relevant line of code.

The List file can therefore be used as an aid to estimate stack and memory usage, although stack usage is a highly intractable problem in any embedded system and to see the assembler level code produced by the compiler.

From experience, the list file is not particularly useful when using a source level debugging tool - generally this shows the relevant disassembled code directly.