module api versioning

reyalp

12690

module api versioning

« on: 11 / March / 2013, 00:40:45 »

Advertisements

I've been confused about this for a long time...

Can anyone clearly explain when the various API versions on modules and camera_info structures need to be incremented?

http://chdk.wikia.com/wiki/Module_System is a start, but it's not really clear to me what specific fields need to change when

Scenarios
- Add a core function to to module_export list. No versions increment, because loading will fail if required function not present (?)
- Add an exported function to a module.
Minor version should increase in module exported API (e.g DNG libdng_sym?) What about the version in _module_info?
If the core requires the new function, this is incremented in modules.c ?
- Change signature of module exported function. Major version increases (?)
- Change signature of a core exported function

- How do we deal with temporary development branches ?

Logged

Don't forget what the H stands for.

philmoz

3163

Re: module api versioning

« Reply #1 on: 11 / March / 2013, 01:26:13 »

Quote from: reyalp on 11 / March / 2013, 00:40:45

I've been confused about this for a long time...

Can anyone clearly explain when the various API versions on modules and camera_info structures need to be incremented?

http://chdk.wikia.com/wiki/Module_System is a start, but it's not really clear to me what specific fields need to change when

Scenarios
- Add a core function to to module_export list. No versions increment, because loading will fail if required function not present (?)
- Add an exported function to a module.
Minor version should increase in module exported API (e.g DNG libdng_sym?) What about the version in _module_info?
If the core requires the new function, this is incremented in modules.c ?
- Change signature of module exported function. Major version increases (?)
- Change signature of a core exported function
- How do we deal with temporary development branches ?

I don't know what the rationale behind it all is - and to be honest I don't really believe it's necessary.

IMO the overhead to maintain it is more trouble than any benefit it might have.

Phil.

Logged

CHDK ports:
sx30is (1.00c, 1.00h, 1.00l, 1.00n & 1.00p)
g12 (1.00c, 1.00e, 1.00f & 1.00g)
sx130is (1.01d & 1.01f)
ixus310hs (1.00a & 1.01a)
sx40hs (1.00d, 1.00g & 1.00i)
g1x (1.00e, 1.00f & 1.00g)
g5x (1.00c, 1.01a, 1.01b)

reyalp

12690

Re: module api versioning

« Reply #2 on: 11 / March / 2013, 02:23:31 »

Quote from: philmoz on 11 / March / 2013, 01:26:13

I don't know what the rationale behind it all is - and to be honest I don't really believe it's necessary.

IMO the overhead to maintain it is more trouble than any benefit it might have.

Oh, there goes my "Get Phil to explain it all" plan

Maybe this is a subject for the module v2 thread then. I agree the current system seems overbuilt and is quite hard to understand.

In principle, it would be preferable to fail gracefully if the modules aren't compatible with the build, but if the system is too complicated to keep up to date, it doesn't really help.

If there were 3rd party modules being distributed separately from CHDK, then it would be more of an issue. But even in that case, I'd be tempted to make a distinction between system modules (tightly integrated with the core code, like DNG, zebra, script languages) and third party standalone modules. I'd say that the former could be required to be exactly the same version as the core, while the latter could have a more limited, versioned public API.

Another approach would be just to version it of the CHDK major version (1.1, 1.2 etc) with the development build assumed to be incompatible from version to version, and the release versions kept stable.

Logged

Don't forget what the H stands for.

philmoz

3163

Re: module api versioning

« Reply #3 on: 11 / March / 2013, 04:03:28 »

Quote from: reyalp on 11 / March / 2013, 02:23:31

Quote from: philmoz on 11 / March / 2013, 01:26:13
I don't know what the rationale behind it all is - and to be honest I don't really believe it's necessary.

IMO the overhead to maintain it is more trouble than any benefit it might have.
Oh, there goes my "Get Phil to explain it all" plan

Maybe this is a subject for the module v2 thread then. I agree the current system seems overbuilt and is quite hard to understand.

In principle, it would be preferable to fail gracefully if the modules aren't compatible with the build, but if the system is too complicated to keep up to date, it doesn't really help.

If there were 3rd party modules being distributed separately from CHDK, then it would be more of an issue. But even in that case, I'd be tempted to make a distinction between system modules (tightly integrated with the core code, like DNG, zebra, script languages) and third party standalone modules. I'd say that the former could be required to be exactly the same version as the core, while the latter could have a more limited, versioned public API.

Another approach would be just to version it of the CHDK major version (1.1, 1.2 etc) with the development build assumed to be incompatible from version to version, and the release versions kept stable.

I've stripped out some of, what I felt, where less useful checks in the modulesV2 branch. I've also added a version data type to make it more readable.

It is currently possible to make the module dependant on the CHDK version, type (CHDK, CHDK-DE or SDM) and even camera platform id (can't see the need for this myself). However all the modules are currently set to be compatible with any version.

There are checks when loading the modules against some magic numbers and the size of the module_info structure. Any major changes here (like the modulesV2 branch) will cause the module load to fail.

Some of the modules checked the GUI, Conf, camera_info and camera_sensor data structures while others did not. To me these checks are possibly not really needed; but I've re-factored it in modulesV2 so the versions are stored in the module_info structure rather than checked in the code. At least this standardises it for those modules that care.

I've also added a new check in modulesV2 for the module auto-load code. There is a new 'handler' data structure that needs to match the module interface version.

One option that might help here would be to define macros for all the relevant version values and use these in the relevant code - i.e. create a versions.h file with all the current version numbers. At least this would ensure that everything was aligned in each build. The possible disadvantage would be that the module files would be tightly bound to the specific build and not be as portable.

Phil.

Logged

srsa_4c

4262

Re: module api versioning

« Reply #4 on: 11 / March / 2013, 13:58:38 »

Quote from: philmoz on 11 / March / 2013, 04:03:28

... and even camera platform id (can't see the need for this myself).

Here's one example, but it's a rather special case. It expects functionality which is not available in any other port.
That said, it's not possible to specify more than one P-ID, so the current way is not really optimal for every theoretical use.

Logged

Menu jumping/flickering on M10?

philmoz

3163

Re: module api versioning

« Reply #5 on: 11 / March / 2013, 17:23:42 »

Quote from: srsa_4c on 11 / March / 2013, 13:58:38

Quote from: philmoz on 11 / March / 2013, 04:03:28
... and even camera platform id (can't see the need for this myself).
Here's one example, but it's a rather special case. It expects functionality which is not available in any other port.
That said, it's not possible to specify more than one P-ID, so the current way is not really optimal for every theoretical use.

There's always one

Personally this is something I'd check in the _module_load function and display an appropriate message if it's not a supported camera. This could then work for more than one camera.

Phil.

Logged

srsa_4c

4262

Re: module api versioning

« Reply #6 on: 11 / March / 2013, 19:56:39 »

Quote from: philmoz on 11 / March / 2013, 17:23:42

Personally this is something I'd check in the _module_load function and display an appropriate message if it's not a supported camera. This could then work for more than one camera.

Right, I haven't noticed that the P-ID is available in the conf structure. In this case, it doesn't make much sense to keep it.

Logged

Menu jumping/flickering on M10?