Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
METEOR(4)	       FreeBSD Kernel Interfaces Manual		     METEOR(4)

NAME
     meteor -- video capture driver interface

DESCRIPTION
     The meteor	driver defined a video capture interface.  The meteor driver
     is	no longer in the tree, but other devices support this interface	so the
     interface portion is documented here.

   Meteor Capture Modes
     The meteor	capture	driver has three modes of capture operation.

     1.	  Conventional read(2) interface.

	  This mode is the easiest and slowest to use.	This mode is great for
	  capturing a single field at little programming cost.

	  In this mode,	the user opens the device, sets	the capture mode and
	  size (see: METEORSETGEO ioctl(2) call), and uses the read(2) system
	  call to load the data	into a buffer.

	  meteor_read.c; read 400x300 RGB24 into a viewable PPM	file

	  #include <sys/fcntl.h>
	  #include <machine/ioctl_meteor.h>

	  extern int errno;
	  #define ROWS 300
	  #define COLS 400
	  #define SIZE (ROWS * COLS * 4)
	  main()
	  {
		  struct meteor_geomet geo;
		  char buf[SIZE],b[4],header[16],*p;
		  int i,o,c;

		  if ((i = open("/dev/meteor0",	O_RDONLY)) < 0)	{
			  printf("open failed: %d\n", errno);
			  exit(1);
		  }
		  /* set up the	capture	type and size */
		  geo.rows = ROWS;
		  geo.columns =	COLS;
		  geo.frames = 1;
		  geo.oformat =	METEOR_GEO_RGB24 ;

		  if (ioctl(i, METEORSETGEO, &geo) < 0)	{
			  printf("ioctl	failed:	%d\n", errno);
			  exit(1);
		  }

		  c = METEOR_FMT_NTSC;

		  if (ioctl(i, METEORSFMT, &c) < 0) {
			  printf("ioctl	failed:	%d\n", errno);
			  exit(1);
		  }

		  c = METEOR_INPUT_DEV0;

		  if (ioctl(i, METEORSINPUT, &c) < 0) {
			  printf("ioctl	failed:	%d\n", errno);
			  exit(1);
		  }

		  if ((c=read(i, &buf[0], SIZE)) < SIZE) {
			  printf("read failed %d %d %d\n", c, i, errno);
			  close(i);
			  exit(1);
		  }
		  close(i);

		  if ((o = open("rgb24.ppm", O_WRONLY |	O_CREAT, 0644))	< 0) {
			  printf("ppm open failed: %d\n", errno);
			  exit(1);
		  }

		  /* make PPM header and save to file */
		  strcpy(&header[0], "P6 400 300 255 ");
		  header[2] = header[6]	 = header[10] =	header[14] = '\n';
		  write	(o, &header[0],	15);
		  /* save the RGB data to PPM file */
		  for (p = &buf[0]; p <	&buf[SIZE]; ) {
			  b[2] = *p++;		  /* blue */
			  b[1] = *p++;		  /* green */
			  b[0] = *p++;		  /* red */
			  *p++;			  /* NULL byte */
			  write(o,&b[0], 3);	  /* not very efficient	*/
		  }
		  close(o);
		  exit(0);
	  }

     2.	  Memory mapped	single capture or unsynchronized continuous capture.

	  The single capture mode is designed for conferencing tools such as
	  nv.  These tools need	to control the starting	of the image capture
	  and also need	several	frames a second.  The continuous capture mode
	  is designed for applications that want free-running data.

	  In this mode,	the user opens the device, sets	the capture mode and
	  size (see: METEORSETGEO ioctl(2) call), mmap(2)s the frame buffer
	  memory into the user process space, and issues either	the single-
	  capture or the continuous capture call (see: METEORCAPTUR ioctl(2)
	  call)	to load	the data into the memory mapped	buffer.

	  As explained in the METEORCAPTUR ioctl(2) call, the single frame
	  capture ioctl(2) will	block until the	capture	is complete, the con-
	  tinuous capture will return immediately.

	  meteor_mmap_single_continuous.c

	  #include <sys/types.h>
	  #include <sys/mman.h>
	  #include <sys/fcntl.h>
	  #include <machine/ioctl_meteor.h>

	  extern int errno;
	  #define ROWS 480
	  #define COLS 640
	  #define SIZE (ROWS * COLS * 2)
	  main()
	  {
		  struct meteor_geomet geo;
		  char buf[SIZE];
		  char *mmbuf;
		  int i,c;

		  if ((i = open("/dev/meteor0",	O_RDONLY)) < 0)	{
			  printf("open failed\n");
			  exit(1);
		  }

		  geo.rows = ROWS;
		  geo.columns =	COLS;
		  geo.frames = 1;
		  geo.oformat =	METEOR_GEO_RGB16 ;

		  if (ioctl(i, METEORSETGEO, &geo) < 0)	{
			  printf("ioctl	failed:	%d\n", errno);
			  exit(1);
		  }

		  c = METEOR_FMT_NTSC;

		  if (ioctl(i, METEORSFMT, &c) < 0) {
			  printf("ioctl	failed:	%d\n", errno);
			  exit(1);
		  }

		  c = METEOR_INPUT_DEV0;

		  if (ioctl(i, METEORSINPUT, &c) < 0) {
			  printf("ioctl	failed:	%d\n", errno);
			  exit(1);
		  }

		  mmbuf=(char *)mmap((caddr_t)0, SIZE, PROT_READ,
			  MAP_SHARED, i, (off_t)0);

	  #ifdef SINGLE_MODE
		  /* single frame capture */
		  c = METEOR_CAP_SINGLE	;
		  ioctl(i, METEORCAPTUR, &c);	  /* wait for the frame	*/

		  /* directly access the frame buffer array data in mmbuf */
	  #else
		  /* continuous	frame capture */
		  c = METEOR_CAP_CONTINOUS ;
		  ioctl(i, METEORCAPTUR, &c);	  /* returns immediately */

		  /* directly access the frame buffer array data in mmbuf */

		  c = METEOR_CAP_STOP_CONT ;
		  ioctl(i, METEORCAPTUR, &c);	  /* close will	also stop capture */
	  #endif

		  close(i);
		  exit(0);
	  }

     3.	  Memory mapped, multi-frame ring buffer synchronize capture.

	  This continuous capture mode is synchronized with the	application
	  that processes up to 32 frames.  This	gives the advantages of	both
	  single and continuous	capture	modes.

	  The kernel notifies the application of a new data by raising an
	  application defined signal.  The driver also shares a	structure with
	  the application that allows them to communicate which	frame has been
	  written by the kernel	and which frame	has been read by the applica-
	  tion.

	  The shared structure starts on the first page	after your data.  The
	  structure address can	be found by calculation:

		(number_rows * number_columns *	pixel_depth + 4095) &
		0xfffff000
	  or
		((number_rows *	number_columns * pixel_depth + 4095)/4096) *
		4096

	  The shared structure is of type struct meteor_mem.  The two most
	  important fields are called active and num_active_buf.  active is a
	  bitmap of frames written by the kernel.  num_active_bufs is a	count
	  of frames marked in the active field.	 When a	frame is read in by
	  the driver, the num_active_bufs count	is tested, if this count is
	  below	the threshold of number	of active frames (value	in
	  meteor_mem's hiwat variable),	the bit	representing frame number in
	  the buffer is	stored in the active variable, the num_active_bufs is
	  incremented, the kernel then raises the specified signal to activate
	  the user application.	 The user application's	responsibility when
	  getting the signal is	to check the active bitmap to determine	the
	  lowest active	frame, use the data as the application desires,	clear
	  the bitmap entry for that frame, and decrement the num_active_bufs.
	  If the threshold of number of	active frames (hiwat) has been
	  exceeded, no new frames or signal from the kernel will occur until
	  the num_active_bufs is less than or equal to lowat.

	  The driver loads the frames in a round-robin fashion.	 It is
	  expected that	the user removes them in the same order.  The driver
	  does not check to see	if the frame is	already	active.

	  The frame_size and number of frames in the buffer are	also provided
	  to the meteor_mem structure, but changing these fields in the	appli-
	  cation will not change the operation of the driver.

	  In programming for this mode,	the user opens the device, sets	the
	  geometry, mmap(2)s the data/common control structure,	then starts
	  the continuous capture mode.	A special signal catcher is required
	  to process the frames	as they	are read by the	kernel.

	  When specifying the geometry (see: METEORSETGEO ioctl(2) call), it
	  is important that the	number of frames is set	greater	than 1.

	  skeleton_capture_n.c

	  #include <sys/types.h>
	  #include <sys/mman.h>
	  #include <sys/fcntl.h>
	  #include <sys/signal.h>
	  #include <machine/ioctl_meteor.h>

	  int video;  /* made global if	you wish to stop capture in signal handler */
	  caddr_t data_frames;
	  struct meteor_mem *common_mem;
	  extern int errno;

	  #define FRAME_MAX

	  void
	  usr2_catcher()
	  {
	  #ifdef SIGNAL_STOP
		  struct meteor_capframe capframe;	  /* for ioctl */
	  #endif
		  char *frame;

		  /* find frame	*/
		  frame	= (char	*) (data_frames	+ sig_cnt * common_mem->frame_size) ;

		  /* add frame processing here */
		  /* deactivate	frame */
		  common_mem->active &=	~(1 << (sig_cnt	% 16));
		  common_mem->num_active_bufs--;

		  /* process next frame	on next	interrupt */
		  sig_cnt = ((sig_cnt+1) % FRAME_MAX);

	  #ifdef SIGNAL_STOP
		  if (some_condition_requiring_stopping) {
			  capframe.command=METEOR_CAP_STOP_FRAMES;

			  if (ioctl(i, METEORCAPFRM, &capframe)	< 0) {
				  printf("METEORCAPFRM failed %d\n", errno);
				  exit(1);
			  }
		  }
	  #endif
	  }

	  main()
	  {
		  struct meteor_geomet geo;
		  int height, width, depth, frames, size;
		  struct meteor_capframe capframe;

		  if ((i = open("/dev/meteor0",	O_RDONLY)) < 0)	{
			  printf("open failed\n");
			  exit(1);
		  }
		  printf("test %d %d\n", errno,	i);

		  height = geo.rows = 120;
		  width= geo.columns = 320;
		  frames = geo.frames =	FRAME_MAX;
		  depth	= 2;	  /* 2 bytes per pixel for RGB*/

		  geo.oformat =	METEOR_GEO_RGB16;

		  if (ioctl(i, METEORSETGEO, &geo) < 0)	{
			  printf("METEORSETGEO failed %d\n", errno);
			  exit(1);
		  }

		  c = METEOR_FMT_NTSC;

		  if (ioctl(i, METEORSFMT, &c) < 0) {
			  printf("ioctl	failed:	%d\n", errno);
			  exit(1);
		  }

		  c = METEOR_INPUT_DEV0;

		  if (ioctl(i, METEORSINPUT, &c) < 0) {
			  printf("ioctl	failed:	%d\n", errno);
			  exit(1);
		  }

		  size = ((width*height*depth*frames+4095)/4096)*4096;
		  /* add one page after	data for meteor_mem */
		  data_frames =	mmap((caddr_t)0, size +	4096, PROT_READ	| PROT_WRITE,
							  MAP_SHARED, i, (off_t)0);

		  if (data_frames == (caddr_t) MAP_FAILED) return (0);

		  /* common_mem	is located at page following data */
		  common_mem = (struct meteor_mem *) (y	+ size);

		  signal(SIGUSR2, usr2_catcher);  /* catch new frame message */

		  capframe.command=METEOR_CAP_N_FRAMES;
		  capframe.signal=SIGUSR2;
		  capframe.lowat=12;		  /* must be < hiwat */
		  capframe.hiwat=14;		  /* must be < FRAME_MAX */

						  /* start the sync capture */
		  if (ioctl(i, METEORCAPFRM, &capframe)	< 0) {
			  printf("METEORCAPFRM failed %d\n", errno);
			  exit(1);
		  }

		  /* this is the background working area, or you can sleep */

		  /* to	stop capture */
		  capframe.command=METEOR_CAP_STOP_FRAMES;

		  if (ioctl(i, METEORCAPFRM, &capframe)	< 0) {
			  printf("METEORCAPFRM failed %d\n", errno);
			  exit(1);
		  }
	  }

   Meteor IOCTL	Call and Parameters
     The meteor	capture	driver has ioctl(2) requests for capturing, reading
     card status, for setting and reading the geometry,	and for	setting	and
     reading the attributes.

     IT	IS VERY	IMPORTANT TO CHECK FOR ERRORS ON THESE RETURNING IOCTLs.
     Errors indicate that something is very wrong with the ioctl(2) and	the
     application should	not attempt to proceed further with capturing.	The
     meteor capture driver still makes attempts	to stop	the next capture step
     if	an error occurred in a previous	step but was ignored by	the applica-
     tion programmer.

     1.	  ioctl(2) requests METEORSETGEO and METEORGETGEO

	  METEORSETGEO and METEORGETGEO	are used to set	and read the input
	  size,	input device, and output format	for frame capture.

	  These	ioctl(2) routines use the meteor_geomet	structure that has the
	  following entries:

	  rows	   number of rows (lines high) in output image

	  columns  number of pixels in a row (width) in	output image

	  frames   number of frames in buffer.	Should be 1, unless using the
		   multi-framed	synchronous capture mode (METEORCAPFRM)	which
		   REQUIRES frames to be larger	than 1.

		   Note: if rows, columns or frames is not changed, then the
		   existing values are used.  The system defaults is
		   640x480x1.

	  oformat  you may choose one of the following output format:

		   METEOR_GEO_RGB16	  (RGB 16 bits xrrrrrgg	gggbbbbb
					  default)

		   METEOR_GEO_RGB24	  (RGB 24 bits packed in 32 bits:
					  00000000 rrrrrrrr gggggggg bbbbbbbb)

		   METEOR_GEO_YUV_PACKED  (4-2-2 YUV 16	bits packed byte for-
					  mat: u0 y0 v0	y1 u1 y2 v1 y3 ...)

		   METEOR_GEO_YUV_PLANER  (4-2-2 YUV 16	bits planer format:
					  rows * columns bytes of y rows *
					  column / 4 bytes of even u rows *
					  column / 4 bytes of even v rows *
					  column / 4 bytes of odd u rows *
					  column / 4 bytes of odd v)

	  The METEORSETGEO ioctl(2) will fail if more than one entry from a
	  category is selected.	 It is highly recommended that a METEORSETGEO
	  is done before capturing data	because	you cannot guarantee the ini-
	  tial mode the	card.

	  The METEORSETGEO will	also attempt to	reallocate a new contiguous
	  kernel buffer	if the new geometry exceeds the	old geometry.  On
	  other	hand, if the new geometry will fit in the existing buffer, the
	  existing buffer is used.

	  If METEORSETGEO fails	the ioctl(2) will return a value of -1 and the
	  external variable errno will be set to:

	  [EINVAL]	     invalid meteor_geomet structure pointer, rows,
			     columns, frames were invalid.

	  [ENOMEM]	     could not allocate	the contiguous block.

     2.	  ioctl(2) requests METEORSFMT and METEORGFMT

	  METEORSFMT and METEORGFMT are	used to	set and	read the camera	input
	  standard format.

	  Possible formats are:

	  METEOR_FMT_NTSC      NTSC (default mode)
	  METEOR_FMT_PAL       PAL
	  METEOR_FMT_SECAM     SECAM
	  METEOR_FMT_AUTOMODE  Autodetect.

     3.	  ioctl(2) requests METEORSINPUT and METEORGINPUT

	  METEORSINPUT and METEORGINPUT	are used to set	and read the camera
	  input	device.	 Using the DB9 connector on the	Meteor card, 4 input
	  devices can be connected and an input	camera can be selected with
	  this ioctl(2).

	  Possible formats are:

	  METEOR_INPUT_DEV0	   (default if none specified)
	  METEOR_INPUT_DEV_RCA	   (same as METEOR_INPUT_DEV0)
	  METEOR_INPUT_DEV1
	  METEOR_INPUT_DEV2
	  METEOR_INPUT_DEV_SVIDEO  (same as METEOR_INPUT_DEV2)

     4.	  ioctl(2) request METEORSTATUS

	  METEORSTATUS is used to read the status of the Meteor	capture	card
	  and returns the following information:

	  METEOR_STATUS_ID_MASK	   4 bit ID of the SAA7196 scaler chip.

	  METEOR_STATUS_DIR	   0 = scaler uses internal source.
				   1 = scaler uses external data of expansion
				       bus.

	  METEOR_STATUS_OEF	   0 = even field detected.
				   1 = odd field detected.

	  METEOR_STATUS_SVP	   VRAM	Port state:
				   0 = inputs HFL and INCADDR inactive.
				   1 = inputs HFL and INCADDR active.

	  METEOR_STATUS_STTC	   0 = TV horizontal time constant (slow).
				   1 = VCR horizontal time constant (fast).

	  METEOR_STATUS_HCLK	   0 = Horizontal Phase	Lock Loop locked.
				   1 = Horizontal Phase	Lock Loop unlocked.

	  METEOR_STATUS_FIDT	   0 = 50 Hz Field detected.
				   1 = 60 Hz Field detected.

	  METEOR_STATUS_ALTD	   0 = no line alternating color burst
				       detected.
				   1 = line alternating	color burst detected
				       (PAL/SECAM).

	  METEOR_STATUS_CODE	   0 = no color	information detected.
				   1 = color information detected.

     5.	  ioctl(2) request METEORCAPTUR

	  METEORCAPTUR is used to single frame capture or unsynchronized con-
	  tinuous capture.

	  The single frame capture ioctl(2) request will return	only after a
	  frame	has been captured and transfered to the	frame buffer.

	  The unsynchronized continuous	capture	will return immediately	and
	  data is directly deposited into the buffer when it is	available.
	  Since	this is	unsynchronized,	it is possible the data	is being writ-
	  ten by the kernel while being	read by	the application.

	  These	ioctl(2) routines use the following settings:

	  METEOR_CAP_SINGLE	capture	one frame
	  METEOR_CAP_CONTINOUS	unsynchronized continuous capture
	  METEOR_CAP_STOP_CONT	stop the unsynchronized	continuous capture

	  If METEORCAPTUR fails	the ioctl(2) will return a value of -1 and the
	  external variable errno will be set to:

	  [EINVAL]	     invalid capture command value

	  [ENXIO]	     there is not internal buffer to hold the frame.
			     This indicates the	previous set geometry ioctl(2)
			     failed.

	  [EIO]		     card is already capturing.

     6.	  ioctl(2) request METEORCAPFRM

	  METEORCAPFRM is used for synchronous capture of multiple frames.

	  This ioctl(2)	routine	uses the meteor_capture	structure that has the
	  following entries:

	  command  possible values for command are:

		   METEOR_CAP_STOP_FRAMES  stop	the capture; does not use the
					   other variable in structure.

		   METEOR_CAP_N_FRAMES	   start the capture using the other
					   variables in	the structure as
					   inputs

	  signal   signal to send to application when a	new frame has been
		   captured.  This signal will only be raised if the captured
		   frame is saved.

	  lowat	   see below

	  hiwat	   see below

	  When a new frame is completed, the driver checks the current unread
	  frame	count stored in	shared variable	(the shared variable is	stored
	  in the meteor_mem structure) num_active_buf; if the count is larger
	  than hiwat, the driver will not store	any new	frames and will	not
	  send capture signal to the user application until the	num_active_buf
	  is lower than	lowat.

	  If METEORCAPFRM fails	the ioctl(2) will return a value of -1 and the
	  external variable errno will be set to:

	  [EINVAL]	     invalid meteor_geomet structure pointer or	bad
			     command.

	  [ENXIO]	     there is not internal buffer to hold the frame.
			     This indicates the	previous set geometry ioctl(2)
			     failed.

	  [EIO]		     card is already capturing.

     7.	  ioctl(2) requests METEORSCHCV	and METEORGCHCV

	  METEORSCHCV and METEORGCHCV are used to set and get the chrominance
	  gain control and effects the UV output amplitude.

	  If METEORSCHCV or METEORGCHCV	fails the ioctl(2) will	return a value
	  of -1	and the	external variable errno	will be	set to:

	  [EINVAL]	     invalid unsigned char pointer.

     8.	  ioctl(2) requests METEORGHUE and METEORSHUE

	  METEORGHUE and METEORSHUE are	used to	get and	set the	hue.  The
	  signed character has legal values are	from +127 which	represent
	  +178.6 degrees to -128 which represents -180 degrees.

	  If METEORGHUE	or METEORSHUE fails the	ioctl(2) will return a value
	  of -1	and the	external variable errno	will be	set to:

	  [EINVAL]	     invalid signed char pointer.

     9.	  ioctl(2) requests METEORSCOUNT and METEORGCOUNT

	  METEORGCOUNT is used to get the count	of frame errors, DMA errors
	  and count of the number of frames captured that have occurred	since
	  the device was opened.  METEORSCOUNT can be used to reinitialize the
	  counters.

	  This ioctl(2)	routines use the meteor_counts structure that has the
	  following entries:

	  fifo_errors  number of FIFO errors since device was opened.

	  dma_errors   number of DMA errors since device was opened.

	  frame_count  number of frames	captured since device was opened.

	  If METEORSCOUNT or METEORGCOUNT fails	the ioctl(2) will return a
	  value	of -1 and the external variable	errno will be set to:

	  [EINVAL]	     invalid meteor_counts structure pointer.

BUGS
     The meteor	driver no longer works at all.

AUTHORS
     Jim Lowe <james@miller.cs.uwm.edu>,
     Mark Tinguely <tinguely@plains.nodak.edu>

FreeBSD	9.3			August 15, 1995			   FreeBSD 9.3

NAME | DESCRIPTION | BUGS | AUTHORS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=meteor&sektion=4&manpath=FreeBSD+5.4-RELEASE>

home | help