Training for Ankit (1)

Today I was at customers development centre. Ankit is to develop the driver for the hardware they develop. This post will record the session that I had with Ankit.

Ankit was new to kernel programming. Even I have not mastered this beast well. Neverthless, I got Ankit started with it.

1. Zaptel discussion

It is not necessary to define a span in case of an FXS/FXO. Just need to define a channel.
However, for registering fxs/fxo also, we pass a span argument to zaptel. I asked Ankit to look at span as an abstraction for a device (E1 card, FXS etc) which 'n' channels. (n = 1, for FXS)
I showed him how to define a fxo channel.
zaptel.conf
loadzone = us
defaultzone = us
fxsks=1
zapata.conf (Additions only)
signalling=fxs_ks
callerid="Green Phone"<(256) 428-6121>
channel => 1
extensions.conf additions
exten => 1000,1,Dial(Zap/1)

2. Kernel module programming

To program kernel modules, you need to have kernel source for your current kernel.
I asked him to first download LDD3.
Then, we copied the code from second chapter and compiled the module.
This had to be done on my laptop, as he did not have kernel sources installed on his system.

#include
#include
MODULE_LICENSE("Dual BSD/GPL");
static int hello_init(void)
{
printk(KERN_ALERT "Hello, world\n");
return 0;
}
static void hello_exit(void)
{
printk(KERN_ALERT "Goodbye, cruel world\n");
}
module_init(hello_init);
module_exit(hello_exit);

Then we created the makefile

obj-m += tzap.o
EXTRA_CFLAGS += -I/root/zaptel/kernel

all:
make -C /lib/modules/$(shell uname -r)/build M=`pwd` modules

With the make file in place, we compiled the module and inserted it.

1. obj-m is a variable understood by kernel build system
2. obj-m = tzap.o indicates that the name of your module source file is tzap.c
3. EXTRA_CFLAGS defines the extra compile time flags specific for your module
4. In this case that extra flag is not really necessary. But as we do more work with this driver, we will need it.
5. Make command arguments: -C Tells the make to change to before actually running
6. Make command arguments: M=`pwd`defines M, which will be used by kernel build system to determine the directory in which module source is present
7. Make command arguments: modules is the target to build

We invoke the kernel build system which in turn compiles the module for us.

Exported functions of zaptel

Asterisk

zt_transcode_fops
A pointer to file operations structure. This is actually populated by zttranscode module. This is a pointer to __zt_transcode_fops defined by the zttranscode module. There is support for: open, release, ioctl, poll and mmap. This structure helps in transcoding.


zt_init_tone_state
Used to initialize the tone state for DTMF tone generation. These initialized values are used in tone generation.


zt_dtmf_tone
For the current channel, returns the DTMF tone structure for the specified digit.


zt_register
Registers a span with zaptel driver. This, I feel, is a method of registering a device with zaptel. The structure zt_span has all the components that is required for accessing/controlling the device. zt_span structure need to be studied in detail.


zt_unregister
Unregister spans registered using zt_register.


__zt_mulaw
ulaw conversion table.


__zt_alaw
alaw conversion table.


__zt_lineartoulaw
Function to convert linear samples to ulaw samples.


__zt_lineartoalaw
Function to convert linear samples to alaw samples.


__zt_lin2mu
Table for converting linear samples to ulaw samples


__zt_lin2a
Table for converting linear samples to alaw samples.


zt_lboname
Retrieve the LBO name strings from an array. LBO: Line build-out. Expressed in DBs. Decides the electrical length


zt_transmit
Transmit a chunk from the channel. There is more to it. Does some processing of slave channels etc. Need to see in detail.


zt_receive
Receives a chunk.Similar to zt_transmit. But it also handles in-band tones.


zt_rbsbits
Process robbed bit signaling. This is based on the channel signaling type.


zt_qevent_nolock
Queue an event for a channel. Do not lock the channel before doing it.


zt_qevent_lock
Queue an event for a channel. Lock the channel before queuing it.


zt_hooksig
Send hook status. (Off hook, on hook, ring etc)


zt_alarm_notify
Send an alarm to all channels in a span.


zt_set_dynamic_ioctl
Dynamically change the ioctl functions by passing a pointer to a new ioctl function.


zt_ec_chunk
Does echo cancellation on a chunk.


zt_ec_span
Does echo cancellation on an entire span.


zt_hdlc_abort
Send hdlc abort events to the channel.


zt_hdlc_finish
Read any remaining data from the channel.


zt_hdlc_getbuf
Copy data from the passed buffer to the output buffer.


zt_hdlc_putbuf
Copy data from the channel buffer to the passed buffer.


zt_alarm_channel
Send the alarm events to the channel.


zt_register_chardev
Register a character driver. Used by transcode module.


zt_unregister_chardev
Unregister the character device. Used by transcode module.


zt_dynamic_register
Takes a pointer to the driver structure and puts it on top of a linked list. The head of the linked list is a global variable called drivers.


zt_dynamic_unregister
Removes the driver from drivers linked list.


zt_dynamic_receive
Receive data for a channel. (Note: This and 3 functions above are for TDM over X. Currently X is ethernet)


zt_transcoder_register
List the transcoder in the global linked list 'trans'.


zt_transcoder_unregister
Remove the transcoder from the linked list pointed by trans


zt_transcoder_alert
Send an alert to the transcoder by setting an alert bit on transcoder status variable.


zt_transcoder_alloc
Allocate memory for a specified number of channels and initialize associated variables.


zt_transcoder_free
Free the memory allocated for a given transcoder.

Whats next?
a. Study the user space interaction of asterisk with zaptel (Chan_zap?)
b. Study the data flow in kernel
c. Study the working of a particular driver

I think, I will start with a & later move to b & c. In fact, it will be difficult to separate b & c.

Files

Below are the files that I want to concentrate on at the beginning

zaptel-base.c
zaptel.h
zconfig.h
ztd-eth.c
ztd-loc.c
ztdummy.c
ztdummy.h
ztdynamic.c
zttranscode.c

There is a large set of symbols that zaptel-base.c exports. First let me list all symbols that are being exported. (This symbol set, I guess, should define the API available for zaptel compatible drivers)

From zaptel-base.c

zt_transcode_fops
zt_init_tone_state
zt_dtmf_tone
zt_register
zt_unregister
__zt_mulaw
__zt_alaw
__zt_lineartoulaw
__zt_lineartoalaw
__zt_lin2mu
__zt_lin2a
zt_lboname
zt_transmit
zt_receive
zt_rbsbits
zt_qevent_nolock
zt_qevent_lock
zt_hooksig
zt_alarm_notify
zt_set_dynamic_ioctl
zt_ec_chunk
zt_ec_span
zt_hdlc_abort
zt_hdlc_finish
zt_hdlc_getbuf
zt_hdlc_putbuf
zt_alarm_channel
zt_register_chardev
zt_unregister_chardev


From ztdynamic.c

t_dynamic_register
zt_dynamic_unregister
zt_dynamic_receive


From zttranscode.c

zt_transcoder_register
zt_transcoder_unregister
zt_transcoder_alert
zt_transcoder_alloc
zt_transcoder_free


In coming days/hours I plan to make each of this symbol a link and write about the functionality of each item.

Asterisk/Zaptel/DAHDI

This is an attempt to study the zaptel interface used by Asterisk for enabling a few custom cards to work with Asterisk. I had started it few days back and plan to continue it for a while. When ever I find something interesting, I will post it here.