OsmocomBB

h1. The Compal RAM Loader

{{>toc}}

The Compal RAMLoader is part of the original vendor firmware and what is executed first when a Compal phone like the [[MotorolaC123]] boots. In the [[OsmocomBB]] project we only use this loader as it is stored in the original flash. We have implemented a host PC program called [[osmocon]] that can talk to this Compal RAM loader.

It is flashed to the first block[s] of the NOR flash, which in turn is mapped to address 0x0000'0000.

The tasks of the RAMLoader are as follows:

* Initialize the minimally necessary hardware (PLL, clock, GPIO, UART, ...)

* Check if a program on a PC is interested in downloading code into the phone:

** if yes, actually perform the serial download into RAM and execute that code

** if no, continue booting the firmware stored in the NOR flash

In both cases, no signature verification is performed (no secure boot)!

h2. Download Protocol

The download protocol is relatively simple, although device-specific quirks complicate it:

h3. Negotiating the existance of a PC download software

* The phone sends the PROMPT1 message (0x1b, 0xf6, 0x02, 0x00, 0x41, 0x01, 0x40)

* The PC responds with DNLOAD_CMD messge (0x1b, 0xf6, 0x02, 0x00, 0x52, 0x01, 0x53)

* The phone responds with the PROMPT2 message (0x1b, 0xf6, 0x02, 0x00, 0x41, 0x02, 0x43)

h3. Actual download of the executable code

* The PC downloads the software

** Optionally (C155) by starting with the byte 0x02 (the XOR initialization value)

** Sending two bytes length, containing the length of the code to be downloaded

** Sending the actual download data

** Sending a single byte containing the XOR sum of all characters sent, including the length bytes

* The phone responds with a DNLOAD_ACK message (0x1b, 0xf6, 0x02, 0x00, 0x41, 0x03, 0x42)

h4. Error cases

If something goes wrong, you will get

* DNLOAD_NACK (0x1b, 0xf6, 0x02, 0x00, 0x45, 0x53, 0x16)

* DNLOAD_NACK_MAGIC (0x1b, 0xf6, 0x02, 0x00, 0x41, 0x03, 0x57)

h2. Execution Environment

All the downloaded data (excluding the length bytes) is stored at the base address 0x0080'0100.

*However, since there is a 4byte header prepended by compal_dnload, use 0x0080'0104 as linker base address!*

The RAM loader already initializes the stack pointer.  It points to a 1020 bytes large location in memory.

On the C118, C121, C123 and C140, the CPU runs in ARM mode when jumping to the base address.

On the C155, the CPU runs in THUMB mode when jumping to the base address.  This is why the ramloader

automatically prefixes your payload with a 4-byte header that switches to ARM mode.

h2. Restrictions

* Since the length field is only 16 bits, you cannot download more than 64kBytes of code

* Since the exception vectors point to NOR flash, you cannot use Interrupts from your RAM-loaded code