DEV Community: ddupard

8051 What does SDCC do part 3 ?

ddupard — Sat, 15 Aug 2026 13:17:52 +0000

1. Introduction and Problem Statement

A good way to learn what a compiler really does when transforming a C source code into a binary is to disassemble the binary and compare it with the C source code. It is especially true for 8 bits microcontrollers like the 8051.

In order to test SDCC we are going to use the following C source code.

/* ========================================================================== *
 * Universal Test Corpus - Heterogeneous Architecture Analysis          *
 * ========================================================================== */


#include <stdint.h>

// 1. Global variables (testing absolute/relative addressing modes)
volatile uint32_t global_var_32 = 0xDEADBEEF;
volatile uint8_t  global_var_8  = 0x42;
const    char     string_const[] = "TARGET_STRING";

// 2. Function with parameter passing and local variables (stack / Frame Pointer test)
int32_t callee_function(int16_t a, int16_t b) {
    volatile int32_t local_result = 0;

    // Basic and mixed arithmetic operations (8, 16, 32 bits)
    local_result += (int32_t)(a * b);
    local_result -= (int32_t)(a / (b | 1)); // Avoid division by zero

    // Shift tests and logical operations (highly variable depending on ISAs)
    local_result = (local_result << 2) ^ 0x55AA55AA;
    local_result = (local_result >> 1) | (int32_t)global_var_8;

    return local_result;
}

// 3. Main function grouping complex control flows
int main(void) {
    volatile int32_t accumulator = 0;
    int16_t i;

    // Loop test (Conditional jumps, decrement, comparison tests)
    for (i = 0; i < 10; i++) {
        if (i == 5) {
            accumulator += 100;
        } else {
            accumulator += i;
        }
    }

    // Multiple branching test (Switch / Jump Table or cascaded if-else)
    switch (global_var_8) {
        case 0x10:
            accumulator += 10;
            break;
        case 0x20:
            accumulator += 20;
            break;
        default:
            accumulator -= 5;
            break;
    }

    // Function call (Stack management, save registers Link Register/PC)
    accumulator += callee_function((int16_t)accumulator, 3);

    // Pointer and indirect memory access test
    volatile uint32_t *ptr = (volatile uint32_t *)&global_var_32;
    *ptr = (uint32_t)accumulator;

    // Terminal infinite loop (classic for raw binaries / microcontrollers)
    while (1) {
        accumulator ^= *ptr;
    }

    return 0;
}

To compile it, we will use SDCC which produces an Intel HEX file. This file will be transformed in a ROM file using either objcopy or makebin (see below).

sdcc  "$SRC/test1.c" -o "8/test1_8051" 
objcopy -I ihex -O binary "8/test1_8051" "8/bin/test1_8051_bin" 
makebin -p "8/test1_8051" "8/bin/test1_8051.rom"

Moreover, to simulate the 8051, I use the MCU 8051 IDE (command mcu8051ide).

In this final part we will study the calling mechanism and what does the callee_function do

This C file is particularly interesting, because in a small source code we have a lot of different cases (for example, some of the variables have a 32 bits size).

2. Function call

// Function call (Stack management, save registers Link Register/PC)
    accumulator += callee_function((int16_t)accumulator, 3);

The above code is translated in the following code

  01F8 851382       MOV DPL, 13h
  01FB 851483       MOV DPH, 14h
  01FE 750D03       MOV 0Dh, #3h
  0201 750E00       MOV 0Eh, #0h
  0204 120071       LCALL L0013
  0207 AC82         MOV R4, DPL
  0209 AD83         MOV R5, DPH
  020B AEF0         MOV R6, B
  020D FF           MOV R7, A
  020E EC           MOV A, R4
  020F 2513         ADD A, 13h
  0211 F513         MOV 13h, A
  0213 ED           MOV A, R5
  0214 3514         ADDC A, 14h
  0216 F514         MOV 14h, A
  0218 EE           MOV A, R6
  0219 3515         ADDC A, 15h
  021B F515         MOV 15h, A
  021D EF           MOV A, R7
  021E 3516         ADDC A, 16h
  0220 F516         MOV 16h, A

See how the cast of accumulator variable is done. The accumulator is stored on 4 bytes at addresses 13h,14h,15h,16h.
Casting the 32 bits integer to a 16 bits integer is done by simply storing to DPL and DPH the value contained at address 13h and 14h by the isntructions

01F8 851382     MOV DPL, 13h
01FB 851483     MOV DPH, 14h

callee_function((int16_t)accumulator, 3);
int32_t callee_function(int16_t a, int16_t b) {

See how 3 is casted to a 16 bits integer because of the defintion of the callee_function

01FE 750D03     MOV 0Dh, #3h
0201 750E00     MOV 0Eh, #0h

In the absence of a sophisticated native stack for function arguments in the default memory model, the compiler often uses fixed locations in internal RAM (DATA) to pass parameters to subroutines.

because callee_function returns a 32 bits integer, we have the following lines

  0204 120071       LCALL L0013
  0207 AC82         MOV R4, DPL
  0209 AD83         MOV R5, DPH
  020B AEF0         MOV R6, B
  020D FF           MOV R7, A

and because we have an addition of the accumulator variable with the result of callee_function

// Function call (Stack management, save registers Link Register/PC)
    accumulator += callee_function((int16_t)accumulator, 3);

we have the following lines which does a simple addition of two 32 bits integers

  020E EC           MOV A, R4
  020F 2513         ADD A, 13h
  0211 F513         MOV 13h, A
  0213 ED           MOV A, R5
  0214 3514         ADDC A, 14h
  0216 F514         MOV 14h, A
  0218 EE           MOV A, R6
  0219 3515         ADDC A, 15h
  021B F515         MOV 15h, A
  021D EF           MOV A, R7
  021E 3516         ADDC A, 16h
  0220 F516         MOV 16h, A

3. Inside the function

// 2. Function with parameter passing and local variables (stack / Frame Pointer test)
int32_t callee_function(int16_t a, int16_t b) {
    volatile int32_t local_result = 0;

    // Basic and mixed arithmetic operations (8, 16, 32 bits)
    local_result += (int32_t)(a * b);
    local_result -= (int32_t)(a / (b | 1)); // Avoid division by zero

    // Shift tests and logical operations (highly variable depending on ISAs)
    local_result = (local_result << 2) ^ 0x55AA55AA;
    local_result = (local_result >> 1) | (int32_t)global_var_8;

    return local_result;
}

The above function is translated into a rather complicated code requiring us to divide it in several paragraphs

4. Inside the function: Initialization

L0013:
  0071 AE82     MOV R6, DPL          ; Save lower byte of first parameter
  0073 AF83     MOV R7, DPH          ; Save higher byte of first parameter

The first thing done by the function when called is to store the first parameter then the C line below is translated into the assembly lines below

 volatile int32_t local_result = 0;

  0075 E4       CLR A                ; 
  0076 F50F     MOV 0Fh, A           ; Initialize local_result to 0. 
  0078 F510     MOV 10h, A           ; Initialize local_result to 0
  007A F511     MOV 11h, A           ; Initialize local_result to 0
  007C F512     MOV 12h, A           ; Initialize local_result to 0

; local_result being a 32 bits integer, Bytes at adresses 0F,10h,11h,12h are used to store local_result

5. Inside the function: Arithmetic operations

 // Basic and mixed arithmetic operations (8, 16, 32 bits)
    local_result += (int32_t)(a * b);

the line above is translated in the block below

; start of   local_result += (int32_t)(a * b);

  007E 850D17   MOV 17h, 0Dh         ; Copy second parameter low byte to 17h
  0081 850E18   MOV 18h, 0Eh         ; Copy second parameter high byte to 18h
  0084 8E82     MOV DPL, R6          ; Restore 'a' low byte to DPL
  0086 8F83     MOV DPH, R7          ; Restore 'a' high byte to DPH
  0088 C007     PUSH 7h              ; Save register R7 on stack
  008A C006     PUSH 6h              ; Save register R6 on stack
  008C 120248   LCALL L0015          ; Call multiplication helper routine (a * b) see below
  008F AC82     MOV R4, DPL          ; Retrieve multiplication result low byte
  0091 AD83     MOV R5, DPH          ; Retrieve multiplication result high byte
  0093 D006     POP 6h               ; Restore register R6 from stack
  0095 D007     POP 7h               ; Restore register R7 from stack

  0097 ED       MOV A, R5            ; Move high byte of result to accumulator
  0098 33       RLC A                ; Rotate left through carry for sign extension
  0099 95E0     SUBB A, ACC          ; Propagate sign bit to form 32-bit value
  009B FB       MOV R3, A            ; Store extension byte in R3
  009C FA       MOV R2, A            ; Store extension byte in R2

  ; addition of two 32 bits integer
  009D EC       MOV A, R4            ; Get low byte of multiplication result
  009E 250F     ADD A, 0Fh           ; Add to accumulated lower result bytes
  00A0 F50F     MOV 0Fh, A           ; Update local result byte 0Fh
  00A2 ED       MOV A, R5            ; Get high byte of multiplication result
  00A3 3510     ADDC A, 10h          ; Add with carry to local result byte 10h
  00A5 F510     MOV 10h, A           ; Update local result byte 10h
  00A7 EB       MOV A, R3            ; Get sign extension byte
  00A8 3511     ADDC A, 11h          ; Add with carry to local result byte 11h
  00AA F511     MOV 11h, A           ; Update local result byte 11h
  00AC EA       MOV A, R2            ; Get sign extension byte
  00AD 3512     ADDC A, 12h          ; Add with carry to local result byte 12h
  00AF F512     MOV 12h, A           ; Update local result byte 12h

; end of   local_result += (int32_t)(a * b);

the code for the multiplication subroutine is below

L0015: ; code making the multiplication  (int32_t)(a * b);
  0248 E582         MOV A, DPL
  024A 8517F0       MOV B, 17h
  024D A4           MUL AB
  024E C582         XCH A, DPL
  0250 C0F0         PUSH B
  0252 8518F0       MOV B, 18h
  0255 A4           MUL AB
  0256 D0F0         POP B
  0258 25F0         ADD A, B
  025A C583         XCH A, DPH
  025C 8517F0       MOV B, 17h
  025F A4           MUL AB
  0260 2583         ADD A, DPH
  0262 F583         MOV DPH, A
  0264 22           RET

pretty straightforward

Then we have the division with the line below

 local_result -= (int32_t)(a / (b | 1)); // Avoid division by zero

the above line is translated into the following assembly code

; start of  local_result -= (int32_t)(a / (b | 1)); // Avoid division by zero

  00B1 AC0D     MOV R4, 0Dh          ; Retrieve original parameter 'b' low byte
  00B3 AD0E     MOV R5, 0Eh          ; Retrieve original parameter 'b' high byte
  00B5 7401     MOV A, #1h           ; Load immediate 1 for division safety check (b | 1)
  00B7 4C       ORL A, R4            ; Bitwise OR with 'b' low byte to prevent division by zero
  00B8 F517     MOV 17h, A           ; Store safe denominator low byte
  00BA 8D18     MOV 18h, R5          ; Store safe denominator high byte
  00BC 8E82     MOV DPL, R6          ; Restore 'a' low byte into DPL for division
  00BE 8F83     MOV DPH, R7          ; Restore 'a' high byte into DPH for division
  00C0 12028E   LCALL L0016          ; Call signed division helper routine (a / (b | 1)) see below

The lines below do the following operation local_result = local_result - result of the division

  00C3 AE82     MOV R6, DPL          ; Get division quotient low byte
  00C5 E583     MOV A, DPH           ; Get division quotient high byte
  00C7 FF       MOV R7, A            ; Store quotient high byte in R7
  00C8 33       RLC A                ; Sign extend quotient high byte
  00C9 95E0     SUBB A, ACC          ; Generate sign extension bits
  00CB FD       MOV R5, A            ; Store extension byte in R5
  00CC FC       MOV R4, A            ; Store extension byte in R4
  00CD E50F     MOV A, 0Fh           ; Load current accumulated result low byte
  00CF C3       CLR C                ; Clear carry flag for subtraction
  00D0 9E       SUBB A, R6           ; Subtract division result low byte
  00D1 F50F     MOV 0Fh, A           ; Update result byte 0Fh
  00D3 E510     MOV A, 10h           ; Load accumulated result byte 10h
  00D5 9F       SUBB A, R7           ; Subtract with borrow quotient high byte
  00D6 F510     MOV 10h, A           ; Update result byte 10h
  00D8 E511     MOV A, 11h           ; Load accumulated result byte 11h
  00DA 9D       SUBB A, R5           ; Subtract with borrow extension byte
  00DB F511     MOV 11h, A           ; Update result byte 11h
  00DD E512     MOV A, 12h           ; Load accumulated result byte 12h
  00DF 9C       SUBB A, R4           ; Subtract with borrow extension byte
  00E0 F512     MOV 12h, A           ; Update result byte 12h

; end of  local_result -= (int32_t)(a / (b | 1)); // Avoid division by zero

As you can see below the division subroutine is rather complicated but don't worry—a full explanation follows.

; all code for a / b  

L0019:
  0265 7A10         MOV R2, #10h
  0267 E4           CLR A
  0268 FB           MOV R3, A
  0269 FC           MOV R4, A
L0022:
  026A E582         MOV A, DPL
  026C 25E0         ADD A, ACC
  026E F582         MOV DPL, A
  0270 E583         MOV A, DPH
  0272 33           RLC A
  0273 F583         MOV DPH, A
  0275 EB           MOV A, R3
  0276 33           RLC A
  0277 FB           MOV R3, A
  0278 EC           MOV A, R4
  0279 33           RLC A
  027A FC           MOV R4, A
  027B EB           MOV A, R3
  027C 9517         SUBB A, 17h
  027E F5F0         MOV B, A
  0280 EC           MOV A, R4
  0281 9518         SUBB A, 18h
  0283 4006         JC L0021
  0285 FC           MOV R4, A
  0286 ABF0         MOV R3, B
  0288 438201       ORL DPL, #1h
L0021:
  028B DADD         DJNZ R2, L0022
  028D 22           RET

L0016: ; entry point of a / b 
  028E C2D5         CLR F0
  0290 E583         MOV A, DPH
  0292 30E70D       JNB ACC.7, L0017
  0295 D2D5         SETB F0
  0297 E4           CLR A
  0298 C3           CLR C
  0299 9582         SUBB A, DPL
  029B F582         MOV DPL, A
  029D E4           CLR A
  029E 9583         SUBB A, DPH
  02A0 F583         MOV DPH, A
L0017:
  02A2 E518         MOV A, 18h
  02A4 30E70D       JNB ACC.7, L0018
  02A7 B2D5         CPL F0
  02A9 E4           CLR A
  02AA C3           CLR C
  02AB 9517         SUBB A, 17h
  02AD F517         MOV 17h, A
  02AF E4           CLR A
  02B0 9518         SUBB A, 18h
  02B2 F518         MOV 18h, A
L0018:
  02B4 120265       LCALL L0019
  02B7 30D50B       JNB F0, L0020
  02BA E4           CLR A
  02BB C3           CLR C
  02BC 9582         SUBB A, DPL
  02BE F582         MOV DPL, A
  02C0 E4           CLR A
  02C1 9583         SUBB A, DPH
  02C3 F583         MOV DPH, A
L0020:
  02C5 22           RET

This routine implements a bit-by-bit 16-bit by 16-bit signed integer division (using a shift-and-subtract binary division algorithm).Here is how it works step-by-step:

Sign Handling and Preparation (L0016):

The code first handles signed numbers by determining and saving the final result's sign in a flag (F0). It then converts both the dividend (stored in DPTR) and the divisor (stored in memory addresses 17h-18h) into their absolute values.

Loop Initialization (L0019): MOV R2, #10h sets a loop counter to 16 (since it is a 16-bit division). The partial remainder (spread across registers R3 and R4) is initialized to zero.
The Core Algorithm (Shift & Subtract inside L0022):

Left Shift: On each iteration, the dividend (DPTR) and the remainder (R3:R4) are shifted left together by one bit using additions and rotations with carry (ADD A, ACC, RLC A), feeding the next highest bit of the dividend into the operation.
Divisor Subtraction: The code subtracts the divisor (17h-18h) from the partial remainder using SUBB.
Test and Adjustment:If the result is greater than or equal to zero (no borrow/no jump JC L0021), the subtraction is kept: the new remainder is saved in R3:R4, and a 1 is shifted into the lowest bit of the quotient (ORL DPL, #1h). If the result is negative (JC L0021), the subtraction is discarded (leaving a 0 bit in the quotient).

Loop Control and Finalization: The DJNZ R2, L0022 instruction repeats this process 16 times (once for each bit). Once finished, DPTR holds the resulting quotient, and L0016 restores the correct mathematical sign before returning.

Now that the arithmetic operations have been studied, it's time to study the shift operations

6. Inside the function: Shift operations

; start of    local_result = (local_result << 2) ^ 0x55AA55AA;
  00E2 E50F     MOV A, 0Fh           ; Load result byte 0Fh for shift left operation (<< 2)
  00E4 25E0     ADD A, ACC           ; Shift left by 1 (multiply by 2)
  00E6 FC       MOV R4, A            ; Save temporary shifted byte in R4
  00E7 E510     MOV A, 10h           ; Load result byte 10h
  00E9 33       RLC A                ; Rotate left through carry
  00EA FD       MOV R5, A            ; Save temporary shifted byte in R5
  00EB E511     MOV A, 11h           ; Load result byte 11h
  00ED 33       RLC A                ; Rotate left through carry
  00EE FE       MOV R6, A            ; Save temporary shifted byte in R6
  00EF E512     MOV A, 12h           ; Load result byte 12h
  00F1 33       RLC A                ; Rotate left through carry
  00F2 FF       MOV R7, A            ; Save temporary shifted byte in R7
  00F3 EC       MOV A, R4            ; Retrieve temporary byte for second shift left (total << 2)
  00F4 2C       ADD A, R4            ; Shift left by another 1 (total shift of 2)
  00F5 FC       MOV R4, A            ; Update R4 with final << 2 low byte
  00F6 ED       MOV A, R5            ; Get next byte
  00F7 33       RLC A                ; Rotate left through carry
  00F8 FD       MOV R5, A            ; Update R5
  00F9 EE       MOV A, R6            ; Get next byte
  00FA 33       RLC A                ; Rotate left through carry
  00FB FE       MOV R6, A            ; Update R6
  00FC EF       MOV A, R7            ; Get highest byte
  00FD 33       RLC A                ; Rotate left through carry
  00FE FF       MOV R7, A            ; Update R7 with final << 2 high byte
  00FF 74AA     MOV A, #0AAh         ; Load lower byte mask for XOR operation (^ 0x55AA55AA)
  0101 6C       XRL A, R4            ; Apply XOR mask to low byte
  0102 F50F     MOV 0Fh, A           ; Save back to working RAM
  0104 7455     MOV A, #55h          ; Load next byte of XOR mask (0x55)
  0106 6D       XRL A, R5            ; Apply XOR mask
  0107 F510     MOV 10h, A           ; Save back to working RAM
  0109 74AA     MOV A, #0AAh         ; Load next byte of XOR mask (0xAA)
  010B 6E       XRL A, R6            ; Apply XOR mask
  010C F511     MOV 11h, A           ; Save back to working RAM
; end of    local_result = (local_result << 2) ^ 0x55AA55AA;


Operation Summary: 
To execute the 2-bit left shift (<< 2), the compiler emulates a 32-bit multiplication by 4 by performing two successive shifts using additions and carry rotations (ADD and RLC) byte by byte across the registers. 

Once this global shift is complete, it applies the bitwise XOR operation (XRL) with the immediate mask 0x55AA55AA by combining constants (0xAA and 0x55) injected directly into the accumulator, before writing the final result back to working RAM.





  ; start of local_result = (local_result >> 1) | (int32_t)global_var_8;
  010E 7455     MOV A, #55h          ; Load upper byte mask of XOR constant
  0110 6F       XRL A, R7            ; Apply XOR mask to high byte
  0111 F512     MOV 12h, A           ; Save back to working RAM
  0113 E512     MOV A, 12h           ; Load high byte for right shift operation (>> 1)
  0115 A2E7     MOV C, ACC.7         ; Save sign bit into Carry flag
  0117 13       RRC A                ; Shift right through carry
  0118 FF       MOV R7, A            ; Update shifted byte
  0119 E511     MOV A, 11h           ; Load next byte down
  011B 13       RRC A                ; Shift right through carry
  011C FE       MOV R6, A            ; Update shifted byte
  011D E510     MOV A, 10h           ; Load next byte down
  011F 13       RRC A                ; Shift right through carry
  0120 FD       MOV R5, A            ; Update shifted byte
  0121 E50F     MOV A, 0Fh           ; Load low byte
  0123 13       RRC A                ; Shift right through carry
  0124 FC       MOV R4, A            ; Update low shifted byte
  0125 A80C     MOV R0, 0Ch          ; Load global variable global_var_8 address into R0
  0127 E4       CLR A                ; Clear accumulator
  0128 F9       MOV R1, A            ; Clear upper bytes for zero-extension of global_var_8
  0129 FA       MOV R2, A            ; Clear upper bytes
  012A FB       MOV R3, A            ; Clear upper bytes
  012B E8       MOV A, R0            ; Retrieve global_var_8 value into accumulator
  012C 4C       ORL A, R4            ; Bitwise OR low byte with global_var_8 (| global_var_8)
  012D F50F     MOV 0Fh, A           ; Update final low result byte
  012F E9       MOV A, R1            ; Get extension byte
  0130 4D       ORL A, R5            ; Bitwise OR with second result byte
  0131 F510     MOV 10h, A           ; Update result byte
  0133 EA       MOV A, R2            ; Get extension byte
  0134 4E       ORL A, R6            ; Bitwise OR with third result byte
  0135 F511     MOV 11h, A           ; Update result byte
  0137 EB       MOV A, R3            ; Get extension byte
  0138 4F       ORL A, R7            ; Bitwise OR with high result byte
  0139 F512     MOV 12h, A           ; Update final high result byte
  ; end of local_result = (local_result >> 1) | (int32_t)global_var_8;

Operation Summary:
To complete the sequence, the compiler finishes the previous XOR operation on the highest byte, and then performs a 32-bit arithmetic right shift (>> 1) by preserving and propagating the sign bit via the carry flag (MOV C, ACC.7 followed by successive RRC instructions across all bytes).

Next, it zero-extends the 8-bit global_var_8 into a 32-bit value across temporary registers, applies a bitwise OR (ORL) operation combining it with the shifted result, and saves the final 32-bit word back to working RAM.

7 . Inside the function: return of the result

  013B 850F82   MOV DPL, 0Fh         ; Prepare return value low byte into DPL
  013E 851083   MOV DPH, 10h         ; Prepare return value high byte into DPH
  0141 8511F0   MOV B, 11h           ; Prepare return value upper-middle byte into register B
  0144 E512     MOV A, 12h           ; Move return value highest byte into Accumulator
  0146 22       RET                  ; Return from function with 32-bit result split across registers

The result of the function is sent to the following registers DPL,DPH, B, A before a RET is called.

8. Conclusion

This article finishes the series on the translation in assembly by SDCC of a small C source code. Even if the C source code was small, it had a lot of features which necessitated to be explained.

This example is a textbook case demonstrating that writing standard C without regard for the target model on an 8-bit microcontroller leads to heavy and slow object code. The constant data shuttling between internal memory and registers (MOV 13h, A, etc.) illustrates why, back then, low-level developers invariably ended up bypassing the compiler to rewrite critical portions directly by hand.

I hope that you have enjoyed your journey into the intricacies of the SDCC translation. See you next time for another series.

9. The full disassembly code

CSEG AT 0000h
  0000 020006       LJMP L0001

L0004:
  0003 020147       LJMP L0005

L0001:
  0006 758118       MOV SP, #18h
  0009 1202C6       LCALL L0002
  000C E582         MOV A, DPL
  000E 6003         JZ L0003
  0010 020003       LJMP L0004

L0003:
  0013 7900         MOV R1, #0h
  0015 E9           MOV A, R1
  0016 4400         ORL A, #0h
  0018 601B         JZ L0025
  001A 7A00         MOV R2, #0h
  001C 9002D8       MOV DPTR, #02D8h
  001F 7801         MOV R0, #1h
  0021 75A000       MOV P2, #0h
L0027:
  0024 E4           CLR A
  0025 93           MOVC A, @A+DPTR
  0026 F2           MOVX @R0, A
  0027 A3           INC DPTR
  0028 08           INC R0
  0029 B80002       CJNE R0, #0h, L0026
  002C 05A0         INC P2
L0026:
  002E D9F4         DJNZ R1, L0027
  0030 DAF2         DJNZ R2, L0027
  0032 75A0FF       MOV P2, #0FFh
L0025:
  0035 E4           CLR A
  0036 78FF         MOV R0, #0FFh
L0028:
  0038 F6           MOV @R0, A
  0039 D8FD         DJNZ R0, L0028
  003B 7800         MOV R0, #0h
  003D E8           MOV A, R0
  003E 4400         ORL A, #0h
  0040 600A         JZ L0029
  0042 7901         MOV R1, #1h
  0044 75A000       MOV P2, #0h
  0047 E4           CLR A
L0030:
  0048 F3           MOVX @R1, A
  0049 09           INC R1
  004A D8FC         DJNZ R0, L0030
L0029:
  004C 7800         MOV R0, #0h
  004E E8           MOV A, R0
  004F 4400         ORL A, #0h
  0051 600C         JZ L0031
  0053 7900         MOV R1, #0h
  0055 900001       MOV DPTR, #0001h
  0058 E4           CLR A
L0032:
  0059 F0           MOVX @DPTR, A
  005A A3           INC DPTR
  005B D8FC         DJNZ R0, L0032
  005D D9FA         DJNZ R1, L0032
L0031:
  005F 7508EF       MOV 8h, #0EFh
  0062 7509BE       MOV 9h, #0BEh
  0065 750AAD       MOV 0Ah, #0ADh
  0068 750BDE       MOV 0Bh, #0DEh
  006B 750C42       MOV 0Ch, #42h
  006E 020003       LJMP L0004

L0013:
  0071 AE82         MOV R6, DPL
  0073 AF83         MOV R7, DPH
  0075 E4           CLR A
  0076 F50F         MOV 0Fh, A
  0078 F510         MOV 10h, A
  007A F511         MOV 11h, A
  007C F512         MOV 12h, A
  007E 850D17       MOV 17h, 0Dh
  0081 850E18       MOV 18h, 0Eh
  0084 8E82         MOV DPL, R6
  0086 8F83         MOV DPH, R7
  0088 C007         PUSH 7h
  008A C006         PUSH 6h
  008C 120248       LCALL L0015
  008F AC82         MOV R4, DPL
  0091 AD83         MOV R5, DPH
  0093 D006         POP 6h
  0095 D007         POP 7h
  0097 ED           MOV A, R5
  0098 33           RLC A
  0099 95E0         SUBB A, ACC
  009B FB           MOV R3, A
  009C FA           MOV R2, A
  009D EC           MOV A, R4
  009E 250F         ADD A, 0Fh
  00A0 F50F         MOV 0Fh, A
  00A2 ED           MOV A, R5
  00A3 3510         ADDC A, 10h
  00A5 F510         MOV 10h, A
  00A7 EB           MOV A, R3
  00A8 3511         ADDC A, 11h
  00AA F511         MOV 11h, A
  00AC EA           MOV A, R2
  00AD 3512         ADDC A, 12h
  00AF F512         MOV 12h, A
  00B1 AC0D         MOV R4, 0Dh
  00B3 AD0E         MOV R5, 0Eh
  00B5 7401         MOV A, #1h
  00B7 4C           ORL A, R4
  00B8 F517         MOV 17h, A
  00BA 8D18         MOV 18h, R5
  00BC 8E82         MOV DPL, R6
  00BE 8F83         MOV DPH, R7
  00C0 12028E       LCALL L0016
  00C3 AE82         MOV R6, DPL
  00C5 E583         MOV A, DPH
  00C7 FF           MOV R7, A
  00C8 33           RLC A
  00C9 95E0         SUBB A, ACC
  00CB FD           MOV R5, A
  00CC FC           MOV R4, A
  00CD E50F         MOV A, 0Fh
  00CF C3           CLR C
  00D0 9E           SUBB A, R6
  00D1 F50F         MOV 0Fh, A
  00D3 E510         MOV A, 10h
  00D5 9F           SUBB A, R7
  00D6 F510         MOV 10h, A
  00D8 E511         MOV A, 11h
  00DA 9D           SUBB A, R5
  00DB F511         MOV 11h, A
  00DD E512         MOV A, 12h
  00DF 9C           SUBB A, R4
  00E0 F512         MOV 12h, A
  00E2 E50F         MOV A, 0Fh
  00E4 25E0         ADD A, ACC
  00E6 FC           MOV R4, A
  00E7 E510         MOV A, 10h
  00E9 33           RLC A
  00EA FD           MOV R5, A
  00EB E511         MOV A, 11h
  00ED 33           RLC A
  00EE FE           MOV R6, A
  00EF E512         MOV A, 12h
  00F1 33           RLC A
  00F2 FF           MOV R7, A
  00F3 EC           MOV A, R4
  00F4 2C           ADD A, R4
  00F5 FC           MOV R4, A
  00F6 ED           MOV A, R5
  00F7 33           RLC A
  00F8 FD           MOV R5, A
  00F9 EE           MOV A, R6
  00FA 33           RLC A
  00FB FE           MOV R6, A
  00FC EF           MOV A, R7
  00FD 33           RLC A
  00FE FF           MOV R7, A
  00FF 74AA         MOV A, #0AAh
  0101 6C           XRL A, R4
  0102 F50F         MOV 0Fh, A
  0104 7455         MOV A, #55h
  0106 6D           XRL A, R5
  0107 F510         MOV 10h, A
  0109 74AA         MOV A, #0AAh
  010B 6E           XRL A, R6
  010C F511         MOV 11h, A
  010E 7455         MOV A, #55h
  0110 6F           XRL A, R7
  0111 F512         MOV 12h, A
  0113 E512         MOV A, 12h
  0115 A2E7         MOV C, ACC.7
  0117 13           RRC A
  0118 FF           MOV R7, A
  0119 E511         MOV A, 11h
  011B 13           RRC A
  011C FE           MOV R6, A
  011D E510         MOV A, 10h
  011F 13           RRC A
  0120 FD           MOV R5, A
  0121 E50F         MOV A, 0Fh
  0123 13           RRC A
  0124 FC           MOV R4, A
  0125 A80C         MOV R0, 0Ch
  0127 E4           CLR A
  0128 F9           MOV R1, A
  0129 FA           MOV R2, A
  012A FB           MOV R3, A
  012B E8           MOV A, R0
  012C 4C           ORL A, R4
  012D F50F         MOV 0Fh, A
  012F E9           MOV A, R1
  0130 4D           ORL A, R5
  0131 F510         MOV 10h, A
  0133 EA           MOV A, R2
  0134 4E           ORL A, R6
  0135 F511         MOV 11h, A
  0137 EB           MOV A, R3
  0138 4F           ORL A, R7
  0139 F512         MOV 12h, A
  013B 850F82       MOV DPL, 0Fh
  013E 851083       MOV DPH, 10h
  0141 8511F0       MOV B, 11h
  0144 E512         MOV A, 12h
  0146 22           RET

L0005:
  0147 E4           CLR A
  0148 F513         MOV 13h, A
  014A F514         MOV 14h, A
  014C F515         MOV 15h, A
  014E F516         MOV 16h, A
  0150 7E00         MOV R6, #0h
  0152 7F00         MOV R7, #0h
L0009:
  0154 8E04         MOV 4h, R6
  0156 8F05         MOV 5h, R7
  0158 BC051A       CJNE R4, #5h, L0006
  015B BD0017       CJNE R5, #0h, L0006
  015E 7464         MOV A, #64h
  0160 2513         ADD A, 13h
  0162 F513         MOV 13h, A
  0164 E4           CLR A
  0165 3514         ADDC A, 14h
  0167 F514         MOV 14h, A
  0169 E4           CLR A
  016A 3515         ADDC A, 15h
  016C F515         MOV 15h, A
  016E E4           CLR A
  016F 3516         ADDC A, 16h
  0171 F516         MOV 16h, A
  0173 801D         SJMP L0007

L0006:
  0175 8E02         MOV 2h, R6
  0177 EF           MOV A, R7
  0178 FB           MOV R3, A
  0179 33           RLC A
  017A 95E0         SUBB A, ACC
  017C FC           MOV R4, A
  017D FD           MOV R5, A
  017E EA           MOV A, R2
  017F 2513         ADD A, 13h
  0181 F513         MOV 13h, A
  0183 EB           MOV A, R3
  0184 3514         ADDC A, 14h
  0186 F514         MOV 14h, A
  0188 EC           MOV A, R4
  0189 3515         ADDC A, 15h
  018B F515         MOV 15h, A
  018D ED           MOV A, R5
  018E 3516         ADDC A, 16h
  0190 F516         MOV 16h, A
L0007:
  0192 0E           INC R6
  0193 BE0001       CJNE R6, #0h, L0008
  0196 0F           INC R7
L0008:
  0197 8E04         MOV 4h, R6
  0199 8F05         MOV 5h, R7
  019B C3           CLR C
  019C EC           MOV A, R4
  019D 940A         SUBB A, #0Ah
  019F ED           MOV A, R5
  01A0 6480         XRL A, #80h
  01A2 9480         SUBB A, #80h
  01A4 40AE         JC L0009
  01A6 AF0C         MOV R7, 0Ch
  01A8 BF1002       CJNE R7, #10h, L0010
  01AB 8005         SJMP L0011

L0010:
  01AD BF2030       CJNE R7, #20h, L0023
  01B0 8017         SJMP L0024

L0011:
  01B2 740A         MOV A, #0Ah
  01B4 2513         ADD A, 13h
  01B6 F513         MOV 13h, A
  01B8 E4           CLR A
  01B9 3514         ADDC A, 14h
  01BB F514         MOV 14h, A
  01BD E4           CLR A
  01BE 3515         ADDC A, 15h
  01C0 F515         MOV 15h, A
  01C2 E4           CLR A
  01C3 3516         ADDC A, 16h
  01C5 F516         MOV 16h, A
  01C7 802F         SJMP L0012

L0024:
  01C9 7414         MOV A, #14h
  01CB 2513         ADD A, 13h
  01CD F513         MOV 13h, A
  01CF E4           CLR A
  01D0 3514         ADDC A, 14h
  01D2 F514         MOV 14h, A
  01D4 E4           CLR A
  01D5 3515         ADDC A, 15h
  01D7 F515         MOV 15h, A
  01D9 E4           CLR A
  01DA 3516         ADDC A, 16h
  01DC F516         MOV 16h, A
  01DE 8018         SJMP L0012

L0023:
  01E0 E513         MOV A, 13h
  01E2 24FB         ADD A, #0FBh
  01E4 F513         MOV 13h, A
  01E6 E514         MOV A, 14h
  01E8 34FF         ADDC A, #0FFh
  01EA F514         MOV 14h, A
  01EC E515         MOV A, 15h
  01EE 34FF         ADDC A, #0FFh
  01F0 F515         MOV 15h, A
  01F2 E516         MOV A, 16h
  01F4 34FF         ADDC A, #0FFh
  01F6 F516         MOV 16h, A
L0012:
  01F8 851382       MOV DPL, 13h
  01FB 851483       MOV DPH, 14h
  01FE 750D03       MOV 0Dh, #3h
  0201 750E00       MOV 0Eh, #0h
  0204 120071       LCALL L0013
  0207 AC82         MOV R4, DPL
  0209 AD83         MOV R5, DPH
  020B AEF0         MOV R6, B
  020D FF           MOV R7, A
  020E EC           MOV A, R4
  020F 2513         ADD A, 13h
  0211 F513         MOV 13h, A
  0213 ED           MOV A, R5
  0214 3514         ADDC A, 14h
  0216 F514         MOV 14h, A
  0218 EE           MOV A, R6
  0219 3515         ADDC A, 15h
  021B F515         MOV 15h, A
  021D EF           MOV A, R7
  021E 3516         ADDC A, 16h
  0220 F516         MOV 16h, A
  0222 AC13         MOV R4, 13h
  0224 AD14         MOV R5, 14h
  0226 AE15         MOV R6, 15h
  0228 AF16         MOV R7, 16h
  022A 8C08         MOV 8h, R4
  022C 8D09         MOV 9h, R5
  022E 8E0A         MOV 0Ah, R6
  0230 8F0B         MOV 0Bh, R7
L0014:
  0232 AC08         MOV R4, 8h
  0234 AD09         MOV R5, 9h
  0236 AE0A         MOV R6, 0Ah
  0238 AF0B         MOV R7, 0Bh
  023A EC           MOV A, R4
  023B 6213         XRL 13h, A
  023D ED           MOV A, R5
  023E 6214         XRL 14h, A
  0240 EE           MOV A, R6
  0241 6215         XRL 15h, A
  0243 EF           MOV A, R7
  0244 6216         XRL 16h, A
  0246 80EA         SJMP L0014

L0015:
  0248 E582         MOV A, DPL
  024A 8517F0       MOV B, 17h
  024D A4           MUL AB
  024E C582         XCH A, DPL
  0250 C0F0         PUSH B
  0252 8518F0       MOV B, 18h
  0255 A4           MUL AB
  0256 D0F0         POP B
  0258 25F0         ADD A, B
  025A C583         XCH A, DPH
  025C 8517F0       MOV B, 17h
  025F A4           MUL AB
  0260 2583         ADD A, DPH
  0262 F583         MOV DPH, A
  0264 22           RET

L0019:
  0265 7A10         MOV R2, #10h
  0267 E4           CLR A
  0268 FB           MOV R3, A
  0269 FC           MOV R4, A
L0022:
  026A E582         MOV A, DPL
  026C 25E0         ADD A, ACC
  026E F582         MOV DPL, A
  0270 E583         MOV A, DPH
  0272 33           RLC A
  0273 F583         MOV DPH, A
  0275 EB           MOV A, R3
  0276 33           RLC A
  0277 FB           MOV R3, A
  0278 EC           MOV A, R4
  0279 33           RLC A
  027A FC           MOV R4, A
  027B EB           MOV A, R3
  027C 9517         SUBB A, 17h
  027E F5F0         MOV B, A
  0280 EC           MOV A, R4
  0281 9518         SUBB A, 18h
  0283 4006         JC L0021
  0285 FC           MOV R4, A
  0286 ABF0         MOV R3, B
  0288 438201       ORL DPL, #1h
L0021:
  028B DADD         DJNZ R2, L0022
  028D 22           RET

L0016:
  028E C2D5         CLR F0
  0290 E583         MOV A, DPH
  0292 30E70D       JNB ACC.7, L0017
  0295 D2D5         SETB F0
  0297 E4           CLR A
  0298 C3           CLR C
  0299 9582         SUBB A, DPL
  029B F582         MOV DPL, A
  029D E4           CLR A
  029E 9583         SUBB A, DPH
  02A0 F583         MOV DPH, A
L0017:
  02A2 E518         MOV A, 18h
  02A4 30E70D       JNB ACC.7, L0018
  02A7 B2D5         CPL F0
  02A9 E4           CLR A
  02AA C3           CLR C
  02AB 9517         SUBB A, 17h
  02AD F517         MOV 17h, A
  02AF E4           CLR A
  02B0 9518         SUBB A, 18h
  02B2 F518         MOV 18h, A
L0018:
  02B4 120265       LCALL L0019
  02B7 30D50B       JNB F0, L0020
  02BA E4           CLR A
  02BB C3           CLR C
  02BC 9582         SUBB A, DPL
  02BE F582         MOV DPL, A
  02C0 E4           CLR A
  02C1 9583         SUBB A, DPH
  02C3 F583         MOV DPH, A
L0020:
  02C5 22           RET

L0002:
  02C6 758200       MOV DPL, #0h
  02C9 22           RET

  02CA 54           DB 054h ; 'T'
  02CB 41           DB 041h ; 'A'
  02CC 52           DB 052h ; 'R'
  02CD 47           DB 047h ; 'G'
  02CE 45           DB 045h ; 'E'
  02CF 54           DB 054h ; 'T'
  02D0 5F           DB 05Fh ; '_'
  02D1 53           DB 053h ; 'S'
  02D2 54           DB 054h ; 'T'
  02D3 52           DB 052h ; 'R'
  02D4 49           DB 049h ; 'I'
  02D5 4E           DB 04Eh ; 'N'
  02D6 47           DB 047h ; 'G'
  02D7 00           DB 000h 
END

8051 What does SDCC do part 2 ?

ddupard — Thu, 13 Aug 2026 08:10:27 +0000

1. Introduction and Problem Statement

In order to test SDCC we are going to use the following C source code.

/* ========================================================================== *
 * Universal Test Corpus - Heterogeneous Architecture Analysis          *
 * ========================================================================== */


#include <stdint.h>

// 1. Global variables (testing absolute/relative addressing modes)
volatile uint32_t global_var_32 = 0xDEADBEEF;
volatile uint8_t  global_var_8  = 0x42;
const    char     string_const[] = "TARGET_STRING";

// 2. Function with parameter passing and local variables (stack / Frame Pointer test)
int32_t callee_function(int16_t a, int16_t b) {
    volatile int32_t local_result = 0;

    // Basic and mixed arithmetic operations (8, 16, 32 bits)
    local_result += (int32_t)(a * b);
    local_result -= (int32_t)(a / (b | 1)); // Avoid division by zero

    // Shift tests and logical operations (highly variable depending on ISAs)
    local_result = (local_result << 2) ^ 0x55AA55AA;
    local_result = (local_result >> 1) | (int32_t)global_var_8;

    return local_result;
}

// 3. Main function grouping complex control flows
int main(void) {
    volatile int32_t accumulator = 0;
    int16_t i;

    // Loop test (Conditional jumps, decrement, comparison tests)
    for (i = 0; i < 10; i++) {
        if (i == 5) {
            accumulator += 100;
        } else {
            accumulator += i;
        }
    }

    // Multiple branching test (Switch / Jump Table or cascaded if-else)
    switch (global_var_8) {
        case 0x10:
            accumulator += 10;
            break;
        case 0x20:
            accumulator += 20;
            break;
        default:
            accumulator -= 5;
            break;
    }

    // Function call (Stack management, save registers Link Register/PC)
    accumulator += callee_function((int16_t)accumulator, 3);

    // Pointer and indirect memory access test
    volatile uint32_t *ptr = (volatile uint32_t *)&global_var_32;
    *ptr = (uint32_t)accumulator;

    // Terminal infinite loop (classic for raw binaries / microcontrollers)
    while (1) {
        accumulator ^= *ptr;
    }

    return 0;
}

To compile it, we will use SDCC which produces an Intel HEX file. This file will be transformed in a ROM file using either objcopy or makebin (see below).

sdcc  "$SRC/test1.c" -o "8/test1_8051" 
objcopy -I ihex -O binary "8/test1_8051" "8/bin/test1_8051_bin" 
makebin -p "8/test1_8051" "8/bin/test1_8051.rom"

Moreover, to simulate the 8051, I use the MCU 8051 IDE (command mcu8051ide).

In our first article, we studied the stub generated by SDCC. In this article we will study the main function except what is related to the call of callee_function.

This C file is particularly interesting, because in a small source code we have a lot of different cases (for example, some of the variables have a 32 bits size).

2. Variable Initialization

Before any instruction related to our program being executed, the state of the 8051 is the following

in our C source code , there are 3 global variables

// 1. Global variables (testing absolute/relative addressing modes)
volatile uint32_t global_var_32 = 0xDEADBEEF;
volatile uint8_t  global_var_8  = 0x42;
const    char     string_const[] = "TARGET_STRING";

The first 2 global variables ( global_var_32 and global_var_8 ) are initialized by the following code

  005F 7508EF       MOV 8h, #0EFh
  0062 7509BE       MOV 9h, #0BEh
  0065 750AAD       MOV 0Ah, #0ADh
  0068 750BDE       MOV 0Bh, #0DEh
  006B 750C42       MOV 0Ch, #42h

See how the memory has changed

and the third one being a constant, SDCC adds it at the end of the program in ROM

  02CA 54           DB 054h ; 'T'
  02CB 41           DB 041h ; 'A'
  02CC 52           DB 052h ; 'R'
  02CD 47           DB 047h ; 'G'
  02CE 45           DB 045h ; 'E'
  02CF 54           DB 054h ; 'T'
  02D0 5F           DB 05Fh ; '_'
  02D1 53           DB 053h ; 'S'
  02D2 54           DB 054h ; 'T'
  02D3 52           DB 052h ; 'R'
  02D4 49           DB 049h ; 'I'
  02D5 4E           DB 04Eh ; 'N'
  02D6 47           DB 047h ; 'G'
  02D7 00           DB 000h 
END

then at the beginning of the main function we find

int main(void) {
    volatile int32_t accumulator = 0;
    int16_t i;

which corresponds to

L0005:
  0147 E4           CLR A
  0148 F513         MOV 13h, A
  014A F514         MOV 14h, A
  014C F515         MOV 15h, A
  014E F516         MOV 16h, A

for volatile int32_t accumulator = 0

3. Loop and Test

for (i = 0; i < 10; i++) {
        if (i == 5) {
            accumulator += 100;
        } else {
            accumulator += i;
        }
    }

The assembly code which corresponds to the C code above is below.

L0005:
  0147 E4           CLR A
  0148 F513         MOV 13h, A
  014A F514         MOV 14h, A
  014C F515         MOV 15h, A
  014E F516         MOV 16h, A
  0150 7E00         MOV R6, #0h
  0152 7F00         MOV R7, #0h
L0009:
  0154 8E04         MOV 4h, R6
  0156 8F05         MOV 5h, R7
  0158 BC051A       CJNE R4, #5h, L0006
  015B BD0017       CJNE R5, #0h, L0006
  015E 7464         MOV A, #64h
  0160 2513         ADD A, 13h
  0162 F513         MOV 13h, A
  0164 E4           CLR A
  0165 3514         ADDC A, 14h
  0167 F514         MOV 14h, A
  0169 E4           CLR A
  016A 3515         ADDC A, 15h
  016C F515         MOV 15h, A
  016E E4           CLR A
  016F 3516         ADDC A, 16h
  0171 F516         MOV 16h, A
  0173 801D         SJMP L0007

L0006:
  0175 8E02         MOV 2h, R6
  0177 EF           MOV A, R7
  0178 FB           MOV R3, A
  0179 33           RLC A
  017A 95E0         SUBB A, ACC
  017C FC           MOV R4, A
  017D FD           MOV R5, A
  017E EA           MOV A, R2
  017F 2513         ADD A, 13h
  0181 F513         MOV 13h, A
  0183 EB           MOV A, R3
  0184 3514         ADDC A, 14h
  0186 F514         MOV 14h, A
  0188 EC           MOV A, R4
  0189 3515         ADDC A, 15h
  018B F515         MOV 15h, A
  018D ED           MOV A, R5
  018E 3516         ADDC A, 16h
  0190 F516         MOV 16h, A
L0007:
  0192 0E           INC R6
  0193 BE0001       CJNE R6, #0h, L0008
  0196 0F           INC R7
L0008:
  0197 8E04         MOV 4h, R6
  0199 8F05         MOV 5h, R7
  019B C3           CLR C
  019C EC           MOV A, R4
  019D 940A         SUBB A, #0Ah
  019F ED           MOV A, R5
  01A0 6480         XRL A, #80h
  01A2 9480         SUBB A, #80h
  01A4 40AE         JC L0009

It is quite complicated essentially because i is a 16 bits integer and the accumulator variable is a 32 bits integer. And since there is no native, general-purpose 16-bit register easy to manipulate for a simple counting loop. The compiler must simulate the variable i (which is an int16_t in our code) by combining multiple registers (such as R6 and R7), which significantly weighs down every increment and loop-end test.
The compiler must also must make heavy generation of comparisons (CJNE) and jumps to handle control structures and nested if/else statements and laborious manipulation of 32-bit types (accumulator += 100 or += i) on an 8-bit machine, where each addition requires propagating carries byte by byte across multiple internal memory addresses.

  017E EA           MOV A, R2
  017F 2513         ADD A, 13h
  0181 F513         MOV 13h, A
  0183 EB           MOV A, R3
  0184 3514         ADDC A, 14h
  0186 F514         MOV 14h, A
  0188 EC           MOV A, R4
  0189 3515         ADDC A, 15h
  018B F515         MOV 15h, A
  018D ED           MOV A, R5
  018E 3516         ADDC A, 16h
  0190 F516         MOV 16h, A

The generated assembly code is therefore verbose, packed with intermediate calls and conditional jumps (JC, CJNE, SJMP). It is a textbook case showing why, on 4 KB ROM microcontrollers, critical developers often end up rewriting critical loops or mathematical functions directly in hand-optimized assembly to avoid the bloat of C compiler-generated code.

An optimized assembly code, should not use more than 6 registers for this loop: R0, R1, R2, R3 for the 32 bits variable
( accumulator ) and R4,R5 for the 16 bits variable ( i ) and no save in the memory. Even more, the optimized assembly code should use only 5 registers because i could be a uint8_t instead of a uint16_t. There is no need for i to be a uint16_t.

The code generated by SDCC uses memory to store the 32 bits variable (addresses 13h,14h,15h, 16h) and for the 16 bits variable (adresses 4h,5h) and then it constantly moves data from the memory to the registers and vice versa which is really really inefficient.

See below for the state of the processor after the loop

4. Switch

 // Multiple branching test (Switch / Jump Table or cascaded if-else)
    switch (global_var_8) {
        case 0x10:
            accumulator += 10;
            break;
        case 0x20:
            accumulator += 20;
            break;
        default:
            accumulator -= 5;
            break;
    }

The code above corresponds to the code below. It is pretty straightforward since global_var_8 is stored at address 0Ch (see 4. variable initialization).

  01A6 AF0C         MOV R7, 0Ch
  01A8 BF1002       CJNE R7, #10h, L0010
  01AB 8005         SJMP L0011

L0010:
  01AD BF2030       CJNE R7, #20h, L0023
  01B0 8017         SJMP L0024

L0011:
  01B2 740A         MOV A, #0Ah
  01B4 2513         ADD A, 13h
  01B6 F513         MOV 13h, A
  01B8 E4           CLR A
  01B9 3514         ADDC A, 14h
  01BB F514         MOV 14h, A
  01BD E4           CLR A
  01BE 3515         ADDC A, 15h
  01C0 F515         MOV 15h, A
  01C2 E4           CLR A
  01C3 3516         ADDC A, 16h
  01C5 F516         MOV 16h, A
  01C7 802F         SJMP L0012

L0024:
  01C9 7414         MOV A, #14h
  01CB 2513         ADD A, 13h
  01CD F513         MOV 13h, A
  01CF E4           CLR A
  01D0 3514         ADDC A, 14h
  01D2 F514         MOV 14h, A
  01D4 E4           CLR A
  01D5 3515         ADDC A, 15h
  01D7 F515         MOV 15h, A
  01D9 E4           CLR A
  01DA 3516         ADDC A, 16h
  01DC F516         MOV 16h, A
  01DE 8018         SJMP L0012

L0023:
  01E0 E513         MOV A, 13h
  01E2 24FB         ADD A, #0FBh
  01E4 F513         MOV 13h, A
  01E6 E514         MOV A, 14h
  01E8 34FF         ADDC A, #0FFh
  01EA F514         MOV 14h, A
  01EC E515         MOV A, 15h
  01EE 34FF         ADDC A, #0FFh
  01F0 F515         MOV 15h, A
  01F2 E516         MOV A, 16h
  01F4 34FF         ADDC A, #0FFh
  01F6 F516         MOV 16h, A

Once again since the variable accumulator is a 32 bits integer, there is a carry propagation.
The only little trick is how the line accumulator -=5 is translated. It's calculated by adding #0FBh in the following instruction

01E2 24FB       ADD A, #0FBh

5. Memory and access tests

  // Pointer and indirect memory access test
    volatile uint32_t *ptr = (volatile uint32_t *)&global_var_32;
    *ptr = (uint32_t)accumulator;

The code above is translated by SDCC in the lines below

  0222 AC13         MOV R4, 13h
  0224 AD14         MOV R5, 14h
  0226 AE15         MOV R6, 15h
  0228 AF16         MOV R7, 16h
  022A 8C08         MOV 8h, R4
  022C 8D09         MOV 9h, R5
  022E 8E0A         MOV 0Ah, R6
  0230 8F0B         MOV 0Bh, R7

Nothing much to say.
The accumulator variable is stored at addresses 13h,14h,15h,16h. and is sent to adresses 8h,9h,0Ah,0Bh which are the precise adresses of global_var_32. The compiler is quite clever since it automatically sees that ptr as the exact same adress than global_var_32, so all this block is equivalent to a transfer of data from the accumator variable to global_var_32

6. Terminal and infinite loop

    // Terminal infinite loop (classic for raw binaries / microcontrollers)
    while (1) {
        accumulator ^= *ptr;
    }

The code above is translated by SDCC in the lines below

L0014:
  0232 AC08         MOV R4, 8h
  0234 AD09         MOV R5, 9h
  0236 AE0A         MOV R6, 0Ah
  0238 AF0B         MOV R7, 0Bh
  023A EC           MOV A, R4
  023B 6213         XRL 13h, A
  023D ED           MOV A, R5
  023E 6214         XRL 14h, A
  0240 EE           MOV A, R6
  0241 6215         XRL 15h, A
  0243 EF           MOV A, R7
  0244 6216         XRL 16h, A
  0246 80EA         SJMP L0014

pretty straightforward

7. Conclusion

The 8051, being an 8-bit chip, may seem uninteresting at first glance in a world dominated by 32-bit and 64-bit processors, but it remains the most widely used microcontroller in the world, and without knowing it, you find it in almost everything around you (from your television remote control to washing machines, microwave ovens, fridges, smart cards, car key fobs, and power supplies).

8. The full disassembly code

CSEG AT 0000h
  0000 020006       LJMP L0001

L0004:
  0003 020147       LJMP L0005

L0001:
  0006 758118       MOV SP, #18h
  0009 1202C6       LCALL L0002
  000C E582         MOV A, DPL
  000E 6003         JZ L0003
  0010 020003       LJMP L0004

L0003:
  0013 7900         MOV R1, #0h
  0015 E9           MOV A, R1
  0016 4400         ORL A, #0h
  0018 601B         JZ L0025
  001A 7A00         MOV R2, #0h
  001C 9002D8       MOV DPTR, #02D8h
  001F 7801         MOV R0, #1h
  0021 75A000       MOV P2, #0h
L0027:
  0024 E4           CLR A
  0025 93           MOVC A, @A+DPTR
  0026 F2           MOVX @R0, A
  0027 A3           INC DPTR
  0028 08           INC R0
  0029 B80002       CJNE R0, #0h, L0026
  002C 05A0         INC P2
L0026:
  002E D9F4         DJNZ R1, L0027
  0030 DAF2         DJNZ R2, L0027
  0032 75A0FF       MOV P2, #0FFh
L0025:
  0035 E4           CLR A
  0036 78FF         MOV R0, #0FFh
L0028:
  0038 F6           MOV @R0, A
  0039 D8FD         DJNZ R0, L0028
  003B 7800         MOV R0, #0h
  003D E8           MOV A, R0
  003E 4400         ORL A, #0h
  0040 600A         JZ L0029
  0042 7901         MOV R1, #1h
  0044 75A000       MOV P2, #0h
  0047 E4           CLR A
L0030:
  0048 F3           MOVX @R1, A
  0049 09           INC R1
  004A D8FC         DJNZ R0, L0030
L0029:
  004C 7800         MOV R0, #0h
  004E E8           MOV A, R0
  004F 4400         ORL A, #0h
  0051 600C         JZ L0031
  0053 7900         MOV R1, #0h
  0055 900001       MOV DPTR, #0001h
  0058 E4           CLR A
L0032:
  0059 F0           MOVX @DPTR, A
  005A A3           INC DPTR
  005B D8FC         DJNZ R0, L0032
  005D D9FA         DJNZ R1, L0032
L0031:
  005F 7508EF       MOV 8h, #0EFh
  0062 7509BE       MOV 9h, #0BEh
  0065 750AAD       MOV 0Ah, #0ADh
  0068 750BDE       MOV 0Bh, #0DEh
  006B 750C42       MOV 0Ch, #42h
  006E 020003       LJMP L0004

L0013:
  0071 AE82         MOV R6, DPL
  0073 AF83         MOV R7, DPH
  0075 E4           CLR A
  0076 F50F         MOV 0Fh, A
  0078 F510         MOV 10h, A
  007A F511         MOV 11h, A
  007C F512         MOV 12h, A
  007E 850D17       MOV 17h, 0Dh
  0081 850E18       MOV 18h, 0Eh
  0084 8E82         MOV DPL, R6
  0086 8F83         MOV DPH, R7
  0088 C007         PUSH 7h
  008A C006         PUSH 6h
  008C 120248       LCALL L0015
  008F AC82         MOV R4, DPL
  0091 AD83         MOV R5, DPH
  0093 D006         POP 6h
  0095 D007         POP 7h
  0097 ED           MOV A, R5
  0098 33           RLC A
  0099 95E0         SUBB A, ACC
  009B FB           MOV R3, A
  009C FA           MOV R2, A
  009D EC           MOV A, R4
  009E 250F         ADD A, 0Fh
  00A0 F50F         MOV 0Fh, A
  00A2 ED           MOV A, R5
  00A3 3510         ADDC A, 10h
  00A5 F510         MOV 10h, A
  00A7 EB           MOV A, R3
  00A8 3511         ADDC A, 11h
  00AA F511         MOV 11h, A
  00AC EA           MOV A, R2
  00AD 3512         ADDC A, 12h
  00AF F512         MOV 12h, A
  00B1 AC0D         MOV R4, 0Dh
  00B3 AD0E         MOV R5, 0Eh
  00B5 7401         MOV A, #1h
  00B7 4C           ORL A, R4
  00B8 F517         MOV 17h, A
  00BA 8D18         MOV 18h, R5
  00BC 8E82         MOV DPL, R6
  00BE 8F83         MOV DPH, R7
  00C0 12028E       LCALL L0016
  00C3 AE82         MOV R6, DPL
  00C5 E583         MOV A, DPH
  00C7 FF           MOV R7, A
  00C8 33           RLC A
  00C9 95E0         SUBB A, ACC
  00CB FD           MOV R5, A
  00CC FC           MOV R4, A
  00CD E50F         MOV A, 0Fh
  00CF C3           CLR C
  00D0 9E           SUBB A, R6
  00D1 F50F         MOV 0Fh, A
  00D3 E510         MOV A, 10h
  00D5 9F           SUBB A, R7
  00D6 F510         MOV 10h, A
  00D8 E511         MOV A, 11h
  00DA 9D           SUBB A, R5
  00DB F511         MOV 11h, A
  00DD E512         MOV A, 12h
  00DF 9C           SUBB A, R4
  00E0 F512         MOV 12h, A
  00E2 E50F         MOV A, 0Fh
  00E4 25E0         ADD A, ACC
  00E6 FC           MOV R4, A
  00E7 E510         MOV A, 10h
  00E9 33           RLC A
  00EA FD           MOV R5, A
  00EB E511         MOV A, 11h
  00ED 33           RLC A
  00EE FE           MOV R6, A
  00EF E512         MOV A, 12h
  00F1 33           RLC A
  00F2 FF           MOV R7, A
  00F3 EC           MOV A, R4
  00F4 2C           ADD A, R4
  00F5 FC           MOV R4, A
  00F6 ED           MOV A, R5
  00F7 33           RLC A
  00F8 FD           MOV R5, A
  00F9 EE           MOV A, R6
  00FA 33           RLC A
  00FB FE           MOV R6, A
  00FC EF           MOV A, R7
  00FD 33           RLC A
  00FE FF           MOV R7, A
  00FF 74AA         MOV A, #0AAh
  0101 6C           XRL A, R4
  0102 F50F         MOV 0Fh, A
  0104 7455         MOV A, #55h
  0106 6D           XRL A, R5
  0107 F510         MOV 10h, A
  0109 74AA         MOV A, #0AAh
  010B 6E           XRL A, R6
  010C F511         MOV 11h, A
  010E 7455         MOV A, #55h
  0110 6F           XRL A, R7
  0111 F512         MOV 12h, A
  0113 E512         MOV A, 12h
  0115 A2E7         MOV C, ACC.7
  0117 13           RRC A
  0118 FF           MOV R7, A
  0119 E511         MOV A, 11h
  011B 13           RRC A
  011C FE           MOV R6, A
  011D E510         MOV A, 10h
  011F 13           RRC A
  0120 FD           MOV R5, A
  0121 E50F         MOV A, 0Fh
  0123 13           RRC A
  0124 FC           MOV R4, A
  0125 A80C         MOV R0, 0Ch
  0127 E4           CLR A
  0128 F9           MOV R1, A
  0129 FA           MOV R2, A
  012A FB           MOV R3, A
  012B E8           MOV A, R0
  012C 4C           ORL A, R4
  012D F50F         MOV 0Fh, A
  012F E9           MOV A, R1
  0130 4D           ORL A, R5
  0131 F510         MOV 10h, A
  0133 EA           MOV A, R2
  0134 4E           ORL A, R6
  0135 F511         MOV 11h, A
  0137 EB           MOV A, R3
  0138 4F           ORL A, R7
  0139 F512         MOV 12h, A
  013B 850F82       MOV DPL, 0Fh
  013E 851083       MOV DPH, 10h
  0141 8511F0       MOV B, 11h
  0144 E512         MOV A, 12h
  0146 22           RET

L0005:
  0147 E4           CLR A
  0148 F513         MOV 13h, A
  014A F514         MOV 14h, A
  014C F515         MOV 15h, A
  014E F516         MOV 16h, A
  0150 7E00         MOV R6, #0h
  0152 7F00         MOV R7, #0h
L0009:
  0154 8E04         MOV 4h, R6
  0156 8F05         MOV 5h, R7
  0158 BC051A       CJNE R4, #5h, L0006
  015B BD0017       CJNE R5, #0h, L0006
  015E 7464         MOV A, #64h
  0160 2513         ADD A, 13h
  0162 F513         MOV 13h, A
  0164 E4           CLR A
  0165 3514         ADDC A, 14h
  0167 F514         MOV 14h, A
  0169 E4           CLR A
  016A 3515         ADDC A, 15h
  016C F515         MOV 15h, A
  016E E4           CLR A
  016F 3516         ADDC A, 16h
  0171 F516         MOV 16h, A
  0173 801D         SJMP L0007

L0006:
  0175 8E02         MOV 2h, R6
  0177 EF           MOV A, R7
  0178 FB           MOV R3, A
  0179 33           RLC A
  017A 95E0         SUBB A, ACC
  017C FC           MOV R4, A
  017D FD           MOV R5, A
  017E EA           MOV A, R2
  017F 2513         ADD A, 13h
  0181 F513         MOV 13h, A
  0183 EB           MOV A, R3
  0184 3514         ADDC A, 14h
  0186 F514         MOV 14h, A
  0188 EC           MOV A, R4
  0189 3515         ADDC A, 15h
  018B F515         MOV 15h, A
  018D ED           MOV A, R5
  018E 3516         ADDC A, 16h
  0190 F516         MOV 16h, A
L0007:
  0192 0E           INC R6
  0193 BE0001       CJNE R6, #0h, L0008
  0196 0F           INC R7
L0008:
  0197 8E04         MOV 4h, R6
  0199 8F05         MOV 5h, R7
  019B C3           CLR C
  019C EC           MOV A, R4
  019D 940A         SUBB A, #0Ah
  019F ED           MOV A, R5
  01A0 6480         XRL A, #80h
  01A2 9480         SUBB A, #80h
  01A4 40AE         JC L0009
  01A6 AF0C         MOV R7, 0Ch
  01A8 BF1002       CJNE R7, #10h, L0010
  01AB 8005         SJMP L0011

L0010:
  01AD BF2030       CJNE R7, #20h, L0023
  01B0 8017         SJMP L0024

L0011:
  01B2 740A         MOV A, #0Ah
  01B4 2513         ADD A, 13h
  01B6 F513         MOV 13h, A
  01B8 E4           CLR A
  01B9 3514         ADDC A, 14h
  01BB F514         MOV 14h, A
  01BD E4           CLR A
  01BE 3515         ADDC A, 15h
  01C0 F515         MOV 15h, A
  01C2 E4           CLR A
  01C3 3516         ADDC A, 16h
  01C5 F516         MOV 16h, A
  01C7 802F         SJMP L0012

L0024:
  01C9 7414         MOV A, #14h
  01CB 2513         ADD A, 13h
  01CD F513         MOV 13h, A
  01CF E4           CLR A
  01D0 3514         ADDC A, 14h
  01D2 F514         MOV 14h, A
  01D4 E4           CLR A
  01D5 3515         ADDC A, 15h
  01D7 F515         MOV 15h, A
  01D9 E4           CLR A
  01DA 3516         ADDC A, 16h
  01DC F516         MOV 16h, A
  01DE 8018         SJMP L0012

L0023:
  01E0 E513         MOV A, 13h
  01E2 24FB         ADD A, #0FBh
  01E4 F513         MOV 13h, A
  01E6 E514         MOV A, 14h
  01E8 34FF         ADDC A, #0FFh
  01EA F514         MOV 14h, A
  01EC E515         MOV A, 15h
  01EE 34FF         ADDC A, #0FFh
  01F0 F515         MOV 15h, A
  01F2 E516         MOV A, 16h
  01F4 34FF         ADDC A, #0FFh
  01F6 F516         MOV 16h, A
L0012:
  01F8 851382       MOV DPL, 13h
  01FB 851483       MOV DPH, 14h
  01FE 750D03       MOV 0Dh, #3h
  0201 750E00       MOV 0Eh, #0h
  0204 120071       LCALL L0013
  0207 AC82         MOV R4, DPL
  0209 AD83         MOV R5, DPH
  020B AEF0         MOV R6, B
  020D FF           MOV R7, A
  020E EC           MOV A, R4
  020F 2513         ADD A, 13h
  0211 F513         MOV 13h, A
  0213 ED           MOV A, R5
  0214 3514         ADDC A, 14h
  0216 F514         MOV 14h, A
  0218 EE           MOV A, R6
  0219 3515         ADDC A, 15h
  021B F515         MOV 15h, A
  021D EF           MOV A, R7
  021E 3516         ADDC A, 16h
  0220 F516         MOV 16h, A
  0222 AC13         MOV R4, 13h
  0224 AD14         MOV R5, 14h
  0226 AE15         MOV R6, 15h
  0228 AF16         MOV R7, 16h
  022A 8C08         MOV 8h, R4
  022C 8D09         MOV 9h, R5
  022E 8E0A         MOV 0Ah, R6
  0230 8F0B         MOV 0Bh, R7
L0014:
  0232 AC08         MOV R4, 8h
  0234 AD09         MOV R5, 9h
  0236 AE0A         MOV R6, 0Ah
  0238 AF0B         MOV R7, 0Bh
  023A EC           MOV A, R4
  023B 6213         XRL 13h, A
  023D ED           MOV A, R5
  023E 6214         XRL 14h, A
  0240 EE           MOV A, R6
  0241 6215         XRL 15h, A
  0243 EF           MOV A, R7
  0244 6216         XRL 16h, A
  0246 80EA         SJMP L0014

L0015:
  0248 E582         MOV A, DPL
  024A 8517F0       MOV B, 17h
  024D A4           MUL AB
  024E C582         XCH A, DPL
  0250 C0F0         PUSH B
  0252 8518F0       MOV B, 18h
  0255 A4           MUL AB
  0256 D0F0         POP B
  0258 25F0         ADD A, B
  025A C583         XCH A, DPH
  025C 8517F0       MOV B, 17h
  025F A4           MUL AB
  0260 2583         ADD A, DPH
  0262 F583         MOV DPH, A
  0264 22           RET

L0019:
  0265 7A10         MOV R2, #10h
  0267 E4           CLR A
  0268 FB           MOV R3, A
  0269 FC           MOV R4, A
L0022:
  026A E582         MOV A, DPL
  026C 25E0         ADD A, ACC
  026E F582         MOV DPL, A
  0270 E583         MOV A, DPH
  0272 33           RLC A
  0273 F583         MOV DPH, A
  0275 EB           MOV A, R3
  0276 33           RLC A
  0277 FB           MOV R3, A
  0278 EC           MOV A, R4
  0279 33           RLC A
  027A FC           MOV R4, A
  027B EB           MOV A, R3
  027C 9517         SUBB A, 17h
  027E F5F0         MOV B, A
  0280 EC           MOV A, R4
  0281 9518         SUBB A, 18h
  0283 4006         JC L0021
  0285 FC           MOV R4, A
  0286 ABF0         MOV R3, B
  0288 438201       ORL DPL, #1h
L0021:
  028B DADD         DJNZ R2, L0022
  028D 22           RET

L0016:
  028E C2D5         CLR F0
  0290 E583         MOV A, DPH
  0292 30E70D       JNB ACC.7, L0017
  0295 D2D5         SETB F0
  0297 E4           CLR A
  0298 C3           CLR C
  0299 9582         SUBB A, DPL
  029B F582         MOV DPL, A
  029D E4           CLR A
  029E 9583         SUBB A, DPH
  02A0 F583         MOV DPH, A
L0017:
  02A2 E518         MOV A, 18h
  02A4 30E70D       JNB ACC.7, L0018
  02A7 B2D5         CPL F0
  02A9 E4           CLR A
  02AA C3           CLR C
  02AB 9517         SUBB A, 17h
  02AD F517         MOV 17h, A
  02AF E4           CLR A
  02B0 9518         SUBB A, 18h
  02B2 F518         MOV 18h, A
L0018:
  02B4 120265       LCALL L0019
  02B7 30D50B       JNB F0, L0020
  02BA E4           CLR A
  02BB C3           CLR C
  02BC 9582         SUBB A, DPL
  02BE F582         MOV DPL, A
  02C0 E4           CLR A
  02C1 9583         SUBB A, DPH
  02C3 F583         MOV DPH, A
L0020:
  02C5 22           RET

L0002:
  02C6 758200       MOV DPL, #0h
  02C9 22           RET

  02CA 54           DB 054h ; 'T'
  02CB 41           DB 041h ; 'A'
  02CC 52           DB 052h ; 'R'
  02CD 47           DB 047h ; 'G'
  02CE 45           DB 045h ; 'E'
  02CF 54           DB 054h ; 'T'
  02D0 5F           DB 05Fh ; '_'
  02D1 53           DB 053h ; 'S'
  02D2 54           DB 054h ; 'T'
  02D3 52           DB 052h ; 'R'
  02D4 49           DB 049h ; 'I'
  02D5 4E           DB 04Eh ; 'N'
  02D6 47           DB 047h ; 'G'
  02D7 00           DB 000h 
END

8051 What does SDCC do part 1 ?

ddupard — Mon, 10 Aug 2026 18:53:59 +0000

1. Introduction and Problem Statement

In order to test SDCC we are going to use the following C source code.

/* ========================================================================== *
 * Universal Test Corpus - Heterogeneous Architecture Analysis          *
 * ========================================================================== */


#include <stdint.h>

// 1. Global variables (testing absolute/relative addressing modes)
volatile uint32_t global_var_32 = 0xDEADBEEF;
volatile uint8_t  global_var_8  = 0x42;
const    char     string_const[] = "TARGET_STRING";

// 2. Function with parameter passing and local variables (stack / Frame Pointer test)
int32_t callee_function(int16_t a, int16_t b) {
    volatile int32_t local_result = 0;

    // Basic and mixed arithmetic operations (8, 16, 32 bits)
    local_result += (int32_t)(a * b);
    local_result -= (int32_t)(a / (b | 1)); // Avoid division by zero

    // Shift tests and logical operations (highly variable depending on ISAs)
    local_result = (local_result << 2) ^ 0x55AA55AA;
    local_result = (local_result >> 1) | (int32_t)global_var_8;

    return local_result;
}

// 3. Main function grouping complex control flows
int main(void) {
    volatile int32_t accumulator = 0;
    int16_t i;

    // Loop test (Conditional jumps, decrement, comparison tests)
    for (i = 0; i < 10; i++) {
        if (i == 5) {
            accumulator += 100;
        } else {
            accumulator += i;
        }
    }

    // Multiple branching test (Switch / Jump Table or cascaded if-else)
    switch (global_var_8) {
        case 0x10:
            accumulator += 10;
            break;
        case 0x20:
            accumulator += 20;
            break;
        default:
            accumulator -= 5;
            break;
    }

    // Function call (Stack management, save registers Link Register/PC)
    accumulator += callee_function((int16_t)accumulator, 3);

    // Pointer and indirect memory access test
    volatile uint32_t *ptr = (volatile uint32_t *)&global_var_32;
    *ptr = (uint32_t)accumulator;

    // Terminal infinite loop (classic for raw binaries / microcontrollers)
    while (1) {
        accumulator ^= *ptr;
    }

    return 0;
}

To compile it, we will use SDCC which produces an Intel HEX file. This file will be transformed in a ROM file using either objcopy or makebin (see below).

sdcc  "$SRC/test1.c" -o "8/test1_8051" 
objcopy -I ihex -O binary "8/test1_8051" "8/bin/test1_8051_bin" 
makebin -p "8/test1_8051" "8/bin/test1_8051.rom"

Moreover, to simulate the 8051, I use the MCU 8051 IDE (command mcu8051ide).

2. 8051 Presentation

The standard 8051 comes with a 4kb rom and a 128 bytes ram. It seems so tiny when you compare it with 32 or 64 bits processors, so every byte is precious especially in RAM.

Here is a concise list of the 8051 registers with a brief explanation for each:

A (Accumulator): The primary 8-bit register for all arithmetic, logical, and data transfer operations.
B: An 8-bit secondary register used primarily in conjunction with the accumulator for multiplication and division operations.
DPTR (Data Pointer): A 16-bit register (split into DPH and DPL) used for external RAM and program memory (ROM) addressing.
PC (Program Counter): A 16-bit register that tracks the memory address of the next instruction to be executed.
SP (Stack Pointer): An 8-bit register pointing to the top of the stack, used for managing subroutine calls and saving return addresses.
PSW (Program Status Word): An 8-bit register containing status flags such as the Carry bit, Overflow bit, and register bank selection bits.
R0 – R7 (Working Registers): Eight general-purpose 8-bit registers grouped into selectable banks, used for temporary data storage and pointer operations.

Beyond its core registers and instruction set, the standard 8051 architecture provides essential hardware peripherals designed for embedded control.

It features four 8-bit bidirectional I/O ports (Port 0 to Port 3) which can be used for both data input/output and special functions like external memory addressing or communication.

For timing and event counting, the chip integrates two 16-bit timer/counters (Timer 0 and Timer 1) configurable in multiple modes.

Additionally, the 8051 implements a flexible interrupt structure supporting five distinct sources (external interrupts INT0 and INT1, timer overflows TF0 and TF1, and the serial port receive/transmit interrupt), each vectoring to a fixed program memory address to handle real-time events efficiently

3. 8051 The instruction set

The 8051 instruction set is rudimentary yet extremely direct.

A. Data Transfer Instructions (14 base mnemonics)

MOV – Move byte (register, direct, indirect, immediate)
MOVC – Move code memory (program ROM to accumulator)
MOVX – Move external data memory (RAM/IO to/from accumulator)
PUSH – Push byte onto stack
POP – Pop byte from stack
XCH – Exchange accumulator with byte
XCHD – Exchange lower-order nibble indirect

B. Arithmetic Instructions (8 base mnemonics)

ADD – Add to accumulator
ADDC – Add to accumulator with carry
SUBB – Subtract from accumulator with borrow
INC – Increment by 1 (accumulator, data pointer, registers, RAM)
DEC – Decrement by 1
MUL – Multiply A by AB
DIV – Divide A by B
DA – Decimal adjust accumulator

C. Logical Instructions (6 base mnemonics)

ANL – Logical AND
ORL – Logical OR
XRL – Logical Exclusive-OR
CLR – Clear accumulator or bit
CPL – Complement accumulator or bit
SWAP – Swap nibbles within the accumulator

D. Rotate & Shift Instructions (4 base mnemonics)

RL – Rotate accumulator left
RLC – Rotate accumulator left through carry
RR – Rotate accumulator right
RRC – Rotate accumulator right through carry

E. Boolean / Bit-Manipulation Instructions (10 base mnemonics)

SETB – Set bit to 1
MOV – Move bit data (listed under data transfer, used heavily in bit space)
JC – Jump if carry is set
JNC – Jump if carry is not set
JB – Jump if bit is set
JNB – Jump if bit is not set
JBC – Jump if bit is set and clear bit
ANL – Bitwise logical AND with carry
ORL – Bitwise logical OR with carry
CPL – Bit complement

6. Program Branching / Control Transfer Instructions (15 base mnemonics)

ACALL – Absolute subroutine call (2KB range)
LCALL – Long subroutine call (64KB range)
RET – Return from subroutine
RETI – Return from interrupt
AJMP – Absolute jump (2KB range)
LJMP – Long jump (64KB range)
SJMP – Short jump (relative offset)
JMP – Indirect jump relative to DPTR or PC (JMP @A+DPTR)
JZ – Jump if accumulator is zero
JNZ – Jump if accumulator is not zero
CJNE – Compare and jump if not equal
DJNZ – Decrement and jump if not zero
NOP – No operation

All these instructions use a 1-byte base opcode, though the full instruction may span 1, 2, or 3 bytes depending on the addressing mode and operands. For the 8051, the total number of instructions is 111 which use 255 opcodes. The only one not used is 0xA5.

To understand the difference between the 57 instructions in the instruction set and the total number of 111 instructions, let's take the example of the 24 arithmetic instructions.

The 24 arithmetic instructions of the 8051 are broken down into 8 families of mnemonics. Combining these mnemonics with their various addressing modes (accumulator, registers, direct or indirect memory, immediate values) yields a total of 24 distinct operation formats.Here is the complete breakdown categorized by function:

1. Addition (8 instructions)

ADD A, R: Adds the contents of register $R0\text{--}R7$ to the Accumulator ($A$).
ADD A, direct: Adds the contents of an internal direct memory address to $A$.
ADD A, @ri: Adds the value pointed to by $R0$ or $R1$ to $A$.
ADD A, #data: Adds an immediate value (constant) to $A$.
ADDC A, R: Adds register $R0\text{--}R7$ to $A$ along with the Carry flag ($C$).
ADDC A, direct: Adds a direct memory address to $A$ along with the Carry flag.ADDC A, @ri: Adds the memory contents pointed to by $R0$ or $R1$ to $A$ along with the Carry flag.
ADDC A, #data: Adds an immediate value to $A$ along with the Carry flag.

2. Subtraction (4 instructions)

SUBB A, R: Subtracts the value of register $R0\text{--}R7$ and the Carry flag ($C$) from $A$.
SUBB A, direct: Subtracts a direct memory address and the Carry flag from $A$.SUBB A, @ri: Subtracts the value pointed to by $R0$ or $R1$ and the Carry flag from $A$.
SUBB A, #data: Subtracts an immediate value and the Carry flag from $A$.

3. Increment (5 instructions)

INC A: Increments the Accumulator ($A = A + 1$).
INC R: Increments one of the registers $R0\text{--}R7$.
INC direct: Increments the contents of a direct memory address.
INC @ri: Increments the value pointed to by $R0$ or $R1$.
INC DPTR: Increments the 16-bit Data Pointer ($DPTR$).

4. Decrement (4 instructions)

DEC A: Decrements the Accumulator ($A = A - 1$).
DEC R: Decrements one of the registers $R0\text{--}R7$.
DEC direct: Decrements the contents of a direct memory address.
DEC @ri: Decrements the value pointed to by $R0$ or $R1$.

5. Multiplication and Division (2 instructions)

MUL AB: Multiplies registers $A$ and $B$ ($A \times B$). The 16-bit result is stored in the $B:A$ pair (High byte in $B$, Low byte in $A$).
DIV AB: Divides $A$ by $B$ ($A / B$). The quotient is stored in $A$ and the remainder in $B$.

6. BCD Adjustment (1 instruction)

*DA A: Decimal Adjust Accumulator. Adjusts the binary result in the Accumulator to yield a valid BCD (Binary Coded Decimal) value following an addition.

7. Comparison with the x86_64

As a comparison, the x86_64 architecture (CISC) has accumulated decades of backward compatibility since the original 8086. The exact number depends on how you count, because a single instruction can vary based on data size (8, 16, 32, or 64 bits), registers used, and prefixes applied:

Basic logical instructions or mnemonics: There are approximately 1,500 distinct instructions (according to Intel's XED decoding tool, which counts instruction classes from AAA to XTEST, including extensions).
Instruction forms / Effective opcodes: If you take into account all variations in operand size, addressing modes, and massive extensions (MMX, SSE, AVX, etc.), you arrive at more than 6,000 instruction variations.

Unlike the 8051, where the base opcode always fits into a single byte, x86_64 opcodes can span multiple bytes (often prefixed by 0x0F, 0x38, etc., or modified by REX bytes to switch to 64-bit mode), resulting in significantly more complex hardware decoding.

4. Memory-Mapped Registers and Direct Addressability

A unique architectural feature of the 8051 is that its Special Function Registers (SFRs) are directly mapped into the upper Special Function Register memory space (addresses 0x80 to 0xFF). In this architecture, core hardware registers—such as the Stack Pointer (SP at 0x81), the Accumulator (ACC at 0xE0), or I/O ports (like P0 at 0x80)—are not isolated processor entities. Instead, they can be accessed directly by their physical hex addresses or by their standard mnemonic names. This memory-mapping allows standard data movement and bit-manipulation instructions (e.g., MOV 0x81, #0x07 or SETB 0x88) to directly configure peripherals and CPU status flags, streamlining low-level hardware control without requiring specialized bus-management instructions.

Now that the general presentation of the 8051 architecture is over, it's time to dive into what SDCC generates

5. SDCC: The stub

In bare-metal environments and microcontroller architectures like the 8051, a stub acts as the foundational initialization bridge between hardware reset and the high-level application code. Because microcontrollers do not feature a host operating system to set up memory spaces or execution contexts, the startup stub is responsible for critical low-level chores: it sets the Stack Pointer (SP) to define the valid stack boundary, clears internal RAM to ensure predictable initial variable states, and configures hardware segments before safely jumping to the user's main routine.

Right below you will find the stub generated by SDCC.

CSEG AT 0000h
  0000 020006       LJMP L0001

L0004:
  0003 020147       LJMP L0005

L0001:
  0006 758118       MOV SP, #18h
  0009 1202C6       LCALL L0002
  000C E582         MOV A, DPL
  000E 6003         JZ L0003
  0010 020003       LJMP L0004

L0003:
  0013 7900         MOV R1, #0h
  0015 E9           MOV A, R1
  0016 4400         ORL A, #0h
  0018 601B         JZ L0025
  001A 7A00         MOV R2, #0h
  001C 9002D8       MOV DPTR, #02D8h
  001F 7801         MOV R0, #1h
  0021 75A000       MOV P2, #0h
L0027:
  0024 E4           CLR A
  0025 93           MOVC A, @A+DPTR
  0026 F2           MOVX @R0, A
  0027 A3           INC DPTR
  0028 08           INC R0
  0029 B80002       CJNE R0, #0h, L0026
  002C 05A0         INC P2
L0026:
  002E D9F4         DJNZ R1, L0027
  0030 DAF2         DJNZ R2, L0027
  0032 75A0FF       MOV P2, #0FFh
L0025:
  0035 E4           CLR A
  0036 78FF         MOV R0, #0FFh
L0028:
  0038 F6           MOV @R0, A
  0039 D8FD         DJNZ R0, L0028
  003B 7800         MOV R0, #0h
  003D E8           MOV A, R0
  003E 4400         ORL A, #0h
  0040 600A         JZ L0029
  0042 7901         MOV R1, #1h
  0044 75A000       MOV P2, #0h
  0047 E4           CLR A
L0030:
  0048 F3           MOVX @R1, A
  0049 09           INC R1
  004A D8FC         DJNZ R0, L0030
L0029:
  004C 7800         MOV R0, #0h
  004E E8           MOV A, R0
  004F 4400         ORL A, #0h
  0051 600C         JZ L0031
  0053 7900         MOV R1, #0h
  0055 900001       MOV DPTR, #0001h
  0058 E4           CLR A
L0032:
  0059 F0           MOVX @DPTR, A
  005A A3           INC DPTR
  005B D8FC         DJNZ R0, L0032
  005D D9FA         DJNZ R1, L0032
L0031:
  005F 7508EF       MOV 8h, #0EFh
  ...

The stub goes from the very first instruction (at address 0000) till the instruction located at address 005D.
The first real instruction related to the program starts at 005F. The stub takes a little bit less than 95 bytes before doing something related to the program. The 95 bytes contain code which is nearly useless for our program. In fact the only 2 things interesting in the 95 bytes are:

the initialization of the SP register
the reset of memory

so it could be easily replaced with the following instructions ( 9 bytes )

    758118      MOV SP, #18h              
    E4          CLR A
    78FF        MOV R0, #0FFh
L0028:
    F6          MOV @R0, A
    D8FD        DJNZ R0, L0028

meaning that we could reuse 86 bytes of the stub without changing the code of the program.

Stub Optimization as a Stealth Vector for verify_system_integrity (see EEPROM Hijacking on 8051 Architecture)

As we observed when analyzing SDCC's compiled output, the default 8051 startup stub wastes nearly 95 bytes on generic memory clearing routines that are largely redundant for custom firmware deployments. Instead of appending our security checks—such as the verify_system_integrity routine—to the end of the program where space may be constrained or easily monitored, we can surgically repurpose these wasted bytes within the startup stub itself. By replacing the bloated initialization code with our compact 9-byte sequence (MOV SP and the RAM-clearing loop), we free up over 86 bytes of pristine ROM space right at the very beginning of execution. Injecting the verify_system_integrity hook directly into this reclaimed space ensures that the integrity check runs before any main application logic or EEPROM operations take place, achieving both zero-overhead optimization and a stealthier boot-time security gatekeeper.

6. the 8051 Today

The 8051 is still used today, although its role has evolved considerably since its launch. Even though newer 32-bit and 64-bit architectures dominate modern computing, the 8051 architecture remains active and omnipresent across several fields:

Everyday Embedded Electronics and Appliances

This is one of the best-known strongholds: you find the 8051 in almost everything around you—from your television remote control to washing machines, microwave ovens, fridges, smart cards, car key fobs, and power supplies, chosen for its reliability, low power, and cost efficiency.

Industrial Embedded Systems and Legacy Hardware

In industry, the golden rule is "if it works, don't change it." Many control devices, automation systems, smart sensors, and power management units incorporate standard 8051 cores or modern enhanced derivatives. Replacing these proven embedded systems often requires costly redesign and recertification.

Modern Descendants and Silicon Vendors

The base architecture also survives through modernized and supercharged versions. Major semiconductor manufacturers (such as NXP, Silicon Labs, and Maxim/Analog Devices) offer high-performance derivatives featuring single-cycle execution, higher frequencies, expanded flash memory, and advanced peripherals like USB, CAN, and ADCs while maintaining software compatibility.

Embedded Education and Hobbyists

The academic and hobbyist community keeps the 8051 extremely alive. As one of the most widely taught microcontrollers in engineering schools, it continues to serve as the foundational platform for learning bare-metal programming, assembly language, and hardware interfacing fundamentals.

7. Conclusion

This article was an introduction of what the SDCC compiler does. Even in this small part we saw, that the compiler adds some code which could be easily removed because unuseful. We will see the same phenomenon in the next article.

Ghidra internals: Where are my logs ?

ddupard — Sun, 09 Aug 2026 22:20:47 +0000

Ghidra uses the Apache Log4j logging library to store a lot of execution messages.

Finding these logs can be quite tricky, especially if you launch Ghidra from a shell (using ghidraRun) because no output is displayed in the terminal. Usually, the first instinct is to look for a .ghidra directory directly in your HOME folder. In our case, that will fail.

Under Linux, Ghidra follows the XDG Base Directory specification, which is why user configuration and logs are located inside ~/.config/ghidra/ instead of a direct ~/.ghidra/ folder.

1. The Quick Command

The fastest way to locate your log file is by running:

find ~ -name "application.log" 2>/dev/null

2. Locating Logs from IDE / Console

Another way to find your logs is when you run Ghidra through Eclipse to inspect its internals.

In Eclipse, launching Ghidra outputs startup traces directly in the console panel:

Look specifically for the following lines:

2026-08-09 23:27:53 INFO  (GhidraRun) User daniel started Ghidra.  
2026-08-09 23:27:53 INFO  (GhidraRun) User settings directory: /home/daniel/.config/ghidra/ghidra_12.2_DEV_location_ghidra-master  
2026-08-09 23:27:53 INFO  (GhidraRun) User temp directory: /tmp/daniel-ghidra  
2026-08-09 23:27:53 INFO  (GhidraRun) User cache directory: /var/tmp/daniel-ghidra  
2026-08-09 23:27:57 INFO  (GhidraRun) Ghidra startup complete (17028 ms)

Listing the files inside the User settings directory gives:

drwx--x--x 8 daniel daniel   4096 Aug  9 23:13 .
drwxr-x--- 5 daniel daniel   4096 Jul 28 16:49 ..
drwxrwxr-x 2 daniel daniel   4096 Jul 28 16:52 analyzer_options
-rw-rw-r-- 1 daniel daniel 393379 Aug  9 23:14 application.log
drwxrwxr-x 2 daniel daniel   4096 Jul 28 16:50 bsim
-rw-rw-r-- 1 daniel daniel   9066 Aug  9 16:38 FrontEndTool.xml
drwxrwxr-x 4 daniel daniel   4096 Aug  9 16:40 osgi
drwxrwxr-x 2 daniel daniel   4096 Jul 28 16:50 parserprofiles
-rw-rw-r-- 1 daniel daniel   1428 Aug  9 23:14 preferences
-rw-rw-r-- 1 daniel daniel      0 Jul 28 16:49 script.log
drwxrwxr-x 3 daniel daniel   4096 Jul 28 17:23 symbols
drwxrwxr-x 2 daniel daniel   4096 Jul 28 16:49 tools

And voilà! We found the application.log file containing all the execution logs.

If you inspect the parent directory of the User settings folder, you will notice several directories—each corresponding to a specific version or launch mode of Ghidra:

drwxr-x---  5 daniel daniel 4096 Jul 28 16:49 .
drwx------ 41 daniel daniel 4096 Aug  2 21:33 ..
drwx--x---  8 daniel daniel 4096 Jul 26 00:44 ghidra_12.1.2_PUBLIC
drwx--x---  8 daniel daniel 4096 Jul 26 20:24 ghidra_12.2_DEV
drwx--x--x  8 daniel daniel 4096 Aug  9 23:13 ghidra_12.2_DEV_location_ghidra-master
-rw-r-----  1 daniel daniel   42 Aug  9 23:44 lastrun

Pro Tip: Stop Using System.out.println

Knowing where logs are saved changes how you format your debug output. Instead of relying on System.out.println, you can use Ghidra's built-in ghidra.util.Msg class to write clean, formatted lines straight to application.log:


import ghidra.util.Msg;

    private void showAnalyzer(Analyzer analyzer) {
        int nameColumnWidth = 50;
        int classColumnWidth = 80;
        int triggerColumnWidth = 30;

        AnalyzerType at = analyzer.getAnalysisType();
        Class<?> clazz = analyzer.getClass();

        String format = "%-" + nameColumnWidth + "s %-" + classColumnWidth + "s %-" + triggerColumnWidth + "s";
        Msg.info(this, String.format(format, analyzer.getName(), clazz.getName(), at.getName()));
    }

3. Conclusion

It took me some time to figure out where Ghidra was hiding its log files. That's why I wrote this short article—hopefully, it saves you a few minutes!

Adapting Ghidra for Reverse Engineering Undocumented Binary Architectures

ddupard — Fri, 07 Aug 2026 12:40:06 +0000

1. Language Architecture in Ghidra

When Ghidra loads an architecture (such as the MOS 6502), it parses the .ldefs manifest file, which declares metadata and binds three foundational specification pillars:

The .pspec (Processor Specification):
Defines the processor’s hardware context. It declares special-purpose registers (e.g., stack pointer SP, status/flags registers), default memory maps (RAM, ROM, I/O), and hardware interrupt vectors.
The .cspec (Compiler Specification):
Defines the ABI and calling conventions (e.g., parameter passing mechanisms), stack alignment rules, and return value handling. This is the critical building block enabling the decompiler to reconstruct assembly into readable C code.
The .sla / .slaspec (SLEIGH Specification):
- .slaspec: The human-readable source file describing the instruction set architecture (opcodes, instruction formats, and p-code semantics).
- .sinc (SLEIGH Include): Modular inclusion files (typically used to split complex architectures like ARM or x86, or isolate instruction subsets like Thumb). Given the simplicity of the 6502, everything is defined directly within the .slaspec file.
- .sla: The compiled binary version of the .slaspec (generated by the Sleigh compiler). Ghidra loads this compiled .sla file into memory at runtime for optimal performance.

2. The Challenges of Reverse Engineering Undocumented Binaries

When dealing with a binary compiled for an undocumented processor, Ghidra's default paradigm faces major limitations:

The .slaspec file is unavailable.
Ghidra attempts to aggressively disassemble everything.
Analyzing an undocumented target requires a strict two-phase approach.

3. Missing `.slaspec` File

Without a valid .slaspec definition, Ghidra renders ?? for every opcode. The primary objective when tackling an unknown CPU is precisely to reconstruct this missing .slaspec specification.

4. Overcoming Ghidra's Aggressive Disassembly

By default, Ghidra (like most disassemblers) employs an exhaustive strategy (using linear sweep or recursive control-flow traversal). Upon encountering unknown data, instruction set switches, or embedded data structures (data-in-code), it attempts to interpret those bytes as executable code anyway. Consequently, the disassembler loses synchronization, creating cascading "garbage code" that corrupts the entire analysis.

To tackle an unknown architecture, we must invert Ghidra’s core logic: shifting from an "aggressive/exhaustive" mindset to an "opportunistic/conservative" model.

A. Why Prevent Full Disassembly?

On an undocumented architecture, instruction alignment, variable opcode boundaries, and the exact demarcation between data and executable code are initially unknown.

Forcing Ghidra to halt rather than guess provides major technical advantages:

Prevents Memory Contamination: A single misidentified instruction can corrupt register tracking, stack depth calculations, and Control Flow Graphs (CFG) across thousands of subsequent bytes.
Isolates "Islands of Certainty": Instead of a 100% flawed disassembly, we isolate distinct, 100% reliable execution blocks (e.g., function prologues/epilogues, branch instructions, or jump tables).
Enables Guided Analysis: Ghidra's analysis engine operates strictly where we (or our heuristic algorithms) explicitly grant permission.

B. Patching Ghidra Under the Hood

Ghidra is modular, written primarily in Java with its decompilation engine in C++. Adapting its disassembly engine can be achieved across three integration levels:

a. Disabling Auto-Analysis Passes

Ghidra executes background automated analyzers upon loading a binary (e.g., Disassemble Entry Points, Subroutine-Direct Call Analyzer).

Action: Disable all automatic disassembly analyzers.
Result: Ghidra loads the binary as raw, unparsed bytes (undefined) without attempting speculative decoding.

b. Overriding `DissectedFlow` & SLEIGH Rules (Architectural Level)

SLEIGH governs instruction semantics and control-flow parsing. For an unknown architecture, we can construct a strict, minimalist SLEIGH module:

If a byte sequence fails to match a known pattern with 100% confidence, it defaults to UNDEFINED rather than throwing an exception or attempting partial decoding.
Unresolved control-flow instructions (unknown JMP/CALL) act as hard terminators, stopping the disassembler from blindly parsing subsequent bytes.

c. Modifying the Java Disassembler Engine (`Disassembler.java`)

This involves modifying Ghidra's core exploration algorithms (ghidra.app.plugin.core.disass).

By default, given an entry point, Ghidra recursively queues and processes all jump targets.
Patch: Enforce traversal depth limits or inject confidence metrics (e.g., based on byte entropy, alignment, or pattern matching). If confidence drops below a threshold, the disassembler halts the branch and flags the location as an "uncertainty node".

5. Two-Phase Analysis for Undocumented CISC Processors

The challenge extends beyond disabling the disassembly engine; variable-length (CISC-like) architectures require a two-phase analysis pipeline:

Instruction Boundary Detection: Identifying length and boundaries.
Opcode Semantic Mapping: Decoding underlying instruction logic.

Ghidra lacks an intermediate representation layer for instruction boundaries; a byte sequence is either a fully formed instruction or nothing at all.

Step 1: Chunking (Instruction Boundary Detection): Through statistical entropy, alignment, or flow analysis, we determine that bytes 0xFA 0x12 0x88 constitute a single instruction unit, without yet knowing its underlying semantics.
Step 2: Decoding (Opcode Mapping): Mapping that sequence to an opcode, operands, and p-code semantics (e.g., MOV R1, [R2+8]).

Because Ghidra bridges raw bytes directly to fully decoded SLEIGH instructions, failure at Step 2 (due to an unknown opcode) breaks the pipeline entirely. Ghidra fails to record the boundary discovered in Step 1 and falls back to an undefined byte, triggering cascading misalignment across subsequent variable-length bytes.

Bridging the Abstraction Gap in Ghidra

To introduce this missing "Boundary/Chunk" layer without re-architecting Ghidra's core engine, two surgical workarounds can be applied:

Option A: Dummy / Proxy Instructions (SLEIGH Abstraction)

Define generic parsing rules within the SLEIGH specification:

Instead of failing on unknown opcodes, SLEIGH instantiates a "Proxy Instruction" matching the precise length identified by your boundary analyzer.
Ghidra Display Example: UNK_LEN3 0xFA, 0x12, 0x88 (a 3-byte unresolved instruction).
Benefit: Ghidra treats this chunk as a valid instruction unit, advancing the Program Counter (PC) by exactly 3 bytes. Control Flow Graphs remain intact, memory alignment is preserved, and phase-1 boundaries are stored directly within Ghidra’s database.

Option B: Data Types & Marker Engines (Ghidra Java API)

Instead of instantiating fake instructions, Phase 1 applies custom data structures across byte ranges via the Ghidra API:

Define a custom low-level Data Type (e.g., InstructionChunk of size N).
Apply it to byte sequences validated by Phase 1.
Ghidra locks these bytes as an indivisible unit. As Phase 2 algorithms progressively resolve opcode semantics, scripts replace InstructionChunk instances with fully decoded instructions.

6. Conclusion

While Ghidra is natively unequipped for out-of-the-box analysis of undocumented processors, rebuilding a reverse engineering framework from scratch would be a mistake. Leveraging and adapting Ghidra's existing infrastructure to handle unknown architectures is significantly more efficient than reinventing the wheel.

My upcoming articles will detail experimental results, patches, and the final integration solutions chosen for this adaptation.

From C Corpus to Machine Code Analysis: A Two-Phase Pipeline for Unknown Architectures

ddupard — Wed, 05 Aug 2026 22:26:35 +0000

Creating a disassembler for an undocumented or novel architecture is a notoriously complex challenge. It requires a deep understanding of how fundamental software constructs—such as variable initialization, function calls, control loops, and return statements—are translated into binary patterns across diverse instruction set architectures (ISAs).
Since the number of existing processors, microcontrollers and chips is huge, knowing all the different cases is impossible for a human being.

That's why working on this subject necessitates a two-phase pipeline:

Filling a pattern matching database
Using the pattern matching database to guess which series of bytes corresponds to which assembly instructions using a Sudoku-like algorithm

1. Filling a pattern matching database (Semantic P-Code Mapping)

During this offline phase, a massive corpus of C source code is compiled across multiple known architectures (ARM, MIPS, RISC-V, x86, etc.). The resulting binaries are parsed using Ghidra's SLEIGH engine to extract their P-Code intermediate representation. By mapping high-level C constructs (variable initialization, loop counters, frame setups) directly to their corresponding P-Code execution graphs, we build an architecture-agnostic database of semantic patterns.

2. Guessing the bytes

A. Entropy Analysis & Decompression / Decryption Detection

Before attempting disassembly, the baseline entropy of the target binary must be evaluated to detect encryption or compression routines. If an encryption or compression layer is identified, one can exploit the hypothesis that the stub or routine resides within the initial boot instructions (e.g., the first 300 to 500 instructions). Decompression and decryption routines leave distinctive algorithmic signatures; identifying them provides critical semantic clues about memory access patterns and execution flow.

B. Finding the reset vector of the processor.

The simplest way to do it is to start by using already known reset vectors.

C. Constraint Propagation and Hypothesis Scoring

This is where the core analysis takes place. The engine scans the unknown binary to match byte sequences against the P-Code semantic patterns stored in our database. When a match is suspected, the candidate sequence is simulated through Ghidra's P-Code engine to check local structural validity (e.g., control flow, stack alignment, and register bounds).

To evaluate ambiguous paths or edge cases, the Hypothesis Evaluator queries an LLM Service to provide high-level semantic scoring based on software idioms and code structure. If an hypothesis leads to impossible execution states or invalid memory access, it is pruned.

Unlike traditional Sudoku puzzles, where constraints naturally collapse the search space quickly, binary disassembly on unknown ISAs faces a massive combinatorial explosion—making this hybrid P-Code simulation and LLM evaluation loop essential.

3. Conclusion

While reverse-engineering unknown architectures remains a formidable challenge due to state-space explosion, combining P-Code constraint propagation with LLM-driven semantic evaluation provides a structured, scalable approach. Beyond its practical applications in hardware security and legacy system recovery, building such a pipeline offers deep insights into the fundamental mechanics of compilation and instruction set semantics.

Identifying the Processor of a Bare-Metal Binary (Strategy 2): Modifying prompts

ddupard — Wed, 05 Aug 2026 05:55:16 +0000

Industrializing the disassembly of an undocumented processor from a raw binary is a complex challenge that can be broken down into 4 main phases:

Verify that the binary does not belong to an already known processor.
Verify that the binary does not correspond to obfuscated, compressed, or encrypted code from a known processor.
Build an undocumented processor generator.
Develop the analysis workflow and disassembly generation pipeline.

For the first step of this project, the goal is to evaluate different strategies and identify the most effective approach.

2. Evaluated Strategies

The first strategy aimed to generate a transcodification table (mapping byte sequences to assembly instructions) in order to disassemble the binary both statically and dynamically for a given processor. This process continues until one or more bytes fail to match any known instruction for that processor, or until disassembly completes successfully (note: successful disassembly does not necessarily mean the binary was compiled for that specific processor).

To implement this strategy and build the transcodification table, several approaches were tested:
Ghidra transcodification table generation: Failed.
Native disassembler transcodification table generation: Failed.
Using Gemini to generate the table from raw byte sequences: Successful.

(For a full summary of the tests conducted under Strategy 1, see "Identifying the Processor of a Bare-Metal Binary (Strategy 1): Building a custom disassembler".)

The second strategy takes a completely different approach. It consists of using Ghidra to disassemble the binary against a large number of target architectures (177 processors) and then leveraging a Large Language Model (LLM) to analyze the resulting disassembly outputs to determine which processor truly matches the binary.

(For a full summary of the tests conducted under Strategy 1, see "Identifying the Processor of a Bare-Metal Binary — (Strategy 2): Testing LLMs".)

Today we are going to test if modifying the prompt of the model with the best results ( qwen3-coder:30b ) could lead to improved results.

3. Test Protocol

We are going to use the same binaries as in our preceding test.

Firmware 1: Target processor is natively supported by Ghidra.
Firmware 2: Target processor is not supported by Ghidra.
Firmware 3: An ELF file, explicitly disassembled as a raw bare-metal binary (forcing raw byte parsing).

The prompt 1 we use in our last test was

SYSTEM_PROMPT = """You are an expert in reverse engineering and processor architectures.
Your task is to verify the consistency of a raw firmware disassembly.
Examine the provided instructions, verify whether the architecture's syntax is valid,
and determine if the instructions appear coherent (absence of repeated invalid instructions, aberrant opcodes, etc.).
Respond strictly in valid JSON format."""

In order to reduce the number of false positives, We will use the next 2 prompts.

Prompt 2:

SYSTEM_PROMPT = """You are a Principal Reverse Engineer specializing in bare-metal firmwares and undocumented ISAs.
Your goal is to REJECT invalid disassemblies and eliminate false positives.

Do NOT assume the code is valid just because instructions look syntactically correct.
Analyze the semantic coherence of the disassembly.

Follow this step-by-step reasoning (Chain-of-Thought):
1. CONTROL FLOW: Are there logical jumps/branches? Or is it a linear sequence of random instructions?
2. REGISTERS & STACK: Are registers used consistently? Is there a coherent function prologue/epilogue (stack handling)?
3. ABERRATIONS: Do you see repetitive opcodes, impossible immediate values, or meaningless instruction loops?
4. PATTERNS: Does this look like real compiled code or raw data/garbage interpreted as instructions?

Based on your analysis, fill out the following JSON. Be aggressive with disqualification: if in doubt, mark is_valid as false.

Respond STRICTLY in valid JSON with this schema:
{
    "reasoning": "Your step-by-step analysis detailing control flow, register use, and anomalies found",
    "processor_id": "{processor_id}",
    "is_valid": false,
    "confidence_score": 0.00,
    "detected_anomalies": ["list of specific anomalies, e.g., 'no jump targets', 'aberrant register R15 write'"]
}"""

Prompt 3:

SYSTEM_PROMPT = """You are an expert in CPU architecture and reverse engineering.
Your task is to detect whether a disassembly snippet is REAL compiled code or GARBAGE output caused by wrong ISA decoding.

Example of GARBAGE code (Wrong ISA):
- Continuous stream of data movement without control flow (e.g. 50 MOV instructions in a row).
- Broken stack usage (e.g. POP without prior PUSH).
- Odd jump targets or incoherent register reuse.

Example of VALID code (Correct ISA):
- Structured prologues (e.g. push {r4-r7, lr}).
- Clear control flow (CMP followed by conditional BRANCH).
- Coherent stack frame adjustments.

Analyze the provided snippet and output STRICTLY a JSON format:
{
    "cot_analysis": "Step-by-step verification of prologues, jump density, and register logic",
    "processor_id": "{processor_id}",
    "is_valid": boolean,
    "confidence_score": float,
    "detected_anomalies": ["list of anomalies"]
}"""

4. Benchmark Results

Firmware 1 (Known Processor)

Prompt 1
qwen3-coder:30b: Generated reports for all 177 files. Identified 35 potential candidate processors (including the correct
Prompt 2

============================================================
                POTENTIAL CANDIDATES REPORT                
============================================================
 Model Tested  : qwen3-coder:30b
 Target Source : /home/daniel/Desktop/Assembleur/python/Toolchain/output_results
============================================================

[✓] Found 1 potential matching processor(s):

  • Processor  : 8051:BE:24:cip-51
    Confidence : 95.0%
    Summary    : The disassembly shows coherent 8051 code with logical control flow, proper function prologue/epilogue patterns, and consistent register usage. There are no obvious aberrations or garbage instructions. The code appears to be a valid firmware routine performing memory operations and I/O handling.
------------------------------------------------------------
============================================================

Prompt 3

============================================================
                POTENTIAL CANDIDATES REPORT                
============================================================
 Model Tested  : qwen3-coder:30b
 Target Source : /home/daniel/Desktop/Assembleur/python/Toolchain/output_results
============================================================

[✓] Found 17 potential matching processor(s):

  • Processor  : 6805:BE:16:default
    Confidence : 95.0%
    Summary    : The disassembly shows valid 6805 code with structured control flow using BRSET/BRCLR instructions, proper use of indexed addressing modes, and coherent register usage. No obvious garbage or malformed instructions are present.
------------------------------------------------------------
  • Processor  : PIC-17:LE:16:PIC-17C7xx
    Confidence : 95.0%
    Summary    : The disassembly shows valid PIC-17C7xx instructions with proper control flow, including CALL, GOTO, and RETURN operations. There are no obvious anomalies such as continuous MOV instructions or broken stack usage. The code appears to be structured with function calls and jumps, indicating real compiled code.
------------------------------------------------------------
  • Processor  : HC05:BE:16:default
    Confidence : 95.0%
    Summary    : The disassembly shows structured control flow with conditional branches, valid use of stack-relative addressing, and coherent register usage. No obvious garbage or malformed instructions are present.
...

Firmware 2 (Unknown Processor)

Prompt 1
qwen3-coder:30b: Generated reports for all 177 files. Identified 32 potential candidate processors (false positives).
Prompt 2

============================================================
                POTENTIAL CANDIDATES REPORT                
============================================================
 Model Tested  : qwen3-coder:30b
 Target Source : /home/daniel/Desktop/Assembleur/python/Toolchain/output_results
============================================================

[✗] No valid processor candidate found among the analyzed files.
============================================================

Prompt 3

============================================================
                POTENTIAL CANDIDATES REPORT                
============================================================
 Model Tested  : qwen3-coder:30b
 Target Source : /home/daniel/Desktop/Assembleur/python/Toolchain/output_results
============================================================

[✓] Found 12 potential matching processor(s):

  • Processor  : PIC-17:LE:16:PIC-17C7xx
    Confidence : 95.0%
    Summary    : The disassembly shows valid PIC-17C7xx instructions with coherent control flow and proper use of registers. There are no obvious anomalies such as broken stack usage or continuous data movement without control flow. The presence of NOPs at the end may indicate padding or optimization artifacts, but does not invalidate the code.
------------------------------------------------------------
  • Processor  : 8048:LE:16:default
    Confidence : 95.0%
    Summary    : The disassembly shows valid 8048 instruction set usage with structured control flow, appropriate use of flags (JTF, JF1, JB1), and coherent data movement. There are no obvious signs of garbage output such as continuous MOV instructions or broken stack usage.
------------------------------------------------------------
  • Processor  : z182:LE:16:default
    Confidence : 95.0%
    Summary    : The disassembly shows valid Z182 instruction set usage with structured control flow, appropriate use of registers, and logical sequence of operations including I/O operations and calls. No clear signs of garbage output or incorrect ISA decoding.
...

Firmware 3 (ELF File disassembled as Bare Metal)

Prompt 1
qwen3-coder:30b: Generated reports for all 177 files. Identified 42 potential candidate processors (including the correct one).
Prompt 2

============================================================
                POTENTIAL CANDIDATES REPORT                
============================================================
 Model Tested  : qwen3-coder:30b
 Target Source : /home/daniel/Desktop/Assembleur/python/Toolchain/output_results
============================================================

[✗] No valid processor candidate found among the analyzed files.
============================================================

Prompt 3

============================================================
                POTENTIAL CANDIDATES REPORT                
============================================================
 Model Tested  : qwen3-coder:30b
 Target Source : /home/daniel/Desktop/Assembleur/python/Toolchain/output_results
============================================================

[✓] Found 10 potential matching processor(s):

  • Processor  : PIC-17:LE:16:PIC-17C7xx
    Confidence : 95.0%
    Summary    : The disassembly shows valid PIC-17C7xx instructions with proper control flow and structured usage of registers. There are no signs of garbage output such as continuous data movement or broken stack usage.
------------------------------------------------------------
  • Processor  : 80390:BE:24:default
    Confidence : 95.0%
    Summary    : The disassembly shows valid 80390 instructions with coherent control flow and logical operation sequences. There are no obvious signs of garbage output such as continuous data movement or broken stack usage. The code includes valid instructions like RETI, JMP, and arithmetic/logic operations that follow expected patterns for this architecture.
...

5. Can we improve the result of the last test ?

To address the failure in the third test (Firmware 3), we attempted to modify Prompt 2 to account for the potential presence of an ELF header or file metadata:

SYSTEM_PROMPT = """You are a Principal Reverse Engineer specializing in bare-metal firmwares, ELF containers, and undocumented ISAs.
Your goal is to REJECT invalid disassemblies while tolerance-checking for static header/metadata noise.

IMPORTANT FOR ELF/RAW BINARIES:
The first few instructions may contain header magic numbers (e.g. '\x7fELF' or vector tables) parsed as garbage assembly. 
Do NOT reject the entire disassembly immediately if only the initial instructions look like metadata/padding, PROVIDED that valid function logic or control flow starts shortly after.

Analyze the semantic coherence of the disassembly using this step-by-step reasoning (Chain-of-Thought):
1. NOISE VS CODE: Is the snippet pure, unrecoverable garbage throughout, OR does it transition into structured code after initial padding/header bytes?
2. CONTROL FLOW: Are there logical jumps, calls, or conditional branches in the main body of the snippet?
3. REGISTERS & STACK: Are registers used consistently, and is there coherent stack manipulation (push/pop, frame setup)?
4. ABERRATIONS: Do you see endless repetitive opcodes without any control flow, or impossible immediate values throughout the ENTIRE sample?

Decision Rule:
- REJECT (is_valid = false) if the disassembly is 100% random garbage, infinite repetitive MOV/NOP loops, or totally lacks control flow.
- ACCEPT (is_valid = true) if you detect a clear pattern of compiled machine code (prologues, jumps, loops), even if preceded by header noise.

Respond STRICTLY in valid JSON with this schema:
{
    "reasoning": "Your step-by-step analysis detailing header noise check, control flow, register use, and final verdict",
    "processor_id": "{processor_id}",
    "is_valid": false,
    "confidence_score": 0.00,
    "detected_anomalies": ["list of specific anomalies, e.g., 'initial ELF header noise detected but valid MIPS branches follow'"]
}"""

However, using this new prompt, qwen3-coder:30b identified 39 potential matching processors for Firmware 3.

By instructing the model to tolerate initial header noise, we inadvertently destroyed the strict rejection bias that made Prompt 2 so effective. The model began using "header noise" as a universal excuse to justify false positives, finding imaginary structure in random byte decodings.

This result proves a fundamental rule in AI engineering: you cannot solve a data windowing problem using Prompt Engineering alone. The LLM should not be used to guess where the code begins; it must analyze code that has been properly delivered to it. So the pre processing pipeline should become

6. Epilogue

The results of this test are stunning. Modifying the prompt improved the result so incredibly. In our case, the prompt 2 gave us the correct answer for 2 of the 3 tests. This shows that the first thing to do when using a LLM is to find the best possible prompt. The last test showed us, that disassembling a binary should be done after having tested for headers, for compression, for obfuscation and encryption.
So now we have modify the toolchain in order to guaranty that the disassembling process occurs on a correct list of bytes.

Identifying the Processor of a Bare-Metal Binary (Strategy 2): Testing LLMs

ddupard — Tue, 04 Aug 2026 19:01:19 +0000

Industrializing the disassembly of an undocumented processor from a raw binary is a complex challenge that can be broken down into 4 main phases:

Verify that the binary does not belong to an already known processor.
Verify that the binary does not correspond to obfuscated, compressed, or encrypted code from a known processor.
Build an undocumented processor generator.
Develop the analysis workflow and disassembly generation pipeline.

For the first step of this project, the goal is to evaluate different strategies and identify the most effective approach.

2. Evaluated Strategies

(For a full summary of the tests conducted under Strategy 1, see "Identifying the Processor of a Bare-Metal Binary — Strategy 1".)

3. Test Protocol

The local LLMs selected for this benchmark are:

dolphinMistral24b
dolphin3-cyber
gemma4:26b
qwen3-coder:30b
qwen2.5-coder

Using a single C source code file and an automated toolchain, test binaries were generated for approximately 30 different processors in both raw bare-metal and standard ELF formats.

Three specific binaries were selected for the evaluation:

Firmware 1: Target processor is natively supported by Ghidra.
Firmware 2: Target processor is not supported by Ghidra.
Firmware 3: An ELF file, explicitly disassembled as a raw bare-metal binary (forcing raw byte parsing).

Disassembly output files were batch-generated using PyGhidra and a custom Java headless script. Each model was then prompted to analyze every generated disassembly file using the exact same system prompt:

Python

SYSTEM_PROMPT = """You are an expert in reverse engineering and processor architectures.
Your task is to verify the consistency of a raw firmware disassembly.
Examine the provided instructions, verify whether the architecture's syntax is valid,
and determine if the instructions appear coherent (absence of repeated invalid instructions, aberrant opcodes, etc.).
Respond strictly in valid JSON format."""

The models were instructed to respond using a strict JSON schema:

JSON
{
    "processor_id": "{processor_id}",
    "is_valid": true,
    "confidence_score": 0.85,
    "summary": "Short explanation of the analysis",
    "detected_anomalies": ["list of errors or anomalies"]
}

4. Benchmark Results

Firmware 1 (Known Processor)

This firmware was generated for a processor supported by Ghidra.

qwen2.5-coder: Generated reports for all 177 files. Identified 69 potential candidate processors (including the correct one).
qwen3-coder:30b: Generated reports for all 177 files. Identified 35 potential candidate processors (including the correct one).
gemma4:26b: Severe formatting failure — generated a valid report for only 1 disassembly file.
dolphinMistral24b: Generated reports for all 177 files. Identified 114 potential candidate processors (including the correct one).
dolphin3-cyber: Generated reports for all 177 files. Identified 168 potential candidate processors (including the correct one).

Firmware 2 (Unknown Processor)

This firmware was generated for a target architecture not supported by Ghidra.

qwen2.5-coder: Generated reports for all 177 files. Identified 67 potential candidate processors (false positives).
qwen3-coder:30b: Generated reports for all 177 files. Identified 32 potential candidate processors (false positives).
gemma4:26b: Failed completely — unable to generate a single report.
dolphinMistral24b: Generated reports for all 177 files. Identified 105 potential candidate processors (false positives).
dolphin3-cyber: Generated reports for all 177 files. Identified 172 potential candidate processors (false positives).

Firmware 3 (ELF File Disassembled as Bare Metal)

Given the poor baseline performance of local models, this test was conducted exclusively on qwen3-coder:30b.

qwen3-coder:30b: Generated reports for all 177 files. Identified 42 potential candidate processors (including the correct one).

5. Why Are the Results So Poor?

The empirical results show an exceptionally high rate of false positives: models validated between 35 and 172 candidates out of 177, failing to act as a selective heuristic filter. Several key technical factors explain this shortfall:

A. Root Causes & Hypotheses

Superficial Syntax Validation vs. Semantic Verification:
Most code-focused LLMs evaluate assembly primarily at a syntactic level. When Ghidra forces a disassembly, it outputs valid instruction strings (e.g., MOV R0, R1) according to the target architecture's grammar. The LLMs mistake syntactically valid instructions for semantically logical code, ignoring structural red flags like non-sensical control flow, impossible stack frame allocations, or meaningless register usage.
Window-Size Contraint & Contextual Blind Spots (First 50 Instructions):
Limiting context to the first 50 instructions creates a severe bias. In raw bare-metal binaries (and especially ELF files parsed as raw bytes), the offset often starts with interrupt vectors, padding, or raw header metadata (\x7fELF). Disassembling metadata produces random, garbage instructions. The LLM either accepts this garbage as valid initialization code or misses real function prologues (PUSH {LR}, frame setup) located further down in the binary.
Hallucination of High Confidence Scores:
Smaller, quantized local models lack calibrated uncertainty. They frequently assign confidence scores between 0.80 and 1.0 to highly improbable disassemblies simply because no explicit .byte unknown directives appeared in the 50-sample window.
JSON Schema Inflation and Special Token Leaks:
Models like gemma4:26b failed due to prompt-adherence degradation when handling low-level assembly syntax, leaking internal reasoning/channel tokens (e.g., thought...) into the JSON stream, which corrupted output parsing.

B. Proposed Solutions to Improve Results

To transform this approach into a viable industrial pipeline, several adjustments are required:

Heuristic Pre-Filtering & Metrics Computation (Hybrid Static Analysis + LLM):
Before calling the LLM, compute mathematical heuristics on the disassembly output:
Invalid Instruction Ratio: Reject architectures where .byte or ?? directives exceed 5% of the total output.
Control Flow Density: Measure the ratio of control-flow instructions (JMP, CALL, BRANCH) to data movement (MOV, LDR). Random/incorrect disassemblies display abnormally low or erratic jump densities.
Entropy & String Artifacts: Calculate entropy across the binary sections to skip static headers before sampling.
Few-Shot Prompting with Counter-Examples:
Update the system prompt with explicit Few-Shot examples contrasting a valid disassembly (coherent stack operations, standard function prologues, structured loops) with an invalid/garbage disassembly (repetitive opcodes, dead jumps, aberrant immediate values).
Dynamic Sample Windowing (Skipping Metadata):
Instead of feeding the first 50 raw instructions, extract 50 instructions starting from detected function entry points (e.g., identified by CALL targets or push/pop entry sequences). For ELF binaries treated as bare metal, automatically skip the initial offset matching known header lengths.
Chain-of-Thought (CoT) Reasoning Before JSON Output:
Forcing the LLM to output raw JSON immediately suppresses its internal analytical capabilities. Changing the prompt structure to require a step-by-step reasoning phase before emitting the final JSON object significantly improves accuracy:

Plaintext
1. Analyze control flow coherence...
2. Check register consistency...
3. Identify function entry signatures...
4. Output JSON verdict.

Cross-Architecture Elimination Tournaments: Instead of asking the LLM "Is Architecture X valid?" in isolation, prompt the model with pairs of disassembly snippets (Architecture A vs. Architecture B) and ask it to select which of the two displays superior architectural coherence.

6. Epilogue

This benchmark highlights the clear limitations of current local LLMs when used out-of-the-box for low-level reverse engineering heuristics. Without statistical pre-filtering, dynamic windowing, and structured chain-of-thought prompting, local models act as overly permissive classifiers.

Can refined prompt engineering, dynamic context sampling, or cloud-grade LLMs bridge this gap to reliably pinpoint unknown architectures? That will be the subject of our next evaluation.

Identifying the Processor of a Bare-Metal Binary (Strategy 1): Building a custom disassembler

ddupard — Mon, 03 Aug 2026 18:09:39 +0000

Industrializing the disassembly of an undocumented processor from a raw binary is a complex task that can be broken down into four key steps:

Verify that the binary does not belong to a known processor.
Verify that the binary is not obfuscated, compressed, or encrypted code for a known processor.
Build an undocumented processor generator.
Create the analysis pipeline and custom disassembler generation process.

For the first phase of this project, the goal is to build dedicated, lightweight disassemblers—since, for bare-metal binaries, tools like Ghidra require manual processor target selection before analysis can begin.

1. Why Build a Custom Disassembler?

To determine whether a binary was compiled for a specific architecture, the strategy consists of disassembling the binary (both statically and dynamically) against candidate instruction sets until:

One or more bytes fail to match any valid instruction for that architecture, allowing us to rule it out.
The disassembly succeeds completely. (Note: a successful disassembly does not guarantee that the binary was originally intended for that CPU; control flow validity must also be verified).

Static disassembly is the first line of defense. However, if it fails due to obfuscation, compression, or encryption, we must escalate to dynamic execution and analysis.

Only after systematically eliminating all known architectures can we confidently conclude that we are dealing with a custom or undocumented processor.

2. How to Build Your Custom Disassembler

Before deploying heavy machinery for undocumented processors, the logical first step was to check against known architectures.

Approach 1: Ghidra and SLAgh

Ghidra relies on the SLAgh specification language and maintains an extensive library of processor definitions. The original plan was to leverage its API to extract a normalized opcode mapping table.

However, after several attempts, Ghidra proved unsuitable for this specific pipeline for two reasons:

Operand Type Loss: Detailed metadata regarding operand types is lost or abstract during Ghidra's generic disassembly phase.
Lack of Specification Standardization: Across different processor modules, .slaspec files are not uniformly structured.

Ghidra is a remarkable tool, and its underlying codebase is a work of art. But when required metadata is missing from the .slaspec or .pspec definitions, it must be added manually. At that point, implementing a dedicated, lightweight disassembler becomes a far more practical alternative.

Approach 2: Native 8051 Disassemblers (`dis51`)

The second attempt involved generating a raw .HEX file containing all possible byte combinations and passing it through dis51.

This approach failed because dis51 is an execution-tracing disassembler: it follows control flow rather than performing linear sweeping. If a JMP instruction branches backward, any bytes immediately following the jump that are not reached by other execution paths are categorized as raw data blocks. To effectively use dis51, one cannot simply feed it a linear array of opcodes; it expects a valid, structured program flow.

Approach 3: LLM-Assisted Table Normalization (Successful)

The winning strategy was prompting Gemini to generate the normalized instruction mapping table. After refining the prompt, the model generated a Python script containing the full opcode mapping alongside a processor-specific lookup table for Special Function Registers (SFR).

Using this generated table, writing the functional static disassembler took under an hour. It also laid the foundation for the dynamic disassembly simulator. While the table contained a few minor bugs, the time saved was substantial.

Although this approach is not fully generic out-of-the-box, it is straightforward. The core structure of the disassembler and execution loop remains virtually identical when porting to other architectures. Furthermore, building small, single-purpose utilities makes parallelizing multi-architecture scanning trivial.

3. Epilogue

This experiment provides a clear demonstration of how Large Language Models (LLMs) can accelerate lower-level systems development and reverse engineering tasks by handling structural boilerplate without sacrificing control over execution logic.

4. Disassembler Python Code


python
import re

INSTRUCTION_TABLE = {
    # -------------------------------------------------------------------------
    # 1 BYTE INSTRUCTIONS
    # -------------------------------------------------------------------------
    0x00: (1, "NOP", "NOP"),
    0x03: (1, "RR A", "RR A"),
    0x04: (1, "INC A", "INC A"),
    0x06: (1, "INC @R0", "INC @R0"),
    0x07: (1, "INC @R1", "INC @R1"),
    0x08: (1, "INC R0", "INC register"),
    0x09: (1, "INC R1", "INC register"),
    0x0A: (1, "INC R2", "INC register"),
    0x0B: (1, "INC R3", "INC register"),
    0x0C: (1, "INC R4", "INC register"),
    0x0D: (1, "INC R5", "INC register"),
    0x0E: (1, "INC R6", "INC register"),
    0x0F: (1, "INC R7", "INC register"),

    0x13: (1, "RRC A", "RRC A"),
    0x14: (1, "DEC A", "DEC A"),
    0x16: (1, "DEC @R0", "DEC @R0"),
    0x17: (1, "DEC @R1", "DEC @R1"),
    0x18: (1, "DEC R0", "DEC register"),
    0x19: (1, "DEC R1", "DEC register"),
    0x1A: (1, "DEC R2", "DEC register"),
    0x1B: (1, "DEC R3", "DEC register"),
    0x1C: (1, "DEC R4", "DEC register"),
    0x1D: (1, "DEC R5", "DEC register"),
    0x1E: (1, "DEC R6", "DEC register"),
    0x1F: (1, "DEC R7", "DEC register"),

    0x22: (1, "RET", "RET"),
    0x23: (1, "RL A", "RL A"),
    0x26: (1, "ADD A, @R0", "ADD A, @R0"),
    0x27: (1, "ADD A, @R1", "ADD A, @R1"),
    0x28: (1, "ADD A, R0", "ADD A, register"),
    0x29: (1, "ADD A, R1", "ADD A, register"),
    0x2A: (1, "ADD A, R2", "ADD A, register"),
    0x2B: (1, "ADD A, R3", "ADD A, register"),
    0x2C: (1, "ADD A, R4", "ADD A, register"),
    0x2D: (1, "ADD A, R5", "ADD A, register"),
    0x2E: (1, "ADD A, R6", "ADD A, register"),
    0x2F: (1, "ADD A, R7", "ADD A, register"),

    0x32: (1, "RETI", "RETI"),
    0x33: (1, "RLC A", "RLC A"),
    0x36: (1, "ADDC A, @R0", "ADDC A, @R0"),
    0x37: (1, "ADDC A, @R1", "ADDC A, @R1"),
    0x38: (1, "ADDC A, R0", "ADDC A, register"),
    0x39: (1, "ADDC A, R1", "ADDC A, register"),
    0x3A: (1, "ADDC A, R2", "ADDC A, register"),
    0x3B: (1, "ADDC A, R3", "ADDC A, register"),
    0x3C: (1, "ADDC A, R4", "ADDC A, register"),
    0x3D: (1, "ADDC A, R5", "ADDC A, register"),
    0x3E: (1, "ADDC A, R6", "ADDC A, register"),
    0x3F: (1, "ADDC A, R7", "ADDC A, register"),

    0x46: (1, "ORL A, @R0", "ORL A, @R0"),
    0x47: (1, "ORL A, @R1", "ORL A, @R1"),
    0x48: (1, "ORL A, R0", "ORL A, register"),
    0x49: (1, "ORL A, R1", "ORL A, register"),
    0x4A: (1, "ORL A, R2", "ORL A, register"),
    0x4B: (1, "ORL A, R3", "ORL A, register"),
    0x4C: (1, "ORL A, R4", "ORL A, register"),
    0x4D: (1, "ORL A, R5", "ORL A, register"),
    0x4E: (1, "ORL A, R6", "ORL A, register"),
    0x4F: (1, "ORL A, R7", "ORL A, register"),

    0x56: (1, "ANL A, @R0", "ANL A, @R0"),
    0x57: (1, "ANL A, @R1", "ANL A, @R1"),
    0x58: (1, "ANL A, R0", "ANL A, register"),
    0x59: (1, "ANL A, R1", "ANL A, register"),
    0x5A: (1, "ANL A, R2", "ANL A, register"),
    0x5B: (1, "ANL A, R3", "ANL A, register"),
    0x5C: (1, "ANL A, R4", "ANL A, register"),
    0x5D: (1, "ANL A, R5", "ANL A, register"),
    0x5E: (1, "ANL A, R6", "ANL A, register"),
    0x5F: (1, "ANL A, R7", "ANL A, register"),

    0x66: (1, "XRL A, @R0", "XRL A, @R0"),
    0x67: (1, "XRL A, @R1", "XRL A, @R1"),
    0x68: (1, "XRL A, R0", "XRL A, register"),
    0x69: (1, "XRL A, R1", "XRL A, register"),
    0x6A: (1, "XRL A, R2", "XRL A, register"),
    0x6B: (1, "XRL A, R3", "XRL A, register"),
    0x6C: (1, "XRL A, R4", "XRL A, register"),
    0x6D: (1, "XRL A, R5", "XRL A, register"),
    0x6E: (1, "XRL A, R6", "XRL A, register"),
    0x6F: (1, "XRL A, R7", "XRL A, register"),

    0x73: (1, "JMP @A+DPTR", "JMP @A+DPTR"),

    0x83: (1, "MOVC A, @A+PC", "MOVC A, @A+PC"),
    0x84: (1, "DIV AB", "DIV AB"),

    0x93: (1, "MOVC A, @A+DPTR", "MOVC A, @A+DPTR"),
    0x96: (1, "SUBB A, @R0", "SUBB A, @R0"),
    0x97: (1, "SUBB A, @R1", "SUBB A, @R1"),
    0x98: (1, "SUBB A, R0", "SUBB A, register"),
    0x99: (1, "SUBB A, R1", "SUBB A, register"),
    0x9A: (1, "SUBB A, R2", "SUBB A, register"),
    0x9B: (1, "SUBB A, R3", "SUBB A, register"),
    0x9C: (1, "SUBB A, R4", "SUBB A, register"),
    0x9D: (1, "SUBB A, R5", "SUBB A, register"),
    0x9E: (1, "SUBB A, R6", "SUBB A, register"),
    0x9F: (1, "SUBB A, R7", "SUBB A, register"),

    0xA3: (1, "INC DPTR", "INC register"),
    0xA4: (1, "MUL AB", "MUL AB"),

    0xC3: (1, "CLR C", "CLR C"),
    0xC4: (1, "SWAP A", "SWAP A"),
    0xC6: (1, "XCH A, @R0", "XCH A, @R0"),
    0xC7: (1, "XCH A, @R1", "XCH A, @R1"),
    0xC8: (1, "XCH A, R0", "XCH A, register"),
    0xC9: (1, "XCH A, R1", "XCH A, register"),
    0xCA: (1, "XCH A, R2", "XCH A, register"),
    0xCB: (1, "XCH A, R3", "XCH A, register"),
    0xCC: (1, "XCH A, R4", "XCH A, register"),
    0xCD: (1, "XCH A, R5", "XCH A, register"),
    0xCE: (1, "XCH A, R6", "XCH A, register"),
    0xCF: (1, "XCH A, R7", "XCH A, register"),

    0xD3: (1, "SETB C", "SETB C"),
    0xD4: (1, "DA A", "DA A"),
    0xD6: (1, "XCHD A, @R0", "XCHD A, @R0"),
    0xD7: (1, "XCHD A, @R1", "XCHD A, @R1"),

    0xE4: (1, "CLR A", "CLR A"),
    0xE6: (1, "MOV A, @R0", "MOV A, @R0"),
    0xE7: (1, "MOV A, @R1", "MOV A, @R1"),
    0xE8: (1, "MOV A, R0", "MOV A, register"),
    0xE9: (1, "MOV A, R1", "MOV A, register"),
    0xEA: (1, "MOV A, R2", "MOV A, register"),
    0xEB: (1, "MOV A, R3", "MOV A, register"),
    0xEC: (1, "MOV A, R4", "MOV A, register"),
    0xED: (1, "MOV A, R5", "MOV A, register"),
    0xEE: (1, "MOV A, R6", "MOV A, register"),
    0xEF: (1, "MOV A, R7", "MOV A, register"),

    0xF4: (1, "CPL A", "CPL A"),
    0xF6: (1, "MOV @R0, A", "MOV @R0, A"),
    0xF7: (1, "MOV @R1, A", "MOV @R1, A"),
    0xF8: (1, "MOV R0, A", "MOV register, A"),
    0xF9: (1, "MOV R1, A", "MOV register, A"),
    0xFA: (1, "MOV R2, A", "MOV register, A"),
    0xFB: (1, "MOV R3, A", "MOV register, A"),
    0xFC: (1, "MOV R4, A", "MOV register, A"),
    0xFD: (1, "MOV R5, A", "MOV register, A"),
    0xFE: (1, "MOV R6, A", "MOV register, A"),
    0xFF: (1, "MOV R7, A", "MOV register, A"),

    # -------------------------------------------------------------------------
    # 2 BYTE INSTRUCTIONS
    # -------------------------------------------------------------------------
    0x05: (2, lambda b: f"INC {b[1]:02X}h", "INC direct"),
    0x15: (2, lambda b: f"DEC {b[1]:02X}h", "DEC direct"),
    0x24: (2, lambda b: f"ADD A, #{b[1]:02X}h", "ADD A, #data"),
    0x25: (2, lambda b: f"ADD A, {b[1]:02X}h", "ADD A, direct"),
    0x34: (2, lambda b: f"ADDC A, #{b[1]:02X}h", "ADDC A, #data"),
    0x35: (2, lambda b: f"ADDC A, {b[1]:02X}h", "ADDC A, direct"),
    0x40: (2, lambda b: f"JC {b[1]:02X}h", "JC offset"),
    0x44: (2, lambda b: f"ORL A, #{b[1]:02X}h", "ORL A, #data"),
    0x45: (2, lambda b: f"ORL A, {b[1]:02X}h", "ORL A, direct"),
    0x50: (2, lambda b: f"JNC {b[1]:02X}h", "JNC offset"),
    0x54: (2, lambda b: f"ANL A, #{b[1]:02X}h", "ANL A, #data"),
    0x55: (2, lambda b: f"ANL A, {b[1]:02X}h", "ANL A, direct"),
    0x60: (2, lambda b: f"JZ {b[1]:02X}h", "JZ offset"),
    0x64: (2, lambda b: f"XRL A, #{b[1]:02X}h", "XRL A, #data"),
    0x65: (2, lambda b: f"XRL A, {b[1]:02X}h", "XRL A, direct"),
    0x70: (2, lambda b: f"JNZ {b[1]:02X}h", "JNZ offset"),
    0x74: (2, lambda b: f"MOV A, #{b[1]:02X}h", "MOV A, #data"),
    0x76: (2, lambda b: f"MOV @R0, #{b[1]:02X}h", "MOV @R0, #data"),
    0x77: (2, lambda b: f"MOV @R1, #{b[1]:02X}h", "MOV @R1, #data"),
    0x78: (2, lambda b: f"MOV R0, #{b[1]:02X}h", "MOV register, #data"),
    0x79: (2, lambda b: f"MOV R1, #{b[1]:02X}h", "MOV register, #data"),
    0x7A: (2, lambda b: f"MOV R2, #{b[1]:02X}h", "MOV register, #data"),
    0x7B: (2, lambda b: f"MOV R3, #{b[1]:02X}h", "MOV register, #data"),
    0x7C: (2, lambda b: f"MOV R4, #{b[1]:02X}h", "MOV register, #data"),
    0x7D: (2, lambda b: f"MOV R5, #{b[1]:02X}h", "MOV register, #data"),
    0x7E: (2, lambda b: f"MOV R6, #{b[1]:02X}h", "MOV register, #data"),
    0x7F: (2, lambda b: f"MOV R7, #{b[1]:02X}h", "MOV register, #data"),

    0x80: (2, lambda b: f"SJMP {b[1]:02X}h", "SJMP offset"),
    0x82: (2, lambda b: f"ANL C, {b[1]:02X}h", "ANL C, bit"),
    0x86: (2, lambda b: f"MOV R0, {b[1]:02X}h", "MOV register, direct"),
    0x87: (2, lambda b: f"MOV R1, {b[1]:02X}h", "MOV register, direct"),
    0x88: (2, lambda b: f"MOV {b[1]:02X}h, R0", "MOV direct, register"),
    0x89: (2, lambda b: f"MOV {b[1]:02X}h, R1", "MOV direct, register"),
    0x8A: (2, lambda b: f"MOV {b[1]:02X}h, R2", "MOV direct, register"),
    0x8B: (2, lambda b: f"MOV {b[1]:02X}h, R3", "MOV direct, register"),
    0x8C: (2, lambda b: f"MOV {b[1]:02X}h, R4", "MOV direct, register"),
    0x8D: (2, lambda b: f"MOV {b[1]:02X}h, R5", "MOV direct, register"),
    0x8E: (2, lambda b: f"MOV {b[1]:02X}h, R6", "MOV direct, register"),
    0x8F: (2, lambda b: f"MOV {b[1]:02X}h, R7", "MOV direct, register"),

    0x92: (2, lambda b: f"MOV {b[1]:02X}h, C", "MOV bit, C"),
    0x94: (2, lambda b: f"SUBB A, #{b[1]:02X}h", "SUBB A, #data"),
    0x95: (2, lambda b: f"SUBB A, {b[1]:02X}h", "SUBB A, direct"),

    0xA0: (2, lambda b: f"ORL C, /{b[1]:02X}h", "ORL C, /bit"),
    0xA2: (2, lambda b: f"MOV C, {b[1]:02X}h", "MOV C, bit"),
    0xA5: (1, "RESERVED (0xA5)", "RESERVED"), # Unassigned Intel Opcode
    0xA6: (2, lambda b: f"MOV @R0, {b[1]:02X}h", "MOV @R0, direct"),
    0xA7: (2, lambda b: f"MOV @R1, {b[1]:02X}h", "MOV @R1, direct"),
    0xA8: (2, lambda b: f"MOV R0, {b[1]:02X}h", "MOV R0, direct"),
    0xA9: (2, lambda b: f"MOV R1, {b[1]:02X}h", "MOV R1, direct"),
    0xAA: (2, lambda b: f"MOV R2, {b[1]:02X}h", "MOV R2, direct"),
    0xAB: (2, lambda b: f"MOV R3, {b[1]:02X}h", "MOV R3, direct"),
    0xAC: (2, lambda b: f"MOV R4, {b[1]:02X}h", "MOV R4, direct"),
    0xAD: (2, lambda b: f"MOV R5, {b[1]:02X}h", "MOV R5, direct"),
    0xAE: (2, lambda b: f"MOV R6, {b[1]:02X}h", "MOV R6, direct"),
    0xAF: (2, lambda b: f"MOV R7, {b[1]:02X}h", "MOV R7, direct"),

    0xB0: (2, lambda b: f"ANL C, /{b[1]:02X}h", "ANL C, /bit"),
    0xB2: (2, lambda b: f"CPL {b[1]:02X}h", "CPL bit"),
    0xB3: (1, "CPL C", "CPL C"),

    0xC0: (2, lambda b: f"PUSH {b[1]:02X}h", "PUSH direct"),
    0xC2: (2, lambda b: f"CLR {b[1]:02X}h", "CLR bit"),
    0xC5: (2, lambda b: f"XCH A, {b[1]:02X}h", "XCH A, direct"),

    0xD0: (2, lambda b: f"POP {b[1]:02X}h", "POP direct"),
    0xD2: (2, lambda b: f"SETB {b[1]:02X}h", "SETB bit"),
    0xD8: (2, lambda b: f"DJNZ R0, {b[1]:02X}h", "DJNZ register, offset"),
    0xD9: (2, lambda b: f"DJNZ R1, {b[1]:02X}h", "DJNZ register, offset"),
    0xDA: (2, lambda b: f"DJNZ R2, {b[1]:02X}h", "DJNZ register, offset"),
    0xDB: (2, lambda b: f"DJNZ R3, {b[1]:02X}h", "DJNZ register, offset"),
    0xDC: (2, lambda b: f"DJNZ R4, {b[1]:02X}h", "DJNZ register, offset"),
    0xDD: (2, lambda b: f"DJNZ R5, {b[1]:02X}h", "DJNZ register, offset"),
    0xDE: (2, lambda b: f"DJNZ R6, {b[1]:02X}h", "DJNZ register, offset"),
    0xDF: (2, lambda b: f"DJNZ R7, {b[1]:02X}h", "DJNZ register, offset"),

    0xE0: (1, "MOVX A, @DPTR", "MOVX A, @DPTR"),
    0xE2: (1, "MOVX A, @R0", "MOVX A, @R0"),
    0xE3: (1, "MOVX A, @R1", "MOVX A, @R1"),
    0xE5: (2, lambda b: f"MOV A, {b[1]:02X}h", "MOV A, direct"),

    0xF0: (1, "MOVX @DPTR, A", "MOVX @DPTR, A"),
    0xF2: (1, "MOVX @R0, A", "MOVX @R0, A"),
    0xF3: (1, "MOVX @R1, A", "MOVX @R1, A"),
    0xF5: (2, lambda b: f"MOV {b[1]:02X}h, A", "MOV direct, A"),

    # -------------------------------------------------------------------------
    # 3 BYTE INSTRUCTIONS (16-bit addresses & 3-parameter instructions)
    # -------------------------------------------------------------------------
    0x02: (3, lambda b: f"LJMP {b[1]:02X}{b[2]:02X}h", "LJMP addr16"),
    0x10: (3, lambda b: f"JBC {b[1]:02X}h, {b[2]:02X}h", "JBC bit, offset"),
    0x12: (3, lambda b: f"LCALL {b[1]:02X}{b[2]:02X}h", "LCALL addr16"),
    0x20: (3, lambda b: f"JB {b[1]:02X}h, {b[2]:02X}h", "JB bit, offset"),
    0x30: (3, lambda b: f"JNB {b[1]:02X}h, {b[2]:02X}h", "JNB bit, offset"),
    0x42: (2, lambda b: f"ORL {b[1]:02X}h, A", "ORL direct, A"),
    0x43: (3, lambda b: f"ORL {b[1]:02X}h, #{b[2]:02X}h", "ORL direct, #data"),
    0x52: (2, lambda b: f"ANL {b[1]:02X}h, A", "ANL direct, A"),
    0x53: (3, lambda b: f"ANL {b[1]:02X}h, #{b[2]:02X}h", "ANL direct, #data"),
    0x62: (2, lambda b: f"XRL {b[1]:02X}h, A", "XRL direct, A"),
    0x63: (3, lambda b: f"XRL {b[1]:02X}h, #{b[2]:02X}h", "XRL direct, #data"),
    0x72: (2, lambda b: f"ORL C, {b[1]:02X}h", "ORL C, bit"),
    0x75: (3, lambda b: f"MOV {b[1]:02X}h, #{b[2]:02X}h", "MOV direct, #data"),
    0x85: (3, lambda b: f"MOV {b[2]:02X}h, {b[1]:02X}h", "MOV direct, direct"),
    0x90: (3, lambda b: f"MOV DPTR, #{b[1]:02X}{b[2]:02X}h", "MOV DPTR, #data16"),
    0xB4: (3, lambda b: f"CJNE A, #{b[1]:02X}h, {b[2]:02X}h", "CJNE A, #data, offset"),
    0xB5: (3, lambda b: f"CJNE A, {b[1]:02X}h, {b[2]:02X}h", "CJNE A, direct, offset"),
    0xB6: (3, lambda b: f"CJNE @R0, #{b[1]:02X}h, {b[2]:02X}h", "CJNE @R0, #data, offset"),
    0xB7: (3, lambda b: f"CJNE @R1, #{b[1]:02X}h, {b[2]:02X}h", "CJNE @R1, #data, offset"),
    0xB8: (3, lambda b: f"CJNE R0, #{b[1]:02X}h, {b[2]:02X}h", "CJNE register, #data, offset"),
    0xB9: (3, lambda b: f"CJNE R1, #{b[1]:02X}h, {b[2]:02X}h", "CJNE register, #data, offset"),
    0xBA: (3, lambda b: f"CJNE R2, #{b[1]:02X}h, {b[2]:02X}h", "CJNE register, #data, offset"),
    0xBB: (3, lambda b: f"CJNE R3, #{b[1]:02X}h, {b[2]:02X}h", "CJNE register, #data, offset"),
    0xBC: (3, lambda b: f"CJNE R4, #{b[1]:02X}h, {b[2]:02X}h", "CJNE register, #data, offset"),
    0xBD: (3, lambda b: f"CJNE R5, #{b[1]:02X}h, {b[2]:02X}h", "CJNE register, #data, offset"),
    0xBE: (3, lambda b: f"CJNE R6, #{b[1]:02X}h, {b[2]:02X}h", "CJNE register, #data, offset"),
    0xBF: (3, lambda b: f"CJNE R7, #{b[1]:02X}h, {b[2]:02X}h", "CJNE register, #data, offset"),
    0xD5: (3, lambda b: f"DJNZ {b[1]:02X}h, {b[2]:02X}h", "DJNZ direct, offset"),
}

sfr_dict = {
    0x80: "P0",     # Port 0
    0x81: "SP",     # Stack Pointer
    0x82: "DPL",    # Data Pointer Low
    0x83: "DPH",    # Data Pointer High
    0x87: "PCON",   # Power Control
    0x88: "TCON",   # Timer Control
    0x89: "TMOD",   # Timer Mode
    0x8A: "TL0",    # Timer 0 Low
    0x8B: "TL1",    # Timer 1 Low
    0x8C: "TH0",    # Timer 0 High
    0x8D: "TH1",    # Timer 1 High
    0x90: "P1",     # Port 1
    0x98: "SCON",   # Serial Control
    0x99: "SBUF",   # Serial Buffer
    0xA0: "P2",     # Port 2
    0xA8: "IE",     # Interrupt Enable
    0xB0: "P3",     # Port 3
    0xB8: "IP",     # Interrupt Priority
    0xD0: "PSW",    # Program Status Word
    0xE0: "ACC",    # Accumulator (A)
    0xF0: "B",      # B Register
}

def decode_bytes(byte_list):
    """Decodes a byte sequence according to the 8051 instruction set."""
    first_byte = byte_list[0]

    # Handle AJMP / ACALL instructions (Page addresses encoded in the upper opcode bits)
    if (first_byte & 0x1F) == 0x01:
        addr = ((first_byte & 0xE0) << 3) | byte_list[1]
        return 2, f"AJMP {addr:04X}h", "AJMP addr11"
    if (first_byte & 0x1F) == 0x11:
        addr = ((first_byte & 0xE0) << 3) | byte_list[1]
        return 2, f"ACALL {addr:04X}h", "ACALL addr11"

    if first_byte in INSTRUCTION_TABLE:
        length, asm, generic = INSTRUCTION_TABLE[first_byte]
        if callable(asm):
            asm = asm(byte_list)
        return length, asm, generic

    return len(byte_list), "UNKNOWN", "UNKNOWN"

def int_to_hex_4(number):
    if not (0 <= number <= 65535):
        raise ValueError("Number must be between 0 and 65535")
    return format(number, '04x')

def buffer_to_hex_text(buffer: bytes) -> str:
    return " ".join(f"{b:02X}" for b in buffer)

def process_opcodes(buffer, reset_vector=0):
    rows = []
    idx = 0
    done = False

    while not done: 
        address = reset_vector + idx
        opcode = buffer[reset_vector + idx]

        if opcode in INSTRUCTION_TABLE:
            length, asm, generic = INSTRUCTION_TABLE[opcode]
            byte_vals = buffer[reset_vector + idx : reset_vector + idx + length]
            opcodes_str = buffer_to_hex_text(byte_vals)

            length, asm, generic = decode_bytes(byte_vals)

            rows.append({
                "address": address,
                "opcodes": opcodes_str,
                "asm": asm,
                "generic": generic
            })  

            idx += length
            if idx >= len(buffer):
                done = True
        else:
            print(f"Opcode 0x{opcode:02X} not found in INSTRUCTION_TABLE")
            done = True

    return rows         

if __name__ == "__main__":
    input_file = "./test1_8051.rom"
    with open(input_file, "rb") as fs:
        buffer = fs.read()

    result_rows = process_opcodes(buffer)

    line_format = "{:<10} {:<20} {:<30}"
    for r in result_rows:
        print(line_format.format(int_to_hex_4(r['address']), r['opcodes'], r['asm']))

EEPROM Hijacking on 8051 Architecture

ddupard — Fri, 31 Jul 2026 09:47:29 +0000

1. Introduction and Problem Statement

In constrained embedded systems engineering, 8051-type microcontrollers remain ubiquitous. Often coupled with external or internal EEPROM memories of very limited size (a few kilobytes), these environments leave no room for excess. Using high-level compilers like SDCC, while convenient for rapid prototyping, generates heavy code (function prologues, complex stack management) that becomes prohibitive when attempting to insert surgical modifications into an existing binary. This article details the methodology of intercepting an SDCC-compiled function via a direct binary hook (jump) and redirecting execution flow to an optimized pure assembly routine located in an unused memory area (slack space), with the goal of conditionally bypassing a critical logic test when a specific trigger condition is met

2. 8051 Architectural Constraints and Low-Level Logic

The 8051 instruction set is rudimentary yet extremely direct. Nothing Fancy, just simple assembly. However, working within this architecture means confronting severe hardware constraints, as ROM space is exceptionally scarce, leaving very little room to inject or expand code without extreme optimization.
The goal of this article is to modify the behavior of a validation function (e.g., a security or integrity test) so that it systematically returns a positive response (True / 0x01) under the effect of a stealthy trigger, while maintaining 100% transparent nominal behavior the rest of the time.

3. Designing the Pure Assembly Patch

Imagine an original routine performing a classic conditional check. The original code evaluates a state and jumps depending on the result.

#include <mcs51/8051.h>

// Simulated security check function generated by SDCC
unsigned char verify_system_integrity(void) {
    unsigned char status = 0;

    // Read a configuration or state register
    status = P1; 

    // Critical security test
    if (status == 0x5A) {
        return 0x01; // Success / Authorized
    }

    return 0x00; // Failure / Unauthorized
}

By injecting our routine directly into some space, and inserting a LJMP at the beginning of the verify_system_integrity, we intercept the execution flow:

Optimized 8051 Assembly Patch Example

ORG 02FAH             ; Injection address in EEPROM
PATCH_ENTRY:
    PUSH ACC          ; Save accumulator register
    PUSH PSW          ; Save PSW register

    ; Check trigger condition
    MOV A, @R0        ; Read status flag from RAM/EEPROM
    CJNE A, #05H, NORMAL_FLOW ; If trigger is not active, normal flow

    ; Condition met: Force negative response
    POP PSW
    POP ACC
    MOV A, #01H       ; Return value forced to TRUE (1)
    RET               ; Early exit from intercepted function


NORMAL_FLOW:
    POP PSW
    POP ACC
    LJMP ORIGINAL_FN  ; Resume normal program execution

4. Critical Engineering Note (Byte Alignment & Patch Footprint):

On the 8051 architecture, an unconditional long jump (LJMP) consumes 3 bytes, whereas the two original prologue instructions we want to overwrite at the beginning of the function (PUSH ACC and PUSH PSW) consume 4 bytes in total (2 bytes each).

The Pitfall: Directly replacing 4 bytes with a 3-byte jump would leave an orphaned byte behind, corrupting the instruction decoding (Program Counter alignment) and causing an immediate crash.

The Workaround: We pad the jump instruction with a harmless 1-byte instruction (NOP) right after the LJMP to precisely match the 4-byte footprint of the original instructions. Furthermore, to maintain stack integrity and preserve the expected environment, our patch routine at 02FAH must begin by executing these exact PUSH operations so the state remains consistent.

5. Efficiency and Stealth Analysis

This approach offers several crucial advantages for operational discretion:

Minimal Footprint: The raw assembly test structure consumes only a few bytes, avoiding any buffer overflow in the allocated memory space.

Total Trigger Control: The system only switches to its modified mode if the stored condition is validated (e.g., a specific initialization sequence or an internal counter).

Structural Indolence: From an external perspective, the binary respects block sizes and structural checksums if the initial space was simply padded with fill bytes (NOP or 0xFF).

6. Conclusion

Transitioning from high-level code to pure assembly on legacy architectures like the 8051 perfectly illustrates how technical constraints stimulate ingenuity. By combining manual register optimization with LLM assistance to rapidly structure low-level code, the analyst or architect regains absolute control over a hardware component's execution logic.

Fundamentally, this methodology is far from new. Similar concepts of control flow hijacking were already applied in the early 2000s to core operating systems—such as hooking system calls in the Windows NT kernel—traceable (you can even find one of my articles on this very precise subject written in 2003) all the way back to the classic code-patching and trainer techniques of 1980s video game cracking. However, the distinct operational nuance here lies in the stealth design: rather than permanently breaking or permanently altering a check, the objective is to preserve 100% transparent nominal behavior by default, introducing a selective, state-driven constraint that activates only when decided.

Ghidra 12.2 DEV Internals: Part 2

ddupard — Thu, 30 Jul 2026 01:27:38 +0000

0. Prologue

Given the sheer size of Ghidra, the most effective way to understand its internals is to use a debugger such as Eclipse. To set up your development environment, run the following command (refer to the official Ghidra GitHub repository for details):

gradle prepdev eclipse buildNatives

I did it otherwise and it was painful to switch between all the directories and all the files. Using the Eclipse debbuger changed my life.

Another tool which changed my life is ripgrep.

rg 'extends PluginTool' -l

This command shows all the files which contain 'extends PluginTool' from the current directory. However, ripgrep offers far more features.

ripgrep is a command-line tool provided by Ghidra for performing regular expression searches within binary files.
To search for a simple string pattern (e.g., "hello") in a binary file: rg hello example.bin
To search for a hexadecimal pattern (e.g., 48 65 6c 6c 6f which corresponds to "Hello" in ASCII): rg '\x48\x65\x6c\x6c\x6f' example.bin
To search for a more complex pattern, such as a sequence of bytes that match a specific format:
rg '[\x00-\xFF]{4}' example.bin = Search for any 4-byte.

To output the matches in hex dump format: rg --hexdump '\x48\x65\x6c\x6c\x6f' example.bin

You have other Options like the following
--binary: Treat the pattern as a binary string.
--hexdump: Output matches in hex dump format.
--offsets: Show byte offsets of matches.
--context: Show context around matches.

1. Initialization

At the beginning of everything is the class GhidraRun.
This class, which can be found in ./Ghidra/Features/Base/src/main/java/ghidra/, performs several initializations (see below):

public void launch(GhidraApplicationLayout layout, String[] args) {

        Runnable mainTask = () -> {

            GhidraApplicationConfiguration configuration = new GhidraApplicationConfiguration();
            Application.initializeApplication(layout, configuration);

            log = LogManager.getLogger(GhidraRun.class);
            log.info("User " + SystemUtilities.getUserName() + " started Ghidra.");
            log.info("User settings directory: " + Application.getUserSettingsDirectory());
            log.info("User temp directory: " + Application.getUserTempDirectory());
            log.info("User cache directory: " + Application.getUserCacheDirectory());

            writeLastRun();

            initializeTooltips();

            updateSplashScreenStatusMessage("Populating Ghidra help...");
            GhidraHelpService.install();

            ExtensionUtils.initializeExtensions();

            updateSplashScreenStatusMessage("Checking for previous project...");
            SystemUtilities.runSwingLater(() -> {
                LaunchArguments launchArgs = processArguments(args);
                openProject(launchArgs);

                log.info("Ghidra startup complete (" + GhidraLauncher.getMillisecondsFromLaunch() +
                    " ms)");

                checkForMissingNativeComponents();
            });
        };

        // Start main thread in GhidraThreadGroup
        Thread mainThread = new Thread(new GhidraThreadGroup(), mainTask, "Ghidra");
        mainThread.start();
    }

before opening a project (with the openProject method). If there is no project given in arguments, it will open the last opened project if still existing otherwise none.

The openProject method will instantiate 3 objects

a DefaultProjectManager (DefaultProjectManager implements ProjectManager)
a FrontEndTool which receives the DefaultProjectManager as a parameter of the constructor ( FrontEndTool extends PluginTool implements OptionsChangeListener)
a ProjectLocator which is a base class

then will call another

openProject method which will show a window and call
doOpenProject which will get a Project from the ProjectManager ( Project activeProject = pm.openProject(projectLocator, true, false);) and then will call the
openDomainFileInTool method which will get a ProjectData from the Project object ( ProjectData projectData = project.getProjectData(); ) which will give a DomainFile (DomainFile domainFile = projectData.getFile(domainFilePath); ) used to launch the default tool on this file ( PluginTool tool = toolServices.launchDefaultTool(List.of(domainFile)); ) using the ToolServices obtained from the project (see below)

private void openDomainFileInTool(Project project, String domainFilePath) {
        // Ensure path starts with /
        if (!domainFilePath.startsWith("/")) {
            domainFilePath = "/" + domainFilePath;
        }

        ProjectData projectData = project.getProjectData();
        DomainFile domainFile = projectData.getFile(domainFilePath);

        if (domainFile == null) {
            Msg.showError(GhidraRun.class, null, "File Not Found",
                "Could not find file in project: " + domainFilePath);
            return;
        }

        log.info("Opening file from command line: " + domainFilePath);

        ToolServices toolServices = project.getToolServices();
        PluginTool tool = toolServices.launchDefaultTool(List.of(domainFile));

        if (tool == null) {
            Msg.showError(GhidraRun.class, null, "Tool Launch Failed",
                "Failed to launch tool for: " + domainFile.getName());
        }
    }

i.e the CodeBrowser tool

2. The CodeBrowser tool

As every tool it can be exported. Let's see what we find for this tool

For example the CodeBrowser tool accepts the following data types

<SUPPORTED_DATA_TYPE CLASS_NAME="ghidra.program.model.listing.Program" />
<SUPPORTED_DATA_TYPE CLASS_NAME="ghidra.program.model.listing.DataTypeArchive" />

it contains the following packages

<PACKAGE NAME="BSim" />
<PACKAGE NAME="Ghidra Core">

and the following plugins

<INCLUDE CLASS="ghidra.app.plugin.core.interpreter.InterpreterPanelPlugin" />
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.navigation.GoToAddressLabelPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.functionwindow.FunctionWindowPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.datapreview.DataTypePreviewPlugin">
<PLUGIN_STATE CLASS="ghidra.features.base.memsearch.gui.MemorySearchPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.overview.OverviewColorPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.symboltree.SymbolTreePlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.calltree.CallTreePlugin">
<PLUGIN_STATE CLASS="functioncalls.plugin.FunctionCallGraphPlugin">
<PLUGIN_STATE CLASS="datagraph.DataGraphPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.symtable.SymbolTablePlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.datamgr.DataTypeManagerPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.script.GhidraScriptMgrPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.bookmark.BookmarkPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.byteviewer.ByteViewerPlugin">
<PLUGIN_STATE CLASS="ghidra.features.codecompare.plugin.FunctionComparisonPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.functiongraph.FunctionGraphPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.graph.GraphDisplayBrokerPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.codebrowser.CodeBrowserPlugin">

All plugins are important but the most important one is the CodeBrowserPlugin

The CodeBrowserPlugin is the Primary Controller of the Ghidra User Interface. If you think of Ghidra as a "game engine" for reverse engineering, the CodeBrowserPlugin is the "Level Controller" that manages everything you see and interact with when you are actually looking at a binary.

It is the "glue" that connects the Logic (the Program object) with all the UI (the Listing, Decompiler, and Function Graph windows).

Here is a breakdown of its specific responsibilities:

1. Orchestrating the "View" (The Orchestrator)

The CodeBrowser is not just one window; it is a collection of specialized windows (the "View"). The CodeBrowserPlugin is responsible for making sure all these windows stay in sync.

The Synchronization Problem: If you click on a specific instruction in the Listing View, the Decompiler View must immediately jump to the corresponding C code. If you click a node in the Function Graph, the Listing View must move to that address.
The Solution: The CodeBrowserPlugin manages the Context and the Selection. It listens to "Selection Events" from one window and broadcasts them to all other windows.

2. Managing the "Program" Lifecycle (The Controller)

The CodeBrowserPlugin is the lifecycle manager for the Program object within the UI.

Loading/Unloading: When you open a new program, the CodeBrowserPlugin handles the logic of "unloading" the old program (cleaning up the UI, clearing the memory) and "loading" the new program (populating the windows with the new address space).
The Active Program: It maintains a reference to the currentProgram. Every action you take (renaming a variable, adding a comment) is sent through the plugin to the currentProgram.

3. Handling User Interactions (The Event Handler)

The CodeBrowserPlugin is the primary listener for user input (Mouse and Keyboard) within the workspace.

Mouse Events: It intercepts clicks to handle things like "Double-click to follow jump," "Right-click for context menu," and "Click-and-drag to select a range of bytes."

Keyboard Events: It manages keyboard shortcuts (e.g., pressing 'c' to create a comment, or 'r' to rename a symbol) and routes them to the active window.
The Context Menu: It is responsible for generating the "Right-Click Menu." It looks at what you have selected (an instruction? a data byte? a function?) and decides which menu options are relevant to that specific selection.

4. Tool Integration (The Bridge)

The CodeBrowserPlugin acts as the bridge between the Core Engine and the User Interface.

It provides the Scripting Engine access to the UI. When you run a Python script that says currentProgram.getFunctionAt(addr), the plugin is the entity that ensures the "current" program is correctly passed to the script environment.
It manages the Tool object. It keeps track of which windows are currently "docked" in the CodeBrowser and ensures that the Tool's state is saved when the project is closed.

When Ghidra is launched, the CodeBrowserPlugin restores the "Active" program you were currently working on, and it "re-awakens" any other programs that were open in the background (the "Disconnected" providers). This is done by the readDataState method (see below)

public void readDataState(SaveState saveState) {
        ProgramManager programManagerService = tool.getService(ProgramManager.class);

        if (connectedProvider != null) {
            connectedProvider.readDataState(saveState);
        }
        int numDisconnected = saveState.getInt("Num Disconnected", 0);
        for (int i = 0; i < numDisconnected; i++) {
            Element xmlElement = saveState.getXmlElement("Provider" + i);
            SaveState providerSaveState = new SaveState(xmlElement);
            String programPath = providerSaveState.getString("Program Path", "");
            DomainFile file = tool.getProject().getProjectData().getFile(programPath);
            if (file == null) {
                continue;
            }
            Program program = programManagerService.openProgram(file);
            if (program != null) {
                CodeViewerProvider provider = createNewDisconnectedProvider();
                provider.doSetProgram(program);
                provider.readDataState(providerSaveState);
            }
        }

        FieldSelection highlight = new FieldSelection();
        highlight.load(saveState);
        if (!highlight.isEmpty()) {
            setConnectedProviderHighlight(highlight);
        }
    }

3. The Analysis process: Under the hood

The analysis process occurs when importing a binary into a project

When a first step is done, Ghidra shows the results.

when a project has been analyzed and saved in the database, a project is no longer analyzed unless you force the analysis

A. Importing a program into a Ghidra project

When clicking on the File > Import File menu or pressing the I key, it's the ImporterPlugin class which comes into play and more precisely its importFile method (see below)

public void importFile(DomainFolder folder, File file) {
        System.out.println("ImporterPlugin  importFile()");
        if (handleSimpleDBUnpack(folder, file)) {
            return;
        }

        FSRL fsrl = fsService().getLocalFSRL(file);
        ProgramManager manager = tool.getService(ProgramManager.class);
        ImporterUtilities.showImportDialog(tool, manager, fsrl, folder, null);
    }

This importFile method calls the static ImporterUtilities showImportDialog method which calls the showImportSingleFileDialog method which instantiates an ImporterDialog object (see below)

public static void showImportSingleFileDialog(FSRL fsrl, DomainFolder destinationFolder,
            String suggestedPath, PluginTool tool, ProgramManager programManager,
            TaskMonitor monitor) {
        System.out.println("ImporterUtilities  showImportSingleFileDialog()");

        try {
            ByteProvider provider = fsService.getByteProvider(fsrl, true, monitor);
            LoaderMap loaderMap = LoaderService.getAllSupportedLoadSpecs(provider, monitor);

            SystemUtilities.runSwingLater(() -> {
                ImporterDialog importerDialog = new ImporterDialog(tool, programManager, loaderMap,
                    provider, suggestedPath);
                if (destinationFolder != null) {
                    importerDialog.setDestinationFolder(destinationFolder);
                }

                tool.showDialog(importerDialog);
            });
        }
        catch (IOException ioe) {
            Msg.showError(ImporterUtilities.class, tool.getActiveWindow(), "Error Importing File",
                "Error when importing file " + fsrl, ioe);
        }
        catch (CancelledException e) {
            Msg.info(ImporterUtilities.class, "Import single file " + fsrl + " cancelled");
        }
    }

As a result of all of this, the following dialog appears

At this stage, the system has already analyzed that the program was an ELF program and that the language was the x86:LE:64 and the compiler was default:gcc

How so ?

In fact the LoaderService class has a method getAllLoaders which lists all the available loaders

private synchronized static Collection<Loader> getAllLoaders() {
        List<Loader> loaders = new ArrayList<>(ClassSearcher.getInstances(Loader.class));
        Collections.sort(loaders);
        return loaders;
    }

ClassSearcher.getInstances(Loader.class):
This line of code is used to retrieve all instances of classes that implement or extend the Loader interface in the runtime classPath of the Ghidra's application. When Ghidra is running, it has a specific classpath that includes all the necessary libraries and classes required for its operation. This classpath is determined by how Ghidra was launched and configured.
The ClassSearcher.getInstances(Loader.class) method searches within this runtime classpath to find all classes that implement or extend the Loader interface.
Most of the loaders can be found in the directory ./Ghidra/Features/Base/src/main/java/ghidra/app/util/opinion/ (see below)

Available Loaders:
Loader Class: ghidra.app.util.opinion.GzfLoader
Loader Class: ghidra.app.plugin.core.debug.utils.GztLoader
Loader Class: ghidra.app.util.opinion.GdtLoader
Loader Class: ghidra.app.util.opinion.DecompileDebugXmlLoader
Loader Class: sarif.SarifLoader
Loader Class: ghidra.app.util.opinion.XmlLoader
Loader Class: ghidra.app.util.opinion.TenetLoader
Loader Class: ghidra.app.util.opinion.TenetPlusPlusLoader
Loader Class: ghidra.app.util.opinion.DyldCacheExtractLoader
Loader Class: ghidra.app.util.opinion.MachoFileSetExtractLoader
Loader Class: ghidra.app.util.opinion.ApkLoader
Loader Class: ghidra.app.util.opinion.CoffLoader
Loader Class: ghidra.app.util.opinion.DyldCacheLoader
Loader Class: ghidra.app.util.opinion.DexLoader
Loader Class: ghidra.app.util.opinion.DbgLoader
Loader Class: ghidra.file.formats.dump.DumpFileLoader
Loader Class: ghidra.app.util.opinion.ElfLoader
Loader Class: ghidra.app.util.opinion.JavaLoader
Loader Class: ghidra.app.util.opinion.MSCoffLoader
Loader Class: ghidra.app.util.opinion.MachoLoader
Loader Class: ghidra.app.util.opinion.DefLoader
Loader Class: ghidra.app.util.opinion.NeLoader
Loader Class: ghidra.app.util.opinion.Omf51Loader
Loader Class: ghidra.app.util.opinion.ComLoader
Loader Class: ghidra.app.util.opinion.PeLoader
Loader Class: ghidra.app.util.opinion.PefLoader
Loader Class: ghidra.app.util.opinion.MapLoader
Loader Class: ghidra.app.util.opinion.OmfLoader
Loader Class: ghidra.app.util.opinion.SomLoader
Loader Class: ghidra.app.util.opinion.UnixAoutLoader
Loader Class: ghidra.app.util.opinion.MzLoader
Loader Class: ghidra.app.util.opinion.IntelHexLoader
Loader Class: ghidra.app.util.opinion.MotorolaHexLoader
Loader Class: ghidra.app.util.opinion.CDexLoader
Loader Class: ghidra.app.util.opinion.BinaryLoader

Identifying which loader should be used to load the binary is done by the LoaderService method getSupportedLoadSpecs (see below)

public static LoaderMap getSupportedLoadSpecs(ByteProvider provider,
            Predicate<Loader> loaderFilter, TaskMonitor monitor) {
        initializeLanguageService(monitor);
        LoaderMap loaderMap = new LoaderMap();
        List<Loader> fallback = new ArrayList<>();
        for (Loader loader : getAllLoaders()) {
            if (loaderFilter.test(loader)) {
                if (!loader.isFallback()) {
                    tryLoadSpecs(loader, provider, loaderMap);
                }
                else {
                    fallback.add(loader);
                }
            }
        }

        // Only try fallback loaders if no other loaders matched (ignoring the BinaryLoader)
        boolean matches = loaderMap.keySet()
                .stream()
                .map(Loader::getName)
                .anyMatch(Predicate.not(BinaryLoader.BINARY_NAME::equals));
        if (!matches) {
            fallback.forEach(loader -> tryLoadSpecs(loader, provider, loaderMap));
        }

        return loaderMap;
    }

There is always one loader which matches: the raw binary loader however, if the program has a known header, ghidra is going to identify the corresponding loader as the first loader to choose ( for example the ELF Loader).

Then it will identify the corresponding language , the compiler and the compiler options

This is done by the ProgramLoader object in methods like the following one

private LoadSpec getLoadSpec(ByteProvider p)
                throws LanguageNotFoundException, LoadException {
            LoaderMap loaderMap = LoaderService.getSupportedLoadSpecs(p, loaderFilter, monitor);
            LoadSpecChooser loadSpecChooser =
                languageId != null ? new LcsHintLoadSpecChooser(languageId, compilerSpecId)
                        : (compilerSpecId != null ? new CsHintLoadSpecChooser(compilerSpecId)
                                : LoadSpecChooser.CHOOSE_THE_FIRST_PREFERRED);
            LoadSpec loadSpec = loadSpecChooser.choose(loaderMap);
            if (loadSpec == null) {
                String name = Objects.requireNonNullElse(p.getName(), "???");
                Msg.info(ProgramLoader.class, "No load spec found for import file: " + name);
                throw new LoadException("No load spec found");
            }
            return loadSpec;
        }

c. Example: Loading a ELF program

The class to load an ELF program is ElfLoader and more specifically the ElfLoader load method

@Override
    public void load(Program program, ImporterSettings settings)
            throws IOException, CancelledException {
        System.out.println("ElfLoader->load()");

        try {
            ElfHeader elf =
                new ElfHeader(settings.provider(), msg -> settings.log().appendMsg(msg));
            ElfProgramBuilder.loadElf(elf, program, settings.options(), settings.log(),
                settings.monitor());
        }
        catch (ElfException e) {
            throw new IOException(e.getMessage());
        }
    }

the ElfLoader load method calls the ElProgramBuilder loadElf (see below) which at the end calls the ElProgramBuilder load method.
And this is the ElProgramBuilder load method which does the main part of the loading process (see below)

    static void loadElf(ElfHeader elf, Program program, List<Option> options, MessageLog log,
            TaskMonitor monitor) throws IOException, CancelledException {
        ElfProgramBuilder elfProgramBuilder = new ElfProgramBuilder(elf, program, options, log);
        elfProgramBuilder.load(monitor);
    }

    protected void load(TaskMonitor monitor) throws IOException, CancelledException {
        System.out.println("ElfProgramBuilder->load()");

        monitor.setMessage("Completing ELF header parsing...");
        monitor.setCancelEnabled(false);
        elf.parse();
        monitor.setCancelEnabled(true);

        int id = program.startTransaction("Load ELF program");
        boolean success = false;
        try {
            addProgramProperties(monitor);

            setImageBase();
            program.setExecutableFormat(ElfLoader.ELF_NAME);

            ByteProvider byteProvider = elf.getByteProvider();

            createFileBytes(byteProvider, monitor);

            adjustSegmentAndSectionFileAllocations(byteProvider, monitor);

            // process headers and define "section" within memory elfProgramBuilder
            processProgramHeaders(monitor);
            processSectionHeaders(monitor);

            // resolve segment/sections and create program memory blocks
            resolve(monitor);

            if (elf.getSectionHeaderCount() == 0) {
                // create/expand segments to their fullsize if no sections are defined
                expandProgramHeaderBlocks(monitor);
            }

            if (memory.isEmpty()) {
                // TODO: Does this really happen?
                success = true;
                return;
            }

            markupElfHeader(monitor);
            markupProgramHeaders(monitor);
            markupSectionHeaders(monitor);

            monitor.setIndeterminate(true);

            markupDynamicTable(monitor);
            markupInterpreter(monitor);

            monitor.setIndeterminate(false);

            processStringTables(monitor);

            processSymbolTables(monitor);

            monitor.setIndeterminate(true);

            elf.getLoadAdapter().processElf(this, monitor);

            monitor.setIndeterminate(false);

            processRelocations(monitor);
            processEntryPoints(monitor);
            processImports(monitor);

            monitor.setIndeterminate(true);

            monitor.setMessage("Processing PLT/GOT ...");
            elf.getLoadAdapter().processGotPlt(this, monitor);

            markupHashTable(monitor);
            markupGnuHashTable(monitor);
            markupGnuXHashTable(monitor);

            processGNU(monitor);
            adjustReadOnlyMemoryRegions(monitor);

            markupElfInfoProducers(monitor);

            success = true;
        }
        finally {
            program.endTransaction(id, success);
        }
    }

At the end the program is loaded and its code is ready to be disassembled

d. The disassembly process

When a program is imported in a project, there is an auto analysis made by the AutoAnalysisManager class.
This auto analysis contains several steps including a disassembling of the binary

INFO  -----------------------------------------------------
    ASCII Strings                              0.497 secs
    Apply Data Archives                        0.702 secs
    Call Convention ID                         0.548 secs
    Call-Fixup Installer                       0.006 secs
    Create Address Tables                      0.004 secs
    Create Function                            0.017 secs
    DWARF                                      0.410 secs
    Data Reference                             0.008 secs
    Decompiler Switch Analysis                 0.879 secs
    Demangler GNU                              0.052 secs
    Disassemble                                0.017 secs
    Disassemble Entry Points                   0.130 secs
    ELF Scalar Operand References              0.011 secs
    Embedded Media                             0.003 secs
    External Entry References                  0.000 secs
    External Symbol Resolver                   0.010 secs
    Function ID                                0.037 secs
    Function Start Pre Search                  0.017 secs
    Function Start Search                      0.068 secs
    Function Start Search After Code           0.003 secs
    Function Start Search After Data           0.001 secs
    GCC Exception Handlers                     0.083 secs
    Non-Returning Functions - Discovered       0.003 secs
    Non-Returning Functions - Known            0.005 secs
    Reference                                  0.018 secs
    Shared Return Calls                        0.012 secs
    Source Language Support                    0.037 secs
    Stack                                      0.038 secs
    Subroutine References                      0.006 secs
    Subroutine References - One Time           0.000 secs
    x86 Constant Reference Analyzer            0.120 secs
-----------------------------------------------------
     Total Time   3 secs
-----------------------------------------------------
   (AutoAnalysisManager.java:1273)

The disassembling process is made by the Disassembler class and precisely by the disassemble method.
This disassemble method uses the SleighLanguage class to get Instruction Alignment and process recursively

public AddressSet disassemble(AddressSetView startSet, AddressSetView restrictedSet,
            RegisterValue initialContextValue, boolean doFollowFlow) {

        System.out.println("Disassembler  disassemble()");
        AddressSet disassembledAddrs;

        disassembledAddrs = new AddressSet();

        int alignment = language.getInstructionAlignment();

        AddressRangeIterator addressRanges = startSet.getAddressRanges();
        for (AddressRange addressRange : addressRanges) {
            if (monitor.isCancelled()) {
                break;
            }

            if (disassembledAddrs.contains(addressRange.getMinAddress(),
                addressRange.getMaxAddress())) {
                continue;
            }

            AddressSet todoSubset = new AddressSet(addressRange);

            while (!todoSubset.isEmpty() && !monitor.isCancelled()) {
                Address nextAddr = todoSubset.getMinAddress();

                // Check if location is already on disassembly list
                if (disassembledAddrs.contains(nextAddr)) {
                    AddressRange doneRange = disassembledAddrs.getRangeContaining(nextAddr);
                    todoSubset.delete(doneRange);
                    continue;
                }

                todoSubset.delete(nextAddr, nextAddr);

                // must be aligned
                if (nextAddr.getOffset() % alignment != 0) {
                    continue;
                }

                Data data = listing.getUndefinedDataAt(nextAddr);
                if (data == null) {
                    AddressSetView undefinedRanges = null;
                    try {
                        undefinedRanges =
                            program.getListing().getUndefinedRanges(todoSubset, true, monitor);
                        todoSubset = new AddressSet(undefinedRanges);
                    }
                    catch (CancelledException e) {
                        break;
                    }
                }
                else {
                    AddressSet currentSet =
                        disassemble(nextAddr, restrictedSet, initialContextValue, doFollowFlow);

                    if (!currentSet.isEmpty()) {  // nothing disassembled
                        todoSubset.delete(currentSet);
                        disassembledAddrs.add(currentSet);
                    }
                }
                if (monitor.isCancelled()) {
                    break;
                }
            }
        }
        return disassembledAddrs;
    }

the SleighLanguage class uses the initialize method to get all the files implied in the disassembly of a binary

private void initialize(boolean forceCompile, TaskMonitor monitor) throws SleighException {
        long startTS = System.currentTimeMillis();

        this.defaultSymbols = new ArrayList<>();
        this.defaultMemoryBlocks = new MemoryBlockDefinition[0];
        this.compilerSpecDescriptions = new LinkedHashMap<>();
        for (CompilerSpecDescription compilerSpecDescription : description
                .getCompatibleCompilerSpecDescriptions()) {
            this.compilerSpecDescriptions.put(compilerSpecDescription.getCompilerSpecID(),
                (SleighCompilerSpecDescription) compilerSpecDescription);
        }
        compilerSpecs = new HashMap<>();
        additionalInject = null;

        SleighLanguageValidator.validatePspecFile(description.getSpecFile());

        readInitialDescription(); // process pspec file

        // Should addressFactory and registers initialization be done at construction time?
        // For now we'll assume yes.
        contextcache = new ContextCache();

        SleighLanguageFile langFile = description.getLanguageFile();
        if (!langFile.getSlaSpecFile().exists()) {
            throw new SleighFileException("Missing slaspec: " + langFile.getSlaSpecFile());
        }

        // check .sla file freshness inside lock, and recompile if necessary before releasing lock.
        // if can't lock, it's single jar mode and we can't recompile anyways
        AtomicLong lockElapsed = new AtomicLong();
        if (langFile.canLock()) {
            try (PreserveStateWrappingTaskMonitor tm =
                new PreserveStateWrappingTaskMonitor(monitor)) {
                tm.setCancelEnabled(true);
                tm.setShowProgressValue(true);
                langFile.withLock(SleighLanguageProvider.LANGUAGE_LOCK_TIMEOUT, tm, () -> {
                    tm.setCancelEnabled(false);
                    long lockStartTS = System.currentTimeMillis();
                    if (forceCompile || langFile.needsCompilation(SlaFormat.FORMAT_VERSION)) {
                        langFile.compileSlaFile(monitor);
                    }
                    lockElapsed.set(System.currentTimeMillis() - lockStartTS);
                });
            }
            catch (TimeoutException e) {
                throw new SleighFileLockException(
                    "Timeout waiting for Sleigh language file lock: %s"
                            .formatted(langFile.getSlaFile()),
                    e);
            }
            catch (IOException e) {
                throw new SleighFileException(
                    "Error locking Sleigh language file %s".formatted(langFile.getSlaFile()), e);
            }
        }

        // Read in the sleigh specification
        try (PackedDecode decoder = SlaFormat.buildDecoder(langFile.getSlaFile())) {
            decode(decoder);
        }
        catch (IOException | DecoderException e) {
            throw new SleighException("Error decoding", e);
        }

        registerBuilder = new RegisterBuilder();
        loadRegisters(registerBuilder);
        readRemainingSpecification();
        buildVolatileSymbolAddresses();
        xrefRegisters();

        instructProtoMap = new ConcurrentHashMap<>();

        initParallelHelper();

        int maxLength =
            getPropertyAsInt(GhidraLanguagePropertyKeys.MAXIMUM_INSTRUCTION_LENGTH, -1);
        if (maxLength > 0) {
            maxInstructionLength = OptionalInt.of(maxLength);
        }

        long initElapsed = System.currentTimeMillis() - startTS;
        Msg.debug(this, "Took %dms (%dms inside lock) to initialize language %s"
                .formatted(initElapsed, lockElapsed.get(), langFile));
    }

There are 3 kind of files

the pspec file
the slaspec file
the sla file

The .pspec file (Processor Specification): This is indeed a specification file linked to the processor architecture. It defines elements such as default registers, specific stack locations, calling conventions, or hardware starting addresses for a given architecture.

<?xml version="1.0" encoding="UTF-8"?>

<processor_spec>
  <programcounter register="PC"/>

  <default_symbols>
    <symbol name="NMI" address="FFFA" entry="true" type="code_ptr"/>
    <symbol name="RES" address="FFFC" entry="true" type="code_ptr"/>
    <symbol name="IRQ" address="FFFE" entry="true" type="code_ptr"/>
  </default_symbols>

  <default_memory_blocks>
    <memory_block name="ZERO_PAGE" start_address="0x0000" length="0x0100" initialized="false"/>
    <memory_block name="STACK" start_address="0x0100" length="0x0100" initialized="false"/>
  </default_memory_blocks>
</processor_spec>

The .slaspec file (SLEIGH Specification): This is the main textual source file that describes the assembly syntax and processor architecture semantics (e.g., x86, ARM, MIPS). It is written by the creators of the architecture (or emulator) and is compiled once and for all.

# sleigh specification file for MOS 6502

define endian=little;
define alignment=1;

define space RAM     type=ram_space      size=2  default;
define space register type=register_space size=1;

define register offset=0x00  size=1 [ A X Y P ];
define register offset=0x20 size=2  [ PC      SP   ];
define register offset=0x20 size=1  [ PCL PCH S SH ];
define register offset=0x30 size=1 [ N V B D I Z C ];   # status bits

#TOKENS

define token opbyte (8)
   op       = (0,7)

   aaa      = (5,7)
   bbb      = (2,4)
   cc       = (0,1)
;

define token data8 (8)
   imm8     = (0,7)
   rel      = (0,7) signed
;

define token data (16)
    imm16 = (0,15)
;

macro popSR() {
    SP = SP + 1;
    local ccr = *:1 SP;
    N = ccr[7,1];
    V = ccr[6,1];
    B = ccr[4,1];
    D = ccr[3,1];
    I = ccr[2,1];
    Z = ccr[1,1];
    C = ccr[0,1];
}

The .sla file (Compiled SLEIGH): SLA stands for SLEIGH Language Architecture format. It is a binary/intermediate file loaded by Ghidra to quickly decode instructions for a specific architecture.

4. Save into the database

if you create a test.gpr project in some directory (example XXXX), Ghidra is going to create a test.rep directory in XXXXX
In the test.rep directory, you will find the following files and directories

ls -la
total 28
drwxr-x--- 5 daniel daniel 4096 Jul 28 16:05 .
drwxrwxr-x 9 daniel daniel 4096 Jul 29 11:06 ..
drwxr-x--- 3 daniel daniel 4096 Jul 29 11:06 idata
-rw-r----- 1 daniel daniel  159 Jul 26 20:21 project.prp
-rw-r----- 1 daniel daniel  602 Jul 29 11:06 projectState
drwxr-x--- 3 daniel daniel 4096 Jul 29 11:06 user
drwxr-x--- 2 daniel daniel 4096 Jul 29 11:06 versioned

Here is a breakdown of what each of those files and directories represents:

project.prp (Project Properties)
What it is: This is the "Identity Card" of your project.
Role: It contains the configuration and metadata specific to the project itself. If you rename your project or change project-wide settings (like certain script paths or project-wide preferences), that information is recorded here. It is essentially the "header" for the .gpr project.
projectState
What it is: The "Session Tracker."
Role: This file tracks the current "state" of your work within the project. It remembers which programs were recently opened, which windows were positioned where, and the overall "context" of your last session. This is why, when you reopen Ghidra, you can pick up exactly where you left off.
idata (Internal Data)
What it is: The "Shared Library" of the project.
Role: This directory holds data that is shared across all programs within this specific project. If you create a custom Data Type (a struct, for example) and save it so that it can be used by multiple different binaries in the same project, that structure definition is stored here. It prevents duplication.
user
What it is: The "User Preference" override.
Role: This directory contains settings or configurations that are specific to the user interacting with this particular project. It allows for user-specific customizations that don't affect the "core" project properties but are relevant to how you interact with this specific analysis.
versioned
What it is: The "History/Snapshot" directory.
Role: The presence of this folder indicates that you (or a script you ran) have used Ghidra's Versioning/Snapshot feature.
How it works: Ghidra allows you to take "snapshots" of a program's state. This folder stores the "diffs" or the historical states of the programs in the project. It allows you to revert the analysis to a previous point in time.

We will study more precisely this subject in another article

How it is handled in Ghidra ?

The Databae Engine is handled by the following files

Framework/FileSystem/bin/main/ghidra/framework/store/db/package.html
Framework/FileSystem/src/main/java/ghidra/framework/store/db/PackedDBHandle.java
Framework/FileSystem/src/main/java/ghidra/framework/store/db/package.html
Framework/FileSystem/src/main/java/ghidra/framework/store/db/PrivateDatabase.java
Framework/FileSystem/src/main/java/ghidra/framework/store/db/PackedDatabase.java
Framework/FileSystem/src/main/java/ghidra/framework/store/db/VersionedDBListener.java
Framework/FileSystem/src/main/java/ghidra/framework/store/db/VersionedDatabase.java
Framework/FileSystem/src/main/java/ghidra/framework/store/db/PackedDatabaseCache.java
Framework/FileSystem/src/test/java/ghidra/framework/store/db/PackedDatabaseTest.java
Framework/FileSystem/src/test/java/ghidra/framework/store/db/VersionFailureRecoveryTest.java
Framework/FileSystem/src/test/java/db/RecoveryDBTest.java
Framework/FileSystem/src/test.slow/java/db/buffers/RecoveryFileTest.java
Framework/DB/src/main/java/db/ObjectStorageAdapterDB.java
Framework/DB/src/main/java/db/TranslatedRecordIterator.java
Framework/DB/src/main/java/db/BinaryCodedField.java
Framework/DB/src/main/java/db/KeyToRecordIterator.java
Framework/DB/src/main/java/db/InteriorNode.java
Framework/DB/src/main/java/db/BTreeNode.java
Framework/DB/src/main/java/db/ShortField.java
Framework/DB/src/main/java/db/BinaryDataBuffer.java
Framework/DB/src/main/java/db/RecordTranslator.java
Framework/DB/src/main/java/db/DatabaseUtils.java
Framework/DB/src/main/java/db/TableRecord.java
Framework/DB/src/main/java/db/DBLongIterator.java
Framework/DB/src/main/java/db/LongKeyInteriorNode.java
Framework/DB/src/main/java/db/VarRecNode.java
Framework/DB/src/main/java/db/VarKeyRecordNode.java
Framework/DB/src/main/java/db/LongKeyNode.java
Framework/DB/src/main/java/db/DBFileListener.java
Framework/DB/src/main/java/db/TerminatedTransactionException.java
Framework/DB/src/main/java/db/VarKeyInteriorNode.java
Framework/DB/src/main/java/db/LongField.java
Framework/DB/src/main/java/db/FixedField.java
Framework/DB/src/main/java/db/TestSpeed.java
Framework/DB/src/main/java/db/VarKeyNode.java
Framework/DB/src/main/java/db/TableStatistics.java
Framework/DB/src/main/java/db/BinaryField.java
Framework/DB/src/main/java/db/IllegalFieldAccessException.java
Framework/DB/src/main/java/db/NoTransactionException.java
Framework/DB/src/main/java/db/NodeMgr.java
Framework/DB/src/main/java/db/DBRecord.java
Framework/DB/src/main/java/db/RecordNode.java
Framework/DB/src/main/java/db/DBHandle.java
Framework/DB/src/main/java/db/LongKeyRecordNode.java
Framework/DB/src/main/java/db/DBInitializer.java
Framework/DB/src/main/java/db/MasterTable.java
Framework/DB/src/main/java/db/Field.java
Framework/DB/src/main/java/db/FixedRecNode.java
Framework/DB/src/main/java/db/ConvertedRecordIterator.java
Framework/DB/src/main/java/db/DBListener.java
Framework/DB/src/main/java/db/FixedKeyRecordNode.java
Framework/DB/src/main/java/db/Table.java
Framework/DB/src/main/java/db/FixedField10.java
Framework/DB/src/main/java/db/FieldKeyRecordNode.java
Framework/DB/src/main/java/db/Buffer.java
Framework/DB/src/main/java/db/ByteField.java
Framework/DB/src/main/java/db/FixedKeyVarRecNode.java
Framework/DB/src/main/java/db/IndexTable.java
Framework/DB/src/main/java/db/DBBuffer.java
Framework/DB/src/main/java/db/IntField.java
Framework/DB/src/main/java/db/SparseRecord.java
Framework/DB/src/main/java/db/DBParms.java
Framework/DB/src/main/java/db/FixedKeyNode.java
Framework/DB/src/main/java/db/IndexField.java
Framework/DB/src/main/java/db/Transaction.java
Framework/DB/src/main/java/db/util/ErrorHandler.java
Framework/DB/src/main/java/db/FieldKeyInteriorNode.java
Framework/DB/src/main/java/db/ConstrainedForwardRecordIterator.java
Framework/DB/src/main/java/db/FixedKeyFixedRecNode.java
Framework/DB/src/main/java/db/FieldIndexTable.java
Framework/DB/src/main/java/db/Database.java
Framework/DB/src/main/java/db/ChainedBuffer.java
Framework/DB/src/main/java/db/FieldKeyNode.java
Framework/DB/src/main/java/db/DBFieldIterator.java
Framework/DB/src/main/java/db/LegacyIndexField.java
Framework/DB/src/main/java/db/DBRollbackException.java
Framework/DB/src/main/java/db/buffers/LocalBufferFile.java
Framework/DB/src/main/java/db/buffers/RecoveryMgr.java
Framework/DB/src/main/java/db/buffers/VersionFile.java
Framework/DB/src/main/java/db/buffers/DataBuffer.java
Framework/DB/src/main/java/db/buffers/LocalManagedBufferFile.java
Framework/DB/src/main/java/db/buffers/BufferNode.java
Framework/DB/src/main/java/db/buffers/VersionFileHandler.java
Framework/DB/src/main/java/db/buffers/InputBlockStream.java
Framework/DB/src/main/java/db/buffers/BufferFile.java
Framework/DB/src/main/java/db/buffers/ManagedBufferFileHandle.java
Framework/DB/src/main/java/db/buffers/BufferFileBlock.java
Framework/DB/src/main/java/db/buffers/IndexProvider.java
Framework/DB/src/main/java/db/buffers/BufferMgr.java
Framework/DB/src/main/java/db/buffers/ChangeMapFile.java
Framework/DB/src/main/java/db/buffers/ManagedBufferFileAdapter.java
Framework/DB/src/main/java/db/buffers/BufferFileHandle.java
Framework/DB/src/main/java/db/buffers/BlockStreamHandle.java
Framework/DB/src/main/java/db/buffers/RemoteManagedBufferFileHandle.java
Framework/DB/src/main/java/db/buffers/ManagedBufferFile.java
Framework/DB/src/main/java/db/buffers/RecoveryFile.java
Framework/DB/src/main/java/db/buffers/BlockStream.java
Framework/DB/src/main/java/db/buffers/BufferFileAdapter.java
Framework/DB/src/main/java/db/buffers/RemoteBufferFileHandle.java
Framework/DB/src/main/java/db/buffers/OutputBlockStream.java
Framework/DB/src/main/java/db/buffers/BufferFileManager.java
Framework/DB/src/main/java/db/buffers/ChangeMap.java
Framework/DB/src/main/java/db/RecordIterator.java
Framework/DB/src/main/java/db/StringField.java
Framework/DB/src/main/java/db/FixedKeyInteriorNode.java
Framework/DB/src/main/java/db/BooleanField.java
Framework/DB/src/main/java/db/Schema.java
Framework/DB/src/main/java/db/DBChangeSet.java
Framework/DB/src/main/java/db/PrimitiveField.java

The files above you are looking at are the source code for the custom database engine that Ghidra uses to power its Repository (.rep) system.

The files are divided into two distinct layers: the API/Abstraction Layer and the Engine/Implementation Layer.

Layer 1: The Abstraction Layer

Path: ghidra/framework/store/db/...

This layer provides the "Java-friendly" way for the rest of Ghidra to interact with the database. If you are writing a Ghidra plugin and you want to save something to the repository, you use these classes.

PrivateDatabase.java & PackedDatabase.java: These are the "Entry Points." They represent a logical database that a user can open. They hide the complexity of the raw bytes and present a structured object.
VersionedDatabase.java: This is the logic that allows the .rep folder to have snapshots. It manages the "History" of the database.
PackedDatabaseCache.java: This manages memory. It ensures that frequently accessed parts of the database stay in RAM so that Ghidra doesn't have to hit the disk every time you click a function.
PackedDBHandle.java: This is the "Pointer" or "Cursor" used to navigate through the database records.

Layer 2: The Engine Layer (The "Heavy Lifters")

Path: db/...

This is the "low-level" code. This is the code that actually manipulates bits and bytes on your hard drive. This is a highly optimized implementation of a B-Tree Database (similar to Berkeley DB).

A. The Structural Layer (The B-Tree)

These classes define the "Shape" of the data.

BTreeNode.java, InteriorNode.java, VarKeyInteriorNode.java: These implement the B-Tree structure. A B-Tree is a self-balancing tree data structure that maintains sorted data and allows searches, sequential access, insertions, and deletions in logarithmic time.
MasterTable.java & IndexTable.java: These are the "Metadata" tables. They store the "Map" of the database (e.g., "Table X exists, and it has 5 columns").

B. The Schema Layer (The Data Types)

These classes define what a "Field" is. Without these, the database is just a blob of random bytes.

Field.java: The base class for all data types.
ByteField.java, IntField.java, StringField.java, BooleanField.java, LongField.java: These define the actual types of data the database can hold. They handle the logic of "How do I turn a Java int into 4 bytes on the disk?"

C. The Transaction & Safety Layer (The ACID Properties)

This is the most critical part for preventing data corruption.

Transaction.java: This manages the "All or Nothing" principle. When you perform a write, this class ensures that either the entire write succeeds, or none of it does.
RecoveryMgr.java & RecoveryFile.java: This is the Write-Ahead Log (WAL) logic. As we discussed earlier, these files record changes before they are committed to the main database, allowing the engine to recover after a crash.
DBListener.java & VersionFileHandler.java: These notify the system when changes occur, allowing for the "Versioned" feature to trigger.

D. The I/O Layer (The Buffer Manager)

This is the bridge between your RAM and your Hard Drive.

BufferMgr.java & BufferFile.java: These manage the "Buffer Pool." They decide which parts of the database files are currently loaded into your computer's RAM.
DataBuffer.java & ChainedBuffer.java: These handle the raw byte arrays that are being streamed from the disk.
InputBlockStream.java & OutputBlockStream.java: These are the "Pipes" that stream data into and out of the database files.

Summary: How they work together

A user clicks "Save" in Ghidra.
The PrivateDatabase (Layer 1) receives the command.
It tells the Transaction (Layer 2) to start a new operation.
The Field classes determine how the new data should be encoded into bytes.
The BTreeNode logic determines where in the tree this new data should be inserted.
The RecoveryMgr writes the change to a log file to ensure safety.
The BufferMgr pushes those bytes into the DataBuffer.
The BufferFile finally writes those bytes to the physical .db file on your disk.

6. Epilogue

This analysis would have been far more difficult if the creators of Ghidra had not done an incredible job standardizing their files and maintaining consistent design rules. Kudos to them! Right now, I am still scratching the surface and there's a lot more to learn. I will continue to document my journey in the next articles.

Ghidra 12.2 DEV Internals: Part I

ddupard — Sun, 26 Jul 2026 21:50:48 +0000

I don't like the way Ghidra displays assembly. In fact, I dislike it so much that I started working on a tool that replicates some of Ghidra's core functions while adding cool new features. I use Ghidra on a 14-inch screen, which probably explains why I'm not a fan of its default assembly view.

Moreover, most of the time I don't have the source code, and since I started to read disassembly code when dinosaurs... (well, maybe a little bit later, on the 6502 and Oric-1), I really like raw disassembly code.

However, Ghidra remains an industry standard for reverse engineering for very good reasons (alongside IDA Pro, etc.).

So, I decided to build a custom assembly view tailored to how I actually like reading assembly code. To achieve this, I need to understand how Ghidra works under the hood. This is my personal journey—I started just 2 days ago.

Below is the way ghidra shows an assembly code

In my view I don't have big blocks of information. Instead I change the view depending on what I want to see. Moreover what I want to see is programmable. For example below I want to see the external calls and the stack allocation:

I am a complete beginner when it comes to Ghidra's internals, so please feel free to leave comments to correct my mistakes or help me understand things better!

1. Some Basic Information

The source code of Ghidra is publicly available on GitHub:
https://github.com/nationalsecurityagency/ghidra

Collecting the sources and compiling them is an absolute breeze—really easy. All I did was applying the instructions on the github repo of Ghidra (see below).

To create the latest development build for your platform from this source repository:

Install build tools:

JDK 25 64-bit
Gradle 9.1.0+ (or provided Gradle wrapper if Internet connection is available)
Python3 (version 3.9 to 3.14) with bundled pip
GCC or Clang, and make (Linux/macOS-only)


Download and extract the source: ghidra-master

unzip ghidra-master
cd ghidra-master

NOTE: Instead of downloading the compressed source, you may instead want to clone the GitHub repository: git clone https://github.com/NationalSecurityAgency/ghidra.git

Download additional build dependencies into source repository:
NOTE: If an Internet connection is available and you did not install Gradle, the ./gradlew (or gradlew.bat) command may be used in place of the gradle command in the following instructions.

gradle -I gradle/support/fetchDependencies.gradle

Create development build:
gradle buildGhidra

The compressed development build will be located at build/dist/.

Ghidra is written mainly (exclusively?) in Java. It is highly modular, allowing you to add your own plugins, tools, extensions, and scripts.

It seems to work smoothly with Python scripts as well, though I have only tested Java scripts so far.

Ghidra is massive. It contains more than 15,700 Java files, which means I urgently need a solid methodology to figure out how it ticks. Fortunately, the creators of Ghidra followed a very rigorous naming convention.

2. The Cartography

Ghidra is organized in tools (like the CodeBrowser, the Emulator, the Debugger, the Version Tracking tool )
Each tool contains plugins. These plugins can be found in files whose names finish with Plugin.java like (SymbolTreePlugin.java, FunctionWindowPlugin.java, CallTreePlugin.java, ..)
There are 235 plugins. See below

//@formatter:on
public class CallTreePlugin extends ProgramPlugin {

    static final Icon PROVIDER_ICON = Icons.ARROW_DOWN_RIGHT_ICON;

    private List<CallTreeProvider> providers = new ArrayList<>();
    private DockingAction showCallTreeFromMenuAction;
    private CallTreeProvider primaryProvider;

    public CallTreePlugin(PluginTool tool) {
        super(tool);

        createActions();
        primaryProvider = new CallTreeProvider(this, true);
        providers.add(primaryProvider);
    }

    @Override
    protected void locationChanged(ProgramLocation loc) {
        for (CallTreeProvider provider : providers) {
            provider.setLocation(loc);
        }
    }

    @Override
    protected void programActivated(Program program) {
        for (CallTreeProvider provider : providers) {
            provider.programActivated(program);
        }
    }

    @Override
    protected void programDeactivated(Program program) {
        for (CallTreeProvider provider : providers) {
            provider.programDeactivated(program);
        }
    }

    @Override
    protected void programClosed(Program program) {
        for (CallTreeProvider provider : providers) {
            provider.programClosed(program);
        }
    }

    @Override
    public void readConfigState(SaveState saveState) {
        primaryProvider.readConfigState(saveState);
    }

    @Override
    public void writeConfigState(SaveState saveState) {
        primaryProvider.writeConfigState(saveState);
    }

    @Override
    protected void dispose() {
        List<CallTreeProvider> copy = new ArrayList<>(providers);
        for (CallTreeProvider provider : copy) {
            removeProvider(provider);
        }
    }
    ...

All Plugins derive from a unique class called Plugin or a class called ProgramPlugin.
The Plugin class can be found in the file ./Ghidra/Framework/Project/src/main/java/ghidra/framework/plugintool/Plugin.java
The ProgramPlugin class which is derived from the class Plugin can be found in the file ./Ghidra/Features/Base/src/main/java/ghidra/app/plugin/ProgramPlugin.java

Plugins are a basic building block in Ghidra, used to bundle features or capabilities into a unit that can be enabled or disabled by the user in their Tool.

Plugins expose their features or capabilities to users via menu items and buttons that the user can click on, and via "service" APIs that other Plugins can programmatically subscribe to, and via {@link PluginEvent}s that are broadcast.

3. The CodeBrowser

Using Ghidra's capability to export tools,

one can see what is hidden in a tool

For example the CodeBrowser accepts the following data types

<SUPPORTED_DATA_TYPE CLASS_NAME="ghidra.program.model.listing.Program" />
<SUPPORTED_DATA_TYPE CLASS_NAME="ghidra.program.model.listing.DataTypeArchive" />

if contains the following packages

 <PACKAGE NAME="BSim" />
<PACKAGE NAME="Ghidra Core">

and the following plugins

<INCLUDE CLASS="ghidra.app.plugin.core.interpreter.InterpreterPanelPlugin" />
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.navigation.GoToAddressLabelPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.functionwindow.FunctionWindowPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.datapreview.DataTypePreviewPlugin">
<PLUGIN_STATE CLASS="ghidra.features.base.memsearch.gui.MemorySearchPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.overview.OverviewColorPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.symboltree.SymbolTreePlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.calltree.CallTreePlugin">
<PLUGIN_STATE CLASS="functioncalls.plugin.FunctionCallGraphPlugin">
<PLUGIN_STATE CLASS="datagraph.DataGraphPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.symtable.SymbolTablePlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.datamgr.DataTypeManagerPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.script.GhidraScriptMgrPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.bookmark.BookmarkPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.byteviewer.ByteViewerPlugin">
<PLUGIN_STATE CLASS="ghidra.features.codecompare.plugin.FunctionComparisonPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.functiongraph.FunctionGraphPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.graph.GraphDisplayBrokerPlugin">
<PLUGIN_STATE CLASS="ghidra.app.plugin.core.codebrowser.CodeBrowserPlugin">

Moreover a tool contains some fields which describe the gui ie. how the panels (or windows) are arranged on the screen

<ROOT_NODE X_POS="348" Y_POS="294" WIDTH="1390" HEIGHT="786" EX_STATE="6" FOCUSED_OWNER="DecompilePlugin" FOCUSED_NAME="Decompiler" FOCUSED_TITLE="Decompile: handle_client">
            <SPLIT_NODE WIDTH="100" HEIGHT="100" DIVIDER_LOCATION="0" ORIENTATION="VERTICAL">
                <SPLIT_NODE WIDTH="1621" HEIGHT="816" DIVIDER_LOCATION="148" ORIENTATION="VERTICAL">
                    <COMPONENT_NODE TOP_INFO="0">
                        <COMPONENT_INFO NAME="Entropy" OWNER="EntropyPlugin" TITLE="Entropy" ACTIVE="false" GROUP="Header" INSTANCE_ID="3207819926581772885" />
                        <COMPONENT_INFO NAME="Overview" OWNER="OverviewPlugin" TITLE="Overview" ACTIVE="false" GROUP="Header" INSTANCE_ID="3207819926581772883" />
                    </COMPONENT_NODE>
                    <SPLIT_NODE WIDTH="1854" HEIGHT="929" DIVIDER_LOCATION="191" ORIENTATION="HORIZONTAL">
                        <SPLIT_NODE WIDTH="353" HEIGHT="929" DIVIDER_LOCATION="640" ORIENTATION="VERTICAL">
                            <SPLIT_NODE WIDTH="353" HEIGHT="592" DIVIDER_LOCATION="502" ORIENTATION="VERTICAL">
                                <COMPONENT_NODE TOP_INFO="0">
                                    <COMPONENT_INFO NAME="Program Tree" OWNER="ProgramTreePlugin" TITLE="Program Trees" ACTIVE="true" GROUP="Default" INSTANCE_ID="3743589477541406473" />
                                </COMPONENT_NODE>
                                <COMPONENT_NODE TOP_INFO="0">
                                    <COMPONENT_INFO NAME="Symbol Tree" OWNER="SymbolTreePlugin" TITLE="Symbol Tree" ACTIVE="true" GROUP="Default" INSTANCE_ID="3743589477541406468" />
                                </COMPONENT_NODE>
                            </SPLIT_NODE>
                            <COMPONENT_NODE TOP_INFO="0">
                                <COMPONENT_INFO NAME="DataTypes Provider" OWNER="DataTypeManagerPlugin" TITLE="Data Type Manager" ACTIVE="true" GROUP="Default" INSTANCE_ID="3743590794492045077" />
                            </COMPONENT_NODE>
                        </SPLIT_NODE>

and finally some preferences in terms of columns and options for the panels

4. Epilogue

In this very short article, I tried to explain what I discovered about Ghidra internals. I am a complete beginner on it. I am just scratching the surface of Ghidra and viewing the amount of work which has been done on it demonstrates how idotic was my idea of creating another tool.

In the next part, we will dive into the CodeBrowser's Java code to understand how it intercepts clicks and renders (or rather, overrides) the assembly view...

DEV Community: ddupard

8051 What does SDCC do part 3 ?

1. Introduction and Problem Statement

2. Function call

3. Inside the function

4. Inside the function: Initialization

5. Inside the function: Arithmetic operations

6. Inside the function: Shift operations

7 . Inside the function: return of the result

8. Conclusion

9. The full disassembly code

8051 What does SDCC do part 2 ?

1. Introduction and Problem Statement

2. Variable Initialization

3. Loop and Test

4. Switch

5. Memory and access tests

6. Terminal and infinite loop

7. Conclusion

8. The full disassembly code

8051 What does SDCC do part 1 ?

1. Introduction and Problem Statement

2. 8051 Presentation

3. 8051 The instruction set

A. Data Transfer Instructions (14 base mnemonics)

B. Arithmetic Instructions (8 base mnemonics)

C. Logical Instructions (6 base mnemonics)

D. Rotate & Shift Instructions (4 base mnemonics)

E. Boolean / Bit-Manipulation Instructions (10 base mnemonics)

6. Program Branching / Control Transfer Instructions (15 base mnemonics)

1. Addition (8 instructions)

2. Subtraction (4 instructions)

3. Increment (5 instructions)

4. Decrement (4 instructions)

5. Multiplication and Division (2 instructions)

6. BCD Adjustment (1 instruction)

7. Comparison with the x86_64

4. Memory-Mapped Registers and Direct Addressability

5. SDCC: The stub

6. the 8051 Today

Everyday Embedded Electronics and Appliances

Industrial Embedded Systems and Legacy Hardware

Modern Descendants and Silicon Vendors

Embedded Education and Hobbyists

7. Conclusion

Ghidra internals: Where are my logs ?

1. The Quick Command

2. Locating Logs from IDE / Console

3. Conclusion

Adapting Ghidra for Reverse Engineering Undocumented Binary Architectures

1. Language Architecture in Ghidra

2. The Challenges of Reverse Engineering Undocumented Binaries

3. Missing .slaspec File

4. Overcoming Ghidra's Aggressive Disassembly

A. Why Prevent Full Disassembly?

B. Patching Ghidra Under the Hood

a. Disabling Auto-Analysis Passes

b. Overriding DissectedFlow & SLEIGH Rules (Architectural Level)

c. Modifying the Java Disassembler Engine (Disassembler.java)

5. Two-Phase Analysis for Undocumented CISC Processors

Bridging the Abstraction Gap in Ghidra

Option A: Dummy / Proxy Instructions (SLEIGH Abstraction)

Option B: Data Types & Marker Engines (Ghidra Java API)

6. Conclusion

From C Corpus to Machine Code Analysis: A Two-Phase Pipeline for Unknown Architectures

1. Filling a pattern matching database (Semantic P-Code Mapping)

2. Guessing the bytes

A. Entropy Analysis & Decompression / Decryption Detection

B. Finding the reset vector of the processor.

C. Constraint Propagation and Hypothesis Scoring

3. Conclusion

Identifying the Processor of a Bare-Metal Binary (Strategy 2): Modifying prompts

2. Evaluated Strategies

3. Test Protocol

4. Benchmark Results

Firmware 1 (Known Processor)

Firmware 2 (Unknown Processor)

Firmware 3 (ELF File disassembled as Bare Metal)

5. Can we improve the result of the last test ?

6. Epilogue

3. Missing `.slaspec` File

b. Overriding `DissectedFlow` & SLEIGH Rules (Architectural Level)

c. Modifying the Java Disassembler Engine (`Disassembler.java`)

Approach 2: Native 8051 Disassemblers (`dis51`)