gen-asm

Translate inline assembly blocks in Oberon source files

Name

gen-asm – translate inline assembly blocks in Oberon source files

Synopsis

gen-asm path [path …] [--recursive] [--dry-run] [-v]

Description

gen-asm finds (* asm ... end asm *) blocks (case-insensitive) in Oberon .mod files and generates the corresponding SYSTEM.EMIT, SYSTEM.EMITH, SYSTEM.LDREG, and SYSTEM.REG calls. Generated code is placed between (* +asm *) and (* -asm *) markers. The tool replaces the generated block on each re-run; the ASM block is the source of truth.

Both (* ASM ... END ASM *) and (* asm ... end asm *) are recognised. Generated markers are always lowercase. If SYSTEM is not in the module's IMPORT list and generated code requires it, the tool adds it automatically.

Handcrafted SYSTEM.EMIT and similar calls outside the markers are never touched.

Mnemonics, register names and system register names are case-insensitive.

Arguments

path

One or more .mod files or directories. When a directory is given, all .mod files in that directory are processed.

Options

--recursive, -r

Scan directories recursively for .mod files.

--dry-run, -n

Show which files would be updated without writing.

-v, --verbose

Print per-file status.

ASM Block Syntax

Assembly is placed in a structured comment block:

(* asm
  mrs r11, PSP -> stackframeBase
  dsb
  isb
end asm *)

Each line contains one assembly instruction. Empty lines and Oberon comments (* ... *) within the block are ignored.

Variable Binding

The -> operator connects assembly registers to Oberon variables:

Output (register to variable):

mrs r11, PSP -> stackframeBase

Generates SYSTEM.EMIT(...) followed by stackframeBase := SYSTEM.REG(11).

Input (variable to register):

ExcPrioBlock -> msr BASEPRI, r3

Generates SYSTEM.LDREG(3, ExcPrioBlock) followed by SYSTEM.EMIT(...).

Without ->, the instruction generates only the SYSTEM.EMIT or SYSTEM.EMITH call.

Generated Code Markers

(* asm
  dsb
  isb
end asm *)
(* +asm *)
SYSTEM.EMIT(0F3BF8F4FH);  (* dsb *)
SYSTEM.EMIT(0F3BF8F6FH);  (* isb *)
(* -asm *)

Everything between (* +asm *) and (* -asm *) is owned by the tool and replaced on each run. On the first run, the markers and generated code are inserted after the ASM block. Both uppercase and lowercase markers are recognised for re-run; generated markers are always lowercase.

Supported Instructions

Barriers

No operands.

Hint Instructions

No operands.

Interrupt Control

Special Register Access

Rd, Rn: r0–r15.

Supported system registers:

System register names are case-insensitive.

Branch Instructions

Stack Instructions

Supervisor Call

Security

GPR Move (for register sanitisation)

mov uses the 16-bit Thumb encoding and is limited to R0–R7. mov.w uses the 32-bit Thumb2 encoding and supports all registers. For mov.w, immediate 0 and 16-bit values (0–65535) are supported.

FPU Instructions (for register sanitisation)

Sn: s0–s31. Dd: d0–d15. Rm, Rn: r0–r15.

Use vmov Dd, Rm, Rn with both core registers zeroed to clear two single-precision registers per instruction (D0 = S0:S1, D1 = S2:S3, etc.).

Examples

Barrier sequence

(* asm
  dsb
  isb
end asm *)

Read system register with variable binding

(* asm
  mrs r11, PSP -> stackframeBase
end asm *)

Generates:

(* +asm *)
SYSTEM.EMIT(0F3EF8B09H);  (* mrs r11, PSP *)
stackframeBase := SYSTEM.REG(11);  (* r11 -> stackframeBase *)
(* -asm *)

Write system register with variable binding

(* asm
  ExcPrioBlock -> msr BASEPRI, r3
end asm *)

Generates:

(* +asm *)
SYSTEM.LDREG(3, ExcPrioBlock);  (* ExcPrioBlock -> r3 *)
SYSTEM.EMIT(0F3838811H);  (* msr BASEPRI, r3 *)
(* -asm *)

BASEPRI critical section

(* asm
  mrs r7, BASEPRI -> saved
  ExcPrioBlock -> msr BASEPRI, r3
end asm *)
(* critical section body *)
(* asm
  saved -> msr BASEPRI, r7
end asm *)

Secure procedure epilogue

(* asm
  add sp, #20
  pop.w {LR}
  bxns lr
end asm *)

GPR and FPU sanitisation (before BLXNS)

(* asm
  mov r0, #0
  mov r1, #0
  mov r2, #0
  mov r3, #0
  mov r4, #0
  mov r5, #0
  mov r6, #0
  mov r7, #0
  mov.w r8, #0
  mov.w r9, #0
  mov.w r10, #0
  mov.w r12, #0
  msr APSR_nzcvq, r0
  vmov d0, r0, r0
  vmov d1, r0, r0
  vmov d2, r0, r0
  vmov d3, r0, r0
  vmov d4, r0, r0
  vmov d5, r0, r0
  vmov d6, r0, r0
  vmov d7, r0, r0
  vmov d8, r0, r0
  vmov d9, r0, r0
  vmov d10, r0, r0
  vmov d11, r0, r0
  vmov d12, r0, r0
  vmov d13, r0, r0
  vmov d14, r0, r0
  vmov d15, r0, r0
  vmsr FPSCR, r0
end asm *)

Process a directory

python gen-asm.py config/

Recursive processing with dry run

python gen-asm.py --recursive lib/v3.1/ --dry-run

Target Compatibility

The supported instructions use Thumb and Thumb-2 encodings common to all ARM Cortex-M processors. The tool does not check the target – it encodes whatever the programmer writes. Most instructions (barriers, hints, interrupt control, mrs/msr with common registers, bx, stack ops, mov) work across the Cortex-M family, including Cortex-M0/M0+ (RP2040) and Cortex-M33 (RP2350, STM32).

Some instructions and registers are specific to Cortex-M33 (Armv8-M):

• Security Extension instructions: bxns, blxns, tt
• Security Extension registers: MSP_NS, PSP_NS, MSPLIM, PSPLIM, CONTROL_NS, SP_NS
• BASEPRI and FAULTMASK (Armv7-M and Armv8-M, not Armv6-M)
• MSPLIM, PSPLIM (Armv8-M only)

Using a target-specific instruction on the wrong processor will produce a valid encoding but fault at runtime.

Limitations

• This is not a general ARM assembler. Only the instruction subset listed above is supported.
• The programmer is responsible for register selection and target compatibility. The tool does not interact with the compiler's register allocator and does not check the target architecture.
• Instructions are emitted in source order. No reordering or optimisation.

See Also

• sec-epilogue – insert Secure return epilogues
• gen-secure – generate NSC veneers and NS interface modules

Last updated: 16 March 2026