Flowchart "ML Pre-Start". First draft and questions

[Walter Schulz]

Hello!

Created a flowchart about what is going on *before* running ML. I think it covers most what might be described as bootload stuff.
https://wiki.magiclantern.fm/_media/ml-prestartup_draft2.png

1): @a1ex: Roughly correct or not?
2): @all: Edible or unable to swallow?

And another one for a1ex: After wake-up from sleep there is another card check slowing down wake-up. What is the cam actually doing? Again checking for bootable card or just reading Autoexec.bin and other files?

EDIT: Dang! Forgot "Check if card is bootable!" New version online.

[a1ex]

Well... having some trouble following it


Startup

First: camera powers on in one of these conditions:
- power switch on AND card/battery doors closed
- after Auto Power Off: the above + half-shutter press

Boot sequence (regardless of how the camera is started):
- Canon firmware (running on main CPU) has two parts: main firmware and bootloader.
- There are parts running on secondary CPUs, one of them being the MPU.
- I believe the MPU starts first.
- Canon bootloader (on main CPU) starts running (possibly started by the MPU).
- checks boot flags in the ROM (there are more of them, but we are interested specifically in the BOOTDISK flag).
- if the boot flag is enabled in the camera (ROM):
  - card present?
    - bootloader mounts card and checks its contents [ this causes startup delay ]
    - is the card bootable? (marked with EOS_DEVELOP and BOOTDISK in the boot sector)
      - camera loads autoexec.bin (possibly without turning on the LED)
      - on error (autoexec.bin not present or whatever), camera locks up (well, it enters the factory menu available via UART, but end user will only see a locked up camera). Battery out.
      - Canon bootloader un-mounts the card and runs autoexec.bin
      - autoexec.bin (our code) turns on the LED, patches Canon's main firmware to "inject" our code, and runs it
      - ML up and running
    - card not bootable:
      - Canon bootloader launches main firmware (unmodified). There was some startup delay from previous step.
  - card not present?
    - Canon bootloader launches main firmware (unmodified). No startup delay, since the bootloader did not attempt to mount the card. It only checked its presence.
- boot flag not set in the ROM:
  - Canon bootloader launches main firmware (unmodified). Factory condition, no startup delays.


Temporary wake-up

There is also a special power on (or wake up if you prefer) when the main switch is OFF:
- when card door changes its state (either open->closed or closed->open)
- when battery door changes its state (either open->closed or closed->open at least on 5D2, to be double-checked on other models)
- when a lens is attached or removed

In this case the camera:
- boots as usual (loading autoexec.bin if configured, yadda yada)
- remains on for 1-2 seconds
- shuts down
- I believe it's the MPU that tells the main CPU to shut down early (will get some UART logs later)

With a ML-enabled card, you will see a LED blink. The first thing done by autoexec.bin is turning on the LED.

Without a ML-enabled card, or without the boot flag enabled, you (the end user) won't see any activity. The camera still wakes up; you will be able to see activity on the UART pins (both ICU and MPU), or with an ammeter.

We have no control over this special wake-up (Canon hardware does it; the decision to wake up is taken outside the main processor, possibly on the MPU side). You must be careful: do not remove the card during this wake up. This is a problem on older models, where card is accessed by Canon's bootloader without turning on the LED. Otherwise, this wake-up is harmless.


Shutdown

Normal shutdown, from main power switch:
- camera powered on (main switch on, card/battery doors closed).
- user turns off from the main switch (which is just a soft button, btw).
- ML is notified and saves its settings.
- DryOS waits for remaining tasks to finish (i.e. last photo to be saved completely etc) [ TODO for me: keep the LED on during this process! ]
- Canon firmware (on main CPU) saves their settings (by reflashing the main ROM).
- Canon firmware (on MPU) saves their settings too (guess: in the EEPROM).
- camera shuts down (well, unless DryOS is left by ML in some invalid state or whatever).
- I belive it's the MPU that decides when the power is cut off (but don't have a hard proof).
- caveat: when user wants to remove the card, card door changes its state => camera wakes up for 1-2 seconds and may access the card (possibly without LED activity); you need to wait until LED stops blinking. Do not rush to remove the card!

Shutdown by opening card door:
- camera powered on (main switch on, card/battery doors closed).
- user opens card door.
- main switch remains on.
- a normal shutdown is performed (as before).
- after shutdown, when user wants to remove the card, card door is already open, i.e. it no longer changes its state => cam no longer wakes up. Safest shutdown method when running ML, if you ask me.

Shutdown by opening the battery door:
- this is an emergency shutdown; DryOS turns off ASAP (well, unless the camera is locked up).
- ML does not get notified in main builds, so it does not save its settings.
- ML assumes the camera crashed and will not load modules at next boot.
- Canon firmware (on main CPU) saves their settings (yes, by reflashing the main ROM), unless we prevent it from doing so.
- Canon firmware (on MPU) saves their settings (guess: in the EEPROM). The main CPU has no veto rights on this.

Taking the battery out:
- user keeps the battery door microswitch pressed and takes the battery out.
- after a camera lockup (i.e. if screen is still open after opening battery door), the same might happen, not 100% sure.
- Canon firmware (on ICU) no longer gets a chance to save their settings.
- Canon firmware (on MPU) no longer gets a chance to save their settings.
- ML no longer gets a chance to save their settings; it assumes crash and skips module loading at next boot.

Related: Shutdown and reboot in QEMU guide.


Software reboot

Triggered from PROP_REBOOT (Lua: camera.reboot()). Apparently handled as clean shutdown + cold boot?!

Wake up from sleep?

There is no such thing on Canon EOS cameras. There is a setting called "Auto Power Off" in Canon menu. If used, the camera powers off completely after some timeout. When it "wakes up" (e.g. by touching half-shutter), it powers on from scratch. The only difference is the button you use for powering it on.

PROP_STARTUP_CONDITION can be used to tell the difference between a cold boot (after battery out) and a warm boot (second or third or n'th boot without taking the battery out). Maybe also waking up from auto power off; need to check.

Hope this clarifies.

TODO: write the above in a way accessible to regular users.


Edit: here's my attempt at drawing the above in a diagram. It also includes what autoexec.bin does, so it may be a bit too detailed for end users. Feel free to edit.

[scrax]

uhmmm... wait...

I have a bootable card but EOS_DIGITAL not EOS_DEVELOP and it works ok, to be honest two of three are EOS_DIGITAL

[a1ex]

Open the raw card contents with a hex editor and you'll have a little surprise. Then look at the code (make_bootable.sh, bootflags.c etc).

I'm not talking about the label displayed by your regular Windows/Mac/Linux PC in the file browser; these will display EOS_DIGITAL in most cases.

Yes, on FAT12/16/32 EOS_DEVELOP is written in the place of the volume label, but... there are two copies of the boot sector. Canon bootloader looks at one of these two copies; most other programs look at the other copy. Yes, this means a ML-bootable FAT12/16/32 card may trigger some warnings when the filesystem is checked for errors, as the boot sectors will not be identical.

I've noticed this nitpick with this commit, and kept the non-compliant, but backwards-compatible solution for now (with different boot sectors, but card mounted as EOS_DIGITAL). I can update everything to EOS_DEVELOP (with both boot sectors identical) if you find a good reason for doing so.

[scrax]

For me is better like this because have scripts that look for /Volumes/EOD_DIGITAL to import when card connected, and I use the EOS_DEVELOP for test and stuff that don't need to autoimport, so basically is a feat 

I was just curious why you talked about the EOS_DEVELOP, I didn't know all the tecnical detail and this post about camera boot up is really informative .

[calle2010]

I like both flowcharts. Walter's is useful from a user and noob developer (read: my) perspective. Users can be educated about the high-level steps and can better understand what is going possibly wrong.

Alex's is great for developers to gain an understanding of the boot process. I already followed boot and reboot. I do not yet understand how the my_big_init_task is launched.

Both should be in documentation. Perhaps in README (Walter's chart) and HACKING (Alex's chart)?