From 7146a9cfa499ac3bfaea18555d67afb04cac40c3 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sun, 13 Sep 2015 13:41:30 -0300 Subject: [media] DocBook media: document the new DCI-P3 colorspace Document this colorspace. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/biblio.xml | 9 ++++ Documentation/DocBook/media/v4l/pixfmt.xml | 70 ++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index fdee6b3..f54db59 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -177,6 +177,15 @@ Signal - NTSC for Studio Applications" 1125-Line High-Definition Production" + + SMPTE RP 431-2 + + Society of Motion Picture and Television Engineers +(http://www.smpte.org) + + SMPTE RP 431-2:2011 "D-Cinema Quality - Reference Projector and Environment" + + sRGB diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index 965ea91..4173333 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -540,6 +540,10 @@ colorspaces except for BT.2020 which uses limited range R'G'B' quantization.See . + V4L2_COLORSPACE_DCI_P3 + See . + + V4L2_COLORSPACE_SMPTE240M See . @@ -601,6 +605,10 @@ colorspaces except for BT.2020 which uses limited range R'G'B' quantization.V4L2_XFER_FUNC_NONE Do not use a transfer function (i.e. use linear RGB values). + + V4L2_XFER_FUNC_DCI_P3 + Use the DCI-P3 transfer function. + @@ -1154,6 +1162,68 @@ clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range clamped to the range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range. +
+ Colorspace DCI-P3 (<constant>V4L2_COLORSPACE_DCI_P3</constant>) + The standard defines the colorspace used by cinema +projectors that use the DCI-P3 colorspace. +The default transfer function is V4L2_XFER_FUNC_DCI_P3. +The default Y'CbCr encoding is V4L2_YCBCR_ENC_709. Note that this +colorspace does not specify a Y'CbCr encoding since it is not meant to be encoded +to Y'CbCr. So this default Y'CbCr encoding was picked because it is the HDTV +encoding. The default Y'CbCr quantization is limited range. The chromaticities of +the primary colors and the white reference are: + + DCI-P3 Chromaticities + + &cs-str; + + + Color + x + y + + + + + Red + 0.6800 + 0.3200 + + + Green + 0.2650 + 0.6900 + + + Blue + 0.1500 + 0.0600 + + + White Reference + 0.3140 + 0.3510 + + + +
+ + + Transfer function: + + L' = L1/2.6 + + + + Inverse Transfer function: + + L = L'2.6 + + + + Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709. +
+
Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>) The standard was an interim standard used during -- cgit v1.1 From 00507a8d6a86973e55076ea21053fd8e786391eb Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sun, 13 Sep 2015 16:15:21 -0300 Subject: [media] DocBook media: Document the SMPTE 2084 transfer function Document this new transfer function used by High Dynamic Range content. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/biblio.xml | 9 +++++++ Documentation/DocBook/media/v4l/pixfmt.xml | 39 ++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index f54db59..9beb30f 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -186,6 +186,15 @@ Signal - NTSC for Studio Applications" SMPTE RP 431-2:2011 "D-Cinema Quality - Reference Projector and Environment" + + SMPTE ST 2084 + + Society of Motion Picture and Television Engineers +(http://www.smpte.org) + + SMPTE ST 2084:2014 "High Dynamic Range Electro-Optical Transfer Function of Master Reference Displays" + + sRGB diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index 4173333..70cd0fd 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -609,6 +609,10 @@ colorspaces except for BT.2020 which uses limited range R'G'B' quantization.V4L2_XFER_FUNC_DCI_P3 Use the DCI-P3 transfer function. + + V4L2_XFER_FUNC_SMPTE2084 + Use the SMPTE 2084 transfer function. + @@ -1472,6 +1476,41 @@ and V4L2_QUANTIZATION_FULL_RANGE.
+
+ Detailed Transfer Function Descriptions +
+ Transfer Function SMPTE 2084 (<constant>V4L2_XFER_FUNC_SMPTE2084</constant>) + The standard defines the transfer function used by +High Dynamic Range content. + + + Constants: + + m1 = (2610 / 4096) / 4 + m2 = (2523 / 4096) * 128 + c1 = 3424 / 4096 + c2 = (2413 / 4096) * 32 + c3 = (2392 / 4096) * 32 + + + + Transfer function: + + L' = ((c1 + c2 * Lm1) / (1 + c3 * Lm1))m2 + + + + + + Inverse Transfer function: + + L = (max(L'1/m2 - c1, 0) / (c2 - c3 * L'1/m2))1/m1 + + + +
+
+
Indexed Format -- cgit v1.1 From 60f4570de80264428ddbd350dc8ed1d95f9dcd9d Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 21 Sep 2015 06:21:55 -0300 Subject: [media] DocBook/media: clarify control documentation - Add missing V4L2_CTRL_TYPE_U32 documentation - Remove 'which are actually different on the hardware' sentence which is confusing. I think the idea was to let the user know that the step can be different for different hardware, but that's obvious because otherwise you wouldn't need to specify the step value. - Clarify that V4L2_CTRL_COMPOUND_TYPES also applies to arrays. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- .../DocBook/media/v4l/vidioc-g-ext-ctrls.xml | 7 +++++++ .../DocBook/media/v4l/vidioc-queryctrl.xml | 21 ++++++++++++++++----- 2 files changed, 23 insertions(+), 5 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml index c5bdbfc..842536a 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml @@ -200,6 +200,13 @@ Valid if this control is of type V4L2_CTRL_TYPE_U16. + __u32 * + p_u32 + A pointer to a matrix control of unsigned 32-bit values. +Valid if this control is of type V4L2_CTRL_TYPE_U32. + + + void * ptr A pointer to a compound type which can be an N-dimensional array and/or a diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml index 6ec39c6..55b7582 100644 --- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml +++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml @@ -101,8 +101,9 @@ prematurely end the enumeration). next supported non-compound control, or EINVAL if there is none. In addition, the V4L2_CTRL_FLAG_NEXT_COMPOUND flag can be specified to enumerate all compound controls (i.e. controls -with type ≥ V4L2_CTRL_COMPOUND_TYPES). Specify both -V4L2_CTRL_FLAG_NEXT_CTRL and +with type ≥ V4L2_CTRL_COMPOUND_TYPES and/or array +control, in other words controls that contain more than one value). +Specify both V4L2_CTRL_FLAG_NEXT_CTRL and V4L2_CTRL_FLAG_NEXT_COMPOUND in order to enumerate all controls, compound or not. Drivers which do not support these flags yet always return EINVAL. @@ -422,7 +423,7 @@ the array to zero. any An integer-valued control ranging from minimum to maximum inclusive. The step value indicates the increment between -values which are actually different on the hardware. +values. V4L2_CTRL_TYPE_BOOLEAN @@ -518,7 +519,7 @@ Older drivers which do not support this feature return an any An unsigned 8-bit valued control ranging from minimum to maximum inclusive. The step value indicates the increment between -values which are actually different on the hardware. +values. @@ -528,7 +529,17 @@ values which are actually different on the hardware. any An unsigned 16-bit valued control ranging from minimum to maximum inclusive. The step value indicates the increment between -values which are actually different on the hardware. +values. + + + + V4L2_CTRL_TYPE_U32 + any + any + any + An unsigned 32-bit valued control ranging from minimum to +maximum inclusive. The step value indicates the increment between +values. -- cgit v1.1 From 1ccd66cca96a377ef924d2ee76fbb753a7bec9ea Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 1 Oct 2015 09:12:23 -0300 Subject: [media] DocBook: add the new videobuf2-v4l2 header This header should also be used to generate documentation. So, add it. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/device-drivers.tmpl | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 1d6008d..31cefc9 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -231,6 +231,7 @@ X!Isound/sound_firmware.c !Iinclude/media/v4l2-of.h !Iinclude/media/v4l2-subdev.h !Iinclude/media/videobuf2-core.h +!Iinclude/media/videobuf2-v4l2.h !Iinclude/media/videobuf2-memops.h Digital TV (DVB) devices -- cgit v1.1 From 07c68a7423c4e44cc4f85caa83bb7fae36367250 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 5 Oct 2015 09:50:36 -0300 Subject: [media] DocBook: Document include/media/tuner.h This is part of the V4L2 core, so its kABI should be documented at device-drivers DocBook. Add the meta-tags for that. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/device-drivers.tmpl | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 31cefc9..2fc3bca 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -221,6 +221,7 @@ X!Isound/sound_firmware.c Media Devices Video2Linux devices +!Iinclude/media/tuner.h !Iinclude/media/v4l2-async.h !Iinclude/media/v4l2-ctrls.h !Iinclude/media/v4l2-dv-timings.h -- cgit v1.1 From 5057f3262c52434fea9eda17494716b9649f25bd Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 5 Oct 2015 11:37:15 -0300 Subject: [media] DocBook: add documentation for tuner-types.h The tuner-types.h is part of the V4L2 core and should be touched for every new tuner added. So, it deserves to be documented at the device-drivers DocBook. Add it to device-drivers.tmpl and add descriptions for enum param_type and struct tuner_range. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/device-drivers.tmpl | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 2fc3bca..8ce967a 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -222,6 +222,7 @@ X!Isound/sound_firmware.c Video2Linux devices !Iinclude/media/tuner.h +!Iinclude/media/tuner-types.h !Iinclude/media/v4l2-async.h !Iinclude/media/v4l2-ctrls.h !Iinclude/media/v4l2-dv-timings.h -- cgit v1.1 From 326ab27bbddf053e6b578fde312b5069aa55b2ab Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 5 Oct 2015 13:08:34 -0300 Subject: [media] DocBook: Document tveeprom.h This header declares the code and structures used to parse Hauppauge eeproms. As this is part of the V4L2 common, and used by several drivers, let's properly document it. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/device-drivers.tmpl | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 8ce967a..bdc0f7e 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -223,6 +223,7 @@ X!Isound/sound_firmware.c Video2Linux devices !Iinclude/media/tuner.h !Iinclude/media/tuner-types.h +!Iinclude/media/tveeprom.h !Iinclude/media/v4l2-async.h !Iinclude/media/v4l2-ctrls.h !Iinclude/media/v4l2-dv-timings.h -- cgit v1.1 From be14c5cd592b6a268c825ca78ff7be758bab316d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 5 Oct 2015 13:35:37 -0300 Subject: [media] DocBook: Convert struct lirc_driver to doc-nano format The struct lirc_driver is already documented, but on some internal format. Convert it to Kernel doc-nano format and add documentation for some additional parameters that are also present at the structure. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/device-drivers.tmpl | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index bdc0f7e..44634e2 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -246,6 +246,7 @@ X!Isound/sound_firmware.c Remote Controller devices !Iinclude/media/rc-core.h +!Iinclude/media/lirc_dev.h Media Controller devices !Iinclude/media/media-device.h -- cgit v1.1 From 95abfdb942a44e165c54a4e890a9b91a1eeb8621 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 5 Oct 2015 15:10:55 -0300 Subject: [media] DocBook: Move struct dmx_demux kABI doc to demux.h The DocBook/media/dvb/kdapi.xml contains the description of the kABI for DVB. The problem is that, by being maintained on a separate file and not being updated for years, it got outdated. So, for example, some callback parameters were changed, but the DocBook were still using the old stuff. As a first step to fix it, let's move the documentation of struct dmx_demux into demux.h and fix the parameters used there. For now, don't document any other field nor touch the descriptions that got moved, letting this job to other patches. That makes easier to review the patch. PS.: Please notice that an additional patch will be needed in order to fix the return values (some uses non-existent return codes) and to the functions and callbacks mentioned at the descriptions. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/device-drivers.tmpl | 1 + Documentation/DocBook/media/dvb/kdapi.xml | 1034 ----------------------------- 2 files changed, 1 insertion(+), 1034 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 44634e2..8d5620a 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -239,6 +239,7 @@ X!Isound/sound_firmware.c Digital TV (DVB) devices !Idrivers/media/dvb-core/dvb_ca_en50221.h +!Idrivers/media/dvb-core/demux.h !Idrivers/media/dvb-core/dvb_frontend.h !Idrivers/media/dvb-core/dvb_math.h !Idrivers/media/dvb-core/dvb_ringbuffer.h diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml index 68bcd33..6efc3ab 100644 --- a/Documentation/DocBook/media/dvb/kdapi.xml +++ b/Documentation/DocBook/media/dvb/kdapi.xml @@ -214,62 +214,6 @@ should be kept identical) to the types in the demux device. ⋆ to the type ⋆ dmx_frontend_t ⋆. ⋆/ - - #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list) - - struct dmx_demux_s { - /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ - char⋆ id; /⋆ Unique demux identifier ⋆/ - char⋆ vendor; /⋆ Name of the demux vendor ⋆/ - char⋆ model; /⋆ Name of the demux model ⋆/ - __u32 capabilities; /⋆ Bitfield of capability flags ⋆/ - dmx_frontend_t⋆ frontend; /⋆ Front-end connected to the demux ⋆/ - struct list_head reg_list; /⋆ List of registered demuxes ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - int users; /⋆ Number of users ⋆/ - int (⋆open) (struct dmx_demux_s⋆ demux); - int (⋆close) (struct dmx_demux_s⋆ demux); - int (⋆write) (struct dmx_demux_s⋆ demux, const char⋆ buf, size_t count); - int (⋆allocate_ts_feed) (struct dmx_demux_s⋆ demux, - dmx_ts_feed_t⋆⋆ feed, - dmx_ts_cb callback); - int (⋆release_ts_feed) (struct dmx_demux_s⋆ demux, - dmx_ts_feed_t⋆ feed); - int (⋆allocate_pes_feed) (struct dmx_demux_s⋆ demux, - dmx_pes_feed_t⋆⋆ feed, - dmx_pes_cb callback); - int (⋆release_pes_feed) (struct dmx_demux_s⋆ demux, - dmx_pes_feed_t⋆ feed); - int (⋆allocate_section_feed) (struct dmx_demux_s⋆ demux, - dmx_section_feed_t⋆⋆ feed, - dmx_section_cb callback); - int (⋆release_section_feed) (struct dmx_demux_s⋆ demux, - dmx_section_feed_t⋆ feed); - int (⋆descramble_mac_address) (struct dmx_demux_s⋆ demux, - __u8⋆ buffer1, - size_t buffer1_length, - __u8⋆ buffer2, - size_t buffer2_length, - __u16 pid); - int (⋆descramble_section_payload) (struct dmx_demux_s⋆ demux, - __u8⋆ buffer1, - size_t buffer1_length, - __u8⋆ buffer2, size_t buffer2_length, - __u16 pid); - int (⋆add_frontend) (struct dmx_demux_s⋆ demux, - dmx_frontend_t⋆ frontend); - int (⋆remove_frontend) (struct dmx_demux_s⋆ demux, - dmx_frontend_t⋆ frontend); - struct list_head⋆ (⋆get_frontends) (struct dmx_demux_s⋆ demux); - int (⋆connect_frontend) (struct dmx_demux_s⋆ demux, - dmx_frontend_t⋆ frontend); - int (⋆disconnect_frontend) (struct dmx_demux_s⋆ demux); - - - /⋆ added because js cannot keep track of these himself ⋆/ - int (⋆get_pes_pids) (struct dmx_demux_s⋆ demux, __u16 ⋆pids); - }; - typedef struct dmx_demux_s dmx_demux_t;
@@ -487,985 +431,7 @@ interface from a bottom half context. Thus, if a demux API function is called fr device code, the function must not sleep. - -
-open() -DESCRIPTION - - -This function reserves the demux for use by the caller and, if necessary, - initializes the demux. When the demux is no longer needed, the function close() - should be called. It should be possible for multiple clients to access the demux - at the same time. Thus, the function implementation should increment the - demux usage count when open() is called and decrement it when close() is - called. - - -SYNOPSIS - - -int open ( demux_t⋆ demux ); - - -PARAMETERS - - -demux_t* demux - -Pointer to the demux API and instance data. - - -RETURNS - - -0 - -The function was completed without errors. - - --EUSERS - -Maximum usage count reached. - - --EINVAL - -Bad parameter. - - - -
-
-close() -DESCRIPTION - - -This function reserves the demux for use by the caller and, if necessary, - initializes the demux. When the demux is no longer needed, the function close() - should be called. It should be possible for multiple clients to access the demux - at the same time. Thus, the function implementation should increment the - demux usage count when open() is called and decrement it when close() is - called. - - -SYNOPSIS - - -int close(demux_t⋆ demux); - - -PARAMETERS - - -demux_t* demux - -Pointer to the demux API and instance data. - - -RETURNS - - -0 - -The function was completed without errors. - - --ENODEV - -The demux was not in use. - - --EINVAL - -Bad parameter. - - -
-
-write() -DESCRIPTION - - -This function provides the demux driver with a memory buffer containing TS - packets. Instead of receiving TS packets from the DVB front-end, the demux - driver software will read packets from memory. Any clients of this demux - with active TS, PES or Section filters will receive filtered data via the Demux - callback API (see 0). The function returns when all the data in the buffer has - been consumed by the demux. Demux hardware typically cannot read TS from - memory. If this is the case, memory-based filtering has to be implemented - entirely in software. - - -SYNOPSIS - - -int write(demux_t⋆ demux, const char⋆ buf, size_t - count); - - -PARAMETERS - - -demux_t* demux - -Pointer to the demux API and instance data. - - -const char* buf - -Pointer to the TS data in kernel-space memory. - - -size_t length - -Length of the TS data. - - -RETURNS - - -0 - -The function was completed without errors. - - --ENOSYS - -The command is not implemented. - - --EINVAL - -Bad parameter. - - - -
allocate_ts_feed() -DESCRIPTION - - -Allocates a new TS feed, which is used to filter the TS packets carrying a - certain PID. The TS feed normally corresponds to a hardware PID filter on the - demux chip. - - -SYNOPSIS - - -int allocate_ts_feed(dmx_demux_t⋆ demux, - dmx_ts_feed_t⋆⋆ feed, dmx_ts_cb callback); - - -PARAMETERS - - -demux_t* demux - -Pointer to the demux API and instance data. - - -dmx_ts_feed_t** - feed - -Pointer to the TS feed API and instance data. - - -dmx_ts_cb callback - -Pointer to the callback function for passing received TS - packet - - -RETURNS - - -0 - -The function was completed without errors. - - --EBUSY - -No more TS feeds available. - - --ENOSYS - -The command is not implemented. - - --EINVAL - -Bad parameter. - - - -
release_ts_feed() -DESCRIPTION - - -Releases the resources allocated with allocate_ts_feed(). Any filtering in - progress on the TS feed should be stopped before calling this function. - - -SYNOPSIS - - -int release_ts_feed(dmx_demux_t⋆ demux, - dmx_ts_feed_t⋆ feed); - - -PARAMETERS - - -demux_t* demux - -Pointer to the demux API and instance data. - - -dmx_ts_feed_t* feed - -Pointer to the TS feed API and instance data. - - -RETURNS - - -0 - -The function was completed without errors. - - --EINVAL - -Bad parameter. - - - -
allocate_section_feed() -DESCRIPTION - - -Allocates a new section feed, i.e. a demux resource for filtering and receiving - sections. On platforms with hardware support for section filtering, a section - feed is directly mapped to the demux HW. On other platforms, TS packets are - first PID filtered in hardware and a hardware section filter then emulated in - software. The caller obtains an API pointer of type dmx_section_feed_t as an - out parameter. Using this API the caller can set filtering parameters and start - receiving sections. - - -SYNOPSIS - - -int allocate_section_feed(dmx_demux_t⋆ demux, - dmx_section_feed_t ⋆⋆feed, dmx_section_cb callback); - - -PARAMETERS - - -demux_t *demux - -Pointer to the demux API and instance data. - - -dmx_section_feed_t - **feed - -Pointer to the section feed API and instance data. - - -dmx_section_cb - callback - -Pointer to the callback function for passing received - sections. - - -RETURNS - - -0 - -The function was completed without errors. - - --EBUSY - -No more section feeds available. - - --ENOSYS - -The command is not implemented. - - --EINVAL - -Bad parameter. - - - -
release_section_feed() -DESCRIPTION - - -Releases the resources allocated with allocate_section_feed(), including - allocated filters. Any filtering in progress on the section feed should be stopped - before calling this function. - - -SYNOPSIS - - -int release_section_feed(dmx_demux_t⋆ demux, - dmx_section_feed_t ⋆feed); - - -PARAMETERS - - -demux_t *demux - -Pointer to the demux API and instance data. - - -dmx_section_feed_t - *feed - -Pointer to the section feed API and instance data. - - -RETURNS - - -0 - -The function was completed without errors. - - --EINVAL - -Bad parameter. - - - -
descramble_mac_address() -DESCRIPTION - - -This function runs a descrambling algorithm on the destination MAC - address field of a DVB Datagram Section, replacing the original address - with its un-encrypted version. Otherwise, the description on the function - descramble_section_payload() applies also to this function. - - -SYNOPSIS - - -int descramble_mac_address(dmx_demux_t⋆ demux, __u8 - ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, - size_t buffer2_length, __u16 pid); - - -PARAMETERS - - -dmx_demux_t - *demux - -Pointer to the demux API and instance data. - - -__u8 *buffer1 - -Pointer to the first byte of the section. - - -size_t buffer1_length - -Length of the section data, including headers and CRC, - in buffer1. - - -__u8* buffer2 - -Pointer to the tail of the section data, or NULL. The - pointer has a non-NULL value if the section wraps past - the end of a circular buffer. - - -size_t buffer2_length - -Length of the section data, including headers and CRC, - in buffer2. - - -__u16 pid - -The PID on which the section was received. Useful - for obtaining the descrambling key, e.g. from a DVB - Common Access facility. - - -RETURNS - - -0 - -The function was completed without errors. - - --ENOSYS - -No descrambling facility available. - - --EINVAL - -Bad parameter. - - - -
descramble_section_payload() -DESCRIPTION - - -This function runs a descrambling algorithm on the payload of a DVB - Datagram Section, replacing the original payload with its un-encrypted - version. The function will be called from the demux API implementation; - the API client need not call this function directly. Section-level scrambling - algorithms are currently standardized only for DVB-RCC (return channel - over 2-directional cable TV network) systems. For all other DVB networks, - encryption schemes are likely to be proprietary to each data broadcaster. Thus, - it is expected that this function pointer will have the value of NULL (i.e., - function not available) in most demux API implementations. Nevertheless, it - should be possible to use the function pointer as a hook for dynamically adding - a “plug-in” descrambling facility to a demux driver. - - -While this function is not needed with hardware-based section descrambling, - the descramble_section_payload function pointer can be used to override the - default hardware-based descrambling algorithm: if the function pointer has a - non-NULL value, the corresponding function should be used instead of any - descrambling hardware. - - -SYNOPSIS - - -int descramble_section_payload(dmx_demux_t⋆ demux, - __u8 ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, - size_t buffer2_length, __u16 pid); - - -PARAMETERS - - -dmx_demux_t - *demux - -Pointer to the demux API and instance data. - - -__u8 *buffer1 - -Pointer to the first byte of the section. - - -size_t buffer1_length - -Length of the section data, including headers and CRC, - in buffer1. - - -__u8 *buffer2 - -Pointer to the tail of the section data, or NULL. The - pointer has a non-NULL value if the section wraps past - the end of a circular buffer. - - -size_t buffer2_length - -Length of the section data, including headers and CRC, - in buffer2. - - -__u16 pid - -The PID on which the section was received. Useful - for obtaining the descrambling key, e.g. from a DVB - Common Access facility. - - -RETURNS - - -0 - -The function was completed without errors. - - --ENOSYS - -No descrambling facility available. - - --EINVAL - -Bad parameter. - - - -
add_frontend() -DESCRIPTION - - -Registers a connectivity between a demux and a front-end, i.e., indicates that - the demux can be connected via a call to connect_frontend() to use the given - front-end as a TS source. The client of this function has to allocate dynamic or - static memory for the frontend structure and initialize its fields before calling - this function. This function is normally called during the driver initialization. - The caller must not free the memory of the frontend struct before successfully - calling remove_frontend(). - - -SYNOPSIS - - -int add_frontend(dmx_demux_t ⋆demux, dmx_frontend_t - ⋆frontend); - - -PARAMETERS - - -dmx_demux_t* - demux - -Pointer to the demux API and instance data. - - -dmx_frontend_t* - frontend - -Pointer to the front-end instance data. - - -RETURNS - - -0 - -The function was completed without errors. - - --EEXIST - -A front-end with the same value of the id field already - registered. - - --EINUSE - -The demux is in use. - - --ENOMEM - -No more front-ends can be added. - - --EINVAL - -Bad parameter. - - - -
remove_frontend() -DESCRIPTION - - -Indicates that the given front-end, registered by a call to add_frontend(), can - no longer be connected as a TS source by this demux. The function should be - called when a front-end driver or a demux driver is removed from the system. - If the front-end is in use, the function fails with the return value of -EBUSY. - After successfully calling this function, the caller can free the memory of - the frontend struct if it was dynamically allocated before the add_frontend() - operation. - - -SYNOPSIS - - -int remove_frontend(dmx_demux_t⋆ demux, - dmx_frontend_t⋆ frontend); - - -PARAMETERS - - -dmx_demux_t* - demux - -Pointer to the demux API and instance data. - - -dmx_frontend_t* - frontend - -Pointer to the front-end instance data. - - -RETURNS - - -0 - -The function was completed without errors. - - --EINVAL - -Bad parameter. - - --EBUSY - -The front-end is in use, i.e. a call to connect_frontend() - has not been followed by a call to disconnect_frontend(). - - - -
get_frontends() -DESCRIPTION - - -Provides the APIs of the front-ends that have been registered for this demux. - Any of the front-ends obtained with this call can be used as a parameter for - connect_frontend(). - - -The include file demux.h contains the macro DMX_FE_ENTRY() for - converting an element of the generic type struct list_head* to the type - dmx_frontend_t*. The caller must not free the memory of any of the elements - obtained via this function call. - - -SYNOPSIS - - -struct list_head⋆ get_frontends(dmx_demux_t⋆ demux); - - -PARAMETERS - - -dmx_demux_t* - demux - -Pointer to the demux API and instance data. - - -RETURNS - - -dmx_demux_t* - -A list of front-end interfaces, or NULL in the case of an - empty list. - - - -
connect_frontend() -DESCRIPTION - - -Connects the TS output of the front-end to the input of the demux. A demux - can only be connected to a front-end registered to the demux with the function - add_frontend(). - - -It may or may not be possible to connect multiple demuxes to the same - front-end, depending on the capabilities of the HW platform. When not used, - the front-end should be released by calling disconnect_frontend(). - - -SYNOPSIS - - -int connect_frontend(dmx_demux_t⋆ demux, - dmx_frontend_t⋆ frontend); - - -PARAMETERS - - -dmx_demux_t* - demux - -Pointer to the demux API and instance data. - - -dmx_frontend_t* - frontend - -Pointer to the front-end instance data. - - -RETURNS - - -0 - -The function was completed without errors. - - --EINVAL - -Bad parameter. - - --EBUSY - -The front-end is in use. - - - -
disconnect_frontend() -DESCRIPTION - - -Disconnects the demux and a front-end previously connected by a - connect_frontend() call. - - -SYNOPSIS - - -int disconnect_frontend(dmx_demux_t⋆ demux); - - -PARAMETERS - - -dmx_demux_t* - demux - -Pointer to the demux API and instance data. - - -RETURNS - - -0 - -The function was completed without errors. - - --EINVAL - -Bad parameter. - - -
Demux Callback API This kernel-space API comprises the callback functions that deliver filtered data to the -- cgit v1.1 From 2f684b239cdbfcc1160392645a8fc056a68847ca Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 6 Oct 2015 19:53:02 -0300 Subject: [media] dvb: get rid of enum dmx_success This enum is not actually used anymore. The only value used from the enum is DMX_OK, passed as a parameter on two callbacks. Yet, this value is not used anywhere. So, just remove it. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/dvb/kdapi.xml | 44 ++++--------------------------- 1 file changed, 5 insertions(+), 39 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml index 6efc3ab..1acae67 100644 --- a/Documentation/DocBook/media/dvb/kdapi.xml +++ b/Documentation/DocBook/media/dvb/kdapi.xml @@ -11,20 +11,6 @@ DVB device driver writers. The header file for this API is named demux Kernel Demux Data Types -
-dmx_success_t - - typedef enum { - DMX_OK = 0, /⋆ Received Ok ⋆/ - DMX_LENGTH_ERROR, /⋆ Incorrect length ⋆/ - DMX_OVERRUN_ERROR, /⋆ Receiver ring buffer overrun ⋆/ - DMX_CRC_ERROR, /⋆ Incorrect CRC ⋆/ - DMX_FRAME_ERROR, /⋆ Frame alignment error ⋆/ - DMX_FIFO_ERROR, /⋆ Receiver FIFO overrun ⋆/ - DMX_MISSED_ERROR /⋆ Receiver missed packet ⋆/ - } dmx_success_t; - -
TS filter types @@ -143,22 +129,19 @@ should be kept identical) to the types in the demux device. size_t buffer1_length, __u8 ⋆ buffer2, size_t buffer2_length, - dmx_ts_feed_t⋆ source, - dmx_success_t success); + dmx_ts_feed_t⋆ source) typedef int (⋆dmx_section_cb) ( __u8 ⋆ buffer1, size_t buffer1_len, __u8 ⋆ buffer2, size_t buffer2_len, - dmx_section_filter_t ⋆ source, - dmx_success_t success); + dmx_section_filter_t ⋆ source); typedef int (⋆dmx_pes_cb) ( __u8 ⋆ buffer1, size_t buffer1_len, __u8 ⋆ buffer2, size_t buffer2_len, - dmx_pes_filter_t⋆ source, - dmx_success_t success); + dmx_pes_filter_t⋆ source); /⋆--------------------------------------------------------------------------⋆/ /⋆ DVB Front-End ⋆/ @@ -523,7 +506,7 @@ role="subsection">dmx_ts_cb() align="char"> int dmx_ts_cb(__u8⋆ buffer1, size_t buffer1_length, __u8⋆ buffer2, size_t buffer2_length, dmx_ts_feed_t⋆ - source, dmx_success_t success); + source); PARAMETERS @@ -564,14 +547,6 @@ role="subsection">dmx_ts_cb() align="char"> Indicates which TS feed is the source of the callback. - -dmx_success_t - success - -Indicates if there was an error in TS reception. - RETURNS @@ -623,8 +598,7 @@ role="subsection">dmx_section_cb() align="char"> int dmx_section_cb(__u8⋆ buffer1, size_t buffer1_length, __u8⋆ buffer2, size_t - buffer2_length, dmx_section_filter_t⋆ source, - dmx_success_t success); + buffer2_length, dmx_section_filter_t⋆ source); PARAMETERS @@ -669,14 +643,6 @@ role="subsection">dmx_section_cb() align="char"> Indicates the filter that triggered the callback. - -dmx_success_t - success - -Indicates if there was an error in section reception. - RETURNS -- cgit v1.1 From 0693bdf75469487812da7c09949b09ad0396a737 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 7 Oct 2015 15:43:58 -0300 Subject: [media] dvb: Remove unused frontend sources at demux.h and sync doc The DVB core has a provision for other frontend sources, but no drivers use it. The kdapi.xml contains provision for some other frontend source types, but it is not in sync with the code. So, remove the unused types and sync both files. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/dvb/kdapi.xml | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml index 1acae67..ff133a3 100644 --- a/Documentation/DocBook/media/dvb/kdapi.xml +++ b/Documentation/DocBook/media/dvb/kdapi.xml @@ -148,14 +148,9 @@ should be kept identical) to the types in the demux device. /⋆--------------------------------------------------------------------------⋆/ typedef enum { - DMX_OTHER_FE = 0, - DMX_SATELLITE_FE, - DMX_CABLE_FE, - DMX_TERRESTRIAL_FE, - DMX_LVDS_FE, - DMX_ASI_FE, /⋆ DVB-ASI interface ⋆/ - DMX_MEMORY_FE - } dmx_frontend_source_t; + DMX_MEMORY_FE, + DMX_FRONTEND_0, + } dmx_frontend_source; typedef struct { /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ @@ -166,7 +161,7 @@ should be kept identical) to the types in the demux device. be connected to a particular demux ⋆/ void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - dmx_frontend_source_t source; + dmx_frontend_source source; } dmx_frontend_t; /⋆--------------------------------------------------------------------------⋆/ -- cgit v1.1 From de08e701c6b9edb0e555da48a95c9250cbec3ea8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 10 Oct 2015 10:02:28 -0300 Subject: [media] DocBook: Add documentation about the demux API There are several stuff at media's kdapi.xml that don't belong there, as it documents the Kernel internal ABI, and not the userspace API. Add the documentation here. The hole kdapi.xml will be removed on a latter patch, after we finish documenting what's there at the proper places. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/device-drivers.tmpl | 77 ++++++++++++++++++++++++++++--- 1 file changed, 71 insertions(+), 6 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 8d5620a..42a2d85 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -239,21 +239,86 @@ X!Isound/sound_firmware.c Digital TV (DVB) devices !Idrivers/media/dvb-core/dvb_ca_en50221.h -!Idrivers/media/dvb-core/demux.h !Idrivers/media/dvb-core/dvb_frontend.h !Idrivers/media/dvb-core/dvb_math.h !Idrivers/media/dvb-core/dvb_ringbuffer.h !Idrivers/media/dvb-core/dvbdev.h - - Remote Controller devices + Digital TV Demux API + The kernel demux API defines a driver-internal interface for + registering low-level, hardware specific driver to a hardware + independent demux layer. It is only of interest for Digital TV + device driver writers. The header file for this API is named + demux.h and located in + drivers/media/dvb-core. + + The demux API should be implemented for each demux in the + system. It is used to select the TS source of a demux and to manage + the demux resources. When the demux client allocates a resource via + the demux API, it receives a pointer to the API of that + resource. + Each demux receives its TS input from a DVB front-end or from + memory, as set via this demux API. In a system with more than one + front-end, the API can be used to select one of the DVB front-ends + as a TS source for a demux, unless this is fixed in the HW platform. + The demux API only controls front-ends regarding to their connections + with demuxes; the APIs used to set the other front-end parameters, + such as tuning, are not defined in this document. + The functions that implement the abstract interface demux should + be defined static or module private and registered to the Demux + core for external access. It is not necessary to implement every + function in the struct dmx_demux. For example, + a demux interface might support Section filtering, but not PES + filtering. The API client is expected to check the value of any + function pointer before calling the function: the value of NULL means + that the “function is not available”. + Whenever the functions of the demux API modify shared data, + the possibilities of lost update and race condition problems should + be addressed, e.g. by protecting parts of code with mutexes. + Note that functions called from a bottom half context must not + sleep. Even a simple memory allocation without using GFP_ATOMIC can + result in a kernel thread being put to sleep if swapping is needed. + For example, the Linux kernel calls the functions of a network device + interface from a bottom half context. Thus, if a demux API function + is called from network device code, the function must not sleep. + + + +
+ Demux Callback API + This kernel-space API comprises the callback functions that + deliver filtered data to the demux client. Unlike the other DVB + kABIs, these functions are provided by the client and called from + the demux code. + The function pointers of this abstract interface are not + packed into a structure as in the other demux APIs, because the + callback functions are registered and used independent of each + other. As an example, it is possible for the API client to provide + several callback functions for receiving TS packets and no + callbacks for PES packets or sections. + The functions that implement the callback API need not be + re-entrant: when a demux driver calls one of these functions, + the driver is not allowed to call the function again before + the original call returns. If a callback is triggered by a + hardware interrupt, it is recommended to use the Linux + “bottom half” mechanism or start a tasklet instead of + making the callback function call directly from a hardware + interrupt. + This mechanism is implemented by + dmx_ts_cb() and + dmx_section_cb(). +
+ +!Idrivers/media/dvb-core/demux.h + + Remote Controller devices !Iinclude/media/rc-core.h !Iinclude/media/lirc_dev.h - - Media Controller devices + + Media Controller devices !Iinclude/media/media-device.h !Iinclude/media/media-devnode.h !Iinclude/media/media-entity.h - + -- cgit v1.1 From a22fa28f85054c16e72f00e51673aeba28360eef Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 10 Oct 2015 10:20:17 -0300 Subject: [media] DocBook: Remove kdapi.xml Now that the Demux kABI is documented at device-drivers.xml, remove it from the API docbook. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/dvb/dvbapi.xml | 3 - Documentation/DocBook/media/dvb/kdapi.xml | 1236 ---------------------------- 2 files changed, 1239 deletions(-) delete mode 100644 Documentation/DocBook/media/dvb/kdapi.xml (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml index 858fd7d..8576481 100644 --- a/Documentation/DocBook/media/dvb/dvbapi.xml +++ b/Documentation/DocBook/media/dvb/dvbapi.xml @@ -125,9 +125,6 @@ Added ISDB-T test originally written by Patrick Boettcher &sub-audio;
- - &sub-kdapi; - &sub-examples; diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml deleted file mode 100644 index ff133a3..0000000 --- a/Documentation/DocBook/media/dvb/kdapi.xml +++ /dev/null @@ -1,1236 +0,0 @@ -Kernel Demux API -The kernel demux API defines a driver-internal interface for registering low-level, -hardware specific driver to a hardware independent demux layer. It is only of interest for -DVB device driver writers. The header file for this API is named demux.h and located in -">drivers/media/dvb-core. - -Maintainer note: This section must be reviewed. It is probably out of date. - - -
-Kernel Demux Data Types - - -
-
-TS filter types - - /⋆--------------------------------------------------------------------------⋆/ - /⋆ TS packet reception ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - /⋆ TS filter type for set_type() ⋆/ - - #define TS_PACKET 1 /⋆ send TS packets (188 bytes) to callback (default) ⋆/ - #define TS_PAYLOAD_ONLY 2 /⋆ in case TS_PACKET is set, only send the TS - payload (<=184 bytes per packet) to callback ⋆/ - #define TS_DECODER 4 /⋆ send stream to built-in decoder (if present) ⋆/ - - -
-
-dmx_ts_pes_t -The structure - - - typedef enum - { - DMX_TS_PES_AUDIO, /⋆ also send packets to audio decoder (if it exists) ⋆/ - DMX_TS_PES_VIDEO, /⋆ ... ⋆/ - DMX_TS_PES_TELETEXT, - DMX_TS_PES_SUBTITLE, - DMX_TS_PES_PCR, - DMX_TS_PES_OTHER, - } dmx_ts_pes_t; - -describes the PES type for filters which write to a built-in decoder. The correspond (and -should be kept identical) to the types in the demux device. - - - struct dmx_ts_feed_s { - int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ - struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - int (⋆set) (struct dmx_ts_feed_s⋆ feed, - __u16 pid, - size_t callback_length, - size_t circular_buffer_size, - int descramble, - struct timespec timeout); - int (⋆start_filtering) (struct dmx_ts_feed_s⋆ feed); - int (⋆stop_filtering) (struct dmx_ts_feed_s⋆ feed); - int (⋆set_type) (struct dmx_ts_feed_s⋆ feed, - int type, - dmx_ts_pes_t pes_type); - }; - - typedef struct dmx_ts_feed_s dmx_ts_feed_t; - - - /⋆--------------------------------------------------------------------------⋆/ - /⋆ PES packet reception (not supported yet) ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - typedef struct dmx_pes_filter_s { - struct dmx_pes_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - } dmx_pes_filter_t; - - - typedef struct dmx_pes_feed_s { - int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ - struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - int (⋆set) (struct dmx_pes_feed_s⋆ feed, - __u16 pid, - size_t circular_buffer_size, - int descramble, - struct timespec timeout); - int (⋆start_filtering) (struct dmx_pes_feed_s⋆ feed); - int (⋆stop_filtering) (struct dmx_pes_feed_s⋆ feed); - int (⋆allocate_filter) (struct dmx_pes_feed_s⋆ feed, - dmx_pes_filter_t⋆⋆ filter); - int (⋆release_filter) (struct dmx_pes_feed_s⋆ feed, - dmx_pes_filter_t⋆ filter); - } dmx_pes_feed_t; - - - typedef struct { - __u8 filter_value [DMX_MAX_FILTER_SIZE]; - __u8 filter_mask [DMX_MAX_FILTER_SIZE]; - struct dmx_section_feed_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - } dmx_section_filter_t; - - - struct dmx_section_feed_s { - int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ - struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - int (⋆set) (struct dmx_section_feed_s⋆ feed, - __u16 pid, - size_t circular_buffer_size, - int descramble, - int check_crc); - int (⋆allocate_filter) (struct dmx_section_feed_s⋆ feed, - dmx_section_filter_t⋆⋆ filter); - int (⋆release_filter) (struct dmx_section_feed_s⋆ feed, - dmx_section_filter_t⋆ filter); - int (⋆start_filtering) (struct dmx_section_feed_s⋆ feed); - int (⋆stop_filtering) (struct dmx_section_feed_s⋆ feed); - }; - typedef struct dmx_section_feed_s dmx_section_feed_t; - - /⋆--------------------------------------------------------------------------⋆/ - /⋆ Callback functions ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - typedef int (⋆dmx_ts_cb) ( __u8 ⋆ buffer1, - size_t buffer1_length, - __u8 ⋆ buffer2, - size_t buffer2_length, - dmx_ts_feed_t⋆ source) - - typedef int (⋆dmx_section_cb) ( __u8 ⋆ buffer1, - size_t buffer1_len, - __u8 ⋆ buffer2, - size_t buffer2_len, - dmx_section_filter_t ⋆ source); - - typedef int (⋆dmx_pes_cb) ( __u8 ⋆ buffer1, - size_t buffer1_len, - __u8 ⋆ buffer2, - size_t buffer2_len, - dmx_pes_filter_t⋆ source); - - /⋆--------------------------------------------------------------------------⋆/ - /⋆ DVB Front-End ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - typedef enum { - DMX_MEMORY_FE, - DMX_FRONTEND_0, - } dmx_frontend_source; - - typedef struct { - /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ - char⋆ id; /⋆ Unique front-end identifier ⋆/ - char⋆ vendor; /⋆ Name of the front-end vendor ⋆/ - char⋆ model; /⋆ Name of the front-end model ⋆/ - struct list_head connectivity_list; /⋆ List of front-ends that can - be connected to a particular - demux ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - dmx_frontend_source source; - } dmx_frontend_t; - - /⋆--------------------------------------------------------------------------⋆/ - /⋆ MPEG-2 TS Demux ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - /⋆ - ⋆ Flags OR'ed in the capabilites field of struct dmx_demux_s. - ⋆/ - - #define DMX_TS_FILTERING 1 - #define DMX_PES_FILTERING 2 - #define DMX_SECTION_FILTERING 4 - #define DMX_MEMORY_BASED_FILTERING 8 /⋆ write() available ⋆/ - #define DMX_CRC_CHECKING 16 - #define DMX_TS_DESCRAMBLING 32 - #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64 - #define DMX_MAC_ADDRESS_DESCRAMBLING 128 - - -
-
-demux_demux_t - - /⋆ - ⋆ DMX_FE_ENTRY(): Casts elements in the list of registered - ⋆ front-ends from the generic type struct list_head - ⋆ to the type ⋆ dmx_frontend_t - ⋆. - ⋆/ - - -
-
-Demux directory - - /⋆ - ⋆ DMX_DIR_ENTRY(): Casts elements in the list of registered - ⋆ demuxes from the generic type struct list_head⋆ to the type dmx_demux_t - ⋆. - ⋆/ - - #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list) - - int dmx_register_demux (dmx_demux_t⋆ demux); - int dmx_unregister_demux (dmx_demux_t⋆ demux); - struct list_head⋆ dmx_get_demuxes (void); - -
-
-Demux Directory API -The demux directory is a Linux kernel-wide facility for registering and accessing the -MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers -is possible using this API. - -All demux drivers in the directory implement the abstract interface dmx_demux_t. - - -
dmx_register_demux() -DESCRIPTION - - -This function makes a demux driver interface available to the Linux kernel. It is - usually called by the init_module() function of the kernel module that contains - the demux driver. The caller of this function is responsible for allocating - dynamic or static memory for the demux structure and for initializing its fields - before calling this function. The memory allocated for the demux structure - must not be freed before calling dmx_unregister_demux(), - - -SYNOPSIS - - -int dmx_register_demux ( dmx_demux_t ⋆demux ) - - -PARAMETERS - - -dmx_demux_t* - demux - -Pointer to the demux structure. - - -RETURNS - - -0 - -The function was completed without errors. - - --EEXIST - -A demux with the same value of the id field already stored - in the directory. - - --ENOSPC - -No space left in the directory. - - - -
dmx_unregister_demux() -DESCRIPTION - - -This function is called to indicate that the given demux interface is no - longer available. The caller of this function is responsible for freeing the - memory of the demux structure, if it was dynamically allocated before calling - dmx_register_demux(). The cleanup_module() function of the kernel module - that contains the demux driver should call this function. Note that this function - fails if the demux is currently in use, i.e., release_demux() has not been called - for the interface. - - -SYNOPSIS - - -int dmx_unregister_demux ( dmx_demux_t ⋆demux ) - - -PARAMETERS - - -dmx_demux_t* - demux - -Pointer to the demux structure which is to be - unregistered. - - -RETURNS - - -0 - -The function was completed without errors. - - -ENODEV - -The specified demux is not registered in the demux - directory. - - -EBUSY - -The specified demux is currently in use. - - - -
dmx_get_demuxes() -DESCRIPTION - - -Provides the caller with the list of registered demux interfaces, using the - standard list structure defined in the include file linux/list.h. The include file - demux.h defines the macro DMX_DIR_ENTRY() for converting an element of - the generic type struct list_head* to the type dmx_demux_t*. The caller must - not free the memory of any of the elements obtained via this function call. - - -SYNOPSIS - - -struct list_head ⋆dmx_get_demuxes () - - -PARAMETERS - - -none - - -RETURNS - - -struct list_head * - -A list of demux interfaces, or NULL in the case of an - empty list. - - -
-
-Demux API -The demux API should be implemented for each demux in the system. It is used to select -the TS source of a demux and to manage the demux resources. When the demux -client allocates a resource via the demux API, it receives a pointer to the API of that -resource. - -Each demux receives its TS input from a DVB front-end or from memory, as set via the -demux API. In a system with more than one front-end, the API can be used to select one of -the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The -demux API only controls front-ends regarding their connections with demuxes; the APIs -used to set the other front-end parameters, such as tuning, are not defined in this -document. - -The functions that implement the abstract interface demux should be defined static or -module private and registered to the Demux Directory for external access. It is not necessary -to implement every function in the demux_t struct, however (for example, a demux interface -might support Section filtering, but not TS or PES filtering). The API client is expected to -check the value of any function pointer before calling the function: the value of NULL means -“function not available”. - -Whenever the functions of the demux API modify shared data, the possibilities of lost -update and race condition problems should be addressed, e.g. by protecting parts of code with -mutexes. This is especially important on multi-processor hosts. - -Note that functions called from a bottom half context must not sleep, at least in the 2.2.x -kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if -swapping is needed. For example, the Linux kernel calls the functions of a network device -interface from a bottom half context. Thus, if a demux API function is called from network -device code, the function must not sleep. - - -
-
-Demux Callback API -This kernel-space API comprises the callback functions that deliver filtered data to the -demux client. Unlike the other APIs, these API functions are provided by the client and called -from the demux code. - -The function pointers of this abstract interface are not packed into a structure as in the -other demux APIs, because the callback functions are registered and used independent -of each other. As an example, it is possible for the API client to provide several -callback functions for receiving TS packets and no callbacks for PES packets or -sections. - -The functions that implement the callback API need not be re-entrant: when a demux -driver calls one of these functions, the driver is not allowed to call the function again before -the original call returns. If a callback is triggered by a hardware interrupt, it is recommended -to use the Linux “bottom half” mechanism or start a tasklet instead of making the callback -function call directly from a hardware interrupt. - - -
dmx_ts_cb() -DESCRIPTION - - -This function, provided by the client of the demux API, is called from the - demux code. The function is only called when filtering on this TS feed has - been enabled using the start_filtering() function. - - -Any TS packets that match the filter settings are copied to a circular buffer. The - filtered TS packets are delivered to the client using this callback function. The - size of the circular buffer is controlled by the circular_buffer_size parameter - of the set() function in the TS Feed API. It is expected that the buffer1 and - buffer2 callback parameters point to addresses within the circular buffer, but - other implementations are also possible. Note that the called party should not - try to free the memory the buffer1 and buffer2 parameters point to. - - -When this function is called, the buffer1 parameter typically points to the - start of the first undelivered TS packet within a circular buffer. The buffer2 - buffer parameter is normally NULL, except when the received TS packets have - crossed the last address of the circular buffer and ”wrapped” to the beginning - of the buffer. In the latter case the buffer1 parameter would contain an address - within the circular buffer, while the buffer2 parameter would contain the first - address of the circular buffer. - - -The number of bytes delivered with this function (i.e. buffer1_length + - buffer2_length) is usually equal to the value of callback_length parameter - given in the set() function, with one exception: if a timeout occurs before - receiving callback_length bytes of TS data, any undelivered packets are - immediately delivered to the client by calling this function. The timeout - duration is controlled by the set() function in the TS Feed API. - - -If a TS packet is received with errors that could not be fixed by the TS-level - forward error correction (FEC), the Transport_error_indicator flag of the TS - packet header should be set. The TS packet should not be discarded, as - the error can possibly be corrected by a higher layer protocol. If the called - party is slow in processing the callback, it is possible that the circular buffer - eventually fills up. If this happens, the demux driver should discard any TS - packets received while the buffer is full. The error should be indicated to the - client on the next callback by setting the success parameter to the value of - DMX_OVERRUN_ERROR. - - -The type of data returned to the callback can be selected by the new - function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t - pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the - include file ost/demux.h) The type parameter decides if the raw TS packet - (TS_PACKET) or just the payload (TS_PACKET—TS_PAYLOAD_ONLY) - should be returned. If additionally the TS_DECODER bit is set the stream - will also be sent to the hardware MPEG decoder. In this case, the second - flag decides as what kind of data the stream should be interpreted. The - possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO, - DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE, - DMX_TS_PES_PCR, or DMX_TS_PES_OTHER. - - -SYNOPSIS - - -int dmx_ts_cb(__u8⋆ buffer1, size_t buffer1_length, - __u8⋆ buffer2, size_t buffer2_length, dmx_ts_feed_t⋆ - source); - - -PARAMETERS - - -__u8* buffer1 - -Pointer to the start of the filtered TS packets. - - -size_t buffer1_length - -Length of the TS data in buffer1. - - -__u8* buffer2 - -Pointer to the tail of the filtered TS packets, or NULL. - - -size_t buffer2_length - -Length of the TS data in buffer2. - - -dmx_ts_feed_t* - source - -Indicates which TS feed is the source of the callback. - - -RETURNS - - -0 - -Continue filtering. - - --1 - -Stop filtering - has the same effect as a call to - stop_filtering() on the TS Feed API. - - - -
dmx_section_cb() -DESCRIPTION - - -This function, provided by the client of the demux API, is called from the - demux code. The function is only called when filtering of sections has been - enabled using the function start_filtering() of the section feed API. When the - demux driver has received a complete section that matches at least one section - filter, the client is notified via this callback function. Normally this function is - called for each received section; however, it is also possible to deliver multiple - sections with one callback, for example when the system load is high. If an - error occurs while receiving a section, this function should be called with - the corresponding error type set in the success field, whether or not there is - data to deliver. The Section Feed implementation should maintain a circular - buffer for received sections. However, this is not necessary if the Section Feed - API is implemented as a client of the TS Feed API, because the TS Feed - implementation then buffers the received data. The size of the circular buffer - can be configured using the set() function in the Section Feed API. If there - is no room in the circular buffer when a new section is received, the section - must be discarded. If this happens, the value of the success parameter should - be DMX_OVERRUN_ERROR on the next callback. - - -SYNOPSIS - - -int dmx_section_cb(__u8⋆ buffer1, size_t - buffer1_length, __u8⋆ buffer2, size_t - buffer2_length, dmx_section_filter_t⋆ source); - - -PARAMETERS - - -__u8* buffer1 - -Pointer to the start of the filtered section, e.g. within the - circular buffer of the demux driver. - - -size_t buffer1_length - -Length of the filtered section data in buffer1, including - headers and CRC. - - -__u8* buffer2 - -Pointer to the tail of the filtered section data, or NULL. - Useful to handle the wrapping of a circular buffer. - - -size_t buffer2_length - -Length of the filtered section data in buffer2, including - headers and CRC. - - -dmx_section_filter_t* - filter - -Indicates the filter that triggered the callback. - - -RETURNS - - -0 - -Continue filtering. - - --1 - -Stop filtering - has the same effect as a call to - stop_filtering() on the Section Feed API. - - -
-
-TS Feed API -A TS feed is typically mapped to a hardware PID filter on the demux chip. -Using this API, the client can set the filtering properties to start/stop filtering TS -packets on a particular TS feed. The API is defined as an abstract interface of the type -dmx_ts_feed_t. - -The functions that implement the interface should be defined static or module private. The -client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the -demux API. - - -
set() -DESCRIPTION - - -This function sets the parameters of a TS feed. Any filtering in progress on the - TS feed must be stopped before calling this function. - - -SYNOPSIS - - -int set ( dmx_ts_feed_t⋆ feed, __u16 pid, size_t - callback_length, size_t circular_buffer_size, int - descramble, struct timespec timeout); - - -PARAMETERS - - -dmx_ts_feed_t* feed - -Pointer to the TS feed API and instance data. - - -__u16 pid - -PID value to filter. Only the TS packets carrying the - specified PID will be passed to the API client. - - -size_t - callback_length - -Number of bytes to deliver with each call to the - dmx_ts_cb() callback function. The value of this - parameter should be a multiple of 188. - - -size_t - circular_buffer_size - -Size of the circular buffer for the filtered TS packets. - - -int descramble - -If non-zero, descramble the filtered TS packets. - - -struct timespec - timeout - -Maximum time to wait before delivering received TS - packets to the client. - - -RETURNS - - -0 - -The function was completed without errors. - - --ENOMEM - -Not enough memory for the requested buffer size. - - --ENOSYS - -No descrambling facility available for TS. - - --EINVAL - -Bad parameter. - - - -
start_filtering() -DESCRIPTION - - -Starts filtering TS packets on this TS feed, according to its settings. The PID - value to filter can be set by the API client. All matching TS packets are - delivered asynchronously to the client, using the callback function registered - with allocate_ts_feed(). - - -SYNOPSIS - - -int start_filtering(dmx_ts_feed_t⋆ feed); - - -PARAMETERS - - -dmx_ts_feed_t* feed - -Pointer to the TS feed API and instance data. - - -RETURNS - - -0 - -The function was completed without errors. - - --EINVAL - -Bad parameter. - - - -
stop_filtering() -DESCRIPTION - - -Stops filtering TS packets on this TS feed. - - -SYNOPSIS - - -int stop_filtering(dmx_ts_feed_t⋆ feed); - - -PARAMETERS - - -dmx_ts_feed_t* feed - -Pointer to the TS feed API and instance data. - - -RETURNS - - -0 - -The function was completed without errors. - - --EINVAL - -Bad parameter. - - -
-
-Section Feed API -A section feed is a resource consisting of a PID filter and a set of section filters. Using this -API, the client can set the properties of a section feed and to start/stop filtering. The API is -defined as an abstract interface of the type dmx_section_feed_t. The functions that implement -the interface should be defined static or module private. The client can get the handle of -a section feed API by calling the function allocate_section_feed() in the demux -API. - -On demux platforms that provide section filtering in hardware, the Section Feed API -implementation provides a software wrapper for the demux hardware. Other platforms may -support only PID filtering in hardware, requiring that TS packets are converted to sections in -software. In the latter case the Section Feed API implementation can be a client of the TS -Feed API. - - -
-
-set() -DESCRIPTION - - -This function sets the parameters of a section feed. Any filtering in progress on - the section feed must be stopped before calling this function. If descrambling - is enabled, the payload_scrambling_control and address_scrambling_control - fields of received DVB datagram sections should be observed. If either one is - non-zero, the section should be descrambled either in hardware or using the - functions descramble_mac_address() and descramble_section_payload() of the - demux API. Note that according to the MPEG-2 Systems specification, only - the payloads of private sections can be scrambled while the rest of the section - data must be sent in the clear. - - -SYNOPSIS - - -int set(dmx_section_feed_t⋆ feed, __u16 pid, size_t - circular_buffer_size, int descramble, int - check_crc); - - -PARAMETERS - - -dmx_section_feed_t* - feed - -Pointer to the section feed API and instance data. - - -__u16 pid - -PID value to filter; only the TS packets carrying the - specified PID will be accepted. - - -size_t - circular_buffer_size - -Size of the circular buffer for filtered sections. - - -int descramble - -If non-zero, descramble any sections that are scrambled. - - -int check_crc - -If non-zero, check the CRC values of filtered sections. - - -RETURNS - - -0 - -The function was completed without errors. - - --ENOMEM - -Not enough memory for the requested buffer size. - - --ENOSYS - -No descrambling facility available for sections. - - --EINVAL - -Bad parameters. - - - -
allocate_filter() -DESCRIPTION - - -This function is used to allocate a section filter on the demux. It should only be - called when no filtering is in progress on this section feed. If a filter cannot be - allocated, the function fails with -ENOSPC. See in section ?? for the format of - the section filter. - - -The bitfields filter_mask and filter_value should only be modified when no - filtering is in progress on this section feed. filter_mask controls which bits of - filter_value are compared with the section headers/payload. On a binary value - of 1 in filter_mask, the corresponding bits are compared. The filter only accepts - sections that are equal to filter_value in all the tested bit positions. Any changes - to the values of filter_mask and filter_value are guaranteed to take effect only - when the start_filtering() function is called next time. The parent pointer in - the struct is initialized by the API implementation to the value of the feed - parameter. The priv pointer is not used by the API implementation, and can - thus be freely utilized by the caller of this function. Any data pointed to by the - priv pointer is available to the recipient of the dmx_section_cb() function call. - - -While the maximum section filter length (DMX_MAX_FILTER_SIZE) is - currently set at 16 bytes, hardware filters of that size are not available on all - platforms. Therefore, section filtering will often take place first in hardware, - followed by filtering in software for the header bytes that were not covered - by a hardware filter. The filter_mask field can be checked to determine how - many bytes of the section filter are actually used, and if the hardware filter will - suffice. Additionally, software-only section filters can optionally be allocated - to clients when all hardware section filters are in use. Note that on most demux - hardware it is not possible to filter on the section_length field of the section - header – thus this field is ignored, even though it is included in filter_value and - filter_mask fields. - - -SYNOPSIS - - -int allocate_filter(dmx_section_feed_t⋆ feed, - dmx_section_filter_t⋆⋆ filter); - - -PARAMETERS - - -dmx_section_feed_t* - feed - -Pointer to the section feed API and instance data. - - -dmx_section_filter_t** - filter - -Pointer to the allocated filter. - - -RETURNS - - -0 - -The function was completed without errors. - - --ENOSPC - -No filters of given type and length available. - - --EINVAL - -Bad parameters. - - - -
release_filter() -DESCRIPTION - - -This function releases all the resources of a previously allocated section filter. - The function should not be called while filtering is in progress on this section - feed. After calling this function, the caller should not try to dereference the - filter pointer. - - -SYNOPSIS - - -int release_filter ( dmx_section_feed_t⋆ feed, - dmx_section_filter_t⋆ filter); - - -PARAMETERS - - -dmx_section_feed_t* - feed - -Pointer to the section feed API and instance data. - - -dmx_section_filter_t* - filter - -I/O Pointer to the instance data of a section filter. - - -RETURNS - - -0 - -The function was completed without errors. - - --ENODEV - -No such filter allocated. - - --EINVAL - -Bad parameter. - - - -
start_filtering() -DESCRIPTION - - -Starts filtering sections on this section feed, according to its settings. Sections - are first filtered based on their PID and then matched with the section - filters allocated for this feed. If the section matches the PID filter and - at least one section filter, it is delivered to the API client. The section - is delivered asynchronously using the callback function registered with - allocate_section_feed(). - - -SYNOPSIS - - -int start_filtering ( dmx_section_feed_t⋆ feed ); - - -PARAMETERS - - -dmx_section_feed_t* - feed - -Pointer to the section feed API and instance data. - - -RETURNS - - -0 - -The function was completed without errors. - - --EINVAL - -Bad parameter. - - - -
stop_filtering() -DESCRIPTION - - -Stops filtering sections on this section feed. Note that any changes to the - filtering parameters (filter_value, filter_mask, etc.) should only be made when - filtering is stopped. - - -SYNOPSIS - - -int stop_filtering ( dmx_section_feed_t⋆ feed ); - - -PARAMETERS - - -dmx_section_feed_t* - feed - -Pointer to the section feed API and instance data. - - -RETURNS - - -0 - -The function was completed without errors. - - --EINVAL - -Bad parameter. - - - -
-- cgit v1.1 From f3c3ecec97c24cf0e53bb61ee85698acc00bcd68 Mon Sep 17 00:00:00 2001 From: Antti Palosaari Date: Sat, 10 Oct 2015 13:50:57 -0300 Subject: [media] v4l2: rename V4L2_TUNER_ADC to V4L2_TUNER_SDR SDR receiver has ADC (Analog-to-Digital Converter) and SDR transmitter has DAC (Digital-to-Analog Converter). Originally I though it could be good idea to have own type for receiver and transmitter, but now I feel one common type for SDR is enough. So lets rename it. Signed-off-by: Antti Palosaari Acked-by: Mauro Carvalho Chehab Signed-off-by: Hans Verkuil [hans.verkuil@cisco.com: this was added in 4.4, so update 4.2 to 4.4] Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 12 ++++++++++++ Documentation/DocBook/media/v4l/dev-sdr.xml | 6 +++--- Documentation/DocBook/media/v4l/v4l2.xml | 7 +++++++ 3 files changed, 22 insertions(+), 3 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index a0aef85..08f4efc 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2591,6 +2591,18 @@ and &v4l2-mbus-framefmt;. +
+ V4L2 in Linux 4.4 + + + Renamed V4L2_TUNER_ADC to +V4L2_TUNER_SDR. The use of +V4L2_TUNER_ADC is deprecated now. + + + +
+
Relation of V4L2 to other Linux multimedia APIs diff --git a/Documentation/DocBook/media/v4l/dev-sdr.xml b/Documentation/DocBook/media/v4l/dev-sdr.xml index f890356..3344921 100644 --- a/Documentation/DocBook/media/v4l/dev-sdr.xml +++ b/Documentation/DocBook/media/v4l/dev-sdr.xml @@ -44,10 +44,10 @@ frequency. -The V4L2_TUNER_ADC tuner type is used for ADC tuners, and +The V4L2_TUNER_SDR tuner type is used for SDR tuners, and the V4L2_TUNER_RF tuner type is used for RF tuners. The -tuner index of the RF tuner (if any) must always follow the ADC tuner index. -Normally the ADC tuner is #0 and the RF tuner is #1. +tuner index of the RF tuner (if any) must always follow the SDR tuner index. +Normally the SDR tuner is #0 and the RF tuner is #1. diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index e98caa1..01a24df 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -151,6 +151,13 @@ Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, structs, ioctls) must be noted in more detail in the history chapter (compat.xml), along with the possible impact on existing drivers and applications. --> + + 4.4 + 2015-05-26 + ap + Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. + + 3.21 -- cgit v1.1 From b2411b93cdcb5cb154827b8fcd2f436dd0ddab73 Mon Sep 17 00:00:00 2001 From: Antti Palosaari Date: Sat, 10 Oct 2015 13:50:59 -0300 Subject: [media] DocBook: document tuner RF gain control Add brief description for tuner RF gain control. Signed-off-by: Antti Palosaari Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 4 ++++ Documentation/DocBook/media/v4l/controls.xml | 14 ++++++++++++++ Documentation/DocBook/media/v4l/v4l2.xml | 1 + 3 files changed, 19 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 08f4efc..6c4e951 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2600,6 +2600,10 @@ and &v4l2-mbus-framefmt;. V4L2_TUNER_ADC is deprecated now. + + Added V4L2_CID_RF_TUNER_RF_GAIN +RF Tuner control. +
diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 33aece5..f13a429 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -5418,6 +5418,18 @@ set. Unit is in Hz. The range and step are driver-specific. Enables/disables IF automatic gain control (AGC) + V4L2_CID_RF_TUNER_RF_GAIN  + integer + + + The RF amplifier is the very first +amplifier on the receiver signal path, just right after the antenna input. +The difference between the LNA gain and the RF gain in this document is that +the LNA gain is integrated in the tuner chip while the RF gain is a separate +chip. There may be both RF and LNA gain controls in the same device. +The range and step are driver-specific. + + V4L2_CID_RF_TUNER_LNA_GAIN  integer @@ -5425,6 +5437,8 @@ set. Unit is in Hz. The range and step are driver-specific. LNA (low noise amplifier) gain is first gain stage on the RF tuner signal path. It is located very close to tuner antenna input. Used when V4L2_CID_RF_TUNER_LNA_GAIN_AUTO is not set. +See V4L2_CID_RF_TUNER_RF_GAIN to understand how RF gain +and LNA gain differs from the each others. The range and step are driver-specific. diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 01a24df..9cc4117 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -156,6 +156,7 @@ applications. --> 2015-05-26 ap Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. +Added V4L2_CID_RF_TUNER_RF_GAIN control. -- cgit v1.1 From be8ee526fb0b91681fb02d69d2a642a6ec2f2377 Mon Sep 17 00:00:00 2001 From: Antti Palosaari Date: Sat, 10 Oct 2015 13:51:01 -0300 Subject: [media] DocBook: document SDR transmitter Add documentation for V4L SDR transmitter (output) devices. Signed-off-by: Antti Palosaari Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 4 +++ Documentation/DocBook/media/v4l/dev-sdr.xml | 30 +++++++++++++++------- Documentation/DocBook/media/v4l/io.xml | 10 ++++++-- Documentation/DocBook/media/v4l/pixfmt.xml | 2 +- Documentation/DocBook/media/v4l/v4l2.xml | 1 + Documentation/DocBook/media/v4l/vidioc-g-fmt.xml | 2 +- .../DocBook/media/v4l/vidioc-querycap.xml | 6 +++++ 7 files changed, 42 insertions(+), 13 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 6c4e951..5701a08 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2604,6 +2604,10 @@ and &v4l2-mbus-framefmt;. Added V4L2_CID_RF_TUNER_RF_GAIN RF Tuner control. + + Added transmitter support for Software Defined Radio (SDR) +Interface. + diff --git a/Documentation/DocBook/media/v4l/dev-sdr.xml b/Documentation/DocBook/media/v4l/dev-sdr.xml index 3344921..a659771 100644 --- a/Documentation/DocBook/media/v4l/dev-sdr.xml +++ b/Documentation/DocBook/media/v4l/dev-sdr.xml @@ -28,6 +28,16 @@ Devices supporting the SDR receiver interface set the capabilities field of &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an Analog to Digital Converter (ADC), which is a mandatory element for the SDR receiver. + + +Devices supporting the SDR transmitter interface set the +V4L2_CAP_SDR_OUTPUT and +V4L2_CAP_MODULATOR flag in the +capabilities field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an +Digital to Analog Converter (DAC), which is a mandatory element for the SDR transmitter. + + At least one of the read/write, streaming or asynchronous I/O methods must be supported. @@ -39,14 +49,15 @@ be supported. SDR devices can support controls, and must support the tuner ioctls. Tuner ioctls are used -for setting the ADC sampling rate (sampling frequency) and the possible RF tuner -frequency. +for setting the ADC/DAC sampling rate (sampling frequency) and the possible +radio frequency (RF). -The V4L2_TUNER_SDR tuner type is used for SDR tuners, and -the V4L2_TUNER_RF tuner type is used for RF tuners. The -tuner index of the RF tuner (if any) must always follow the SDR tuner index. +The V4L2_TUNER_SDR tuner type is used for setting SDR +device ADC/DAC frequency, and the V4L2_TUNER_RF +tuner type is used for setting radio frequency. +The tuner index of the RF tuner (if any) must always follow the SDR tuner index. Normally the SDR tuner is #0 and the RF tuner is #1. @@ -59,9 +70,9 @@ The &VIDIOC-S-HW-FREQ-SEEK; ioctl is not supported. Data Format Negotiation -The SDR capture device uses the format ioctls to -select the capture format. Both the sampling resolution and the data streaming -format are bound to that selectable format. In addition to the basic +The SDR device uses the format ioctls to +select the capture and output format. Both the sampling resolution and the data +streaming format are bound to that selectable format. In addition to the basic format ioctls, the &VIDIOC-ENUM-FMT; ioctl must be supported as well. @@ -69,7 +80,8 @@ must be supported as well. To use the format ioctls applications set the type field of a &v4l2-format; to -V4L2_BUF_TYPE_SDR_CAPTURE and use the &v4l2-sdr-format; +V4L2_BUF_TYPE_SDR_CAPTURE or +V4L2_BUF_TYPE_SDR_OUTPUT and use the &v4l2-sdr-format; sdr member of the fmt union as needed per the desired operation. Currently there is two fields, pixelformat and diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 7bbc2a4..da65403 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -1006,8 +1006,14 @@ must set this to 0. V4L2_BUF_TYPE_SDR_CAPTURE 11 - Buffer for Software Defined Radio (SDR), see . + Buffer for Software Defined Radio (SDR) capture stream, see + . + + + V4L2_BUF_TYPE_SDR_OUTPUT + 12 + Buffer for Software Defined Radio (SDR) output stream, see + . diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index 70cd0fd..d871245 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -1732,7 +1732,7 @@ extended control V4L2_CID_MPEG_STREAM_TYPE, see
SDR Formats - These formats are used for SDR Capture + These formats are used for SDR interface only. &sub-sdr-cu08; diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 9cc4117..0ceea3f 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -157,6 +157,7 @@ applications. --> ap Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added V4L2_CID_RF_TUNER_RF_GAIN control. +Added transmitter support for Software Defined Radio (SDR) Interface. diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml index 4fe19a7a..ffcb448 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml @@ -175,7 +175,7 @@ capture and output devices. &v4l2-sdr-format; sdr Definition of a data format, see -, used by SDR capture devices. +, used by SDR capture and output devices. diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml b/Documentation/DocBook/media/v4l/vidioc-querycap.xml index 20fda75..cd82148 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querycap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querycap.xml @@ -308,6 +308,12 @@ modulator programming see fields. + V4L2_CAP_SDR_OUTPUT + 0x00400000 + The device supports the +SDR Output interface. + + V4L2_CAP_READWRITE 0x01000000 The device supports the Date: Sat, 10 Oct 2015 13:51:03 -0300 Subject: [media] DocBook: add modulator type field Add new modulator type field to documentation. Signed-off-by: Antti Palosaari Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-g-modulator.xml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml index 7068b59..80167fc 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml @@ -140,7 +140,13 @@ indicator, for example a stereo pilot tone. __u32 - reserved[4] + type + Type of the modulator, see . + + + __u32 + reserved[3] Reserved for future extensions. Drivers and applications must set the array to zero. -- cgit v1.1 From f9b4376c82a81943fc196709315dfe554774286a Mon Sep 17 00:00:00 2001 From: Antti Palosaari Date: Sat, 10 Oct 2015 13:51:08 -0300 Subject: [media] DocBook: add SDR specific info to G_TUNER / S_TUNER Add SDR specific notes to G_TUNER / S_TUNER documentation. Add V4L2_TUNER_SDR and V4L2_TUNER_RF to supported tuner types to table. Signed-off-by: Antti Palosaari [hans.verkuil@cisco.com: add quotes in "The term 'tuner'"] Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-g-tuner.xml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml index b0d8659..459b7e5 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml @@ -80,6 +80,12 @@ if the requested mode is invalid or unsupported. Since this is a write-only ioctl, it does not return the actually selected audio mode. + SDR specific tuner types are +V4L2_TUNER_SDR and V4L2_TUNER_RF. +For SDR devices audmode field must be +initialized to zero. +The term 'tuner' means SDR receiver in this context. + To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl is available. @@ -261,6 +267,16 @@ applications must set the array to zero. 2 + + V4L2_TUNER_SDR + 4 + + + + V4L2_TUNER_RF + 5 + + -- cgit v1.1 From c7c1d5a5dea80d908fa9a7945424d872b3588757 Mon Sep 17 00:00:00 2001 From: Antti Palosaari Date: Sat, 10 Oct 2015 13:51:09 -0300 Subject: [media] DocBook: add SDR specific info to G_MODULATOR / S_MODULATOR Add SDR specific notes to G_MODULATOR / S_MODULATOR documentation. Signed-off-by: Antti Palosaari [hans.verkuil@cisco.com: add quotes in "The term 'modulator'"] Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-g-modulator.xml | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml index 80167fc..96e17b3 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml @@ -78,6 +78,12 @@ different audio modulation if the request cannot be satisfied. However this is a write-only ioctl, it does not return the actual audio modulation selected. + SDR specific modulator types are +V4L2_TUNER_SDR and V4L2_TUNER_RF. +For SDR devices txsubchans field must be +initialized to zero. +The term 'modulator' means SDR transmitter in this context. + To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl is available. -- cgit v1.1 From b2df45531619508a722cdafac2bde3ca2f8ae9e5 Mon Sep 17 00:00:00 2001 From: Jean-Michel Hautbois Date: Tue, 13 Oct 2015 11:17:39 -0300 Subject: [media] DocBook media: Fix a typo in encoder cmd A copy-paste from DECODER_CMD : replace decoded by encoded. Signed-off-by: Jean-Michel Hautbois Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml index fc1d462..70a4a08 100644 --- a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml @@ -130,7 +130,7 @@ encoding will continue until the end of the current Group Of Pictures, otherwise encoding will stop immediately. When the encoder is already stopped, this command does nothing. mem2mem encoders will send a V4L2_EVENT_EOS event -when the last frame has been decoded and all frames are ready to be dequeued and +when the last frame has been encoded and all frames are ready to be dequeued and will set the V4L2_BUF_FLAG_LAST buffer flag on the last buffer of the capture queue to indicate there will be no new buffers produced to dequeue. This buffer may be empty, indicated by the driver setting the -- cgit v1.1 From eab2b7612d2bce0b06873e24899a8455a04bb915 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 16 Oct 2015 06:13:01 -0300 Subject: [media] DocBook media: update copyright/version numbers - Update the copyright year to 2015 in media_api.tmpl. - Main version number of the spec updated to 4.4. - Version 3.21 was used for one changelog, this should be 4.1. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/v4l2.xml | 4 ++-- Documentation/DocBook/media_api.tmpl | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 0ceea3f..7e61643 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -162,7 +162,7 @@ Added transmitter support for Software Defined Radio (SDR) Interface. - 3.21 + 4.1 2015-02-13 mcc Fix documentation for media controller device nodes and add support for DVB device nodes. @@ -566,7 +566,7 @@ and discussions on the V4L mailing list. Video for Linux Two API Specification - Revision 3.19 + Revision 4.4 &sub-common; diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl index f3f5fe5..9203703 100644 --- a/Documentation/DocBook/media_api.tmpl +++ b/Documentation/DocBook/media_api.tmpl @@ -38,7 +38,7 @@ LINUX MEDIA INFRASTRUCTURE API - 2009-2014 + 2009-2015 LinuxTV Developers -- cgit v1.1