2 .\" $FreeBSD: src/share/man/man4/man4.i386/meteor.4,v 1.10.2.4 2001/08/17 13:08:45 ru Exp $
3 .\" $DragonFly: src/share/man/man4/man4.i386/meteor.4,v 1.2 2003/06/17 04:36:59 dillon Exp $
10 .Nd "video capture driver"
16 driver provides support for a PCI
19 It allows the capture of 24 bit RGB, 16 bit RGB and 16 bit YUV
22 .Ss Meteor Driver Installation
25 card in your system, you need a computer
26 that supports the PCI (preferably the Type 2 or better) interface bus.
27 It is recommended that the system has more than 16 MB of RAM since this
28 capture card directly deposits the image to system RAM.
30 The files required for
34 .Bl -item -offset indent -compact
38 .Pa /sys/i386/include/ioctl_meteor.h
43 release versions 2.1 and earlier, the following patch files are also required:
45 .Bl -item -offset indent -compact
47 .Pa meteor/usr/sys/i386/i386/conf.patch
49 .Pa meteor/usr/sys/conf/files.patch
51 .Pa meteor/sys/i386/conf/LINT.patch
54 These files are available for anonymous FTP at:
55 .Pa ftp://joy.cs.ndsu.nodak.edu/pub/meteor.tgz
59 In the configuration file, add the line (as shown in
60 .Pa meteor/usr/sys/i386/conf/LINT.patch ) :
64 There is also a couple of optional parameters you may use:
65 .Bl -tag -width indent
66 .It Cd "options ""METEOR_ALLOC_PAGES=xxx"""
67 Specifies the number of contiguous pages to allocate when successfully
69 The default number of pages allocated by the kernel is 151.
70 This means that there are (151*4096) bytes available for use.
71 .It Cd "options METEOR_DEALLOC_PAGES"
72 Deallocate all pages when closing the device.
74 contiguously re-allocating new pages are very small.
76 behavior is to not deallocate pages.
77 .It Cd "options ""METEOR_DEALLOC_ABOVE=xxx"""
78 Deallocate all pages above the specified number.
80 to not deallocate above any pages.
83 Make and install the kernel.
85 Make the special file name:
87 .Dl "# mknod /dev/meteor0 c <major> 0"
89 The major number is determined by the placement of the device in
91 The patch supplied with the driver will make the major number 67.
93 .Ss Meteor Capture Modes
96 capture driver has three modes of capture operation.
103 This mode is the easiest and slowest to use.
104 This mode is great for
105 capturing a single field at little programming cost.
107 In this mode, the user opens the device, sets the capture mode
114 call to load the data into a buffer.
117 read 400x300 RGB24 into a viewable PPM file
119 #include <sys/fcntl.h>
120 #include <machine/ioctl_meteor.h>
125 #define SIZE (ROWS * COLS * 4)
128 struct meteor_geomet geo;
129 char buf[SIZE],b[4],header[16],*p;
132 if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
133 printf("open failed: %d\\n", errno);
136 /* set up the capture type and size */
140 geo.oformat = METEOR_GEO_RGB24 ;
142 if (ioctl(i, METEORSETGEO, &geo) < 0) {
143 printf("ioctl failed: %d\\n", errno);
149 if (ioctl(i, METEORSFMT, &c) < 0) {
150 printf("ioctl failed: %d\\n", errno);
154 c = METEOR_INPUT_DEV0;
156 if (ioctl(i, METEORSINPUT, &c) < 0) {
157 printf("ioctl failed: %d\\n", errno);
161 if ((c=read(i, &buf[0], SIZE)) < SIZE) {
162 printf("read failed %d %d %d\\n", c, i, errno);
168 if ((o = open("rgb24.ppm", O_WRONLY | O_CREAT, 0644)) < 0) {
169 printf("ppm open failed: %d\\n", errno);
173 /* make PPM header and save to file */
174 strcpy(&header[0], "P6 400 300 255 ");
175 header[2] = header[6] = header[10] = header[14] = '\\n';
176 write (o, &header[0], 15);
177 /* save the RGB data to PPM file */
178 for (p = &buf[0]; p < &buf[SIZE]; ) {
179 b[2] = *p++; /* blue */
180 b[1] = *p++; /* green */
181 b[0] = *p++; /* red */
182 *p++; /* NULL byte */
183 write(o,&b[0], 3); /* not very efficient */
190 Memory mapped single capture or unsynchronized continuous capture.
192 The single capture mode is designed for conferencing tools such as
194 These tools need to control the starting of the image capture and also
195 need several frames a second.
196 The continuous capture mode is designed
197 for applications that want free-running data.
199 In this mode, the user opens the device, sets the capture mode
206 memory into the user process space, and issues either the
207 single-capture or the continuous capture call (see:
210 call) to load the data into the memory mapped buffer.
215 call, the single frame capture
217 will block until the capture is complete, the continuous capture
218 will return immediately.
220 .Pa meteor_mmap_single_continuous.c
222 #include <sys/types.h>
223 #include <sys/mman.h>
224 #include <sys/fcntl.h>
225 #include <machine/ioctl_meteor.h>
230 #define SIZE (ROWS * COLS * 2)
233 struct meteor_geomet geo;
238 if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
239 printf("open failed\\n");
246 geo.oformat = METEOR_GEO_RGB16 ;
248 if (ioctl(i, METEORSETGEO, &geo) < 0) {
249 printf("ioctl failed: %d\\n", errno);
255 if (ioctl(i, METEORSFMT, &c) < 0) {
256 printf("ioctl failed: %d\\n", errno);
260 c = METEOR_INPUT_DEV0;
262 if (ioctl(i, METEORSINPUT, &c) < 0) {
263 printf("ioctl failed: %d\\n", errno);
267 mmbuf=(char *)mmap((caddr_t)0, SIZE, PROT_READ,
268 MAP_SHARED, i, (off_t)0);
271 /* single frame capture */
272 c = METEOR_CAP_SINGLE ;
273 ioctl(i, METEORCAPTUR, &c); /* wait for the frame */
275 /* directly access the frame buffer array data in mmbuf */
277 /* continuous frame capture */
278 c = METEOR_CAP_CONTINOUS ;
279 ioctl(i, METEORCAPTUR, &c); /* returns immediately */
281 /* directly access the frame buffer array data in mmbuf */
283 c = METEOR_CAP_STOP_CONT ;
284 ioctl(i, METEORCAPTUR, &c); /* close will also stop capture */
292 Memory mapped, multi-frame ring buffer synchronize capture.
294 This continuous capture mode is synchronized with the application that
295 processes up to 32 frames.
296 This gives the advantages of both single and
297 continuous capture modes.
299 The kernel notifies the application of a new data by raising an
300 application defined signal.
301 The driver also shares a structure with
302 the application that allows them to communicate which frame has been
303 written by the kernel and which frame has been read by the application.
305 The shared structure starts on the first page after your data.
307 structure address can be found by calculation:
309 .Dl "(number_rows * number_columns * pixel_depth + 4095) & 0xfffff000"
311 .Dl "((number_rows * number_columns * pixel_depth + 4095)/4096) * 4096"
313 The shared structure is of type
314 .Va struct meteor_mem .
316 important fields are called
321 is a bitmap of frames written by the kernel.
324 a count of frames marked in the
328 in by the driver, the
330 count is tested, if this
331 count is below the threshold of number of active frames (value
335 variable), the bit representing frame
336 number in the buffer is stored in the
340 is incremented, the kernel then raises the specified
341 signal to activate the user application.
342 The user application's
343 responsibility when getting the signal is to check the active bitmap
344 to determine the lowest active frame, use the data as the application
345 desires, clear the bitmap entry for that frame, and decrement the
346 .Va num_active_bufs .
347 If the threshold of number of active frames
349 has been exceeded, no new frames or signal from the kernel will occur
352 is less than or equal to
355 The driver loads the frames in a round-robin fashion.
357 that the user removes them in the same order.
359 check to see if the frame is already active.
363 and number of frames in the buffer are also provided
366 structure, but changing these fields in the
367 application will not change the operation of the driver.
369 In programming for this mode, the user opens the device, sets the
372 the data/common control structure, then starts the
373 continuous capture mode.
374 A special signal catcher is required to
375 process the frames as they are read by the kernel.
377 When specifying the geometry (see:
382 is important that the number of frames is set greater than 1.
384 .Pa skeleton_capture_n.c
386 #include <sys/types.h>
387 #include <sys/mman.h>
388 #include <sys/fcntl.h>
389 #include <sys/signal.h>
390 #include <machine/ioctl_meteor.h>
392 int video; /* made global if you wish to stop capture in signal handler */
394 struct meteor_mem *common_mem;
403 struct meteor_capframe capframe; /* for ioctl */
408 frame = (char *) (data_frames + sig_cnt * common_mem->frame_size) ;
410 /* add frame processing here */
411 /* deactivate frame */
412 common_mem->active &= ~(1 << (sig_cnt % 16));
413 common_mem->num_active_bufs--;
415 /* process next frame on next interrupt */
416 sig_cnt = ((sig_cnt+1) % FRAME_MAX);
419 if (some_condition_requiring_stopping) {
420 capframe.command=METEOR_CAP_STOP_FRAMES;
422 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
423 printf("METEORCAPFRM failed %d\\n", errno);
432 struct meteor_geomet geo;
433 int height, width, depth, frames, size;
434 struct meteor_capframe capframe;
436 if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
437 printf("open failed\\n");
440 printf("test %d %d\\n", errno, i);
442 height = geo.rows = 120;
443 width= geo.columns = 320;
444 frames = geo.frames = FRAME_MAX;
445 depth = 2; /* 2 bytes per pixel for RGB*/
448 geo.oformat = METEOR_GEO_RGB16;
450 if (ioctl(i, METEORSETGEO, &geo) < 0) {
451 printf("METEORSETGEO failed %d\\n", errno);
457 if (ioctl(i, METEORSFMT, &c) < 0) {
458 printf("ioctl failed: %d\\n", errno);
462 c = METEOR_INPUT_DEV0;
464 if (ioctl(i, METEORSINPUT, &c) < 0) {
465 printf("ioctl failed: %d\\n", errno);
469 size = ((width*height*depth*frames+4095)/4096)*4096;
470 /* add one page after data for meteor_mem */
471 data_frames = mmap((caddr_t)0, size + 4096, PROT_READ | PROT_WRITE,
472 MAP_SHARED, i, (off_t)0);
474 if (data_frames == (caddr_t) MAP_FAILED) return (0);
476 /* common_mem is located at page following data */
477 common_mem = (struct meteor_mem *) (y + size);
479 signal(SIGUSR2, usr2_catcher); /* catch new frame message */
481 capframe.command=METEOR_CAP_N_FRAMES;
482 capframe.signal=SIGUSR2;
483 capframe.lowat=12; /* must be < hiwat */
484 capframe.hiwat=14; /* must be < FRAME_MAX */
486 /* start the sync capture */
487 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
488 printf("METEORCAPFRM failed %d\\n", errno);
492 /* this is the background working area, or you can sleep */
495 /* to stop capture */
496 capframe.command=METEOR_CAP_STOP_FRAMES;
498 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
499 printf("METEORCAPFRM failed %d\\n", errno);
505 .Ss Meteor IOCTL Call and Parameters
510 requests for capturing, reading card
511 status, for setting and reading the geometry, and for setting and reading the
515 IT IS VERY IMPORTANT TO CHECK FOR ERRORS ON THESE RETURNING IOCTLs.
517 Errors indicate that something is very wrong with the
520 application should not attempt to proceed further with capturing.
523 capture driver still makes attempts to stop the next capture step if
524 an error occurred in a previous step but was ignored by the application
537 are used to set and read the input
538 size, input device, and output format for frame capture.
544 structure that has the
547 .Bl -tag -width columns
549 number of rows (lines high) in output image
551 number of pixels in a row (width) in output image
553 number of frames in buffer.
554 Should be 1, unless using
555 the multi-framed synchronous capture mode
557 which REQUIRES frames to be larger than 1.
564 the existing values are used.
568 you may choose one of the following output format:
569 .Bl -tag -width METEOR_GEO_YUV_PACKED
570 .It Dv METEOR_GEO_RGB16
571 (RGB 16 bits xrrrrrgg gggbbbbb default)
572 .It Dv METEOR_GEO_RGB24
573 (RGB 24 bits packed in 32 bits:
574 00000000 rrrrrrrr gggggggg bbbbbbbb)
575 .It Dv METEOR_GEO_YUV_PACKED
576 (4-2-2 YUV 16 bits packed byte format:
577 u0 y0 v0 y1 u1 y2 v1 y3 ...)
578 .It Dv METEOR_GEO_YUV_PLANER
579 (4-2-2 YUV 16 bits planer format:
580 rows * columns bytes of y
581 rows * column / 4 bytes of even u
582 rows * column / 4 bytes of even v
583 rows * column / 4 bytes of odd u
584 rows * column / 4 bytes of odd v)
591 will fail if more than one entry from a category
593 It is highly recommended that a
596 before capturing data because you cannot guarantee the initial mode
601 will also attempt to reallocate a new contiguous
602 kernel buffer if the new geometry exceeds the old geometry.
604 other hand, if the new geometry will fit in the existing buffer,
605 the existing buffer is used.
611 will return a value of -1 and the
620 .Va rows , columns , frames
623 could not allocate the contiguous block.
635 are used to set and read the camera input
638 Possible formats are:
640 .Bl -tag -width METEOR_FMT_AUTOMODE -compact
641 .It Dv METEOR_FMT_NTSC
643 .It Dv METEOR_FMT_PAL
645 .It Dv METEOR_FMT_SECAM
647 .It Dv METEOR_FMT_AUTOMODE
660 are used to set and read the camera
662 Using the DB9 connector on the
665 devices can be connected and an input camera can be selected with this
668 Possible formats are:
670 .Bl -tag -width METEOR_INPUT_DEV_SVIDEO -compact
671 .It Dv METEOR_INPUT_DEV0
672 (default if none specified)
673 .It Dv METEOR_INPUT_DEV_RCA
674 (same as METEOR_INPUT_DEV0)
675 .It Dv METEOR_INPUT_DEV1
676 .It Dv METEOR_INPUT_DEV2
677 .It Dv METEOR_INPUT_DEV_SVIDEO
678 (same as METEOR_INPUT_DEV2)
686 is used to read the status of the
689 and returns the following information:
690 .Bl -column "METEOR_STATUS_ID_MASK" ""
691 .It Dv METEOR_STATUS_ID_MASK " 4 bit ID of the SAA7196 scaler chip."
693 .It Dv METEOR_STATUS_DIR " 0 = scaler uses internal source."
694 .It " 1 = scaler uses external data of expansion bus."
696 .It Dv METEOR_STATUS_OEF " 0 = even field detected."
697 .It " 1 = odd field detected."
699 .It Dv METEOR_STATUS_SVP " VRAM Port state:"
700 .It " 0 = inputs HFL and INCADDR inactive."
701 .It " 1 = inputs HFL and INCADDR active."
703 .It Dv METEOR_STATUS_STTC " 0 = TV horizontal time constant (slow)."
704 .It " 1 = VCR horizontal time constant (fast)."
706 .It Dv METEOR_STATUS_HCLK " 0 = Horizontal Phase Lock Loop locked."
707 .It " 1 = Horizontal Phase Lock Loop unlocked."
709 .It Dv METEOR_STATUS_FIDT " 0 = 50 Hz Field detected."
710 .It " 1 = 60 Hz Field detected."
712 .It Dv METEOR_STATUS_ALTD " 0 = no line alternating color burst detected."
713 .It " 1 = line alternating color burst detected (PAL/SECAM)."
715 .It Dv METEOR_STATUS_CODE " 0 = no color information detected."
716 .It " 1 = color information detected."
724 is used to single frame capture or unsynchronized
727 The single frame capture
729 request will return only after a
730 frame has been captured and transfered to the frame buffer.
732 The unsynchronized continuous capture will return immediately and
733 data is directly deposited into the buffer when it is available.
734 Since this is unsynchronized, it is possible the data is being
735 written by the kernel while being read by the application.
739 routines use the following settings:
741 .Bl -tag -width METEOR_CAP_CONTINOUS -compact
742 .It Dv METEOR_CAP_SINGLE
744 .It Dv METEOR_CAP_CONTINOUS
745 unsynchronized continuous capture
746 .It Dv METEOR_CAP_STOP_CONT
747 stop the unsynchronized continuous
755 will return a value of -1 and the
761 invalid capture command value
763 there is not internal buffer to hold the frame.
764 This indicates the previous set geometry
768 card is already capturing.
776 is used for synchronous capture of multiple frames.
782 structure that has the
784 .Bl -tag -width command
789 .Bl -tag -width METEOR_CAP_STOP_FRAMES
790 .It Dv METEOR_CAP_STOP_FRAMES
791 stop the capture; does not use the
792 other variable in structure.
793 .It Dv METEOR_CAP_N_FRAMES
794 start the capture using the other
795 variables in the structure as inputs
798 signal to send to application when a new
799 frame has been captured.
801 only be raised if the captured frame is saved.
808 When a new frame is completed, the driver checks the current unread
809 frame count stored in shared variable (the shared variable is stored
814 if the count is larger
817 the driver will not store any new frames and will not
818 send capture signal to the user application until the
827 will return a value of -1 and the
833 invalid meteor_geomet structure pointer or bad command.
835 there is not internal buffer to hold the frame.
836 This indicates the previous set geometry
840 card is already capturing.
852 are used to set and get the chrominance
853 gain control and effects the UV output amplitude.
862 of -1 and the external variable
867 invalid unsigned char pointer.
879 are used to get and set the hue.
881 signed character has legal values are from +127 which represent
882 +178.6 degrees to -128 which represents -180 degrees.
890 will return a value of
891 -1 and the external variable
896 invalid signed char pointer.
906 is used to get the count of frame errors, DMA errors and
907 count of the number of frames captured that have occurred since
908 the device was opened.
910 can be used to reinitialize the
917 structure that has the
919 .Bl -tag -width frame_count
921 number of FIFO errors since device was opened.
923 number of DMA errors since device was opened.
925 number of frames captured since device was opened.
935 of -1 and the external variable
940 invalid meteor_counts structure pointer.
946 IIC register is difficult to set.
947 We got around that by adding a long
948 wait at each IIC register write.
950 We had difficulties getting the
952 capture card to work on systems
953 that used NCR chipset SCSI cards.
954 It is possible that the
958 could work together using the newer TRITON motherboards.
961 .An Jim Lowe Aq james@miller.cs.uwm.edu ,
962 .An Mark Tinguely Aq tinguely@plains.nodak.edu