share/man/man4/man4.i386/meteor.4

   1 .\"
   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 $
   4 .\"
   5 .Dd August 15, 1995
   6 .Dt METEOR 4 i386
   7 .Os
   8 .Sh NAME
   9 .Nm meteor
  10 .Nd "video capture driver"
  11 .Sh SYNOPSIS
  12 .Cd "device meteor"
  13 .Sh DESCRIPTION
  14 The
  15 .Nm
  16 driver provides support for a PCI
  17 .Em video
  18 capture.
  19 It allows the capture of 24 bit RGB, 16 bit RGB and 16 bit YUV
  20 output formats.
  21 .Pp
  22 .Ss Meteor Driver Installation
  23 To use the
  24 .Tn "Matrox Meteor"
  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.
  29 .Pp
  30 The files required for
  31 .Tn "Matrox Meteor"
  32 card are:
  33 .Pp
  34 .Bl -item -offset indent -compact
  35 .It
  36 .Pa /sys/pci/meteor.c
  37 .It
  38 .Pa /sys/i386/include/ioctl_meteor.h
  39 .El
  40 .Pp
  41 For
  42 .Fx
  43 release versions 2.1 and earlier, the following patch files are also required:
  44 .Pp
  45 .Bl -item -offset indent -compact
  46 .It
  47 .Pa meteor/usr/sys/i386/i386/conf.patch
  48 .It
  49 .Pa meteor/usr/sys/conf/files.patch
  50 .It
  51 .Pa meteor/sys/i386/conf/LINT.patch
  52 .El
  53 .Pp
  54 These files are available for anonymous FTP at:
  55 .Pa ftp://joy.cs.ndsu.nodak.edu/pub/meteor.tgz
  56 .Pp
  57 .Bl -enum
  58 .It
  59 In the configuration file, add the line (as shown in
  60 .Pa meteor/usr/sys/i386/conf/LINT.patch ) :
  61 .Pp
  62 .Cd "device meteor0"
  63 .It
  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
  68 probed.
  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.
  73 Note, the chances of
  74 contiguously re-allocating new pages are very small.
  75 The default
  76 behavior is to not deallocate pages.
  77 .It Cd "options ""METEOR_DEALLOC_ABOVE=xxx"""
  78 Deallocate all pages above the specified number.
  79 The default action is
  80 to not deallocate above any pages.
  81 .El
  82 .It
  83 Make and install the kernel.
  84 .It
  85 Make the special file name:
  86 .Pp
  87 .Dl "# mknod /dev/meteor0 c <major> 0"
  88 .Pp
  89 The major number is determined by the placement of the device in
  90 .Pa conf.c .
  91 The patch supplied with the driver will make the major number 67.
  92 .El
  93 .Ss Meteor Capture Modes
  94 The
  95 .Nm
  96 capture driver has three modes of capture operation.
  97 .Bl -enum
  98 .It
  99 Conventional
 100 .Xr read 2
 101 interface.
 102 .Pp
 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.
 106 .Pp
 107 In this mode, the user opens the device, sets the capture mode
 108 and size (see:
 109 .Dv METEORSETGEO
 110 .Xr ioctl 2
 111 call), and uses the
 112 .Xr read 2
 113 system
 114 call to load the data into a buffer.
 115 .Pp
 116 .Pa meteor_read.c ;
 117 read 400x300 RGB24 into a viewable PPM file
 118 .Bd -literal
 119 #include <sys/fcntl.h>
 120 #include <machine/ioctl_meteor.h>
 121
 122 extern int errno;
 123 #define ROWS 300
 124 #define COLS 400
 125 #define SIZE (ROWS * COLS * 4)
 126 main()
 127 {
 128         struct meteor_geomet geo;
 129         char buf[SIZE],b[4],header[16],*p;
 130         int i,o,c;
 131
 132         if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
 133                 printf("open failed: %d\\n", errno);
 134                 exit(1);
 135         }
 136         /* set up the capture type and size */
 137         geo.rows = ROWS;
 138         geo.columns = COLS;
 139         geo.frames = 1;
 140         geo.oformat = METEOR_GEO_RGB24 ;
 141
 142         if (ioctl(i, METEORSETGEO, &geo) < 0) {
 143                 printf("ioctl failed: %d\\n", errno);
 144                 exit(1);
 145         }
 146
 147         c = METEOR_FMT_NTSC;
 148
 149         if (ioctl(i, METEORSFMT, &c) < 0) {
 150                 printf("ioctl failed: %d\\n", errno);
 151                 exit(1);
 152         }
 153
 154         c = METEOR_INPUT_DEV0;
 155
 156         if (ioctl(i, METEORSINPUT, &c) < 0) {
 157                 printf("ioctl failed: %d\\n", errno);
 158                 exit(1);
 159         }
 160
 161         if ((c=read(i, &buf[0], SIZE)) < SIZE) {
 162                 printf("read failed %d %d %d\\n", c, i, errno);
 163                 close(i);
 164                 exit(1);
 165         }
 166         close(i);
 167
 168         if ((o = open("rgb24.ppm", O_WRONLY | O_CREAT, 0644)) < 0) {
 169                 printf("ppm open failed: %d\\n", errno);
 170                 exit(1);
 171         }
 172
 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 */
 184         }
 185         close(o);
 186         exit(0);
 187 }
 188 .Ed
 189 .It
 190 Memory mapped single capture or unsynchronized continuous capture.
 191 .Pp
 192 The single capture mode is designed for conferencing tools such as
 193 .Nm nv .
 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.
 198 .Pp
 199 In this mode, the user opens the device, sets the capture mode
 200 and size (see:
 201 .Dv METEORSETGEO
 202 .Xr ioctl 2
 203 call),
 204 .Xr mmap 2 Ns s
 205 the frame buffer
 206 memory into the user process space, and issues either the
 207 single-capture or the continuous capture call (see:
 208 .Dv METEORCAPTUR
 209 .Xr ioctl 2
 210 call) to load the data into the memory mapped buffer.
 211 .Pp
 212 As explained in the
 213 .Dv METEORCAPTUR
 214 .Xr ioctl 2
 215 call, the single frame capture
 216 .Xr ioctl 2
 217 will block until the capture is complete, the continuous capture
 218 will return immediately.
 219 .Pp
 220 .Pa meteor_mmap_single_continuous.c
 221 .Bd -literal
 222 #include <sys/types.h>
 223 #include <sys/mman.h>
 224 #include <sys/fcntl.h>
 225 #include <machine/ioctl_meteor.h>
 226
 227 extern int errno;
 228 #define ROWS 480
 229 #define COLS 640
 230 #define SIZE (ROWS * COLS * 2)
 231 main()
 232 {
 233         struct meteor_geomet geo;
 234         char buf[SIZE];
 235         char *mmbuf;
 236         int i,c;
 237
 238         if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
 239                 printf("open failed\\n");
 240                 exit(1);
 241         }
 242
 243         geo.rows = ROWS;
 244         geo.columns = COLS;
 245         geo.frames = 1;
 246         geo.oformat = METEOR_GEO_RGB16 ;
 247
 248         if (ioctl(i, METEORSETGEO, &geo) < 0) {
 249                 printf("ioctl failed: %d\\n", errno);
 250                 exit(1);
 251         }
 252
 253         c = METEOR_FMT_NTSC;
 254
 255         if (ioctl(i, METEORSFMT, &c) < 0) {
 256                 printf("ioctl failed: %d\\n", errno);
 257                 exit(1);
 258         }
 259
 260         c = METEOR_INPUT_DEV0;
 261
 262         if (ioctl(i, METEORSINPUT, &c) < 0) {
 263                 printf("ioctl failed: %d\\n", errno);
 264                 exit(1);
 265         }
 266
 267         mmbuf=(char *)mmap((caddr_t)0, SIZE, PROT_READ,
 268                 MAP_SHARED, i, (off_t)0);
 269
 270 #ifdef SINGLE_MODE
 271         /* single frame capture */
 272         c = METEOR_CAP_SINGLE ;
 273         ioctl(i, METEORCAPTUR, &c);     /* wait for the frame */
 274
 275         /* directly access the frame buffer array data in mmbuf */
 276 #else
 277         /* continuous frame capture */
 278         c = METEOR_CAP_CONTINOUS ;
 279         ioctl(i, METEORCAPTUR, &c);     /* returns immediately */
 280
 281         /* directly access the frame buffer array data in mmbuf */
 282
 283         c = METEOR_CAP_STOP_CONT ;
 284         ioctl(i, METEORCAPTUR, &c);     /* close will also stop capture */
 285 #endif
 286
 287         close(i);
 288         exit(0);
 289 }
 290 .Ed
 291 .It
 292 Memory mapped, multi-frame ring buffer synchronize capture.
 293 .Pp
 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.
 298 .Pp
 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.
 304 .Pp
 305 The shared structure starts on the first page after your data.
 306 The
 307 structure address can be found by calculation:
 308 .Pp
 309 .Dl "(number_rows * number_columns * pixel_depth + 4095) & 0xfffff000"
 310 or
 311 .Dl "((number_rows * number_columns * pixel_depth + 4095)/4096) * 4096"
 312 .Pp
 313 The shared structure is of type
 314 .Va struct meteor_mem .
 315 The two most
 316 important fields are called
 317 .Va active
 318 and
 319 .Va num_active_buf .
 320 .Va active
 321 is a bitmap of frames written by the kernel.
 322 .Va num_active_bufs
 323 is
 324 a count of frames marked in the
 325 .Va active
 326 field.
 327 When a frame is read
 328 in by the driver, the
 329 .Va num_active_bufs
 330 count is tested, if this
 331 count is below the threshold of number of active frames (value
 332 in
 333 .Va meteor_mem Ns 's
 334 .Va hiwat
 335 variable), the bit representing frame
 336 number in the buffer is stored in the
 337 .Va active
 338 variable, the
 339 .Va num_active_bufs
 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
 348 .Pq Va hiwat
 349 has been exceeded, no new frames or signal from the kernel will occur
 350 until the
 351 .Va num_active_bufs
 352 is less than or equal to
 353 .Va lowat .
 354 .Pp
 355 The driver loads the frames in a round-robin fashion.
 356 It is expected
 357 that the user removes them in the same order.
 358 The driver does not
 359 check to see if the frame is already active.
 360 .Pp
 361 The
 362 .Va frame_size
 363 and number of frames in the buffer are also provided
 364 to the
 365 .Va meteor_mem
 366 structure, but changing these fields in the
 367 application will not change the operation of the driver.
 368 .Pp
 369 In programming for this mode, the user opens the device, sets the
 370 geometry,
 371 .Xr mmap 2 Ns s
 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.
 376 .Pp
 377 When specifying the geometry (see:
 378 .Dv METEORSETGEO
 379 .Xr ioctl 2
 380 call),
 381 it
 382 is important that the number of frames is set greater than 1.
 383 .Pp
 384 .Pa skeleton_capture_n.c
 385 .Bd -literal
 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>
 391
 392 int video;  /* made global if you wish to stop capture in signal handler */
 393 caddr_t data_frames;
 394 struct meteor_mem *common_mem;
 395 extern int errno;
 396
 397 #define FRAME_MAX
 398
 399 void
 400 usr2_catcher()
 401 {
 402 #ifdef SIGNAL_STOP
 403         struct meteor_capframe capframe;        /* for ioctl */
 404 #endif
 405         char *frame;
 406
 407         /* find frame */
 408         frame = (char *) (data_frames + sig_cnt * common_mem->frame_size) ;
 409
 410         /* add frame processing here */
 411         /* deactivate frame */
 412         common_mem->active &= ~(1 << (sig_cnt % 16));
 413         common_mem->num_active_bufs--;
 414
 415         /* process next frame on next interrupt */
 416         sig_cnt = ((sig_cnt+1) % FRAME_MAX);
 417
 418 #ifdef SIGNAL_STOP
 419         if (some_condition_requiring_stopping) {
 420                 capframe.command=METEOR_CAP_STOP_FRAMES;
 421
 422                 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
 423                         printf("METEORCAPFRM failed %d\\n", errno);
 424                         exit(1);
 425                 }
 426         }
 427 #endif
 428 }
 429
 430 main()
 431 {
 432         struct meteor_geomet geo;
 433         int height, width, depth, frames, size;
 434         struct meteor_capframe capframe;
 435
 436         if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
 437                 printf("open failed\\n");
 438                 exit(1);
 439         }
 440         printf("test %d %d\\n", errno, i);
 441
 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*/
 446
 447
 448         geo.oformat = METEOR_GEO_RGB16;
 449
 450         if (ioctl(i, METEORSETGEO, &geo) < 0) {
 451                 printf("METEORSETGEO failed %d\\n", errno);
 452                 exit(1);
 453         }
 454
 455         c = METEOR_FMT_NTSC;
 456
 457         if (ioctl(i, METEORSFMT, &c) < 0) {
 458                 printf("ioctl failed: %d\\n", errno);
 459                 exit(1);
 460         }
 461
 462         c = METEOR_INPUT_DEV0;
 463
 464         if (ioctl(i, METEORSINPUT, &c) < 0) {
 465                 printf("ioctl failed: %d\\n", errno);
 466                 exit(1);
 467         }
 468
 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);
 473
 474         if (data_frames == (caddr_t) MAP_FAILED) return (0);
 475
 476         /* common_mem is located at page following data */
 477         common_mem = (struct meteor_mem *) (y + size);
 478
 479         signal(SIGUSR2, usr2_catcher);  /* catch new frame message */
 480
 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 */
 485
 486                                         /* start the sync capture */
 487         if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
 488                 printf("METEORCAPFRM failed %d\\n", errno);
 489                 exit(1);
 490         }
 491
 492         /* this is the background working area, or you can sleep */
 493
 494
 495         /* to stop capture */
 496         capframe.command=METEOR_CAP_STOP_FRAMES;
 497
 498         if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
 499                 printf("METEORCAPFRM failed %d\\n", errno);
 500                 exit(1);
 501         }
 502 }
 503 .Ed
 504 .El
 505 .Ss Meteor IOCTL Call and Parameters
 506 The
 507 .Nm
 508 capture driver has
 509 .Xr ioctl 2
 510 requests for capturing, reading card
 511 status, for setting and reading the geometry, and for setting and reading the
 512 attributes.
 513 .Pp
 514 .Bf -symbolic
 515 IT IS VERY IMPORTANT TO CHECK FOR ERRORS ON THESE RETURNING IOCTLs.
 516 .Ef
 517 Errors indicate that something is very wrong with the
 518 .Xr ioctl 2
 519 and the
 520 application should not attempt to proceed further with capturing.
 521 The
 522 .Nm
 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
 525 programmer.
 526 .Bl -enum
 527 .It
 528 .Xr ioctl 2
 529 requests
 530 .Dv METEORSETGEO
 531 and
 532 .Dv METEORGETGEO
 533 .Pp
 534 .Dv METEORSETGEO
 535 and
 536 .Dv METEORGETGEO
 537 are used to set and read the input
 538 size, input device, and output format for frame capture.
 539 .Pp
 540 These
 541 .Xr ioctl 2
 542 routines use the
 543 .Va meteor_geomet
 544 structure that has the
 545 following entries:
 546 .Pp
 547 .Bl -tag -width columns
 548 .It Va rows
 549 number of rows (lines high) in output image
 550 .It Va columns
 551 number of pixels in a row (width) in output image
 552 .It Va frames
 553 number of frames in buffer.
 554 Should be 1, unless using
 555 the multi-framed synchronous capture mode
 556 .Pq Dv METEORCAPFRM
 557 which REQUIRES frames to be larger than 1.
 558 .Pp
 559 Note: if
 560 .Va rows , columns
 561 or
 562 .Va frames
 563 is not changed, then
 564 the existing values are used.
 565 The system defaults
 566 is 640x480x1.
 567 .It Va oformat
 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)
 585 .El
 586 .El
 587 .Pp
 588 The
 589 .Dv METEORSETGEO
 590 .Xr ioctl 2
 591 will fail if more than one entry from a category
 592 is selected.
 593 It is highly recommended that a
 594 .Dv METEORSETGEO
 595 is done
 596 before capturing data because you cannot guarantee the initial mode
 597 the card.
 598 .Pp
 599 The
 600 .Dv METEORSETGEO
 601 will also attempt to reallocate a new contiguous
 602 kernel buffer if the new geometry exceeds the old geometry.
 603 On
 604 other hand, if the new geometry will fit in the existing buffer,
 605 the existing buffer is used.
 606 .Pp
 607 If
 608 .Dv METEORSETGEO
 609 fails the
 610 .Xr ioctl 2
 611 will return a value of -1 and the
 612 external variable
 613 .Va errno
 614 will be set to:
 615 .Bl -tag -width Er
 616 .It Bq Er EINVAL
 617 invalid
 618 .Va meteor_geomet
 619 structure pointer,
 620 .Va rows , columns , frames
 621 were invalid.
 622 .It Bq Er ENOMEM
 623 could not allocate the contiguous block.
 624 .El
 625 .It
 626 .Xr ioctl 2
 627 requests
 628 .Dv METEORSFMT
 629 and
 630 .Dv METEORGFMT
 631 .Pp
 632 .Dv METEORSFMT
 633 and
 634 .Dv METEORGFMT
 635 are used to set and read the camera input
 636 standard format.
 637 .Pp
 638 Possible formats are:
 639 .Pp
 640 .Bl -tag -width METEOR_FMT_AUTOMODE -compact
 641 .It Dv METEOR_FMT_NTSC
 642 NTSC (default mode)
 643 .It Dv METEOR_FMT_PAL
 644 PAL
 645 .It Dv METEOR_FMT_SECAM
 646 SECAM
 647 .It Dv METEOR_FMT_AUTOMODE
 648 Autodetect.
 649 .El
 650 .It
 651 .Xr ioctl 2
 652 requests
 653 .Dv METEORSINPUT
 654 and
 655 .Dv METEORGINPUT
 656 .Pp
 657 .Dv METEORSINPUT
 658 and
 659 .Dv METEORGINPUT
 660 are used to set and read the camera
 661 input device.
 662 Using the DB9 connector on the
 663 .Tn Meteor
 664 card, 4 input
 665 devices can be connected and an input camera can be selected with this
 666 .Xr ioctl 2 .
 667 .Pp
 668 Possible formats are:
 669 .Pp
 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)
 679 .El
 680 .It
 681 .Xr ioctl 2
 682 request
 683 .Dv METEORSTATUS
 684 .Pp
 685 .Dv METEORSTATUS
 686 is used to read the status of the
 687 .Tn Meteor
 688 capture card
 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."
 692 .Pp
 693 .It Dv METEOR_STATUS_DIR "      0 =     scaler uses internal source."
 694 .It "   1 =     scaler uses external data of expansion bus."
 695 .Pp
 696 .It Dv METEOR_STATUS_OEF "      0 =     even field detected."
 697 .It "   1 =     odd field detected."
 698 .Pp
 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."
 702 .Pp
 703 .It Dv METEOR_STATUS_STTC "     0 =     TV horizontal time constant (slow)."
 704 .It "   1 =     VCR horizontal time constant (fast)."
 705 .Pp
 706 .It Dv METEOR_STATUS_HCLK "     0 =     Horizontal Phase Lock Loop locked."
 707 .It "   1 =     Horizontal Phase Lock Loop unlocked."
 708 .Pp
 709 .It Dv METEOR_STATUS_FIDT "     0 =     50 Hz Field detected."
 710 .It "   1 =     60 Hz Field detected."
 711 .Pp
 712 .It Dv METEOR_STATUS_ALTD "     0 =     no line alternating color burst detected."
 713 .It "   1 =     line alternating color burst detected (PAL/SECAM)."
 714 .Pp
 715 .It Dv METEOR_STATUS_CODE "     0 =     no color information detected."
 716 .It "   1 =     color information detected."
 717 .El
 718 .It
 719 .Xr ioctl 2
 720 request
 721 .Dv METEORCAPTUR
 722 .Pp
 723 .Dv METEORCAPTUR
 724 is used to single frame capture or unsynchronized
 725 continuous capture.
 726 .Pp
 727 The single frame capture
 728 .Xr ioctl 2
 729 request will return only after a
 730 frame has been captured and transfered to the frame buffer.
 731 .Pp
 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.
 736 .Pp
 737 These
 738 .Xr ioctl 2
 739 routines use the following settings:
 740 .Pp
 741 .Bl -tag -width METEOR_CAP_CONTINOUS -compact
 742 .It Dv METEOR_CAP_SINGLE
 743 capture one frame
 744 .It Dv METEOR_CAP_CONTINOUS
 745 unsynchronized continuous capture
 746 .It Dv METEOR_CAP_STOP_CONT
 747 stop the unsynchronized continuous
 748 capture
 749 .El
 750 .Pp
 751 If
 752 .Dv METEORCAPTUR
 753 fails the
 754 .Xr ioctl 2
 755 will return a value of -1 and the
 756 external variable
 757 .Va errno
 758 will be set to:
 759 .Bl -tag -width Er
 760 .It Bq Er EINVAL
 761 invalid capture command value
 762 .It Bq Er ENXIO
 763 there is not internal buffer to hold the frame.
 764 This indicates the previous set geometry
 765 .Xr ioctl 2
 766 failed.
 767 .It Bq Er EIO
 768 card is already capturing.
 769 .El
 770 .It
 771 .Xr ioctl 2
 772 request
 773 .Dv METEORCAPFRM
 774 .Pp
 775 .Dv METEORCAPFRM
 776 is used for synchronous capture of multiple frames.
 777 .Pp
 778 This
 779 .Xr ioctl 2
 780 routine uses the
 781 .Va meteor_capture
 782 structure that has the
 783 following entries:
 784 .Bl -tag -width command
 785 .It Va command
 786 possible values for
 787 .Va command
 788 are:
 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
 796 .El
 797 .It Va signal
 798 signal to send to application when a new
 799 frame has been captured.
 800 This signal will
 801 only be raised if the captured frame is saved.
 802 .It Va lowat
 803 see below
 804 .It Va hiwat
 805 see below
 806 .El
 807 .Pp
 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
 810 in the
 811 .Va meteor_mem
 812 structure)
 813 .Va num_active_buf ;
 814 if the count is larger
 815 than
 816 .Va hiwat ,
 817 the driver will not store any new frames and will not
 818 send capture signal to the user application until the
 819 .Va num_active_buf
 820 is lower than
 821 .Va lowat .
 822 .Pp
 823 If
 824 .Dv METEORCAPFRM
 825 fails the
 826 .Xr ioctl 2
 827 will return a value of -1 and the
 828 external variable
 829 .Va errno
 830 will be set to:
 831 .Bl -tag -width Er
 832 .It Bq Er EINVAL
 833 invalid meteor_geomet structure pointer or bad command.
 834 .It Bq Er ENXIO
 835 there is not internal buffer to hold the frame.
 836 This indicates the previous set geometry
 837 .Xr ioctl 2
 838 failed.
 839 .It Bq Er EIO
 840 card is already capturing.
 841 .El
 842 .It
 843 .Xr ioctl 2
 844 requests
 845 .Dv METEORSCHCV
 846 and
 847 .Dv METEORGCHCV
 848 .Pp
 849 .Dv METEORSCHCV
 850 and
 851 .Dv METEORGCHCV
 852 are used to set and get the chrominance
 853 gain control and effects the UV output amplitude.
 854 .Pp
 855 If
 856 .Dv METEORSCHCV
 857 or
 858 .Dv METEORGCHCV
 859 fails the
 860 .Xr ioctl 2
 861 will return a value
 862 of -1 and the external variable
 863 .Va errno
 864 will be set to:
 865 .Bl -tag -width Er
 866 .It Bq Er EINVAL
 867 invalid unsigned char pointer.
 868 .El
 869 .It
 870 .Xr ioctl 2
 871 requests
 872 .Dv METEORGHUE
 873 and
 874 .Dv METEORSHUE
 875 .Pp
 876 .Dv METEORGHUE
 877 and
 878 .Dv METEORSHUE
 879 are used to get and set the hue.
 880 The
 881 signed character has legal values are from +127 which represent
 882 +178.6 degrees to -128 which represents -180 degrees.
 883 .Pp
 884 If
 885 .Dv METEORGHUE
 886 or
 887 .Dv METEORSHUE
 888 fails the
 889 .Xr ioctl 2
 890 will return a value of
 891 -1 and the external variable
 892 .Va errno
 893 will be set to:
 894 .Bl -tag -width Er
 895 .It Bq Er EINVAL
 896 invalid signed char pointer.
 897 .El
 898 .It
 899 .Xr ioctl 2
 900 requests
 901 .Dv METEORSCOUNT
 902 and
 903 .Dv METEORGCOUNT
 904 .Pp
 905 .Dv METEORGCOUNT
 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.
 909 .Dv METEORSCOUNT
 910 can be used to reinitialize the
 911 counters.
 912 .Pp
 913 This
 914 .Xr ioctl 2
 915 routines use the
 916 .Va meteor_counts
 917 structure that has the
 918 following entries:
 919 .Bl -tag -width frame_count
 920 .It Va fifo_errors
 921 number of FIFO errors since device was opened.
 922 .It Va dma_errors
 923 number of DMA errors since device was opened.
 924 .It Va frame_count
 925 number of frames captured since device was opened.
 926 .El
 927 .Pp
 928 If
 929 .Dv METEORSCOUNT
 930 or
 931 .Dv METEORGCOUNT
 932 fails the
 933 .Xr ioctl 2
 934 will return a value
 935 of -1 and the external variable
 936 .Va errno
 937 will be set to:
 938 .Bl -tag -width Er
 939 .It Bq Er EINVAL
 940 invalid meteor_counts structure pointer.
 941 .El
 942 .El
 943 .Sh BUGS
 944 .Bl -enum
 945 .It
 946 IIC register is difficult to set.
 947 We got around that by adding a long
 948 wait at each IIC register write.
 949 .It
 950 We had difficulties getting the
 951 .Tn Meteor
 952 capture card to work on systems
 953 that used NCR chipset SCSI cards.
 954 It is possible that the
 955 .Tn Meteor
 956 and
 957 .Tn "NCR SCSI"
 958 could work together using the newer TRITON motherboards.
 959 .El
 960 .Sh AUTHORS
 961 .An Jim Lowe Aq james@miller.cs.uwm.edu ,
 962 .An Mark Tinguely Aq tinguely@plains.nodak.edu