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="../../application/executable/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.