Eurotech CTR-1472/CTR-1475

From EnneEnneWiki

Contents 1 References 2 Compilation 2.1 Compiling and loading the driver 2.2 Compiling the utilities 3 The driver's devices 3.1 The file /dev/ctr1472 3.2 The files /dev/ctr1472encX 3.3 The files /dev/ctr1472mdX 4 The driver's structures 4.1 The structure ctr1472_video_s 4.2 The structure ctr1472_monitor_s 4.3 The structure ctr1472_encoding_s 4.4 The structure ctr1472_osd_s 4.5 The structure ctr1472_md_s 4.6 The structure ctr1472_md_data_s 5 The driver's system calls 5.1 open() 5.2 close() 5.3 read() 5.4 mmap() 5.5 ioctl() 6 The utilities 6.1 encoding 6.2 monit 6.3 osd 6.4 md 6.5 io 7 The procfs support 7.1 The file status 7.2 The file monitor 7.3 The directory video 8 FAQ 8.1 General questions 8.2 Video encoding questions

This driver implements the support for Linux 2.6 series of the Eurotech CTR-1472 and CTR-1475 (the RoHS version). These boards are a four channel MPEG-4 encoder and motion detection system.

The driver should support multiple boards even if it has been tested with only one board on a Linux 2.6.32.

This manual will show how to compile the driver and how to use the methods it exports into the user space in order to allow a normal process to get MPEG-4 streams and to manage all (most) supported by CTR-1472 and CTR-1475's features.

References

The boards' main references are at Eurotech's sites: CTR-1472, CTR-1475.

The stable driver's source code is available on my GITWeb as unofficial site but you can contact the Eurotech's Technical Support in order to have an official version.

To download the code you need the GIT tools and then using the following command:

giometti@zaigor:~$ git clone git://git.enneenne.com/ctr1472

after the clone is finished into directory ctr1472 you can find the code.

Stable code is under branch master, while unstable code are under branch develop.

Compilation

This driver has a main part (the driver itself) and one subparts that is the utilities.

This section will show you how to compile these parts.

Compiling and loading the driver

To compile the driver you need an already configured Linux 2.6.x source tree for your system (or for the one who should manage the CTR-1472).

Currently the driver should work for Linux version 2.6.x where x is greater than 31. My testing system was a PC104 CPU board (Eurotech CPU-1432, i386 architecture) running Linux version 2.6.32 (vanilla), so please, refer to this kernel version.

Once you have exploded the tarball you should get the following directory listing:

$ ls
Makefile   firmware   io.c     pca9544.c   saa7121h.c  tables_font.c
ap5200.c   global.c   ioctl.c  pca9555.c   saa7146a.c  tables_video.c
ctr1472.h  i2c.c      load     procfs.c    scripts     unload
debi.c     ime6400.c  main.c   saa7113h.c  sysdep.h    utils

The directory:

• Directory utils holds several testing utilities (#The utilities).
• Directory firmware holds special (and proprietary) firmware code who is needed by the driver in order to manage some internal chips.
• Directory scripts holds special scripts whose are needed during driver compilation stage.

To compile the driver and the utilities you can just give the command make but before this I think is better you know something about compilation variables.

Looking at the Makefile we can see that is possible to do special settings by modifying the following variables' default values:

• MAJOR - Defines the default driver's major number. Just set it to a values greater than zero if you wish to fix a special value or just leave it to zero if you wish the system will choose one for you.
• VIDEO_MEM_BLOCKS - Defines how many memory blocks the driver can use for buffering the MPEG-4 streams. A block is 1KB large. Largest allowed value is 4096 (4MB).

This buffer should be greater as your CPU is slower, in fact fast CPUs can keep this value small but if your CPU is slow and your system is heavily load you should consider increasing the default value.

• FIRMWARE - Defines which firmware should be used into the driver. Please DO NOT MODIFY this variable unless you know what you are doing!
• PROCFS - Just enable or disable the procfs support into the driver (see #The procfs support). Note: on kernels 2.6 this is deprecated.

Note that you don't need this support if you use the C programming language to access the device.

• KERNELDIR - Defines where the compiler may find your (well configured) kernel source tree.
• DEBUG - Just enable the debugging mode.

Do not modify it unless you decide to help me in enhancing this driver! :)

Just for example here is shown the command (and its output on my machine) to compile the driver with 3072 video blocks:

$ make VIDEO_MEM_BLOCKS=3072
make -C /lib/modules/2.6.32-24-generic/build/ SUBDIRS=/home/giometti/Projects/eurotech/ctr1475/ctr1475 modules
make[1]: Entering directory `/usr/src/linux-headers-2.6.32-24-generic'
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/main.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/global.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/ioctl.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/procfs.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/debi.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/i2c.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/io.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/ap5200.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/ime6400.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/saa7146a.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/saa7113h.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/saa7121h.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/pca9544.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/pca9555.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/tables_video.o
  CC [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/tables_font.o
  LD [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/ctr1472.o
  Building modules, stage 2.
  MODPOST 1 modules
  CC      /home/giometti/Projects/eurotech/ctr1475/ctr1475/ctr1472.mod.o
  LD [M]  /home/giometti/Projects/eurotech/ctr1475/ctr1475/ctr1472.ko
make[1]: Leaving directory `/usr/src/linux-headers-2.6.32-24-generic'
[snip...]

Once the compilation is finished you can try to install the driver into your system by using the utility load as follows:

$ sudo ./load 
Copying mp4-P.bin firmware in /lib/firmware/ctr1472_mp4-P.fw... done
Loading ctr1472 device driver (./ctr1472.ko)......... done

By default you'll get both compilation of driver and utilities.

Compiling the utilities

To compile the utility tools there is nothing special to do, just use the command make utils or go into the utils directory and give the command:

giometti@zaigor:~/Projects/eurotech/ctr1472/utils$ make
cc -Wall  -D_GNU_SOURCE -I.. -O2 -I. -M  avilib.c encoding.c monit.c osd.c md.c 
io.c > .depend
cc -Wall  -D_GNU_SOURCE -I.. -O2 -I.   -c -o encoding.o encoding.c
encoding.c: In function `main':
encoding.c:179: warning: unused variable `buf'
cc -Wall  -D_GNU_SOURCE -I.. -O2 -I.   -c -o avilib.o avilib.c
cc   encoding.o avilib.o   -o encoding
cc -Wall  -D_GNU_SOURCE -I.. -O2 -I.   -c -o monit.o monit.c
cc   monit.o   -o monit
cc -Wall  -D_GNU_SOURCE -I.. -O2 -I.   -c -o osd.o osd.c
cc   osd.o   -o osd
cc -Wall  -D_GNU_SOURCE -I.. -O2 -I.   -c -o md.o md.c
cc   md.o   -o md
cc -Wall  -D_GNU_SOURCE -I.. -O2 -I.   -c -o io.o io.c
cc   io.o   -o io

Note that some programs need the library avilib to compile. If haven't it and you are using a i386 compatible system I provided the needed files to compile, so you shouldn't have problems. Otherwise you must install such library to get your tools.

See paragraph The utilities, in order to know how to use these utilities.

The driver's devices

This driver implements several "virtual" devices. They are just some "specialized" devices who can be used to do a very simple access to some device's features.

Once you have installed the driver (by using the load command) you should get the following files into your /dev directory:

giometti@jeeg:~/Projects/eurotech/ctr1472$ ls /dev/ctr1472*
/dev/ctr1472@        /dev/ctr1472_0_md3   /dev/ctr1472_1_md3
/dev/ctr1472_0       /dev/ctr1472_1       /dev/ctr1472enc0@
/dev/ctr1472_0_enc0  /dev/ctr1472_1_enc0  /dev/ctr1472enc1@
/dev/ctr1472_0_enc1  /dev/ctr1472_1_enc1  /dev/ctr1472enc2@
/dev/ctr1472_0_enc2  /dev/ctr1472_1_enc2  /dev/ctr1472enc3@
/dev/ctr1472_0_enc3  /dev/ctr1472_1_enc3  /dev/ctr1472md0@
/dev/ctr1472_0_md0   /dev/ctr1472_1_md0   /dev/ctr1472md1@
/dev/ctr1472_0_md1   /dev/ctr1472_1_md1   /dev/ctr1472md2@
/dev/ctr1472_0_md2   /dev/ctr1472_1_md2   /dev/ctr1472md3@

The files /dev/ctr1472_0* address the first CTR-1472, while the files /dev/ctr1472_1* address the second one and so on.

Please, note that I used two boards so you have a different configuration you will get a different number of files.

The files /dev/ctr1472, /dev/ctr1472enc0, /dev/ctr1472md0, etc, are symbolic links to files /dev/ctr1472_0, /dev/ctr1472_0_enc0,/code>, <code>/dev/ctr1472_0_md0.

In the next paragraphs I refer to the symbolic link files for simplicity but everything I say can be applied to the device files of each boards installed on your system. For example, when I use the file /dev/ctr1472 you can replace it with /dev/ctr1472_0 or /dev/ctr1472_1, when I use the file /dev/ctr1472md0 you replace it with file /dev/ctr1472_0_md0 or /dev/ctr1472_0_md1 and so on.

The file /dev/ctr1472

This file is the most important one since it represents the driver itself. So you should use it everywhere in order to get access to the CTR-1472 from a C program.

The files /dev/ctr1472encX

These files can be used to get an encoded stream by using simple command line tools.

For example you can get a RAW stream in NTSC format form channel 0 by using the following command line:

jeeg:~# echo ntsc > /proc/driver/ctr1472/0/video/norm
jeeg:~# cat /dev/ctr1472enc0 > /tmp/stream.0.raw

To stop the encoding just hit C-c.

Note that the RAW data stream cannot be read by any known playback tool since it is strictly board dependent (see the source of the utility encoding in order to know how you can manage RAW data format).

The files /dev/ctr1472mdX

These files can be used to manage motion detection by using simple command line tools.

For example you can get motion detection data for channel 0 by using the following command lines commands:

giometti@jeeg:~/Projects/eurotech/ctr1472$ od -v -tx1 /dev/ctr1472md0
0000000 01 00 00 00 00 00 f3 09 00 0d 00 00 e6 00 de 4a
0000020 00 00 00 00 66 07 80 05 00 00 00 00 00 00 00 00
0000040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

The read() is blocking until a motion detection event arrives then you'll get the structure struct ctr1472_md_data_s in hexadecimal format.

The example showed above says to you that a motion detection event is arrived (first word) on channel 0 (second word).

The driver's structures

To modify the device settings by using the C programming language you can use several @code{ioctl()} commands (see #ioctl()). Most of these commands use a special structure to pass data to/from the driver.

Here I'll explain these structures' fields and which commands they are associated to.

The structure ctr1472_video_s

This structure can be used to manage video settings. It is defined as follow:

struct ctr1472_video_s {
   __u8 brightness;
   __u8 contrast;
   __u8 saturation;
   __u8 hue;
};

It is used by the ioctl() commands: CTR1472_VID_GET_CH0...CTR1472_VID_GET_CH3 and CTR1472_VID_SET_CH0...CTR1472_VID_SET_CH3.

Its fields are:

• brightness - Set the brightness of the input channel selected.
• contrast - Set the contrast of the input channel selected.
• saturation - Set the saturation of the input channel selected.
• hue - Set the hue of the input channel selected.

The structure ctr1472_monitor_s

This structure can be used to manage monitoring function. It is defined has follow:

struct ctr1472_monitor_s {
   int mode;
   __u8 channel;
   __u8 channel_ul;
   __u8 channel_ur;
   __u8 channel_ll;
   __u8 channel_lr;
};

It is used by the ioctl() commands: CTR1472_MON_GET and CTR1472_MON_SET.

The fields are:

• mode - Set the monitoring mode.

Valid values are:

• • CTR1472_MON_DISABLED - Disable all monitoring functions.
  • CTR1472_MON_FULL - Set the FULL monitoring mode using as input channel the one specified into channel. variable.
  • CTR1472_MON_QUAD - Set the QUAD monitoring (In QUAD monitoring mode the output video is divided into 4 parts each of them show a single channel) using as upper left channel the one specified into channel_ul variable, as upper right channel the one specified into channel_ur and so on.
• channel - Select the channel to use in FULL monitoring mode. Allowed values are in [0,CTR1472_MAX_CHANNEL].
• channel_ul, channel_ur, channel_ll and channel_lr - Select the channel to show, respectively in the upper left, upper right, lower left and lower right position for QUAD monitoring mode.

The structure ctr1472_encoding_s

This structure can be used to manage encoding functions. It is defined has follow:

struct ctr1472_encoding_s {
   int mode;
   __u8 channel;
   int norm;
   struct {
      __u8 ctrl;
      __u8 quant;
      union {
         __u32 target;
         struct {
            __u16 min;
            __u16 max;
         } range;
      } value;
   y} bitrate[CTR1472_MAX_CHANNEL];
   __u8 fps_div;
   __u8 audio;
};

It is used by the ioctl() commands: CTR1472_ENC_GET and CTR1472_ENC_SET.

The fields are:

• mode - Set the encoding mode. Valid values are:
  • CTR1472_ENC_FULL - Set FULL encoding mode using as input channel the one specified into channel variable.
  • CTR1472_ENC_QUAD - Set the QUAD monitoring mode. Note that in this mode you don't get an output similar to the monitoring mode, but the device will return four different streams, one for each channels.
  • channel - Set the channel to use in FULL encoding mode.
• norm - Set the norm of all input (and output) channels. The valid values are:
  • CTR1472_ENC_PAL<code> - Set PAL as system norm.
  • <code>CTR1472_ENC_NTSC - Set NTSC as system norm.

Please, note that this setting will affect all device featuring, like, for example, the monitoring. So you can NOT have, for example, a PAL input (encoding) and a NTSC output (monitoring).

• bitrate - This array is used to select the bit rate for each encoding channel. If you use FULL mode you have to setup only the bit rate for the used channel but if you use QUAD mode you have to setup all channels.
  • ctrl - May be set to CTR1472_ENC_VBR for variable bit rate, CTR1472_ENC_CBR for constant bit rate or CTR1472_ENC_HVBR for hybrid variable bit rate (please refere to the IME6400 data sheet for further info.
  • quant - It's the default quality level for the constant bit rate and for the hybrid variable bit rate
  • target - It's the bit rate for he constant bit rate.
  • min and max - They're the minimum and maximum bit rate for hybrid variable bit rate.
• fps_div - Set the frame rate divisor.
  • CTR1472_ENC_FPS_FULL - No dision at all. So for PAL you'll have 25fps and for NTSC you'll have 30fps.
  • CTR1472_ENC_FPS_DIV2, CTR1472_ENC_FPS_DIV4, CTR1472_ENC_FPS_DIV8, CTR1472_ENC_FPS_DIV16, CTR1472_ENC_FPS_DIV32 - Divide the default frame rate by 2, 4, 8, 16 or 32.
• audio - Set the audio encoding type. Valid values are:
  • CTR1472_ENC_NONE - Disable audio encoding.
  • CTR1472_ENC_MPEG1L2 - Use the MPEG1 level 2 audio format.
  • CTR1472_ENC_ULAW - Use the ULAW audio format.
  • CTR1472_ENC_ADPCM - Use the ADPCM audio format.

Please, note that some settings may be not valid depending which firmware you are using.

The structure ctr1472_osd_s

This structure can be used to manage the OSD (On Screen Display) functions. It is defined has follow:

struct ctr1472_osd_s {
   int command;
   __u16 position;
   char string[CTR1472_MAX_OSD_STRING];
   __u8 window;
   __u16 x_ul;
   __u16 y_ul;
   __u16 x_lr;
   __u16 y_lr;
   __u8 color;
   struct ctr1472_osd_colordata_s {
      __u8 y;
      __u8 cb;
      __u8 cr;
   } colordata[CTR1472_OSD_MAX_COLORS-1];
};

It is used by the ioctl() command CTR1472_OSD_SET.

The fields are:

• command - Define the command to execute on OSD screen. The CTR-1472 has two OSD screens: one for monitoring and one for encoding, so you can set up them in different ways. The valid values are:
  • CTR1472_OSD_MON_DISABLED - Disable all OSD functions for the monitoring.
  • CTR1472_OSD_MON_ENABLED - Enable OSD functions for the monitoring.
  • CTR1472_OSD_MON_STRING - Modify the OSD string to display in the monitoring output by using the string hold into string,/code> variable starting at position <code>position and using color color.
  • CTR1472_OSD_MON_ERASE - Erase the OSD string in the monitoring output leaving the OSD function enabled.
  • CTR1472_OSD_MON_WINDOW - Set OSD windows coords in the monitoring output by using variables x_ul, y_ul and so on. Windows type is defined by using variable window. You can use four different windows: windows 0 and 1 are "transparent" (you can still see images under the window) while windows 2 and 3 are "fill" (you can't see images under the window).
  • CTR1472_OSD_ENC_DISABLED - Disable all OSD functions for the encoding.
  • CTR1472_OSD_ENC_ENABLED - Enable OSD functions for the encoding.
  • CTR1472_OSD_ENC_STRING - Modify the OSD string to display in the encoding output by using the string hold into string variable starting at position position and using color color.
  • CTR1472_OSD_ENC_ERASE - Erase the OSD string in the encoding output leaving the OSD function enabled.
  • CTR1472_OSD_STING_COLOR - Set the colors array (hold into colordata array) to use to display the string hold into string variable. Once you have defined these color you can index them by using the color variable (color 0 is reserved as white while colors 1, 2 and 3 index the defined colors).
  • CTR1472_OSD_WINDOW_COLOR - Set the colors array (hold into colordata array) to use to display the OSD windows. First color is for windows 0 and 2 while second color is for windows 1 and 3.
• position - Define the starting position at which OSD string string will be displayed. Valid values are in [0,CTR1472_MAX_OSD_STRING].
• string - Define the OSD string to display.
• window - Define the OSD window to display. Valid values are in [0,CTR1472_OSD_MAX_WINDOWS].
• x_ul, y_ul, x_lr, y_lr - Define the upper left corner coords (x_ul,y_ul) and lower right corner coords (x_lr, y_lr) of the OSD windows.
• color - Index which color to use to display OSD string. Index 0 are reserved while index 1<code>, <code>2 and 3 point to the color defined with the colordata array.
• colordata - Define y, cb and cr components of string or windows colors.

The structure ctr1472_md_s

This structure can be used to manage the motion detection functions. It is defined has follow:

struct ctr1472_md_s {
   int mode;
   __u16 win_row[CTR1472_MD_MAX_WINS_ROWS];
   __u8 low_th;
   __u8 hi_th;
   __u16 md_th;
   __u16 abcd_th;
   __u8 wnum_th;
   __u8 refresh;
};

It is used by the commands: CTR1472_MD_GET_CH0..CTR1472_MD_GET_CH3 and CTR1472_MD_SET_CH0..CTR1472_MD_SET_CH3.

The fields are:

• mode - Set the motion detection mode. Valid values are:
  • CTR1472_MD_DISABLED - Disable the motion detection.
  • CTR1472_MD_ENABLED - Enable the motion detection.
• win_row - Defines the 12x16 detection windows status. Each words define a row and each bits into the word define the on/off windows status.
• low_th - Define the motion detection absolute low threshold (please, see the AP-5200 user manual to have further info).
• hi_th - Define the motion detection absolute hi threshold (please, see the AP-5200 user manual to have further info).
• md_th - Define the motion detection threshold (please, see the AP-5200 user manual to have further info).
• abcd_th - Define the ABCD (A Blind Camera Detection) threshold (please, see the AP-5200 user manual to have further info).
• wnum_th - Define the threshold of window number for generating a motion detection event (please, see the AP-5200 user manual to have further info).
• refresh - Define the refreshing interval of reference image (please, see the AP-5200 user manual to have further info).

The structure ctr1472_md_data_s

This structure can be used to get motion events. It is defined has follow:

struct ctr1472_md_data_s {
   __u16 id;
   __u16 channel;
   __u16 win_row[CTR1472_MD_MAX_WINS_ROWS];
};

It is used by the ioctl() command CTR1472_MD_WAIT_DATA.

The fields are:

• id - Defines the event type. Valid values are:
  • CTR1472_MD_ID_MD - The current event is a motion detection event.
  • CTR1472_MD_ID_ABCD - The current event is an ABCD event.
• channel - Address the channel where the event has been got.
• win_row - Holds the windows detection status when the event occurred.

The driver's system calls

To get the best performance in using this driver you must use the C programming language with the following system calls.

open()

Use this method to get the first access to the device in order to get a file descriptor to be used in the following system calls.

Here a little code to show how to obtain a file descriptor:

   devfd = open("/dev/ctr1472", O_RDWR);
   if (devfd < 0) {
       PERR("unable to open CR1472 device (\"%m\")");
      exit(EXIT_FAILURE);
   }

The open() system call may be called more times but keep in mind that:

1. Only the first time the open() is invoked the device is activated.
2. Multiple access to the device must be serialized by the specific applications. A system call is atomic but multiple ones are _not_ from each other!

Please refer to man 2 open in order to have further information on open() usage.

close()

Once you have finished in using the device you should call this system call in order to signal the driver you are no more interested in using it.

Last close call is the one who disactivates all device activities.

Please refer to man 2 close<code> in order to have further information on <code>close() usage.

read()

This system call is implemented for devices /dev/ctr1472encX and /dev/ctr1472mdX,/code>. If you try to use this system call on the main device <code>/dev/ctr1472 you'll get an error.

By using this system call you can read encoded streams or motion detection events form the driver. The system call will suspend the calling process until some data are available.

Note that this system call is not optimal for reading encoded streams since it require a double data copy to work. So I suggest to use the @code{ioctl} interface instead (see #ioctl()).

Please refer to man 2 read in order to have further information on read() usage.

mmap()

This system call allows a process to directly map the driver memory into its memory image. By doing this you can avoid the double copying of the read() system call when reading the encoded stream.

Here a little code to show how use the mmap() and ioctl() system calls together:

   ret = ioctl(devfd, CTR1472_ENC_GET_MEM_SIZE, &mblocks);
   if (ret < 0) {
      PERR("unable to get memory size (\"%m\")");
      exit(EXIT_FAILURE);
   }

   ret = ioctl(devfd, CTR1472_ENC_GET_BLOCK_SIZE, &sblock);
   if (ret < 0) {
      PERR("unable to get min block size (\"%m\")");
      exit(EXIT_FAILURE);
   }

   smem = mblocks*sblock;
    addr = mmap(0, smem, PROT_READ, MAP_FILE|MAP_SHARED, devfd, 0);
   if (addr == MAP_FAILED) {
      PERR("unable to mmap() device (\"%m\")");
      exit(EXIT_FAILURE);
   }

With the first ioctl() command returns the reserved memory size in blocks. then the second command gets the memory block size (currently this value is fixed to 1KB but it may change in the future).

Once you know the reserved memory size in bytes (mblocks*sblock you can execute the mmap() system call and get the pointer addr who can be used to directly access to the driver memory.

ioctl()

This is the most important system call (with mmap() of this driver. By using this syscall you can setup all device features and you can get encoded streams and motion events.

Lets start explaining all ioctl() commands:

• CTR1472_VID_GET_CH0..CTR1472_VID_GET_CH3 - Get the video status for selected channel. The command gets a pointer to the structure ctr1472_video_s.
• CTR1472_VID_SET_CH0..CTR1472_VID_SET_CH3 - Set the video status for selected channel. The command gets a pointer to the structure ctr1472_video_s.
• CTR1472_MON_GET and CTR1472_MON_SET - Get and set the monitoring settings. The commands get a pointer to the structure ctr1472_monitor_s.
• CTR1472_MON_CLEAN - Clean monitor memory. Usefull when you have less than 4 camers in quad mode

and you don't wish seeing dust in unconnected channels.

• CTR1472_ENC_GET and CTR1472_ENC_SET - Get and set the encoding settings. The commands get a pointer to the structure ctr1472_encoding_s.

Please note that these commands do not start the encoding but they simply set up its parameters.

• CTR1472_ENC_GET_MEM_SIZE - Get the reserved memory size for encoding in blocks. The command must

supply a pointer to an unsigned integer where the driver will store the memory size. This command can be used before doing a mmap() call (see #mmap()).

• CTR1472_ENC_GET_BLOCK_SIZE - Get the reserved memory block size. The command must supply a pointer to an unsigned integer where the driver will store the data.

Currently this value is fixed to 1KB but it may be change in future driver release so I suggest to use this system call to get the block size instead of usung a fixed value. This command can be used before doing a mmap() call .

• CTR1472_ENC_START - Start the encoding activities.

Once you have mapped the driver memory into the process image by using the mmap() system call you can use this command to signal the device to start the encoding.

• CTR1472_ENC_WAIT_DATA - Wait for encoded data.

After starting the encoding activities you should use this command to wait for available encoded data. Your process will be blocked until new encoded data are available. When new data arrives sleeping process will be awaked and the driver will return how many data blocks you can read. This information will be stored into the variable passed to the command by its pointer. If something went wrong during encoding activities the ioctl() system call will return an error (EIO) and you should check the encoding flags (with the ioctl() command CTR1472_ENC_GET_ERRORS, see below) in order to know what happens.

• CTR1472_ENC_GET_ERRORS - Return the encoding flags.

These flags are set if something went wrong during encoding activities. Allowed values are:

• • CTR1472_ERR_BUFFER_OVERFLOW - The internal buffers went filled.

When you got such error it means your process was not so quick to read all encoded data. Try to modify your algorithm or increase driver internal memory (see #Compiling and loading the driver).

• • CTR1472_ERR_INTERNAL_IO - Internal data flow error.

When you got such error it means something really wrong happen into the driver! Try to restart the encoding or, if you still get this error, try to write to me a note...

• CTR1472_ENC_DISCARD_BLOCKS - Once you have read the encoded stream you should inform the driver how many blocks you read so it can deallocate them to be used for future encoded data.

If you forget doing it the internal buffer will fill quickly and you'll get an overflow error.

• CTR1472_ENC_STOP - Stop the encoding.
• CTR1472_OSD_SET - Set the OSD. The command gets a pointer to the structure ctr1472_osd_s.
• CTR1472_MD_GET_CH0..CTR1472_MD_GET_CH3 - Get the motion detection status for selected channel. The command gets a pointer to the structure ctr1472_md_s.
• CTR1472_MD_SET_CH0..CTR1472_MD_SET_CH3 - Set the motion detection status for selected channel. The command gets a pointer to the structure ctr1472_md_s.

Please note that these commands do not start the motion detection but they simply set up its parameters.

• CTR1472_MD_START - Start the motion detection activities.
• CTR1472_MD_WAIT_DATA - Wait for motion detection data.

Once you started the motion detection you should use this command to wait for new motion events. The calling process will be blocked until new data arrives. At that point the driver will awake the process and it will store the motion data into the structure ctr1472_md_data_s passed with this command. Note that the command returns only one event at time! If something went wrong during motion detection activities the system call will return an error (EIO) so you should check the motion flags in order to know what happened (the error code are the same of encoding flags shown above).

• CTR1472_MD_GET_ERRORS - Return the motion error flags.

Allowed valued are the same as encoding error flags shown above.

• CTR1472_MD_STOP - Stop the motion detection activities.

Please refer to man 2 ioctl in order to have further information on ioctl() usage.

The utilities

Here a little tutorial about several testing utilities. Each utility has been used to test a special feature of CTR-1472.

encoding

This utility reads RAW data directly from the CTR-1472 and makes an AVI file or returns an MPEG stream.

This program shows how is possible to use ioctl() and mmap() syscalls to get encoded data. Use the following command to get an AVI file:

giometti@jeeg:~$ ./encoding -c 0 -n pal -o stream.avi
encoding: Eurotech CT1472 audio/video encoding - version 1.0.0
encoding: Copyright (C) 2005 - Eurotech S.p.A. <support@eurotech.it>
encoding: Copyright (C) 2005 - Rodolfo Giometti <giometti@linux.it>
encoding:    saving AVI stream 0 (channel 0) into "stream.avi"
encoding:    FULL mode on channel 0
encoding:    CBR at br=61440b/s, q=10
encoding:    video stream 0 is pal 720x576 at 25.0fps
encoding:    audio stream 0 is disabled
encoding:    encoding memory is 2097152B (2048KB)
encoding:    encoding memory blocks are 2048
encoding:    encoding memory block size is 1024B
0I0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0
P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0I0P0P0P0P0P0P
0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0P0
Pdev2avi: AVI file(s) closed

Here another example who shows how you can send an MPEG stream across the network. In the following example I used two Gnu/Linux machines: zaigor who are running the X-Window system and jeeg who carries the CTR1472.

giometti@zaigor:~$ netcat -l -p 12345 | mplayer -fps 25 -

Run the mplayer on zaigor.

giometti@jeeg:~$ ./encoding -M -p | netcat zaigor 12345
encoding: Eurotech CT1472 audio/video encoding - version 1.0.0
encoding: Copyright (C) 2005 - Eurotech S.p.A. <support@eurotech.it>
encoding: Copyright (C) 2005 - Rodolfo Giometti <giometti@linux.it>
encoding:    sending stream 0 to stdout
encoding:    FULL mode on channel 0
encoding:    CBR at br=61440b/s, q=10
encoding:    video stream 0 is pal 720x576 at 25.0fps
encoding:    audio stream 0 is disabled
encoding:    encoding memory is 2097152B (2048KB)
encoding:    encoding memory blocks are 2048
encoding:    encoding memory block size is 1024B

That's all. :)

monit

This utility sets the monitoring functions for the CTR-1472.

To enable FULL monitoring for channel 1, use:

giometti@jeeg:~$ ./monit f 1
monit: Eurotech CT1472 monitoring setup - version 1.0.1
monit: Copyright (C) 2004 - Eurotech S.p.A. <support@eurotech.it>
monit: Copyright (C) 2004 - Rodolfo Giometti <giometti@linux.it>
monit: FULL mode for channel 1 set

To enable QUAD monitoring for all channels with channel 0 in the upper left corner, channel 1 in upper right corner , channel 2 in lower left corner and channel 3 in lower right corner, use:

giometti@jeeg:~$ ./monit q 0:1:2:3
monit: Eurotech CT1472 monitoring setup - version 1.0.1
monit: Copyright (C) 2004 - Eurotech S.p.A. <support@eurotech.it>
monit: Copyright (C) 2004 - Rodolfo Giometti <giometti@linux.it>
monit: QUAD mode on channels 0-1:2-3 set

To disable monitoring use:

giometti@jeeg:~utils$ ./monit d
monit: Eurotech CT1472 monitoring setup - version 1.0.1
monit: Copyright (C) 2004 - Eurotech S.p.A. <support@eurotech.it>
monit: Copyright (C) 2004 - Rodolfo Giometti <giometti@linux.it>
monit: monitoring disabled

osd

This utility sets the OSD functions for the CTR-1472.

To enable OSD for monitoring use:

giometti@jeeg:~$ ./osd -m e
osd: Eurotech CT1472 OSD setup - version 0.80.0
osd: Copyright (C) 2004 - Eurotech S.p.A. <support@eurotech.it>
osd: Copyright (C) 2004 - Rodolfo Giometti <giometti@linux.it>

To disable it:

giometti@jeeg:~$ ./osd -m d
osd: Eurotech CT1472 OSD setup - version 0.80.0
osd: Copyright (C) 2004 - Eurotech S.p.A. <support@eurotech.it>
osd: Copyright (C) 2004 - Rodolfo Giometti <giometti@linux.it>

To write a string starting at position 16 using color 1 on monitoring use:

giometti@jeeg:~$ ./osd -m -c 1 -p 16 s "Test string"
osd: Eurotech CT1472 OSD setup - version 0.80.0
osd: Copyright (C) 2004 - Eurotech S.p.A. <support@eurotech.it>
osd: Copyright (C) 2004 - Rodolfo Giometti <giometti@linux.it>

To erase all strings on minitoring use:

giometti@jeeg:~$ ./osd -m r
osd: Eurotech CT1472 OSD setup - version 0.80.0
osd: Copyright (C) 2004 - Eurotech S.p.A. <support@eurotech.it>
osd: Copyright (C) 2004 - Rodolfo Giometti <giometti@linux.it>

Use the same commands as above for encoding but replace option "-m" with option "-e".

To add an overlay window on monitoring in "transparent" mode use:

giometti@jeeg:~$ ./osd -m w 1 100,60:600,270
osd: Eurotech CT1472 OSD setup - version 0.80.0
osd: Copyright (C) 2004 - Eurotech S.p.A. <support@eurotech.it>
osd: Copyright (C) 2004 - Rodolfo Giometti <giometti@linux.it>

To add the same window on monitoring but in "fill" mode use:

giometti@jeeg:~$ ./osd -m w 3 100,60:600,270
osd: Eurotech CT1472 OSD setup - version 0.80.0
osd: Copyright (C) 2004 - Eurotech S.p.A. <support@eurotech.it>
osd: Copyright (C) 2004 - Rodolfo Giometti <giometti@linux.it>

md

This utility manage the motion detection for the CTR-1472.

To start motion detection on channel 0 use:

giometti@jeeg:~/Projects/eurotech/ctr1472/utils$ ./md e 0
md: Eurotech CT1472 MD setup - version 0.80.0
md: Copyright (C) 2004 - Eurotech S.p.A. <support@eurotech.it>
md: Copyright (C) 2004 - Rodolfo Giometti <giometti@linux.it>
md: MD event on channel 0
md:         windows patterns:
md:                 win 00 - 0000
md:                 win 01 - 36aa
md:                 win 02 - 2200
md:                 win 03 - 0000
md:                 win 04 - 0011
md:                 win 05 - 0da5
md:                 win 06 - 0000
md:                 win 07 - 0000
md:                 win 08 - 1d8f
md:                 win 09 - 1b7b
md:                 win 10 - 0000
md:                 win 11 - 0000

Each time a new motion event arrives the md utility will show its data.

io

This utility manage the digital IOs of the CTR-1472.

To read/write the IOs status just use the following simple command:

giometti@jeeg:~/Projects/eurotech/ctr1472/utils$ ./io r
io: Eurotech CT1472 IOs management - version 0.90.0
io: Copyright (C) 2005 - Eurotech S.p.A. <support@eurotech.it>
io: Copyright (C) 2005 - Rodolfo Giometti <giometti@linux.it>
0
giometti@jeeg:~/Projects/eurotech/ctr1472/utils$ ./io w 0x11
io: Eurotech CT1472 IOs management - version 0.90.0
io: Copyright (C) 2005 - Eurotech S.p.A. <support@eurotech.it>
io: Copyright (C) 2005 - Rodolfo Giometti <giometti@linux.it>

The "r" command reads inputs status while the "w" command writes outputs status (please, note that you have only 4 output bits so only values from 0x00 to 0x0f will take effect)

The procfs support

As explained above you can enable procfs support by setting PROCFS=y during compiling stage. If you do that you'll get the directory /proc/driver/ctr1472/.

If you take a look into this directory you'll see one subdirectory for each boards you have installed on your system. For example, on my system I have:

giometti@jeeg:~/Projects/eurotech/ctr1472$ ls /proc/driver/ctr1472/
0/

since I have only one board installed.

If you go into this subdirectory you'll get several files as shown below:

giometti@jeeg:~/Projects/eurotech/ctr1472$ cd /proc/driver/ctr1472/0/
giometti@jeeg:/proc/driver/ctr1472/0$ ls
monitor  status  video/

Let's start explain what these files are.

The file status

This file show some information about current board configuration. To get them just use the command:

giometti@jeeg:/proc/driver/ctr1472/0$ cat status
name:                    ctr1472#0 [1131, 7146]
major/minor:             254/0
usage:                   0
irq:                     9
io ports:                c8b59000 - c8b59200
res. kernel memory:      8388608b (8192Kb) - 2048 blocks of 4096b

The file monitor

This file can be used to inquiry the monitoring settings.

To get current monitoring setting use the following command:

giometti@jeeg:/proc/driver/ctr1472/0$ cat monitor
F 0

While if you wish to set a new monitoring mode use the command (as root):

jeeg:/proc/driver/ctr1472/0# echo D > monitor
jeeg:/proc/driver/ctr1472/0# cat monitor
D
jeeg:/proc/driver/ctr1472/0# echo F 0 > monitor
jeeg:/proc/driver/ctr1472/0# cat monitor
F 0

The syntax for this file is:

• D - Disable the monitoring function.
• F channel - Enable the monitoring function in FULL mode for specfied channel.
• Q channel_ul channel_ur channel_ll channel_lr"" - Enable the monitoring function in QUAD mode by displaying in the upper left corner the channel channel_ul, in the upper right corner the channel channel_ur and so on.

The directory video

In this directory you'll find all video setting like brightness, contrast etc..

To get the current settings just use the command cat as above:

giometti@jeeg:/proc/driver/ctr1472/0$ cd video/
giometti@jeeg:/proc/driver/ctr1472/0/video$ cat brightness
0 80
1 80
2 80
3 80
giometti@jeeg:/proc/driver/ctr1472/0/video$ cat hue
0 0
1 0
2 0
3 0
giometti@@eeg:/proc/driver/ctr1472/0/video$ cat norm
pal

Please note that all file but norm as per channel while norm is global to the system. In fact you can change brightness, contrast, etc. for each channel but you must change the normalization for the whole system (Note that this setting cover also the other device's functions like, for example, the monitoring).

To change one video setting (but the normalization) use the syntax "channel value", for example:

jeeg:/proc/driver/ctr1472/0/video# cat contrast
0 40
1 40
2 40
3 40
jeeg:/proc/driver/ctr1472/0/video# echo 0 80 > contrast
jeeg:/proc/driver/ctr1472/0/video# cat contrast
0 80
1 40
2 40
3 40

Values must be in [0,255] range.

To set the normalization you can use the syntax:

• pal - Set the PAL normalization.
• ntsc - Set the NTSC normalization.

So, for example to switch form PAL (default) to NTSC use:

jeeg:/proc/driver/ctr1472/0/video# cat norm
pal
jeeg:/proc/driver/ctr1472/0/video# echo ntsc > norm
jeeg:/proc/driver/ctr1472/0/video# cat norm
ntsc

FAQ

General questions

Q1.1)

How I can see my driver version number?

A1.1)

There are several ways:

1. By inserting the driver and looking at your kernel logs:

Jun  7 09:57:56 jeeg kernel: ctr1472:main.c[1009]: Driver for the Eurotech CTR-1
472 - ver. 0.95.0
           ^^^^^^

1. Directly from the source code by using the command:

giometti@jeeg:~/Projects/eurotech/ctr1472$ grep '\<VERSION\>' ctr1472.h
#define VERSION         "0.95.0"

Video encoding questions

Q2.1)

I'm just start encoding on channel 0 (or another one) and I get a stream with a fixed image... what's happen?

A2.1)

Check your video connector since if you start encoding, for instance, on channel 0 and your camera in on channel 3 you get a valid stream but with a fixed image in it.

Q2.2) Christopher J. Wasniak

During MPEG encoding I'm getting a video overflow error into kernel messages as below:

ctr1472: video memory overflow!

A2.2)

You get this error whenever your application loose too much time in reading encoding stream or when your system setup is wrong and the CPU is not receveing IRQs from the CTR-1472.

First of all check if CTR-1472's IRQ line is working and the signal reaches the CPU. See file /proc/interrups as follow:

giometti@jeeg:~/ctr1472$ grep ctr1472 /proc/interrupts 
  9:          124          XT-PIC  ctr1472#0

and if everything goes well during encoding you should see the second number is increasing. If not, verify into your system settings if the IRQ line is enabled and connected to the PCI bus (please, refere to your CPU manual pages).

On the other hand, if the IRQs are ok, then your application is not quick enought to empty internal CTR-1472's buffers and MPEG encoding is stopped and the error message above is displayed into kernel log.

You have two possibilities:

1. run more quikly your application, or
2. enlarge CTR-1472's buffers by setting define VIDEO_MEM_BLOCKS to higher value at complition time or setting v_blocks to higher value at driver load (modprobe/insmod) time.

Q2.3)

I'd like to use video4linux and/or video4linux2 applications with this driver, is it possible?

A2.3)

No. Internal CTR-1472 encoding chip has a proper audio/video data encoding which is totally incompatible with the video4linux nor video4linux2 interface.

Q2.4)

Running the encoding utility I notice that the CPU load goes toward 60-70%, why?

A2.4)

Utility encoding requires to get a fixed amount of data aven if the driver has something more to return, this cause the driver never stops in waiting data and the CPU is always running. Utility encoding is just a testing tool.

If you wish a better performance you need to rewrite the encoding tool in order to correctly manage the incoming data buffers to suite your needs.