Stack Trace Reader

Principle

Stack Trace Reader is a MicroEJ tool that reads and decodes the MicroEJ stack traces. When an exception occurs, the Core Engine prints the stack trace on the standard output System.out. The class names, non-required types names(see Types), and method names obtained are encoded with a MicroEJ internal format. This internal format prevents embedding all class names and method names in the executable image to save some memory space. The Stack Trace Reader tool allows you to decode the stack traces by replacing the internal class names and method names with their real names. It also retrieves the line numbers in the Application.

Functional Description

The Stack Trace Reader reads the debug information from the fully linked ELF file (the ELF file that contains the Core Engine, the other libraries, the BSP, the OS, and the compiled Application). It prints the decoded stack trace.

When Multi-Sandbox capability is enabled, the stack trace reader can simultaneously decode heterogeneous stack traces with lines owned by different Sandboxed Applications and the Kernel. Lines owned by the Kernel can be decoded with the Executable debug information file (optionally made available by your Kernel provider).

Use (Standalone Application)

For example, write the following new line to dump the currently executed stack trace on the standard output.

package com.mycompany;

public class Test {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
        new Exception().printStackTrace();
    }
}

To decode an application stack trace, the stack trace reader tool requires the application executable ELF file. In the case of a platform with full BSP connection (see BSP Connection Cases), the file is application.out in the output folder. In the other cases, the ELF file is generated by the C toolchain when building the BSP project (usually a .out or .axf file).

On successful deployment, the application is started on the device and the following trace is dumped on standard output.

VM START
Hello World from Gradle!
Exception in thread "main" @C:0x8070c30@
     at @C:0x8070c60@.@M:0x8075850:0x807585a@
     at @C:0x8070c30@.@M:0x80769a4:0x80769ba@
     at @C:0x8070c30@.@M:0x807857c:0x8078596@
     at @C:0x8070c00@.@M:0x8074e04:0x8074e1a@
     at @C:0x8070ce0@.@M:0x807601c:0x807603c@
     at @C:0x806fe10@.@M:0x807779c:0x80777b0@
     at @C:0x8070c00@.@M:0x8077b40:0x8077b4c@
     at @C:0x8070c00@.@M:0x80779b0:0x80779bb@

To decode the trace, execute the execTool task as followed:

./gradlew execTool --name=stackTraceDecrypter \
  --toolProperty="proxy.connection.connection.type=console" \
  --toolProperty="application.file=../../executable/application/application.out" \
  --toolProperty="additional.application.files=" \
  --console plain

Paste the previous trace dump into the console. The output of the Stack Trace Reader is the following:

=============== [ MicroEJ Core Engine Trace ] ===============
console:
[INFO] Paste the MicroEJ core engine stack trace here.
    VM START
    Hello World from Gradle!
    Exception in thread "main" @C:0x8070c30@
         at @C:0x8070c60@.@M:0x8075850:0x807585a@
         at @C:0x8070c30@.@M:0x80769a4:0x80769ba@
         at @C:0x8070c30@.@M:0x807857c:0x8078596@
         at @C:0x8070c00@.@M:0x8074e04:0x8074e1a@
         at @C:0x8070ce0@.@M:0x807601c:0x807603c@
         at @C:0x806fe10@.@M:0x807779c:0x80777b0@
         at @C:0x8070c00@.@M:0x8077b40:0x8077b4c@
         at @C:0x8070c00@.@M:0x80779b0:0x80779bb@
    VM START
    Hello World from Gradle!
    Exception in thread "main" java.lang.Throwable
         at java.lang.System.getStackTrace(Unknown Source)
         at java.lang.Throwable.fillInStackTrace(Throwable.java:82)
         at java.lang.Throwable.<init>(Throwable.java:32)
         at java.lang.Thread.dumpStack(Thread.java:573)
         at com.microej.Main.main(Main.java:22)
         at java.lang.MainThread.run(Thread.java:855)
         at java.lang.Thread.runWrapper(Thread.java:464)
         at java.lang.Thread.callWrapper(Thread.java:449)

Options

Option: Executable file

Option Name: application.file

Required?: Yes

Description:

Specify the full path of a full linked elf file.

Option: Additional object files

Option Name: additional.application.files

Required?: Yes

Option: Connection type

Option Name: proxy.connection.connection.type

Required?: Yes

Available values:

  • console
  • file
  • uart
  • socket

Description:

Specify the connection type between the device and PC.

Option: Port

Option Name: pcboardconnection.usart.pc.port

Required?: (For uart Connection Type)

Description:

Format: port name

Specifies the PC COM port:

  • Windows - COM1, COM2, ..., COM*n*
  • Linux - /dev/ttyS0, /dev/ttyS1, ..., /dev/ttyS*n*

Option: Baudrate

Option Name: pcboardconnection.usart.pc.baudrate

Required?: (For uart Connection Type)

Available values:

  • 9600
  • 38400
  • 57600
  • 115200

Description:

Defines the COM baudrate for PC-Device communication.

Option: Port

Option Name: pcboardconnection.socket.port

Required?: (For socket Connection Type)

Description:

IP port.

Option: Address

Option Name: pcboardconnection.socket.address

Required?: (For socket Connection Type)

Description:

IP address, on the form A.B.C.D. or empty.

Option: Stack trace file

Option Name: pcboardconnection.file.path

Required?:

Description:

Path to a stack trace file or empty.