HACKING.rst 63.2 KB
Newer Older
1
2
3
EOS firmware in QEMU - development and reverse engineering guide
================================================================

4
5
6
For "user" documentation and installation guide, please see the main `README.rst <README.rst>`_.

-----------
7
8
9
10

This is bleeding-edge development used primarily for reverse engineering.
You will want to modify the sources, sooner or later.

11
12
.. contents::

13
14
How is this code organazized?
`````````````````````````````
15

16
17
By default, the install script sets up QEMU by creating a ``qemu-eos`` subdirectory
"near" the ``magic-lantern`` directory (so both directories will end up at the same level).
18
19
20
21
22
23
24
25
26
27
28
29
30
The default directory structure looks like this::

  .
  ├── magic-lantern/            # Magic Lantern working directory
  │   │
  │   ├── src/                      # main ML source files
  │   │
  │   ├── platform/                 # camera-specific (platform) directories
  │   │   ├── 5D3.113                   # camera model . firmware version
  │   │   ├── EOSM.202                  # here you would run "make", "make install_qemu" etc
  │   │   └── ...
  │   │
  │   ├── minimal/                  # minimal targets, for experiments
31
32
  │   │   ├── hello-world           # these will use other files from the platform directory
  │   │   ├── qemu-frsp             # compile with "make MODEL=EOSM" or "make MODEL=5D3 FW_VERSION=123"
33
34
35
36
37
  │   │   └── ...
  │   │
  │   ├── installer/                # for building ML-SETUP.FIR (which enables/disables the boot flag)
  │   └── ...

38
  └── qemu-eos/                 # QEMU working directory
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

      ├── qemu-2.5.0/               # QEMU sources and binaries

      ├── 60D/                      # camera-specific subdirectories
      │   ├── ROM*.BIN                  # ROM files (user-supplied)
      │   └── debugmsg.gdb              # GDB script
      ├── EOSM2/
      │   ├── ROM*.BIN                  # ROM files (user-supplied)
      │   ├── SFDATA.BIN                # serial flash contents (recent models use one)
      │   ├── patches.gdb               # patches required for emulation (for tricky models)
      │   └── debugmsg.gdb              # GDB script
      ├── 5D3/
      │   ├── 113/                      # firmware-specific files
      │   │   └── ROM*.BIN              # ROM files (user-supplied)
      │   ├── 123/
      │   │   └── ROM*.BIN              # ROM files (user-supplied)
      │   └── debugmsg.gdb              # GDB script (common)

      ├── ...
      ├── tests/                    # our test suite
      │   ├── 60D/                      # model-specific test files
      │   └── ...                       # (expected and actual results)

      ├── run_canon_fw.sh           # main script for running the emulation
      └── ...                       # other scripts / utilities

The sources are stored in the Magic Lantern tree, under ``contrib/qemu``. Our modifications to QEMU sources
66
are stored as a patch file (``qemu-2.5.0-eos.patch``), while the new files are stored directly. The install script
67
68
copies the following files:

69
70
.. code:: shell

71
72
73
74
75
76
77
78
  magic-lantern/contrib/qemu/eos/ -> qemu-eos/qemu-2.5.0/hw/eos/  (emulation sources)
  magic-lantern/contrib/qemu/eos/mpu_spells/ -> qemu-eos/qemu-2.5.0/hw/eos/mpu_spells/  (MPU messages, button codes)
  magic-lantern/contrib/qemu/eos/dbi/ -> qemu-eos/qemu-2.5.0/hw/eos/dbi/ (instrumentation)
  magic-lantern/src/backtrace.[ch] -> qemu-eos/qemu-2.5.0/hw/eos/dbi/backtrace.[ch] (shared with ML)
  magic-lantern/contrib/qemu/scripts/ -> qemu-eos/ (helper scripts, such as run_canon_fw.sh)
  magic-lantern/contrib/qemu/scripts/*/debugmsg.gdb -> qemu-eos/*/debugmsg.gdb (GDB scripts for reverse engineering)
  magic-lantern/contrib/qemu/scripts/*/patches.gdb -> qemu-eos/*/patches.gdb (patches required for emulation — only on some models)
  magic-lantern/contrib/qemu/tests -> qemu-eos/tests (guess)
79

80
Customizing directories
81
'''''''''''''''''''''''
82

83
Once QEMU is compiled into some subdirectory (such as ``/path/to/qemu-eos/qemu-2.5.0/``),
84
85
86
87
88
it will no longer work elsewhere (you will not be able to rename/move this directory
without a full reconfiguration and recompilation).

Should you want to customize these paths, you may set the following environment variables:

89
90
91
- ``QEMU_DIR``: defaults to ``qemu-eos`` (QEMU working directory, created near ``magic-lantern``)
- ``QEMU_NAME``: defaults to ``qemu-2.5.0`` (a subdirectory under your ``qemu-eos`` directory)
- ``ML_PATH``: defaults to ``../magic-lantern``, relative to your ``qemu`` directory.
92
93
94

Tip: after installation, you may change ``ML_PATH`` to emulate ML from other directories, located anywhere in the filesystem.

95
96
When using ``make install_qemu``, the Makefiles will also find the QEMU working directory from ``QEMU_DIR``.

97
98
Basic concepts
``````````````
99

100
Some parts were adapted from `Jake Sandler's excellent operating system tutorial for Raspberry Pi <https://jsandler18.github.io>`_.
101

102
103
Memory-mapped I/O, peripherals and registers
''''''''''''''''''''''''''''''''''''''''''''
104

105
Adapted from https://jsandler18.github.io/extra/peripheral.html
106

107
**Memory-mapped I/O** or **MMIO** is a way of interacting with hardware devices
108
by reading from and writing to predefined memory addresses.
109
All interactions with the DIGIC hardware happen using MMIO.
110

111
112
.. _peripheral:

113
114
115
116
A **Peripheral** is a `hardware device <https://barrgroup.com/Embedded-Systems/Books/Programming-Embedded-Systems/Peripherals-Device-Drivers>`_
used in embedded systems, in addition to processor and memory. Some peripherals, such as timers or interrupt controller,
are often included in the same chip as the processor; others, such as the real-time clock or LCD controller, are usually external.
The firmware interacts with peripherals through specific MMIO address(es) in the memory space.
117

118
Each peripheral has a (hardcoded) range of memory addresses. On Canon hardware, this region is generally located
119
120
somewhere within ``0xC0000000 - 0xDFFFFFFF`` (with variations: ``C0000000 - CFFFFFFF``, ``C0000000 - C0FFFFFF`` and so on).

121
A **Register** is a 32-bit wide (4-byte) location in some peripheral's address range, used to control that peripheral.
122
These registers are at predefined offsets from the peripheral’s base address.
123
It is quite common for at least one register to be a control register,
124
125
126
127
128
129
where each bit in the register corresponds to a certain behavior that the hardware should have.
Another common register is a write register, where anything written in it gets sent off to the hardware.
Some peripherals also have a status register (which may be either read-only or shared with a control register).

For example, there are 8 DMA channels placed at ``0xC0A10000-0xC0A100FF``,
``0xC0A20000-0xC0A200FF``, ..., ``0xC0A80000-0xC0A800FF``. All these DMA channels
130
share the same behavior; moreover, they are controlled by registers located in the above ranges.
131
132
133
134
135
136
137
138
139
140
For example, at offset ``0x08`` you will find the control register (``0xC0A10008``, ``0xC0A20008``, ..., ``0xC0A80008``),
offset ``0x18`` is the source address, ``0x1C`` is the destination address
and offset ``0x20`` is the transfer size (see ``eos_handle_dma`` in ``eos.c``).

Figuring out where all the peripherals are, what registers they have
and how to use them, is difficult — there's no documentation on DIGIC hardware.
One may start analyzing Canon code that uses these peripherals (what values are written to them,
what values are expected to be read, what the hardware is supposed to do with them)
and by `cross-checking the register values with those obtained on physical hardware`__ (by logging what Canon code does).
Generally, the behavior of these peripherals is common across many camera models; very often,
alex@thinkpad's avatar
alex@thinkpad committed
141
compatibility is maintained across many generations of the hardware. For example, a 20-bit microsecond timer
142
("DIGIC timer") can be read from register ``0xC0242014`` on all EOS and PowerShot models from DIGIC 2 to DIGIC 5.
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185

__ `Cross-checking the emulation with actual hardware`_

See `Working out all the way to Canon GUI`_ for some examples of figuring out what certain peripherals are supposed to do.

Hardware interfaces are generally compatible between EOS and PowerShot models. For example,
EDMAC (image processing DMA) works the same at hardware level on both EOS and PowerShot
(therefore, the same emulation code can be reused for both platforms);
however, the front-end functions used in the firmware are different
(that makes porting CHDK on EOS models or Magic Lantern on PowerShot models a non-trivial task).

Documentation for certain off-the-shelf peripherals (such as RTC, audio chip, serial flash)
is available (`Datasheets <http://magiclantern.wikia.com/wiki/Datasheets>`_,
`Circuit boards <http://magiclantern.wikia.com/wiki/Circuit_boards>`_ and `photo-parts.ua <https://photo-parts.com.ua/parts/?part=550D>`_).
For this purpose, high-resolution pictures of (your) camera mainboards are always welcome.

MMIO register activity can be logged by running the emulation with ``-d io``.

What we know about these registers can be found in emulator sources, starting at the ``eos_handlers`` table,
and on the `Register Map <http://magiclantern.wikia.com/wiki/Register_Map>`_ wiki page.

Interrupts and exceptions
'''''''''''''''''''''''''

Adapted from https://jsandler18.github.io/extra/interrupts.html

An **Exception** is an event that is triggered when something exceptional occurs
during normal program execution. Examples of such exceptional occurrences include hardware devices
presenting new data to the CPU, user code asking to perform a privileged action, and a bad instruction
was encountered.

On ARM processors, when an exception occurs, a specific address is loaded into the program counter register,
branching execution to this point. At this location, the firmware contains branch instructions
to routines that handle the exceptions. This set of addresses, also known as the Vector Table,
usually starts at address 0 (in RAM) or 0xFFFF0000 (configuration known as `HIVECS <https://developer.arm.com/docs/ddi0363/e/programmers-model/exceptions/exception-vectors>`_), but on recent models
it can be located anywhere in the system memory.

Below is a table that describes the exceptions interesting to us:

========  ============================  ===========================================================
Offset    Exception name                What happened
========  ============================  ===========================================================
0x00      Reset                         Execution starts here at power on (see `Initial firmware analysis`_)
alex@thinkpad's avatar
alex@thinkpad committed
186
0x04      Undefined Instruction         Attempted to execute an invalid instruction
187
188
189
190
191
192
193
194
195
196
197
0x0C      Prefetch Abort                Attempted to read an instruction from non-executable memory
0x10      Data Abort                    Attempted to read data from a privileged memory region
**0x18**  **Interrupt Request (IRQ)**   Hardware wants to make the CPU aware of something
0x1C      Fast Interrupt Request (FIQ)  One select hardware can do the above faster than all others
========  ============================  ===========================================================


An **Interrupt Request** or **IRQ** is a notification to the processor
that something happened to some hardware that the processor should know about.
This can take many forms, for example, a character was received on the serial line
or a file I/O transfer was completed. The operating system (DryOS, VxWorks) uses a periodic timer interrupt
198
199
(`heartbeat <https://sites.google.com/site/rtosmifmim/home/timer-functions>`_) that usually fires every 10ms;
many other peripherals use interrupts to signal various events.
200

201
In order to find out which hardware devices are allowed to trigger interrupts,
alex@thinkpad's avatar
alex@thinkpad committed
202
and which device triggered an interrupt, we need to look at the interrupt controller
203
(``eos_handle_intengine``, which comes in many shapes and sizes, depending on camera generation).
204
205

For emulation purposes, we need to know when the firmware expects an interrupt for each peripheral
206
207
(for example, after completing a DMA transfer, or when a timer overflows, or when a `secondary CPU`__ wants to talk, and so on)
and how to react to MMIO activity from the interrupt handling routine
208
209
(for example, the firmware may check the status of the peripheral to figure out why the interrupt was triggered, or what to do next).

210
211
__ `Secondary processors`_

212
213
214
215
216
217
218
219
220
221
222
223
Interrupt activity can be logged by running the emulation with ``-d int``.
When troubleshooting interrupt issues, you will also want to log MMIO activity,
as well as some additional messages that are hidden by default: ``-d io,int,v``.

The interrupt IDs are mostly common across EOS models, but there are exceptions.
Model-specific interrupts can be found in ``model_list.c``, while generic ones
are hardcoded throughout the source.

A good janitor project would be to `document all the registers, interrupts and other model-specific constants
<http://www.magiclantern.fm/forum/index.php?topic=14656.0>`_,
in a way that's easy to read, reuse and doesn't go out of sync with the source code.

224
225
226
227
GPIO ports
''''''''''

These work much like the I/O ports on a Raspberry Pi or Arduino —
g3gg0's avatar
g3gg0 committed
228
229
signal lines that you can switch high or low from software (outputs)
or whose input state (high or low) can be read by the processor (inputs).
230
231
232

__ `WriteProtect switch`_

g3gg0's avatar
g3gg0 committed
233
234
Example: the SD card LED is driven by a GPIO output (by setting specific bits within the GPIO's register).
The `write-protect switch`__ state is read from a GPIO input (by reading back other bits).
235
236
237
238
239
240
241
Events from `hot-pluggable devices`__ (USB, external monitors, microphone etc) are usually detected
by reading some GPIO registers in a loop (but they may as well expect interrupts, e.g. ``MICDetectISR``).

__ `HotPlug events`_

GPIO ports are also used as `chip select <https://en.wikipedia.org/wiki/Chip_select>`_ signals
for various hardware devices that use the SPI protocol (examples below),
g3gg0's avatar
g3gg0 committed
242
or as signalling lines to `secondary processors`_ for communication purposes.
243
244
245
246

Usual register values for driving GPIO ports: ``0x46/0x44``, ``0x138800/0x838C00``, ``0xD0002/0xC0003``.
More details `on the wiki <http://magiclantern.wikia.com/wiki/Register_Map#GPIO_Ports>`_.

247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
Serial communication
''''''''''''''''''''

Some peripherals use the well-known
`I2C and SPI <https://www.byteparadigm.com/applications/introduction-to-i2c-and-spi-protocols/>`_ interfaces.
While their low-level communication uses MMIO registers and (sometimes) interrupts, one has to understand
the high-level protocol in order to emulate — or interact with — these peripherals.

Examples:

- `RTC chip <http://www.magiclantern.fm/forum/index.php?topic=2864.msg190823#msg190823>`_ (real-time clock)
- `ADTG and CMOS registers <http://magiclantern.wikia.com/wiki/ADTG>`_ (image capture hardware)
- `TFT SIO registers <http://www.magiclantern.fm/forum/index.php?topic=21108>`_ (built-in LCD controller)
- `HDMI CEC <http://www.magiclantern.fm/forum/index.php?topic=12022.msg136689#msg136689>`_ (Ctrl over HDMI)
- `Touch screen controller <http://www.magiclantern.fm/forum/index.php?topic=15895.msg187011#msg187011>`_
- `MPU communication`_ (see below).

Secondary processors
''''''''''''''''''''

alex@thinkpad's avatar
alex@thinkpad committed
267
Canon cameras are generally multiprocessor systems. Since our understanding of all these processors
268
269
270
271
272
273
274
275
276
277
278
279
280
281
is quite limited, we attempt to emulate only one of them at a time (at least for the time being)
and model the secondary processors as regular `peripherals`__.

__ `peripheral`_

Common secondary processors:

- the `MPU`__ (I/O microcontroller on EOS models, `TX19A <http://magiclantern.wikia.com/wiki/Tx19a>`_ on DIGIC 4)
- the `Eeko <http://www.magiclantern.fm/forum/index.php?topic=13408.msg175656#msg175656>`_ (on DIGIC 5, emulated as ``5D3eeko``)
  and `Omar <http://www.magiclantern.fm/forum/index.php?topic=13408.msg194424#msg194424>`_ (on DIGIC 6)
  cores likely used for image processing
- the `JPCORE <http://www.magiclantern.fm/forum/index.php?topic=18443.msg177082#msg177082>`_ (JPEG/LJ92 and H.264 encoders, likely CPU-based)
- the AE processor on 5D Mark IV (``K349AE``, emulated as ``5D4AE``)
- the secondary ARM core on 7D (``K250M``, emulated as ``7DM``), 7D Mark II (``K289S``, emulated as ``7D2S``) and other Dual DIGIC models
alex@thinkpad's avatar
alex@thinkpad committed
282
- the `Zico <http://chdk.setepontos.com/index.php?topic=11316.msg129104#msg129104>`_ 
283
284
285
286
  `GPU <http://chdk.setepontos.com/index.php?topic=12788.0>`_ on DIGIC 6 and 7 models (Xtensa)
- the `lens MCU <http://www.magiclantern.fm/forum/index.php?topic=20969>`_ (firmware upgradeable on recent models).

__ `MPU communication`_
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302


Adding support for a new camera model
`````````````````````````````````````

Initial firmware analysis
'''''''''''''''''''''''''

1) Find the ROM load address and the code start address.
   If unknown, use an initial guess to disassemble (even 0),
   then look for code jumping to or referencing some absolute address
   and make an educated guess from there.

   DIGIC 5 and earlier models will start the bootloader at ``0xFFFF0000`` (HIVECS)
   and will jump to main firmware at ``0xFF810000``, ``0xFF010000`` or ``0xFF0C0000``.
   There is one main ROM (ROM1) at ``0xF8000000``, 4/8/16/32 MiB mirrored until ``0xFFFFFFFF``,
303
304
   and there may be a second ROM (ROM0) at ``0xF0000000``, mirrored until ``0xF8000000 - 1 = 0xF7FFFFFF``.
   Some DIGIC 5 models also use a serial flash for storing properties (persistent settings).
305

306
   DIGIC 6 models will start at ``*(uint32_t*)0xFC000000``,
307
308
   bootloader is at 0xFE020000 and main firmware starts at 0xFE0A0000. There is
   a 32 MiB ROM mirrored at 0xFC000000 and 0xFE000000 (there may be others).
309
310
311
312
313
314
315
   There is a serial flash as well, used for storing properties.

   DIGIC 7 models will start at ``0xE0000000`` in ARM mode
   and will jump to main firmware at ``0xE0040000`` in Thumb mode.
   There is a 32 MiB ROM (ROM0) at ``0xE0000000``, mirrored until ``0xEFFFFFFF``,
   and an unusually slow 16 MiB ROM (ROM1) at ``0xF0000000``, mirrored until ``0xFFFFFFFF``.
   No serial flash was identified.
316
317
318
319
320
321
322
323
324
325

   The ROM load address is the one you have used when dumping it (usually one of the mirrors).
   The memory map is printed when starting QEMU — you'll see where each ROM is loaded
   and where are the mirrored copies, if any.

   The MPU/MMU configuration (printed in QEMU as soon as the guest code
   changes the relevant registers) is very useful for finding the memory map
   on new models -- see the ARM Architecture Reference Manual (aka ARM ARM)
   for the CPU you are interested in:

alex@thinkpad's avatar
alex@thinkpad committed
326
   - DIGIC 2..5: ARM946E-S `[1] <http://chdk.setepontos.com/index.php?topic=9801.msg99865#msg99865>`_ -- `arm_arm.pdf <https://www.cs.miami.edu/home/burt/learning/Csc521.141/Documents/arm_arm.pdf>`_;
327
328
329
   - DIGIC 6: Cortex R4 `[2] <http://chdk.setepontos.com/index.php?topic=11316.msg124273#msg124273>`_ -- `ARM ARM v7 A&R <https://www.cs.utexas.edu/~simon/378/resources/ARMv7-AR_TRM.pdf>`_ and `Cortex R4 TRM <http://infocenter.arm.com/help/topic/com.arm.doc.ddi0363g/DDI0363G_cortex_r4_r1p4_trm.pdf>`_;
   - DIGIC 7: Cortex A9 `[3] <http://chdk.setepontos.com/index.php?topic=13014.msg131110#msg131110>`_ -- `ARM ARM v7 A&R <https://www.cs.utexas.edu/~simon/378/resources/ARMv7-AR_TRM.pdf>`_ and `Cortex A9 TRM <http://infocenter.arm.com/help/topic/com.arm.doc.ddi0388f/DDI0388F_cortex_a9_r2p2_trm.pdf>`_.

alex@thinkpad's avatar
alex@thinkpad committed
330
331
   |

332
333
334
335
336
337
338
339
340
341
342
343
2) (Re)load the code in the disassembler at the correct address:

   - `Loading into IDA <http://www.magiclantern.fm/forum/index.php?topic=6785.0>`_
   - `Tutorial: finding stubs (with disassemble.pl) <http://www.magiclantern.fm/forum/index.php?topic=12177.0>`_
   - `Loading into ARMu <http://www.magiclantern.fm/forum/index.php?topic=9827.0>`_
   - Other disassemblers will also work (the list is open).

   |

3) Add a very simple definition for your camera and get an `initial test run`_.
   Try to guess some missing bits from the error messages, if possible.

344
4) Code blocks copied from ROM to RAM
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365

   .. code:: shell
  
     ./run_canon_fw.sh EOSM2,firmware="boot=0" -d romcpy |& grep ROMCPY
    [ROMCPY] 0xFFFF0000 -> 0x0        size 0x40       at 0xFFFF0980
    [ROMCPY] 0xFFFE0000 -> 0x100000   size 0xFF2C     at 0xFFFF0FCC
    [ROMCPY] 0xFFD1F0E4 -> 0x1900     size 0xB70A0    at 0xFF0C000C
    [ROMCPY] 0xFF0C0E04 -> 0x4B0      size 0x1E8      at 0xFF0C0D70

   You may extract these blobs with e.g.:

   .. code:: shell

     dd if=ROM1.BIN of=EOSM2.0x1900.BIN bs=1 skip=$((0xD1F0E4)) count=$((0xB70A0))

   If you are analyzing the main firmware, load ``EOSM2.0x1900.BIN`` as an additional binary file
   (in IDA, choose segment 0, offset 0x1900). Do the same for the blob copied at 0x4B0.

   If you are analyzing the bootloader, extract and load the first two blobs in the same way.
   Other models may have slightly different configurations, so YMMV.

366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
5) Export the functions called during your test run:

   .. code:: shell

     ./run_canon_fw.sh EOSM2,firmware="boot=0" -d idc
     ...
     EOSM2.idc saved.

   Load the IDC script into IDA, or convert it if you are using a different disassembler.

   Locate ``task_create``, ``register_func``, ``register_interrupt`` and ``CreateStateObject``
   and add GDB stubs for them in ``CAM/debugmsg.gdb``. Run the firmware under GDB
   to identify some (thousands of) named functions.

   .. code:: shell

     ./run_canon_fw.sh EOSM2,firmware="boot=0" -d debugmsg -s -S & arm-none-eabi-gdb -x EOSM2/debugmsg.gdb
     ...
     named_functions.idc saved.

   Load the new IDC script into IDA and start hacking!

   Repeat this procedure as the emulation is getting better, to identify new functions.

390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
   |

Initial test run
''''''''''''''''

Start by editing ``hw/eos/model_list.c``, where you'll need to add an entry
for your camera model. The simplest one would be:

.. code:: C

    {
        .name                   = "5DS",
        .digic_version          = 6,
    },

Then, run it and follow the errors:

.. code:: shell

  ./run_canon_fw.sh 5DS
  ...
  BooMEMIF NG MR05=00000000 FROM=00000001
  BTCM Start Master

What's that? Looks like some sort of error message, and indeed, it is.
In Canon parlance, NG means "not good" — see for example ``NG AllocateMemory``
on the "out of memory" code path. Let's check whether this error message has to do
with I/O activity (usually that's where most emulation issues come from):

.. code:: shell

  ./run_canon_fw.sh 5DS -d io
  ...
  [DIGIC6]   at 0xFE020CD0:FE020B5C [0xD203040C] <- 0x500     : MR (RAM manufacturer ID)
  [DIGIC6]   at 0xFE020CDC:FE020B5C [0xD203040C] <- 0x20500   : MR (RAM manufacturer ID)
  [DIGIC6]   at 0xFE020CE4:FE020B5C [0xD203040C] -> 0x0       : MR (RAM manufacturer ID)
  MEMIF NG MR05=00000000 FROM=00000001
  BTCM Start Master

OK, so the message appears to be related to these I/O registers.
Look up the code that's handling them (search for "RAM manufacturer ID").
You'll find it in eos.c:eos_handle_digic6, at the register 0xD203040C
(as expected), and you'll find it uses a model-specific constant:
``s->model->ram_manufacturer_id``. Let's look around to see what's up with it:

.. code:: C

  .name                   = "80D",
  .ram_manufacturer_id    = 0x18000103,   /* RAM manufacturer: Micron */

  .name                   = "750D",
  .ram_manufacturer_id    = 0x14000203,

  .name                   = "5D4",
  .ram_manufacturer_id    = 0x18000401,

Good — it's now clear you'll have to find this constant. You have many choices here:

- disassemble the ROM near the affected address,
  and try to understand what value Canon code expects from this register
- use pattern matching and find it based on a similar camera model
- try the values from another camera model, hoping for the best
- trial and error

Let's go for the last one (probably the easiest). If you look at the code,
you may notice the "5" corresponds to the least significant byte in this RAM ID.
If you didn't, don't worry — you can just try something like 0x12345678:

.. code:: C

    {
        .name                   = "5DS",
        .digic_version          = 6,
        .ram_manufacturer_id    = 0x12345678,
    },

and the new error message will tell you the answer right away::

  MEMIF NG MR05=00000078 FROM=00000001

You now have at most 4 test runs to find this code :)

A more complete example: the `EOS M2 walkthrough <http://www.magiclantern.fm/forum/index.php?topic=15895.msg185103#msg185103>`_
shows how to add support for this camera from scratch, right through to getting the Canon GUI to boot (and more!)

Although this model is already supported in the repository,
you can always roll back to an older changeset (``3124887``) and follow the tutorial.

Working out all the way to Canon GUI
````````````````````````````````````

This might be a short journey (such as finding a typo or tweaking some MMIO register), or a long one (lots of things to adjust).
It's hard to tell in advance how much work it's going to be (each camera model has its own quirks),
but here's a short overview of Canon EOS boot process.

Overview of Canon EOS boot process
''''''''''''''''''''''''''''''''''

There are at least two (different) code blobs in Canon firmware:
the bootloader (what runs at power on) and the main firmware.
Generally, you cannot call bootloader functions from main firmware, or viceversa
(except maybe for trivial functions that do not use any global variables).

The start addresses for bootloader and main firmware can be found at
`Initial firmware analysis`_.

The bootloader has the following functionality:

- initialize the RAM configuration (memory protection regions, cache setup etc)
- jump to main firmware if everything is alright
- load AUTOEXEC.BIN or firmware updates, if the boot flags are configured for this
- fallback to factory menus if the hardware or the main firmware are somehow out of order
- handshaking with other CPU cores, if any.

Note: the EOS M5 has `two bootloaders <http://chdk.setepontos.com/index.php?topic=13014.msg131205#msg131205>`_, one of them running DryOS!

Getting the bootloader to run
'''''''''''''''''''''''''''''

There are two major goals here:

- launch the main firmware
- initialize the SD or CF card to load ``AUTOEXEC.BIN``.

The first goal is a lot easier, so let's start with that. What can go wrong?

- bootloader gets stuck in a loop somewhere
- bootloader executes some factory tool

Both of these are likely affected by some MMIO register. Run the emulation with ``-d io``
and try to figure out what registers might change the code paths taken by the bootloader.

Easiest case: code gets stuck reading some MMIO register. Solutions:

- look in the disassembly at the code where the register is read, and figure out what value it expects
- try random values (it may even work for simple handshakes)

Example for 5D3: comment out register ``0xC0400204`` (``case 0x204`` under ``C0400000``,
528
introduced in `b79cd7a <https://foss.heptapod.net/magic-lantern/magic-lantern/-/commit/e40aeb41b3846aa30ea94b44ab49aeab9a4f19a5>`_)
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
and run with ``-d io``::

  [BASIC]    at 0xFFFF066C:00000000 [0xC0400204] -> 0x0       : ???
  (infinite loop repeating the same message over and over)

Just for kicks, let's see what happens if we return random values::

  ./run_canon_fw.sh 5D3,firmware="boot=0" -d io |& grep 0xC0400204
  [BASIC]    at 0xFFFF0554:00000000 [0xC0400204] -> 0x9474BA98: ???
  [BASIC]    at 0xFFFF066C:00000000 [0xC0400204] -> 0xCD84DC39: ???
  [BASIC]    at 0xFFFF066C:00000000 [0xC0400204] -> 0x9BC36796: ???

As soon as the random value matches what the firmware expects, emulation continues. In our case, the test was::

  FFFF066C   LDR R1, [R0]
  FFFF0670   AND R1, R1, #2
  FFFF0674   CMP R1, #2

Easy, right?

Harder case: the value of some MMIO register steers the code on a path you don't want.

551
Example for 1300D, before changeset `cbf042b <https://foss.heptapod.net/magic-lantern/magic-lantern/-/commit/57fb8141f01065195279fabbc5704855b10ba3f1>`_
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
(to try this, manually undo the linked change):

After adding the basic definition, the bootloader shows a factory menu, rather than jumping to main firmware.

.. code:: C

    {
        .name                   = "1300D",
        .digic_version          = 4,
        .rom0_size              = 0x02000000,
        .rom1_size              = 0x02000000,
        .firmware_start         = 0xFF0C0000,
    },

It does not get stuck anywhere, the factory menu works (you can navigate it on the serial console), so what's going on?

Run the emulation with ``-d io``, look at all MMIO register reads (any of these might steer the program on a different path)
and analyze the disassembly where these registers are read.

.. code:: shell

  ./run_canon_fw.sh 1300D -d io
  ...
  [*unk*]    at 0xFFFF066C:FFFF00C4 [0xC0300000] -> 0x0       : ???
  [*unk*]    at 0xFFFF0680:FFFF00C4 [0xC0300000] <- 0x1550    : ???
  [*unk*]    at 0xFFFF068C:FFFF00C4 [0xC0300208] <- 0x1       : ???
  [GPIO]     at 0xFFFF0694:FFFF00C4 [0xC022F48C] -> 0x10C     : 70D/6D SD detect?
  [FlashIF]  at 0x00000108:FFFF00C4 [0xC00000D0] -> 0x0       : ???
  [FlashIF]  at 0x00000114:FFFF00C4 [0xC00000D0] <- 0xE0000   : ???
  [FlashIF]  at 0x0000011C:FFFF00C4 [0xC00000D8] <- 0x0       : ???
  [GPIO]     at 0x00000128:FFFF00C4 [0xC022F4D0] <- 0x3000    : ???
  [FlashIF]  at 0x0000012C:FFFF00C4 [0xC00000D0] -> 0x0       : ???
  [FlashIF]  at 0x00000130:FFFF00C4 [0xC00000D0] -> 0x0       : ???
  [FlashIF]  at 0x00000134:FFFF00C4 [0xC00000D0] -> 0x0       : ???
  System & Display Check & Adjustment program has started.

If the number of registers is small, consider trial and error, or some sort of brute-forcing.
For more complex cases, look into advanced RE tools that use SMT solvers or similar black magic,
or try to understand what the code does (and how to get it back on track).

In this particular case, it's easy to guess
(exercise: give it a try, pretending you haven't already seen the solution).

In a few cases, the bootloader may use interrupts as well
(for example, 7D uses interrupts for IPC — communication between the two DIGIC cores).
To analyze them, place a breakpoint at 0x18 and see what happens from there.

The second goal — loading ``AUTOEXEC.BIN`` from the card — requires emulation of the SD or CF card.
alex@thinkpad's avatar
alex@thinkpad committed
600
If it doesn't already work, look at MMIO activity (``-d io,sdcf``) and try to make sense of the SD or CF
601
602
initialization sequences (both protocols are documented online). The emulation has to be able
to read arbitrary sectors from the virtual card — once you provide the low-level block transfer
alex@thinkpad's avatar
alex@thinkpad committed
603
functionality, Canon firmware would be able to handle the rest (filesystem drivers etc).
604
605
606
607
608
609
610
611
612
In other words, you shouldn't have to adjust anything in order to emulate EXFAT, for example.

Getting the main firmware to run
''''''''''''''''''''''''''''''''

Step by step:

- get debug messages

alex@thinkpad's avatar
alex@thinkpad committed
613
  - identify DebugMsg (lots of calls, format string is third argument), add the stub to ``CAM/debugmsg.gdb``, run with ``-d debugmsg``
614
615
616
617
618
619
620
621
622
623
624
625
  - identify other functions used to print errors (uart_printf, variants of DebugMsg with format string at second argument etc — look for strings)
  - identify any other strings that might be helpful (tip: run with ``-d calls`` and look for something that makes even a tiny bit of sense)
  
  |

- make sure DryOS timer (heartbeat) runs (**important!**):

  - look for MMIO activity that might set up a timer at 10ms or nearby
  - figure out what interrupt is expects (run with ``-d io,int,v`` and look for "Enabled interrupt XXh", usually right before the timer configuration)
  - make sure you get periodical interrupts when running with ``-d io,int``, even when all DryOS tasks are idle

  Example: 1300D (comment out ``dryos_timer_id`` and ``dryos_timer_interrupt`` from the 1300D section
626
  in ``model_list.c`` to get the state before `7f1a436 <https://foss.heptapod.net/magic-lantern/magic-lantern/-/commit/7d7c4247e2752c603e945b1f39498194f7cc14c7#ab988524dbc98fad520db2edfb579770144b8234>`_)::
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642

    [INT]      at 0xFE0C3E10:FE0C0C18 [0xC0201010] <- 0x9       : Enabled interrupt 09h
    ...
    [TIMER]    at 0xFE0C0C54:FE0C0C54 [0xC0210108] <- 0x270F    : Timer #1: will trigger after 10 ms
    [TIMER]    at 0xFE0C3F5C:FE0C0C68 [0xC0210110] <- 0x1       : Timer #1: interrupt enable?
    [TIMER]    at 0xFE0C3F5C:FE0C0C68 [0xC0210100] <- 0x1       : Timer #1: starting
    ...

  Caveat: the emulation may go **surprisingly far *without* DryOS timer** — as far as running the GUI
  with bugs that are almost impossible to explain (such as menu selection bar being behind the logical selection by exactly 1 position).
  To see it with your own eyes, set ``dryos_timer_interrupt = 0x09`` (correct is ``0x0A``) on 60D (maybe also on other models).

  Therefore, please do not assume this works, even if you think it does — double-check!

- get some tasks running

alex@thinkpad's avatar
alex@thinkpad committed
643
  - identify ``task_create`` (in ``debugmsg.gdb`` — same as in ML ``stubs.S``) and run the firmware under GDB
644
645
  - identify the pointer to current DryOS task

alex@thinkpad's avatar
alex@thinkpad committed
646
    This is called ``current_task_addr`` in ``model_list.c``, ``CURRENT_TASK`` in ``debugmsg.gdb`` or ``current_task`` in ML stubs —
647
    see `debug-logging.gdb <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/scripts/debug-logging.gdb>`_
648
649
650
651
    for further hints.

  - identify where the current interrupt is stored
  
652
    Look in the interrupt handler — breakpoint at 0x18 to find it — and find ``CURRENT_ISR`` in
653
    `debug-logging.gdb <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/scripts/debug-logging.gdb>`_,
654
655
656
657
658
659
660
661
662
663
664
    or current_interrupt in ML stubs.
    If you can't find it, you may set it to 0, but if you do, please take task names with a grain of salt if they are printed from some interrupt handler.

  - run with ``-d tasks`` and watch the DryOS task switches.

  |

- optional, sometimes helpful: enable the serial console and the DryOS shell (debug with ``-d io,int,uart``)
- make the startup sequence run (see `EOS firmware startup sequence`_)
- these may need tweaking: WriteProtect switch, HotPlug events (usually GPIOs)
- make sure the GUI tasks are starting (in particular, GuiMainTask)
665
- identify button codes (`extract_button_codes.py <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/eos/mpu_spells/extract_button_codes.py>`_)
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
- make sure the display is initialized, identify the image buffers etc.

EOS firmware startup sequence
'''''''''''''''''''''''''''''

Please note: this section does not apply to recent EOS models (M3 and newer); these models use PowerShot firmware.

If you've looked at enough `startup logs <http://www.magiclantern.fm/forum/index.php?topic=2388>`_,
you've probably noticed they are **not deterministic** (they don't always execute in the same order,
even on two runs performed under identical conditions). The EOS firmware starts many things in parallel;
there is a Sequencer object (SEQ) with a notification system that uses some binary flags
to know where things are finished. Let's look at its debug messages::

   ./run_canon_fw.sh 60D,firmware="boot=0" -d debugmsg |& grep -E --text Notify.*Cur
   [        init:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 0, 0x10000, Flag = 0x10000)
   [    PowerMgr:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 1, 0x20000002, Flag = 0x2)
   [     Startup:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 1, 0x20000000, Flag = 0x20000000)
   [     FileMgr:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 2, 0x10, Flag = 0x10)
   [     Startup:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 3, 0xe0110, Flag = 0x40000)
   [     Startup:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 3, 0xa0110, Flag = 0x80000)
   [     Startup:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 3, 0x20110, Flag = 0x100)
   [      RscMgr:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 3, 0x20010, Flag = 0x20000)
   [     FileMgr:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 3, 0x10, Flag = 0x10)
   [     Startup:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 4, 0x110, Flag = 0x100)
   [     FileMgr:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 4, 0x10, Flag = 0x10)
   [     Startup:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 5, 0x80200200, Flag = 0x80000000)
   [ GuiMainTask:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 5, 0x200200, Flag = 0x200000)
   [       DpMgr:ff02b9f8 ] (00:03) [SEQ] NotifyComplete (Cur = 5, 0x200, Flag = 0x200)
   ...

696
Notice the pattern? Every time a component is initialized, it calls ``NotifyComplete`` with some binary flag.
697
698
699
700
701
702
The bits from this flag are cleared from the middle number, so this number must indicate what processes
still have to do their initialization. Once this number reaches 0 (not printed),
the startup sequence advances to the next stage.

**What if it gets stuck?**

alex@thinkpad's avatar
alex@thinkpad committed
703
You will need to figure it out. Difficulty: anywhere within [0 — infinity); a great dose of luck will help.
704
705
706
707
708
709
710
711
712
713
714
715
716

Let's look at an example — 1300D::

   ./run_canon_fw.sh 1300D,firmware="boot=0" -d debugmsg |& grep --text -E Notify.*Cur
   [        init:fe0d4054 ] (00:03) [SEQ] NotifyComplete (Cur = 0, 0x10000, Flag = 0x10000)
   [     Startup:fe0d4054 ] (00:03) [SEQ] NotifyComplete (Cur = 1, 0x20000002, Flag = 0x20000000)
   [    PowerMgr:fe0d4054 ] (00:03) [SEQ] NotifyComplete (Cur = 1, 0x2, Flag = 0x2)
   [     FileMgr:fe0d4054 ] (00:03) [SEQ] NotifyComplete (Cur = 2, 0x10, Flag = 0x10)
   [     Startup:fe0d4054 ] (00:03) [SEQ] NotifyComplete (Cur = 3, 0xe0110, Flag = 0x40000)
   [     Startup:fe0d4054 ] (00:03) [SEQ] NotifyComplete (Cur = 3, 0xa0110, Flag = 0x80000)
   [     Startup:fe0d4054 ] (00:03) [SEQ] NotifyComplete (Cur = 3, 0x20110, Flag = 0x100)
   [     FileMgr:fe0d4054 ] (00:03) [SEQ] NotifyComplete (Cur = 3, 0x20010, Flag = 0x10)

alex@thinkpad's avatar
alex@thinkpad committed
717
It got stuck because somebody has yet to call ``NotifyComplete`` with ``Flag = 0x20000``.
718

alex@thinkpad's avatar
alex@thinkpad committed
719
Who's supposed to call that? Either look in the disassembly to find who calls ``NotifyComplete`` with the right argument,
720
721
722
723
724
725
726
727
728
or — if not obvious — look in the startup logs of other camera models from the same generation, where the flag is likely the same.

Why it didn't get called? Most of the time:
  
- some task is waiting at some semaphore / message queue / event flag
- it may expect some interrupt to be triggered (to complete the initialization of some peripheral)
- it may expect some message from the MPU
- other (some task stuck in a loop, some prerequisite code did not run etc)

alex@thinkpad's avatar
alex@thinkpad committed
729
How to solve? There's no fixed recipe; generally, try to steer the code towards calling ``NotifyComplete`` with the missing flag.
730
731
You'll need to figure out where it gets stuck and how to fix it. Some things to try:

alex@thinkpad's avatar
alex@thinkpad committed
732
733
734
735
736
- check whether the task supposed to call the troublesome ``NotifyComplete`` is waiting
  (not advancing past a ``take_semaphore`` / ``msg_queue_receive`` / ``wait_for_event_flag``; 
  the ``extask`` command in `Dry-shell`__ may help)

__ `Serial console`_
737
738
739
740
741
742
743
744
745
746
747

- check who calls the corresponding give_semaphore / msg_queue_send etc and why it doesn't run
  (it may be some callback, it may be expected to run from an interrupt, it may wait for some peripheral and so on)

In our case, after cross-checking the same sequence on a 60D (another DIGIC 4 camera) and figuring out a hackish way to patch it
(enough to bring the GUI, but unreliable, with some mysterious bugs), noticed that... we were looking in the wrong place!

The DryOS timer interrupt (heartbeat) was different from *all other* DIGIC 4 and 5 models, and we've never expected
the emulation to go **that** far without a valid heartbeat (that way, we've lost many hours of debugging).
Now scroll up and read that section again ;)

748
Fixing that and a few other things (`commit 7f1a436 <https://foss.heptapod.net/magic-lantern/magic-lantern/-/commit/7d7c4247e2752c603e945b1f39498194f7cc14c7>`_)
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
were enough to bring the GUI on 1300D.

PowerShot firmware startup sequence
'''''''''''''''''''''''''''''''''''

TODO (see CHDK). Startup code is generally simpler and single-threaded, but less verbose.

Assertions
''''''''''

These are triggered by Canon code when something goes wrong. On the UI, these will show ERR70 —
if the rest of the system is able to change the GUI mode and show things of the screen.

When running Magic Lantern, it will attempt to save a crash log for each ERR70.

There are usually over 1000 different conditions that can trigger an assertion (ERR70).
**The only way to tell** which one it was is to read the assert message and locate it in the disassembly.
The `ERR70 description from Canon <http://cpn.canon-europe.com/content/education/infobank/camera_settings/eos_error_codes_and_messages.do>`_
("A malfunction with the images has been detected.") is overly simplistic.

769
770
-------------

771
772
773
774
**Do not attempt to fix a camera with ERR70 yourself!** Please contact us instead,
providing any relevant details (crash logs, what you did before the error and so on).
This section is for fixing assertions **in the emulation** (on a virtual machine), not on real cameras!

775
776
-------------

777
778
779
780
781
782
783
What we can do about them?

- figure out why they happen and fix the emulation
- as a workaround, patch the affected function (see `Patching code`_)

Tip: find the assert stub, add assert_log to your debugmsg.gdb
and run the firmware under GDB with ``-d callstack``.
784
You'll get a stack trace to see what code called that assertion - example below.
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800

Patching code
'''''''''''''

Emulation is not perfect, and neither our skills. If we can figure out how to emulate cleanly
all the code, that's great. If not, there will be some code bits that will not be emulated well.
For example, an unhandled microsecond timer (USleep in DIGIC 6 models) will cause the emulation to halt
when the firmware only wants to wait for a few microseconds.

When you don't know how to solve it, you may get away with patching the troublesome routine.
This shouldn't be regarded as a fix — it's just a workaround that will hopefully help advancing the emulation.

That's why we prefer to patch the firmware from GDB scripts. These can be edited easily to experiment with,
and there is some additional burden for running a patched firmware (longer commands to type),
as a reminder that a proper fix is still wanted.

801
802
803
804
805
806
807
808
809
810
811
812
Patching things may very well break other stuff down the road — use with care.

-------------

**Be very careful patching the assertions when running on a physical camera.
If an assert was reached, that usually means something already went terribly wrong —
hiding the error message from the user is *not* the way to solve it!**

-------------

Examples:

813
**Patching the UTimer waiting routine on 80D** (``80D/patches.gdb``, commit `7ea57e7 <https://foss.heptapod.net/magic-lantern/magic-lantern/-/commit/a683fdb973e6140fae0c1ac054f101ce76b5a8d5>`_):
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828

.. code::

 source patch-header.gdb
 
 # UTimer (fixme)
 set *(int*)0xFE5998C6 = 0x4770
 
 source patch-footer.gdb

Note: ``0x4770`` is ``BX LR`` on Thumb code; on ARM, that would be ``0xe12fff1e``.
See arm-mcr.h for a few useful instructions encodings, use an assembler or read the ARM docs
(in particular, `ARM Architecture Reference Manual <http://www.scss.tcd.ie/~waldroj/3d1/arm_arm.pdf>`_ 
and `Thumb-2 Supplement Reference Manual <http://read.pudn.com/downloads159/doc/709030/Thumb-2SupplementReferenceManual.pdf>`_).

829
**Patching the EstimatedSize assertion on 80D** (``80D/patches.gdb``, commit `b6c5710af <https://foss.heptapod.net/magic-lantern/magic-lantern/-/commit/8b508a551481e1fc31c0551fb765d58c7937ac6c#a00dc09672f2d3657f02a954e0f25f464763b032>`_)
830

831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
After enabling the above UTimer patch, with the generic MPU messages you may get this error::

  ASSERT : Resource/./EstimatedSize.c, Task = RscMgr, Line 1484

To find where it was triggered from, make sure you have the assert stub enabled in ``80D/debugmsg.gdb``::

  b *0xFE547CD4
  assert_log

then run the firmware under GDB, with ``-d callstack``:

.. code:: shell

  (./run_canon_fw.sh 80D,firmware="boot=0" -d debugmsg,callstack -s -S & arm-none-eabi-gdb -x 80D/debugmsg.gdb) |& grep --text -C 5 ASSERT
  ...
          0xFE19B1A9(0, 1, 51, 8000003b)                                           at [RscMgr:fe19b287:2f4330] (pc:sp)
           0xFE19B03B(2f4320, 1, 51, 8000003b)                                     at [RscMgr:fe19b1af:2f4310] (pc:sp)
            0xFE547CD5(fe19b104 "FALSE", fe19b0d0 "Resource/./EstimatedSize.c", 5cc, 8000003b)
                                                                                   at [RscMgr:fe19b14b:2f42f0] (pc:sp)
  [      RscMgr:fe19b14b ] [ASSERT] FALSE at Resource/./EstimatedSize.c:1484, fe19b14f
  ...

The function you are looking for is ``0xFE19B03B`` (could have been any of the callers) and the assertion was triggered at ``0xfe19b14b``.
854
`Our patch <https://foss.heptapod.net/magic-lantern/magic-lantern/-/commit/8b508a551481e1fc31c0551fb765d58c7937ac6c#a00dc09672f2d3657f02a954e0f25f464763b032>`_
855
is at ``0xFE19B06A``, in the function identified with this method.
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895

Incorrect firmware version?
'''''''''''''''''''''''''''

If you have to use ``patches.gdb`` for your camera, you need to be careful:
these patching scripts may perform temporary changes to the ROM. However,
at startup, ML computes a simple signature of the firmware,
to make sure it is started on the correct camera model and firmware version
(and print an error message otherwise, with portable display routines).
These patches will change the firmware signature — so you'll get an error message
telling you the firmware version is incorrect (even though it is the right one).

To avoid this issue, please consider one of the following:

- fix the emulation to avoid unnecessary patches (preferred)

- implement the patches as GDB breakpoints, rather than changing ROM contents
  (that way, the patches will not interfere with ML's firmware signature checking.)

Note: at the time of writing, firmware signature only covers the first 0x40000 bytes
from main firmware start address; ROM patches after this offset should be fine.
If in doubt, just make sure the same ML binary loads on both the patched and unpatched ROMs.


MPU communication
'''''''''''''''''

On EOS firmware, buttons, some properties (camera settings) and a few others are handled on a different CPU,
called MPU in Canon code (not sure what it stands for). On PowerShot firmware you don't need to worry about it — buttons are handled on the main CPU (PhySw).

Communication is done on a serial interface with some GPIO handshaking (look up SIO3 and MREQ in the firmware).
It can be initiated from the main CPU (mpu_send, which toggles a GPIO to get MPU's attention) or from the MPU (by triggering a MREQ interrupt); 
the transfer is then continued in SIO3 interrupts. Each interrupt transfers two bytes of data.

Message format is: ``[message_size] [payload_size] <payload>`` (where ``[x]`` is 1 byte and ``<x>`` is variable-sized).

Payload format is: ``[class] [id] <data> [ack_requested]``.

The first two bytes can be used to identify the message
(and for messages that refer to a property, to identify the property).
896
Property events are in `known_spells.h <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/eos/mpu_spells/known_spells.h>`_;
897
898
899
900
GUI events (button codes) have ``class = 06``.

To log the MPU communication:

901
902
903
- `dm-spy-experiments <http://www.magiclantern.fm/forum/index.php?topic=2388.0>`_ branch, ``CONFIG_DEBUG_INTERCEPT_STARTUP=y`` (``mpu_send`` and ``mpu_recv`` stubs are enabled by default)
- `startup log <http://builds.magiclantern.fm/jenkins/view/Experiments/job/startup-log/>`_ builds (compiled with the above configuration)
- in QEMU, enable ``mpu_send`` and ``mpu_recv`` in ``debugmsg.gdb`` and run the firmware under GDB
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
- low-level: ``-d io,mpu``.

The first message is sent from the main CPU; upon receiving it, the MPU replies back:

.. code::

  ./run_canon_fw.sh 60D -s -S & arm-none-eabi-gdb -x 60D/debugmsg.gdb
  ...
  [     Startup:ff1bf228 ] register_interrupt(MREQ_ISR, 0x50, 0xff1bf06c, 0x0)
  [     Startup:ff1bf23c ] register_interrupt(SIO3_ISR, 0x36, 0xff1bf0fc, 0x0)
  [     Startup:ff1dcc18 ] task_create(PropMgr, prio=14, stack=0, entry=ff1dcb24, arg=807b1c)
  [     Startup:ff05e1b8 ] mpu_send( 06 04 02 00 00 )
  [MPU] Received: 06 04 02 00 00 00  (Init - spell #1)
  [MPU] Sending : 08 07 01 33 09 00 00 00  (unnamed)
  [     INT-36h:ff1bf420 ] mpu_recv( 08 07 01 33 09 00 00 00 )
  [MPU] Sending : 06 05 01 20 00 00  (PROP_CARD1_EXISTS)
  [     INT-36h:ff1bf420 ] mpu_recv( 06 05 01 20 00 00 )
  [MPU] Sending : 06 05 01 21 01 00  (PROP_CARD2_EXISTS)
  [     INT-36h:ff1bf420 ] mpu_recv( 06 05 01 21 01 00 )
  ...

The message sent by the main CPU is::

  06 04 02 00 00 00

- ``06`` is message size (always even)
- ``04`` is payload size (always ``message_size - 1`` or ``message_size - 2``)
- ``02 00 00 00`` is the payload:

933
  - ``02 00`` identifies the message (look it up in `known_spells.h <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/eos/mpu_spells/known_spells.h>`_)
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
  - the last ``00`` means no special confirmation was requested (``Complete WaitID`` string)
  - the remaining ``00`` may contain property data or other information (nothing interesting here)

The first message sent back by the MPU is::

  08 07 01 33 09 00 00 00

- ``08 07``: message size and payload size
- ``01 33`` identifies the message (maps to property 0x80000029, unknown meaning)
- ``09 00 00`` is the property data (note: its size is 3 on the MPU, but 4 on the main CPU)
- ``00`` means no special confirmation was requested
  (``01`` would print ``Complete WaitID = 0x80000029``)

The second and third messages are easier to grasp::

  06 05 01 20 00 00
  06 05 01 21 01 00

- ``06 05``: message size and payload size
- ``01 20`` and ``01 21`` identify the messages (``0x8000001D/1E PROP_CARD1/CARD2_EXISTS``)
- ``00`` and ``01``: property data, meaning CF absent and SD present (size 1 on MPU, 4 on main CPU)
- ``00`` (last one) means no special confirmation was requested.


How do you get these messages?

From a `startup log <http://builds.magiclantern.fm/jenkins/view/Experiments/job/startup-log/>`_ (`dm-spy-experiments <http://www.magiclantern.fm/forum/index.php?topic=2388.0>`_), use 
961
962
`extract_init_spells.py <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/eos/mpu_spells/extract_init_spells.py>`_
to parse the MPU communication into C code (see `make_spells.sh <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/eos/mpu_spells/make_spells.sh>`_).
963

964
There are also generic spells in `generic.h <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/eos/mpu_spells/generic.h>`_
965
966
967
968
969
970
971
972
973
974
975
976
977
978
that are recognized by most EOS models and are good enough to enable navigation on Canon menus.

Things to check:

- mpu_send: the message format should make sense (consistent sizes etc)
- our emulated MPU should receive the message correctly: ``[MPU] Received:`` should match the previous mpu_send line
- it should reply back with something: ``[MPU] Sending :``
- mpu_recv should be called, with the same message as argument
- to see what the firmware does with these messages, look in mpu_send and track the messages from there.

Serial flash
''''''''''''

To enable serial flash emulation (if your camera needs it, you'll see some relevant startup messages),
979
define ``.serial_flash_size`` in ``model_list.c`` and a few other parameters:
980
981
982

- chip select signal (CS): some GPIO register toggled before and after serial flash access
- SIO channel (used for SPI transfers)
983
- check SFIO and SFDMA in ``eos_handlers`` (for DMA transfers — Canon reused the same kind of DMA used for SD card).
984

985
Dumper: `sf_dump module <https://foss.heptapod.net/magic-lantern/magic-lantern/-/tree/branch/unified/modules/sf_dump>`_.
986
987
988

For early ports, you might (or might not) get away with serial flash contents from another model.

989
`Patching <https://foss.heptapod.net/magic-lantern/magic-lantern/-/commit/bd4cdc0497e4354f71747031afc57ec1d1478943>`_ might help.
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
When editing SFDATA.BIN files manually, watch out — some data blocks are shifted by 4 bits for some reason.

WriteProtect switch
'''''''''''''''''''

This is easy: run with ``-d debugmsg,io`` and look for a GPIO read right before this message::

  [STARTUP] WriteProtect (%#x)

Example::

  ./run_canon_fw.sh 6D,firmware="boot=0" -d debugmsg,io |& ansi2txt | grep WriteProtect -C 5
  ...
  [GPIO]   at Startup:FF14A330:FF0C4490 [0xC02200D0] -> 0x1       : GPIO_52
  [     Startup:ff0c44a8 ] (00:05) [STARTUP] WriteProtect (0x1)
  ...

That means, register 0xC02200D0 shows the WriteProtect switch state; you may want to change it to emulate a SD card without write protection.

If you don't see the WriteProtect message, this register is probably OK. To test the above, comment out the WriteProtect register handling code for your camera (usually in eos_handle_gpio).

HotPlug events
''''''''''''''

There is a task polling for hardware events, such as plugging a microphone, an external monitor,
an USB cable and maybe a few others. Generally, you want to emulate without these things,
so you'll need to look in the disassembly of HotPlug and see what it expects for each peripheral;
most of the time, it checks some GPIO registers — you may have to adjust them (usually in ``eos_handle_gpio``).

Since all of these registers are checked in a loop, you may want to silence them (``IGNORE_CONNECT_POLL``).

Adding support for a new Canon firmware version
```````````````````````````````````````````````

You will have to update:

- GDB scripts (easy — copy/paste from ML stubs or `look them up <http://www.magiclantern.fm/forum/index.php?topic=12177.0>`_)
- expected test results (time-consuming, see the `Test suite`_)
- any hardcoded stubs that might be around (e.g. in ``dbi/memcheck.c``)

Most other emulation bits usually do not depend on the firmware version
(5D3 1.2.3 was an exception).

`Updating Magic Lantern to run on a new Canon firmware version <http://www.magiclantern.fm/forum/index.php?topic=19417.0>`_
is a bit more time-consuming, but it's not difficult.

Are there any good docs on QEMU internals?
``````````````````````````````````````````

alex@thinkpad's avatar
alex@thinkpad committed
1039
- `http://nairobi-embedded.org/category/qemu.html <https://web.archive.org/web/20180324054427/http://nairobi-embedded.org/category/qemu.html>`_ (archived)
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
- http://blog.vmsplice.net
- QEMU mailing list (huge!)
- Xilinx QEMU

DryOS internals?
````````````````

This is the perfect tool for studying them. Start at:

- `Working out all the way to Canon GUI`_ for an overview
- DryOS shell (View -> Serial in menu, then type ``akashimorino``, then ``drysh``)
- task_create (from GDB scripts)
- semaphores (some GDB scripts have them)
- message queues (some GDB scripts have them)
1054
- heartbeat timer (dryos_timer_id/interrupt in `model_list.c <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/eos/model_list.c>`_)
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
- interrupt handler (follow the code at 0x18)
- to debug: ``-d io,int`` is very helpful (although a bit too verbose)

|

Serial console
``````````````

.. image:: doc/img/drysh.png
   :scale: 50 %
   :align: center

QEMU menu: ``View -> Serial``.

Hardware connections: possibly in the `battery grip pins <http://www.magiclantern.fm/forum/index.php?topic=7531>`_; 
see also `JTAG on PowerShot <https://nada-labs.net/2014/finding-jtag-on-a-canon-elph100hs-ixus115/>`_ 
and `UART pins on EOS M3 <http://chdk.setepontos.com/index.php?topic=12542.msg129346#msg129346>`_.

Some of these functions **can damage your camera!**

EOS menus
'''''''''

- FROMUTILITY menu

  - delete ``AUTOEXEC.BIN`` from the virtual card, but leave it bootable (and start with ``firmware="boot=1"``).
  - this is what happens when your camera locks up (see the warnings in `ML install guide <http://wiki.magiclantern.fm/install>`_).
  - interesting items:

    - boot flags
    - SROM menu on models with serial flash
1086
    - Bufcon (GPIO names, `hidden menu <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/3bf1042657334a2266b74540adf3114cddcee691/contrib/qemu/eos/eos_bufcon_100D.h>`_)
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146

- FACTADJ menu

  - exit from FROMUTILITY menu to find it.

- Event shell

  - start main firmware (e.g. ``firmware="boot=0"``)
  - type ``akashimorino``
  - type ``?`` to see functions registered by name (aka `eventprocs <http://chdk.wikia.com/wiki/Event_Procedure>`_)
  - interesting items:

    - ``drysh`` to open the DryOS shell console
    - ``smemShowFix`` for the `RscMgr memory map <http://www.magiclantern.fm/forum/index.php?topic=5071.0>`_
    - ``dumpf`` to save a debug log (not all messages are saved; use `dm-spy-experiments <http://www.magiclantern.fm/forum/index.php?topic=2388.0>`_ to capture all of them)
    - ``dispcheck`` to save a screenshot of the BMP overlay
    - there are more functions than you can count, feel free to experiment and report back ;)
    - some of these functions **can damage your camera!** (but you can safely try them in QEMU)

- Dry-shell console (DryOS shell, DrySh)

  - type ``drysh`` at the event shell
  - type ``help`` for the available functions
  - interesting items:

    - ``extask`` to display DryOS tasks and their status, memory usage etc
    - ``meminfo`` and ``memmap`` to display DryOS memory map (ML is loaded in the *malloc* memory pool on many models)
    - network functions on recent models

PowerShot menus
'''''''''''''''

The PowerShot firmware expects some sort of `loopback <http://chdk.setepontos.com/index.php?topic=13278.0>`_ —
it prints a ``#`` and expects it to be echoed back, then waits for this switch to be turned off.

On EOS M3/M10, you can enter this menu by adding this to eos_handle_uart, under ``Write char``:

.. code:: C

    if (value == '#')
    {
        s->uart.reg_rx = value;
        s->uart.reg_st |= ST_RX_RDY;
    }

This will enable a debug shell; type ``?`` for the available commands.

Cross-checking the emulation with actual hardware
`````````````````````````````````````````````````

- dm-spy-experiments branch
- CONFIG_DEBUG_INTERCEPT_STARTUP=y
- run the same build on both camera and QEMU
- compare the logs (sorry, no good tool for this)
- add extra hooks as desired (dm-spy-extra.c)
- caveat: the order of execution is not deterministic.

Checking MMIO values from actual hardware
'''''''''''''''''''''''''''''''''''''''''

1147
See `this commit <https://foss.heptapod.net/magic-lantern/magic-lantern/-/commit/3a0cfbe682cb31b0794d6a866d019c231306b6a1>`_:
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158

- ``./run_canon_fw.sh 5D3 [...] -d io_log``
- copy/paste some entries into ``dm-spy-extra.c`` (grep for ``mmio_log`` to find them)
- get logs from both camera and QEMU (dm-spy-experiments branch, ``CONFIG_DEBUG_INTERCEPT_STARTUP=y``, maybe also `CONFIG_QEMU=y`)
- adjust the emulation until the logs match.

Checking interrupts from actual hardware
''''''''''''''''''''''''''''''''''''''''

LOG_INTERRUPTS in dm-spy-experiments.

1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
Misc notes
``````````

Model-specific parameters: ``eos/model_list.c`` (todo: move all hardcoded stuff there).

MMIO handlers: ``eos_handlers`` -> ``eos_handle_whatever`` (with ``io_log`` for debug messages).

Useful: ``eos_get_current_task_name/id/stack``, ``eos_mem_read/write``.

To extract MPU messages from a `startup log <http://builds.magiclantern.fm/jenkins/view/Experiments/job/startup-log/>`_,
1169
use `extract_init_spells.py <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/eos/mpu_spells/extract_init_spells.py>`_ (see `MPU communication`_).
1170
1171

To customize keys or add support for new buttons or GUI events,
1172
1173
1174
edit `mpu.c <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/eos/mpu.c>`_,
`button_codes.h <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/eos/mpu_spells/button_codes.h>`_
and `extract_button_codes.py <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/eos/mpu_spells/extract_button_codes.py>`_.
1175

1176
Known MPU messages and properties are exported to `known_spells.h <https://foss.heptapod.net/magic-lantern/magic-lantern/-/blob/branch/qemu/contrib/qemu/eos/mpu_spells/known_spells.h>`_.
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205

Committing your changes
```````````````````````

After editing the sources outside the magic-lantern directory, 
first make sure you are on the ``qemu`` branch:

.. code:: shell

  # from the magic-lantern directory
  hg up qemu -C

Then copy your changes back into the ML tree:

.. code:: shell

  # from the qemu directory
  ./copy_back_to_contrib.sh

Then commit as usual, from the ``contrib/qemu`` directory.

Reverting your changes
``````````````````````

If you want to go back to an older changeset, or just undo any changes you
made outside the magic-lantern directory, you may run the install script
again. It will not re-download QEMU, but unfortunately you will have to
recompile QEMU from scratch (which is very slow).

1206
Alternative, slightly faster:
1207
1208
1209

.. code:: shell

1210
1211
1212
1213
1214
  # from the qemu directory
  ./sure_copy_from_contrib.sh

If you have changed only the ``eos`` files (i.e. no changes to QEMU core),
use the following command; afterwards, recompilation will be very fast:
1215

1216
.. code:: shell
1217

1218
1219
  # from the qemu directory
  ./sure_copy_from_contrib.sh -q
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282

Test suite
``````````

Most Canon cameras are very similar inside — which is why one is able to run the same codebase
from DIGIC 2 (original 5D) all the way to DIGIC 5 (and soon 6). Yet, every camera model has its own quirks
(not only on the firmware, but also on the hardware side). Therefore, it's hard to predict whether a tiny change in the emulation, to fix a quirk for camera model X,
will have a positive or negative or neutral impact on camera model Y. The test suite tries to answer this,
and covers the following:

- Bootloader code (to make sure AUTOEXEC.BIN is loaded from the card)
- Portable display test (all EOS models)
- Portable ROM dumper (EOS models with bootloader file write routines)
- Menu navigation (on supported models) — depends on user settings from the ROM
- Card formatting (and restoring ML)
- Call/return trace until booting the GUI (a rigid test that may have to be updated frequently)
- Call/return trace on bootloader (likely independent of firmware version and user settings)
- Callstack consistency with call/return trace (at every DebugMsg call)
- File I/O (whether the firmware creates a DCIM directory on startup)
- FA_CaptureTestImage (basic image capture process, without compression or CR2 output)
- HPTimer (difficult to get right)
- DryOS task information (current_task, current_interrupt)
- GDB scripts (just a few basics)
- DryOS shell (UART)
- PowerShot models (limited tests)
- Secondary DryOS cores (limited tests)

Limitations:

- The tests are tied to our copies of the ROMs (which also store various user settings);
  unfortunately, these ROMs are not public (see `ML FAQ <http://wiki.magiclantern.fm/faq>`_).
  
  Workarounds:
  
  - run the test suite for your camera model(s) only, e.g. ``./run_tests.sh 5D3 60D 70D``
  - inspect the test results (e.g. screenshots) manually, and compare them to
    `our results from Jenkins <http://builds.magiclantern.fm/jenkins/view/QEMU/job/QEMU-tests/>`_
    to decide whether they are correct or not
  - if you have made changes to the emulation, just ask us to test them.

  Saving the ROM right after clearing camera settings may or may not give repeatable results (not tested).

- The test suite is very slow (30-60 minutes, even on decent hardware)

  Workarounds:

  - run the test suite for a small number of camera model(s): ``./run_tests.sh 5D3 60D 70D``
  - run only the test(s) you are interested in: ``./run_tests.sh 5D3 80D menu calls-main drysh``

  If you have any ideas on how to improve the tests, we are listening.

To avoid committing (large) reference screenshots or log files,
a lot of expected test results are stored as MD5 sums. That's a bit rigid,
but it does the job for now. Where appropriate, we also have grep-based
tests or custom logic on log files.

The expected test results ("`needles <http://open.qa/docs/#_needles>`_") are updated manually
(e.g. ``md5sum disp.ppm > disp.md5``). Suggestions welcome.

Code coverage?
``````````````

`Yes <http://builds.magiclantern.fm/jenkins/view/QEMU/job/QEMU-coverage/>`_.
1283
1284
1285
1286
1287
1288
1289
1290
1291


----------

..

----------

`Back to README.rst <README.rst#rst-header-hacking>`_