diff options
Diffstat (limited to 'README')
-rw-r--r-- | README | 83 |
1 files changed, 83 insertions, 0 deletions
@@ -576,6 +576,89 @@ see an extra '(In use)': 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 |