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.d
igium.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
_______________________________________________
--Bandwidth and Colocation Provided by http://www.api-digital.c
om--
zaptel-commits mailing list
To UNSUBSCRIBE or update options visit:
http://lists.digium.com/mailman/listinfo/zaptel-commits
|