[zaptel-commits] tzafrir: branch 1.4 r4106 - /branches/1.4/README

[SVN commits to the Zaptel project]

Author: tzafrir
Date: Sat Mar 29 01:30:02 2008
New Revision: 4106

URL: http://svn.digium.com/view/zaptel?view=rev&rev=4106
Log:
Document some ABI changes.

Modified:
    branches/1.4/README

Modified: branches/1.4/README
URL: http://svn.digium.com/view/zaptel/branches/1.4/README?view=diff&rev=4106&r1=4105&r2=4106
==============================================================================
--- branches/1.4/README (original)
+++ branches/1.4/README Sat Mar 29 01:30:02 2008
@@ -576,6 +576,89 @@
 
            2 XPP_FXS/0/0/1 FXOLS (In use)
 
+
+ABI Compatibility
+~~~~~~~~~~~~~~~~~
+Like any other kernel code, Zaptel strives to maintain a stable
+interface to userspace programs. The API of Zaptel to userspace
+programs, zaptel.h, has remained backword-compatible for a long time and
+is expected to remain so in the future. With the ABI (the bits
+themselves) things are slightly trickier.
+
+Zaptel's interface to userspace is mostly ioctl(3) calls. Ioctl calls
+are identified by a number that stems from various things, one of which
+is the size of the data structure passed between the kernel and
+userspace. 
+
+Many of the Zaptel ioctl-s use some sepcific structs to pass information
+between kernel and userspace. In some cases the need arose to pass a few
+more data members in each call. Simply adding a new member to the struct
+would have meant a new number for the ioctl, as its number depends on
+the size of the data passed.
+
+Thus we would add a new ioctl with the same base number and with the
+original struct.
+
+So suppose we had the following ioctl:
+------------------------------------
+struct zt_example {
+	int sample;
+}
+
+#define ZT_EXAMPLE     _IOWR (ZT_CODE, 62, struct zt_example)
+------------------------------------
+
+And we want to add the field 'int onemore', we won't just add it to the
+struct. We will do something that is more complex:
+------------------------------------
+/* The original, unchanged: */
+struct zt_example_v1 {
+	int sample;
+}
+
+/* The new struct: */
+struct zt_example {
+	int sample;
+	int onemore;
+}
+
+#define ZT_EXAMPLE_V1  _IOWR (ZT_CODE, 62, struct zt_example_v1)
+#define ZT_EXAMPLE     _IOWR (ZT_CODE, 62, struct zt_example)
+------------------------------------
+We actually have here two different ioctls: the old ZT_EXAMPLE would be
+0xC0044A3E . ZT_EXAMPLE_V1 would have the same value. But the new value
+of ZT_EXAMPLE would be 0xC0084A3E .
+
+Programs built with the original zaptel.h (before the change) use the
+original ioctl, whether or not the kerenl code is actually of the newer
+version. Thus in most cases there are no compatibility issues.
+
+When can we have compatibility issues? if we have code built with the
+new zaptel.h, but the loaded kernel code (modules) are of the older
+version. Thus the userspace program will try to use the newer ZT_EXAMPLE
+(0xC0084A3E). But the kernel code has no handler for that ioctl. The
+result: the error 25, ENOTTY, which means "Inappropriate ioctl for
+device".
+
+As a by-product of that method, for each interface change a new #define
+is added. That definition is for the old version and thus it might
+appear slightly confusing in the code, but it is useful for writing code
+that works with both versions of Zaptel. 
+
+Past Incompatibilities
+^^^^^^^^^^^^^^^^^^^^^^
+.Zaptel 1.4.8:
+* ZT_GET_PARAMS_V1
+* ZT_SET_PARAMS_V1
+* ZT_SPANINFO_V2
+
+.Zaptel 1.4.6:
+* ZT_SPANINFO_V1
+
+ZT_SPANINFO_V1 was originally called (up to zaptel 1.4.8)
+"ZT_SPANINFO_COMPAT".
+
+
 PPP Support
 -----------
 Zaptel digital cards can provide data channels through ppp as