Re: [PATCH 02/39] wimax: declarations for the in-kernel WiMAX API

Johannes Berg
2008-11-27T09:32:50Z

[-- Attachment #1: Type: text/plain, Size: 1950 bytes --]

On Wed, 2008-11-26 at 15:07 -0800, Inaky Perez-Gonzalez wrote:

> + * NOTE: this versioning is a last resort to avoid hard
> + * incompatibilities. It is the intention of the design of this
> + * stack not to introduce backward incompatible changes.
> + *
> + * The version code has to fit in one byte (restrictions imposed by
> + * generic netlink); we use `version / 10` for the major version and
> + * `version % 10` for the minor. This gives 9 minors for each major
> + * and 25 majors.
> + *
> + * The version change protocol is as follow:
> + *
> + * - Major versions: needs to be increased if an existing message/API
> + * call is changed or removed. Doesn't need to be changed if a new
> + * message is added.
> + *
> + * - Minor verion: needs to be increased if new messages/API calls are

small typo there

> + * being added or some other consideration that doesn't impact the
> + * user-kernel interface too much (like some kind of bug fix) and
> + * that is kind of left up in the air to common sense.
> + *
> + * User space code should not try to work if the major version it was
> + * compiled for differs from what the kernel offers. As well, if the
> + * minor version of the kernel interface is lower than the one user
> + * space is expecting (the one it was compiled for), the kernel
> + * might be missing API calls; user space shall be ready to handle
> + * said condition.
> + *
> + * libwimax:wimax_open() takes care of checking versions.

Why bother versioning the API? Since this is generic netlink, and things
are looked up by the family name, a completely new version would just
use a new family name and be done with it, old userspace won't even
_find_ that new "version" of the API. The "minor version" seems also
useless, either you can do the change in a backward compatible way or
you cannot and need to provide compat code.

I'd just remove this.

johannes

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 836 bytes --]