API documentation and what to avoid

Started by apalazzi, February 21, 2023, 09:51:06 PM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

apalazzi

Hi,

I want to modify the astro module to see if I can make it suit my needs, however I have two questions:
- So far Iv'e found only the LUA API documentation, and I'm using partly this and partly look at the functions names to guess what a call does: is there some documentation for the C api calls?
- What should  avoid to mess with to avoid bricking my camera? Is there some calls that are more dangerous and should not mess with unless necessary?

Thanks
Andrea

names_are_hard

Hi - first I need to point out while I know ML code pretty well, I know the Lua stuff hardly at all.  Hopefully Garry will notice this and have some better answers for those parts.

You say you're using Lua API docs.  Which ones?

When you say "C API calls", do you mean there are some C functions in ML that are an API?  Or are you using this more informally to just mean calling C functions?  If the former, where is the API defined?  If the latter, there's no good documentation that I'm aware of.  You'll often need to check the source and work out what a C function does, and there are often no comments.

In general, don't call C functions unless you understand what they do.  To lower risk, test things in Qemu first.  Only test on a physical camera if things work how you expect in Qemu.  Of course, not all things are emulated well enough, but where possible this is a good option.

Some functions certainly are more dangerous than others.  Generally things that are "active", like triggering shutter, or in some sense involve writing / storing, e.g. changing properties or writing to disk or memory.




apalazzi

Quote from: names_are_hard on February 22, 2023, 12:27:48 AM
Hi - first I need to point out while I know ML code pretty well, I know the Lua stuff hardly at all.  Hopefully Garry will notice this and have some better answers for those parts.

You say you're using Lua API docs.  Which ones?
The ones on the ML site: https://builds.magiclantern.fm/lua_api/

Quote
When you say "C API calls", do you mean there are some C functions in ML that are an API?  Or are you using this more informally to just mean calling C functions?  If the former, where is the API defined?  If the latter, there's no good documentation that I'm aware of.  You'll often need to check the source and work out what a C function does, and there are often no comments.
I mean "calling C functions". EDIT: when I say API I mean "the functions that should be available for people developing modules and similar things", thus excluding the functions that are intended for internal ML use and code organization.
I'm working on the astro module and, in the case at hand, I discovered that the "star focus" function is disabled when lv_luma_is_accurate() is not true:

if (!lv_luma_is_accurate()) return 0;

And this arises two question: I guessed that lv_luma_is_accurate() had something to do with the LV screen gain, but for the future it would have been handy to have some documentation other than the sources - but I guess it's not the case.
The second question is why there's this check and if it's save to do the things the module is doing even when lv_luma_is_accurate() returns false; and in general what can I modify and assume there is little risk, and what instead I should handle with care.


Quote
In general, don't call C functions unless you understand what they do.  To lower risk, test things in Qemu first.  Only test on a physical camera if things work how you expect in Qemu.  Of course, not all things are emulated well enough, but where possible this is a good option.

Some functions certainly are more dangerous than others.  Generally things that are "active", like triggering shutter, or in some sense involve writing / storing, e.g. changing properties or writing to disk or memory.

Thanks for the info :)

Bye
Andrea

names_are_hard

Quote
when I say API I mean "the functions that should be available for people developing modules and similar things", thus excluding the functions that are intended for internal ML use and code organization.
I don't know if such a set of functions is defined.  I would assume not.

Quote
The second question is why there's this check and if it's save to do the things the module is doing even when lv_luma_is_accurate() returns false
Sometimes you can get more info from the commit message when the change was made.  Is there a repo associated with this module?

Quote
and in general what can I modify and assume there is little risk, and what instead I should handle with care.
There is no simple answer to this, you'll have to inspect the code.  Testing in qemu helps so I highly recommend that.

apalazzi

Quote from: names_are_hard on February 23, 2023, 01:47:43 AM
Sometimes you can get more info from the commit message when the change was made.  Is there a repo associated with this module?
Yes, there is, however there's only one commit: https://bitbucket.org/xaint/magic-lantern-astro-module/commits/

I guess the next step is to setup the qemu emulator and also do some source diving then.

Thanks for your help :)

Andrea

apalazzi

Quote from: names_are_hard on February 23, 2023, 01:47:43 AM
Testing in qemu helps so I highly recommend that.

Hi,

Talking about Qemu, I guess the recommended way is to build from your repository https://github.com/reticulatedpines/qemu-eos ? Is the Qemu documentation on the ML site still relevant?

Bye
Andrea

names_are_hard

My recommendation depends on what you're trying to do.

Qemu 4 is easier to build, and if you find bugs / problems, I will try to fix them.  In theory it emulates ARM and some of the peripherals we use better than 2, but in practice this is not as clear: we made changes against qemu 2 to make it do things we wanted, and I ported those to 4.  This was not easy (qemu changed their fundamental architecture significantly in this time), there are some known problems, and likely some unknown ones.  Are these relevant to you?  Perhaps, perhaps not.

Qemu 2 is a known quantity, it's what official ML has always worked with and tested against.  However, it's so old it's hard to build unless you use an old system.  And nobody is maintaining the ML qemu 2 patches.  And if you want to make changes to qemu 2, the workflow is very annoying, because we don't keep those changes nicely in source control, it's a combination of properly managed files and patch files.  Updating patch files is not a clear way to manage code.  I split out qemu 4 into a separate repo so the workflow is normal.

So, qemu 4 is easier to work with in multiple ways, but probably more buggy.  These aren't the kind of bugs that will lead you to accidentally write code that doesn't work on cam.  These bugs would make ML qemu docs not make sense, or break emulator functionality (e.g., maybe emulated serial port doesn't work how it should in some circumstances).  You can't use the official ML docs to install qemu 4, but, I have a mini-guide here: https://github.com/reticulatedpines/qemu-eos/tree/qemu-eos-v4.2.1/magiclantern
I think 4 is easier to install, but I've only tested on Linux.  In theory it'll work on Win (WSL) and Mac.

If you know you only care about a well supported cam, and you don't mind setting up an older build environment, and/or you want to get your changes into official ML, you might want to use qemu 2.

If you don't mind possibly encountering confusing behaviour from qemu, I'd say 4 is better.

You can of course install both.

Lucagw

Hi Andrea, are you still working on astro.mo?
Ciao
Luca
Canon EOS 600D