[OpenAFS-devel] afsd & libafs module version checking??

[Jeffrey Hutzelman]

On Wednesday, December 14, 2005 09:04:57 AM -0500 Tom Keiser 
<tkeiser@gmail.com> wrote:

> Basing this on cml_version_number has a few disadvantages:
>
> (1)compile date becomes part of the decision
> (2)autoconf flags cannot change syscall and ioctl interface behavior
> (3)it's overly brittle; the kernel interfaces shouldn't be assumed to
> change between every minor revision
> (4)because of the packaging issues Russ brought up, we would end up
> sending spurious warnings to users (who would probably send in
> unnecessary bug reports)

Indeed, this is not what the CML version number is for, and overloading it 
for that purpose is a bad idea.  I've had too many bad experiences with 
software that breaks because it insists on exact matching of software 
version numbers instead of using interface versions.


> Instead, I'd propose we define a monotonically increasing kernel
> interface version counter that gets incremented by the developer
> whenever backwards-incompatible changes are made to a syscall or ioctl
> interface.  Even this seems a bit harsh since a change to an
> afsd-specific syscall would cause the fs command to issue warnings.
> Should there instead be a few version counters that codify stability
> of different subsets of the kernel interfaces in a way that is
> meaningful to our userspace apps (e.g. common interfaces,
> afsd-specific interfaces, inode interfaces, pioctl interfaces, etc.)?

I think there is a distinction to be made here.  The afsd-libafs interface 
is an internal interface, and while we'd like it to be backward compatible, 
the components are tightly bound and it is reasonable to expect that if you 
upgrade one you might have to upgrade the other.  Introducing an interface 
version for this interface (particularly, AFSCALL_CALL) is probably a good 
idea.


However, the pioctl interface is a _public_ interface.  It's expected to 
interoperate not only with other versions of OpenAFS, but also with other 
implementations, including arla and a number of utilities that make their 
own system calls.  The operation codes are coordinated, and the parameters 
and behavior for each operation are reasonably well-defined.  I can think 
of only one occasion in which a change was made to one of these interfaces, 
and that was over 10 years ago, when the code was maintained by a different 
entity which did not consider these to be public interfaces (and even then, 
it was an ill-considered change).  I don't think it will be repeated any 
time soon.

In short, I think it's entirely reasonable to introduce an afsd-libafs 
interface version, and a mechanism for querying it.  But I don't think we 
need such a version for the public interfaces, and I suspect it would be 
counterproductive to introduce one.


> Personally, i'd rather see it added as a syscall since you're not
> dealing with a path.  Regardless, the version query interface should
> be defined carefully, and declared immutable.

A query-version for the afsd-libafs interface is part of that interface, 
and so should be provided as an operation of AFSCALL_CALL, like the rest of 
that interface.

If we really wanted to provide a query-version operation for the public 
pioctl interface, that should be done as a pioctl, preferably with an 
opcode in the coordinated 'C' space, rather than in the openafs-private 'O' 
space (note that we decided some time ago not to add new ioctl or pioctl 
opcodes in the 'V' space, to avoid potential conflicts with codes assigned 
by IBM without coordination).

While I agree that it would be desirable to separate cache manager 
configuration, status, and control operations from true path-based 
operations, at the moment they are part of the same interface, and as I 
noted above, that is a public, coordinated interface, which we can 
reasonably expect other implementors to support.  And, because it is quite 
regular, it is possible to provide a pioctl() syscall stub which does not 
know the details of every possible pioctl; in fact, both OpenAFS and 
libkafs include such a stub.  Adding a new syscall for querying an 
interface version would unnecessarily place an undue burden on users of 
such libraries, as they would be unable to perform a version query without 
a new enough library.

-- Jeff