Add video(4) and video(9) man pages.
This commit is contained in:
jmcneill
parent
623f49d4ea
commit
55507439a1
@ -1,4 +1,4 @@
|
||||
# $NetBSD: Makefile,v 1.470 2008/09/03 23:44:24 ober Exp $
|
||||
# $NetBSD: Makefile,v 1.471 2008/09/06 19:08:29 jmcneill Exp $
|
||||
# @(#)Makefile 8.1 (Berkeley) 6/18/93
|
||||
|
||||
MAN= aac.4 ac97.4 acardide.4 aceride.4 acphy.4 acpidalb.4 \
|
||||
@ -53,7 +53,8 @@ MAN= aac.4 ac97.4 acardide.4 aceride.4 acphy.4 acpidalb.4 \
|
||||
tap.4 tc.4 tcds.4 tcp.4 termios.4 tfb.4 ti.4 tl.4 tlp.4 tlphy.4 \
|
||||
tp.4 tr.4 tra.4 trm.4 tty.4 tun.4 tqphy.4 twa.4 twe.4 txp.4 \
|
||||
ubsec.4 udp.4 uep.4 ug.4 uha.4 uk.4 ukphy.4 unix.4 userconf.4 \
|
||||
veriexec.4 vga.4 vge.4 viaide.4 vlan.4 vmmon.4 vmnet.4 vnd.4 vr.4 \
|
||||
veriexec.4 vga.4 vge.4 viaide.4 video.4 vlan.4 vmmon.4 vmnet.4 \
|
||||
vnd.4 vr.4 \
|
||||
wapbl.4 wd.4 wdc.4 wi.4 wm.4 wpi.4 wscons.4 wsdisplay.4 wsfont.4 \
|
||||
wskbd.4 wsmouse.4 wsmux.4 \
|
||||
xbox.4 xge.4 \
|
||||
|
||||
244
share/man/man4/video.4
Normal file
244
share/man/man4/video.4
Normal file
@ -0,0 +1,244 @@
|
||||
.\" $NetBSD: video.4,v 1.1 2008/09/06 19:08:29 jmcneill Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 2008 Patrick Mahoney
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
||||
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
||||
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||||
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
||||
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||||
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
||||
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
||||
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
||||
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||
.\" POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd August 11, 2008
|
||||
.Dt VIDEO 4
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm video
|
||||
.Nd device-independent video driver layer
|
||||
.Sh SYNOPSIS
|
||||
.In sys/videoio.h
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Nm
|
||||
driver provides support for various video peripherals.
|
||||
It provides a uniform programming interface layer above different
|
||||
underlying video hardware drivers. The video layer provides a Video4Linux2
|
||||
compatible API. A number of
|
||||
.Xr ioctl 2
|
||||
commands are supported controling the device.
|
||||
See http://v4l2spec.bytesex.org/ for the official V4L2
|
||||
specification.
|
||||
.Pp
|
||||
The device file for video operation is:
|
||||
.Pa /dev/video
|
||||
.Sh READING VIDEO SAMPLES
|
||||
Video data is separated into logical video samples which will
|
||||
typically be one complete video frame. With compressed formats, a
|
||||
video sample may be one logical chunk and not one complete frame
|
||||
depending on the compression format. Video samples may be read from
|
||||
.Pa /dev/video
|
||||
in one of several different modes.
|
||||
.Pp
|
||||
In read mode, calls to
|
||||
.Xr read 2
|
||||
will return at most the data of one video sample. If the entire
|
||||
sample is not read, then subsequent reads will return at most the
|
||||
remaining data in that video sample.
|
||||
.Pp
|
||||
Video samples may be mapped into memory with
|
||||
.Xr mmap 2 .
|
||||
The driver allocates internal buffers for a number of video samples
|
||||
which are mapped into memory.
|
||||
Initiating this mode requires several
|
||||
.Xr ioctl 2
|
||||
commands:
|
||||
.Dv VIDIOC_REQBUFS
|
||||
to request the driver reserve buffers,
|
||||
.Dv VIDIOC_QUERYBUF
|
||||
to query the details of each buffer,
|
||||
.Xr mmap 2
|
||||
to map each buffer into memory,
|
||||
.Dv VIDIOC_QBUF
|
||||
to queue the buffers for receiving video data,
|
||||
.Dv VIDIOC_STREAMON
|
||||
to begin streaming of video data, and
|
||||
.Dv VIDIOC_DQBUF
|
||||
to remove a filled buffer from the queue. At this point the video
|
||||
data from the dequeued buffer is valid.
|
||||
.Sh DEVICE CAPABILITIES
|
||||
.Bl -tag -width indent
|
||||
.It Dv VIDIOC_QUERYCAP (struct v4l2_capabilities)
|
||||
This command queries the capabilities of the device.
|
||||
The first three fields are informational NULL terminated strings
|
||||
filled by the driver:
|
||||
.Va driver
|
||||
describes the driver used by this device,
|
||||
.Va card
|
||||
describes the video capture card or camera, and
|
||||
.Va buf_info
|
||||
represents the bus to which the hardware device is attached.
|
||||
.Pp
|
||||
The
|
||||
.Va capabilities
|
||||
field contains a number of flags indicating various features supported
|
||||
by the driver or hardware:
|
||||
.Pp
|
||||
.Bl -tag -width indent
|
||||
.It Dv V4L2_CAP_VIDEO_CAPTURE
|
||||
support video capturing
|
||||
.It Dv V4L2_CAP_READWRITE
|
||||
supports the
|
||||
.Xr read 2
|
||||
and/or
|
||||
.Xr write 2
|
||||
mode
|
||||
.It Dv V4L2_CAP_STREAMING
|
||||
supports
|
||||
.Xr mmap 2
|
||||
mode
|
||||
.El
|
||||
.Bd -literal
|
||||
struct v4l2_capability {
|
||||
uint8_t driver[16];
|
||||
uint8_t card[32];
|
||||
uint8_t bus_info[32];
|
||||
uint32_t version;
|
||||
uint32_t capabilities;
|
||||
uint32_t reserved[4];
|
||||
};
|
||||
.Ed
|
||||
.El
|
||||
.Sh STREAMING INTERFACE
|
||||
.Bl -tag -width indent
|
||||
.It Dv VIDIOC_REQBUFS (struct v4l2_requestbuffers)
|
||||
This command requests that the driver reserve space for
|
||||
.Va count
|
||||
samples.
|
||||
.Va type
|
||||
must be set to
|
||||
.Dv V4L2_BUF_TYPE_VIDEO_CAPTURE
|
||||
and
|
||||
.Va memory
|
||||
to
|
||||
.Dv V4L2_MEMORY_MMAP .
|
||||
The returned
|
||||
.Va count
|
||||
represents the actual number of samples reserved which may be more
|
||||
or fewer than requested.
|
||||
.Bd -literal
|
||||
struct v4l2_requestbuffers {
|
||||
uint32_t count;
|
||||
enum v4l2_buf_type type;
|
||||
enum v4l2_memory memory;
|
||||
uint32_t reserved[2];
|
||||
};
|
||||
.Ed
|
||||
.It Dv VIDIOC_QUERYBUF (struct v4l2_buffer)
|
||||
This command should be called for each buffer in
|
||||
.Va count
|
||||
above. The fields
|
||||
.Va index ,
|
||||
.Va type , and
|
||||
.Va memory
|
||||
must be set to a valid index from 0 to
|
||||
.Va count-1 ,
|
||||
and the same type and memory as used in
|
||||
.Dv VIDIOC_QUERYBUF .
|
||||
The driver returns
|
||||
.Va m.offset and
|
||||
.Va length .
|
||||
.Bd -literal
|
||||
struct v4l2_buffer {
|
||||
uint32_t index;
|
||||
enum v4l2_buf_type type;
|
||||
uint32_t bytesused;
|
||||
uint32_t flags;
|
||||
enum v4l2_field field;
|
||||
struct timeval timestamp;
|
||||
struct v4l2_timecode timecode;
|
||||
uint32_t sequence;
|
||||
enum v4l2_memory memory;
|
||||
union {
|
||||
uint32_t offset;
|
||||
unsigned long userptr;
|
||||
} m;
|
||||
uint32_t length;
|
||||
uint32_t input;
|
||||
uint32_t reserved;
|
||||
};
|
||||
.Ed
|
||||
.It Xr mmap 2
|
||||
Each buffer must be mapped with a call to
|
||||
.Xr mmap 2 ,
|
||||
passing the
|
||||
.Va length
|
||||
and
|
||||
.Va m.offset
|
||||
values obtained above. The prot
|
||||
.Dv PROT_READ|PROT_WRITE
|
||||
and flags
|
||||
.Dv MAP_SHARED
|
||||
are recommended.
|
||||
.It Dv VIDIOC_QBUF (struct v4l2_buffer)
|
||||
This command indicates to the driver that the buffer is ready to
|
||||
receive a video sample. The following fields must be set:
|
||||
.Va index ,
|
||||
set to a valid buffer index from 0 to
|
||||
.Va count
|
||||
- 1;
|
||||
.Va type ,
|
||||
set to the same type used above; and
|
||||
.Va memory ,
|
||||
set to the same memory used above. Each buffer should be queued with
|
||||
this command. Order is not important.
|
||||
.It Dv VIDIOC_STREAMON (int)
|
||||
This command starts streaming. Queued buffers will be filled with data.
|
||||
.Xr select 2
|
||||
will indicate that a buffer is done and available for reading.
|
||||
.It Dv VIDIOC_DQBUF (struct v4l2_buffer)
|
||||
This command dequeues an available buffer from the driver. If no
|
||||
buffer is available, it blocks until one is, unless O_NONBLOCK was
|
||||
specified to
|
||||
.Xr open 2 ,
|
||||
in which case it returns
|
||||
.Dv EAGAIN .
|
||||
.Xr select 2 , or
|
||||
.Xr poll 2
|
||||
prior to initiating any other mode will begin streaming of video for
|
||||
reading with
|
||||
.Xr read 2 .
|
||||
In this streaming mode
|
||||
.Xr select 2 or
|
||||
.Xr poll 2
|
||||
indicate the availability of a video frame. Calls to
|
||||
.Xr read 2
|
||||
will return at most the video data of one video sample. If the entire
|
||||
sample is not read, then subsequent reads will return at most the
|
||||
remaining data in that video sample.
|
||||
.El
|
||||
.Sh FILES
|
||||
.Bl -tag -width /dev/video -compact
|
||||
.It Pa /dev/video
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Ss USB
|
||||
.Xr uvideo 4
|
||||
.Sh BUGS
|
||||
Does not support all of V4L2 api. Only supports the capture
|
||||
interface. Does not support writing, overlay, VBI, tuner, audio,
|
||||
radio, or asyncio
|
||||
@ -1,4 +1,4 @@
|
||||
# $NetBSD: Makefile,v 1.268 2008/09/03 03:02:48 erh Exp $
|
||||
# $NetBSD: Makefile,v 1.269 2008/09/06 19:08:29 jmcneill Exp $
|
||||
|
||||
# Makefile for section 9 (kernel function and variable) manual pages.
|
||||
|
||||
@ -51,7 +51,8 @@ MAN= accept_filter.9 accf_data.9 accf_http.9 \
|
||||
store.9 suspendsched.9 \
|
||||
sysctl.9 sysmon_envsys.9 tc.9 tcp_congctl.9 timecounter.9 \
|
||||
time_second.9 todr.9 uiomove.9 ucom.9 userret.9 \
|
||||
vattr.9 veriexec.9 vcons.9 vfs.9 vfs_hooks.9 vfsops.9 vfssubr.9 vme.9 \
|
||||
vattr.9 veriexec.9 vcons.9 vfs.9 vfs_hooks.9 vfsops.9 vfssubr.9 \
|
||||
video.9 vme.9 \
|
||||
vnfileops.9 vnode.9 vnodeops.9 vnsubr.9 \
|
||||
usbdi.9 uvm.9 \
|
||||
vmem.9 vmem_alloc.9 vmem_create.9 vmem_destroy.9 vmem_free.9 \
|
||||
|
||||
176
share/man/man9/video.9
Normal file
176
share/man/man9/video.9
Normal file
@ -0,0 +1,176 @@
|
||||
.\" $NetBSD: video.9,v 1.1 2008/09/06 19:08:29 jmcneill Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 2008 Patrick Mahoney
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
||||
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
||||
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||||
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
||||
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||||
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
||||
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
||||
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
||||
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||
.\" POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd July 24, 2008
|
||||
.Dt VIDEO 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm video
|
||||
.Nd interface between low and high level audio drivers
|
||||
.Sh SYNOPSIS
|
||||
.In dev/video_if.h
|
||||
.Ft device_t
|
||||
.Fn video_attach_mi "const struct video_hw_if *hw_if" "device_t hw_dev"
|
||||
.Ft void
|
||||
.Fn video_submit_payload "devict_t vl_dev" "const struct video_payload *payload"
|
||||
.Sh DESCRIPTION
|
||||
The video device driver is divided into a high level, machine
|
||||
independent layer, and a low level hardware dependent layer. The
|
||||
interface between these is the
|
||||
.Fa video_hw_if
|
||||
structure function pointers called by the video layer, and video layer
|
||||
functions called by the hardware driver.
|
||||
.Pp
|
||||
The high level video driver attaches to the low level driver
|
||||
when the latter calls
|
||||
.Fa video_attach_mi .
|
||||
The
|
||||
.Fa video_hw_if
|
||||
struct is as shown below.
|
||||
.Fa dev
|
||||
is the device struct for the hardware device. Return value is the
|
||||
video layer device.
|
||||
.Bd -literal
|
||||
struct video_hw_if {
|
||||
int (*open)(void *, int); /* open hardware */
|
||||
void (*close)(void *); /* close hardware */
|
||||
|
||||
const char * (*get_devname)(void *);
|
||||
|
||||
int (*enum_format)(void *, uint32_t, struct video_format *);
|
||||
int (*get_format)(void *, struct video_format *);
|
||||
int (*set_format)(void *, struct video_format *);
|
||||
int (*try_format)(void *, struct video_format *);
|
||||
|
||||
int (*start_transfer)(void *);
|
||||
int (*stop_transfer)(void *);
|
||||
|
||||
int (*control_iter_init)(void *, struct video_control_iter *);
|
||||
int (*control_iter_next)(void *, struct video_control_iter *);
|
||||
int (*get_control_desc_group)(void *,
|
||||
struct video_control_desc_group *);
|
||||
int (*get_control_group)(void *, struct video_control_group *);
|
||||
int (*set_control_group)(void *, const struct video_control_group *);
|
||||
};
|
||||
.Ed
|
||||
.Pp
|
||||
The upper layer of the video driver allocates buffers for video
|
||||
samples. The hardware driver submits data to the video layer with
|
||||
.Fa video_submit_payload .
|
||||
.Fa vl_dev
|
||||
is the video layer device returned by
|
||||
.Fa video_attach_mi .
|
||||
.Bl -tag -width indent
|
||||
.Bd -literal
|
||||
struct video_payload {
|
||||
const uint8_t *data;
|
||||
size_t size;
|
||||
int frameno;
|
||||
bool end_of_frame;
|
||||
};
|
||||
.Ed
|
||||
.It Fa data
|
||||
Pointer to the video data for this payload. This may only be a
|
||||
portion of the data in one video sample or frame.
|
||||
.It Fa size
|
||||
Size in bytes of the video data in this payload
|
||||
.It Fa frameno
|
||||
Frame number to which this payload belongs. The hardware driver must
|
||||
toggle the frame number between 0 and 1 so the video layer can detect
|
||||
sample or frame boundaries.
|
||||
.It Fa end_of_frame
|
||||
Optional end of frame marker. If the hardware layer sets this, the
|
||||
video layer can immediately pass the completed sample or frame to
|
||||
userspace rather than waiting for the next payload to toggle
|
||||
.Fa frameno .
|
||||
.El
|
||||
.Sh HARDWARE-LAYER FUNCTIONS
|
||||
The fields of
|
||||
.Va video_hw_if
|
||||
are described in some more detail below.
|
||||
Some fields are optional and can be set to NULL if not needed.
|
||||
.Bl -tag -width indent
|
||||
.It Dv int open(void *hdl, int flags)
|
||||
optional, is called when the video device is opened.
|
||||
It should initialize the hardware for I/O.
|
||||
Every successful call to
|
||||
.Va open
|
||||
is matched by a call to
|
||||
.Va close .
|
||||
Return 0 on success, otherwise an error code.
|
||||
.It Dv void close(void *hdl)
|
||||
optional, is called when the audio device is closed.
|
||||
.It Dv const char * get_devname(void *hdl)
|
||||
mandatory, returns a NULL-terminated string naming the device, e.g. a
|
||||
vendor and product model name.
|
||||
.It Dv int enum_format(void *hdl, uint32_t index, struct video_format *format);
|
||||
mandatory, called with an
|
||||
.Va index
|
||||
from 0 to
|
||||
.Va max_index - 1 .
|
||||
Fills
|
||||
.Va format
|
||||
with the format description at that index. Returns 0 on success,
|
||||
otherwise an error code.
|
||||
.It Dv int get_format(void *hdl, struct video_format *format)
|
||||
mandatory, fills
|
||||
.Va format
|
||||
with the current video format. There should be a default format so
|
||||
this function works before and streaming has begun. Returns 0 on
|
||||
success, otherwise an error code.
|
||||
.It Dv int set_format(void *hdl, struct video_format *format)
|
||||
mandatory, sets the format of the video stream based on
|
||||
.Va format .
|
||||
Fills
|
||||
.Va format
|
||||
with the actual format used which may not be the same as requested.
|
||||
Returns 0 on success, otherwise an error code.
|
||||
.It Dv int try_format(void *hdl, struct video_format *format)
|
||||
optional, like
|
||||
.Va set_format
|
||||
but does not actually change the stream format, just checks what is
|
||||
available. Returns 0 on success, otherwise an error code.
|
||||
.It Dv int start_transfer(void *hdl)
|
||||
mandatory, starts the capture of video frames. Incoming video data
|
||||
must be submitted to the video layer with repeated calls to
|
||||
.Va video_submit_payload() .
|
||||
.It Dv int stop_transfer(void *hdl)
|
||||
.It Dv int control_iter_init(void *hdl, struct video_control_iter *)
|
||||
Does nothing at this time.
|
||||
.It Dv int control_iter_next(void *hdl, struct video_control_iter *)
|
||||
Does nothing at this time.
|
||||
.It Dv int get_control_group(void *hdl, struct video_control_group *)
|
||||
.It Dv int set_control_group(void *hdl, struct video_control_group *)
|
||||
.El
|
||||
.Pp
|
||||
.Sh SEE ALSO
|
||||
.Xr video 4
|
||||
.Sh BUGS
|
||||
Incomplete. Only supports a single video capture stream. Does not
|
||||
support output streams. Format handling may change in the future.
|
||||
Control handling may change. Current design requires copying all
|
||||
incoming video data.
|
||||
Loading…
Reference in New Issue
Block a user