From c046707ff99912878ba63db5f2f2e2916ca961ce Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 15 Jun 2015 08:33:41 -0300 Subject: [media] DocBook/media: fix bad spacing in VIDIOC_EXPBUF The VIDIOC_EXPBUF documentation had spurious spaces that made it irritating to read. Fix this. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-expbuf.xml | 38 +++++++++++------------ 1 file changed, 19 insertions(+), 19 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml index a78c9207422f..0ae0b6a915d0 100644 --- a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml @@ -62,28 +62,28 @@ buffer as a DMABUF file at any time after buffers have been allocated with the &VIDIOC-REQBUFS; ioctl. To export a buffer, applications fill &v4l2-exportbuffer;. The - type field is set to the same buffer type as was -previously used with &v4l2-requestbuffers; type . -Applications must also set the index field. Valid +type field is set to the same buffer type as was +previously used with &v4l2-requestbuffers; type. +Applications must also set the index field. Valid index numbers range from zero to the number of buffers allocated with -&VIDIOC-REQBUFS; (&v4l2-requestbuffers; count ) -minus one. For the multi-planar API, applications set the plane - field to the index of the plane to be exported. Valid planes +&VIDIOC-REQBUFS; (&v4l2-requestbuffers; count) +minus one. For the multi-planar API, applications set the plane +field to the index of the plane to be exported. Valid planes range from zero to the maximal number of valid planes for the currently active -format. For the single-planar API, applications must set plane - to zero. Additional flags may be posted in the -flags field. Refer to a manual for open() for details. +format. For the single-planar API, applications must set plane +to zero. Additional flags may be posted in the flags +field. Refer to a manual for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, and O_RDWR are supported. All other fields must be set to zero. In the case of multi-planar API, every plane is exported separately using -multiple VIDIOC_EXPBUF calls. +multiple VIDIOC_EXPBUF calls. - After calling VIDIOC_EXPBUF the fd - field will be set by a driver. This is a DMABUF file +After calling VIDIOC_EXPBUF the fd +field will be set by a driver. This is a DMABUF file descriptor. The application may pass it to other DMABUF-aware devices. Refer to DMABUF importing for details about importing DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it -is no longer used to allow the associated memory to be reclaimed. +is no longer used to allow the associated memory to be reclaimed. @@ -170,9 +170,9 @@ multi-planar API. Otherwise this value must be set to zero. __u32 flags - Flags for the newly created file, currently only -O_CLOEXEC , O_RDONLY, O_WRONLY -, and O_RDWR are supported, refer to the manual + Flags for the newly created file, currently only +O_CLOEXEC, O_RDONLY, O_WRONLY, +and O_RDWR are supported, refer to the manual of open() for more details. @@ -200,9 +200,9 @@ set the array to zero. EINVAL A queue is not in MMAP mode or DMABUF exporting is not -supported or flags or type - or index or plane - fields are invalid. +supported or flags or type +or index or plane fields +are invalid. -- cgit v1.2.3-58-ga151 From 6a219f15a86812a226d197aa93b2806e9cecda7c Mon Sep 17 00:00:00 2001 From: Ian Molton Date: Wed, 3 Jun 2015 10:59:52 -0300 Subject: [media] media: adv7604: document support for ADV7612 dual HDMI input decoder This documentation accompanies the patch adding support for the ADV7612 dual HDMI decoder / repeater chip. Signed-off-by: Ian Molton Reviewed-by: William Towle Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- .../devicetree/bindings/media/i2c/adv7604.txt | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/media/i2c/adv7604.txt b/Documentation/devicetree/bindings/media/i2c/adv7604.txt index c27cede3bd68..7eafdbc055f9 100644 --- a/Documentation/devicetree/bindings/media/i2c/adv7604.txt +++ b/Documentation/devicetree/bindings/media/i2c/adv7604.txt @@ -1,15 +1,17 @@ -* Analog Devices ADV7604/11 video decoder with HDMI receiver +* Analog Devices ADV7604/11/12 video decoder with HDMI receiver -The ADV7604 and ADV7611 are multiformat video decoders with an integrated HDMI -receiver. The ADV7604 has four multiplexed HDMI inputs and one analog input, -and the ADV7611 has one HDMI input and no analog input. +The ADV7604 and ADV7611/12 are multiformat video decoders with an integrated +HDMI receiver. The ADV7604 has four multiplexed HDMI inputs and one analog +input, and the ADV7611 has one HDMI input and no analog input. The 7612 is +similar to the 7611 but has 2 HDMI inputs. -These device tree bindings support the ADV7611 only at the moment. +These device tree bindings support the ADV7611/12 only at the moment. Required Properties: - compatible: Must contain one of the following - "adi,adv7611" for the ADV7611 + - "adi,adv7612" for the ADV7612 - reg: I2C slave address @@ -22,10 +24,10 @@ port, in accordance with the video interface bindings defined in Documentation/devicetree/bindings/media/video-interfaces.txt. The port nodes are numbered as follows. - Port ADV7611 + Port ADV7611 ADV7612 ------------------------------------------------------------ - HDMI 0 - Digital output 1 + HDMI 0 0, 1 + Digital output 1 2 The digital output port node must contain at least one endpoint. -- cgit v1.2.3-58-ga151 From bf9c82278c348eb6b72496de6a3e5269aadb6b34 Mon Sep 17 00:00:00 2001 From: Ian Molton Date: Wed, 3 Jun 2015 10:59:53 -0300 Subject: [media] media: adv7604: ability to read default input port from DT Adds support to the adv7604 driver for specifying the default input port in the Device tree. If no value is provided, the driver will be unable to select an input without help from userspace. Tested-by: William Towle Signed-off-by: Ian Molton Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/devicetree/bindings/media/i2c/adv7604.txt | 3 +++ drivers/media/i2c/adv7604.c | 8 +++++++- 2 files changed, 10 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/media/i2c/adv7604.txt b/Documentation/devicetree/bindings/media/i2c/adv7604.txt index 7eafdbc055f9..8337f75c75da 100644 --- a/Documentation/devicetree/bindings/media/i2c/adv7604.txt +++ b/Documentation/devicetree/bindings/media/i2c/adv7604.txt @@ -47,6 +47,7 @@ Optional Endpoint Properties: If none of hsync-active, vsync-active and pclk-sample is specified the endpoint will use embedded BT.656 synchronization. + - default-input: Select which input is selected after reset. Example: @@ -60,6 +61,8 @@ Example: #address-cells = <1>; #size-cells = <0>; + default-input = <0>; + port@0 { reg = <0>; }; diff --git a/drivers/media/i2c/adv7604.c b/drivers/media/i2c/adv7604.c index c8fefeab0513..21b549a8dc74 100644 --- a/drivers/media/i2c/adv7604.c +++ b/drivers/media/i2c/adv7604.c @@ -2772,6 +2772,7 @@ static int adv76xx_parse_dt(struct adv76xx_state *state) struct device_node *endpoint; struct device_node *np; unsigned int flags; + u32 v; np = state->i2c_clients[ADV76XX_PAGE_IO]->dev.of_node; @@ -2781,6 +2782,12 @@ static int adv76xx_parse_dt(struct adv76xx_state *state) return -EINVAL; v4l2_of_parse_endpoint(endpoint, &bus_cfg); + + if (!of_property_read_u32(endpoint, "default-input", &v)) + state->pdata.default_input = v; + else + state->pdata.default_input = -1; + of_node_put(endpoint); flags = bus_cfg.bus.parallel.flags; @@ -2819,7 +2826,6 @@ static int adv76xx_parse_dt(struct adv76xx_state *state) /* Hardcode the remaining platform data fields. */ state->pdata.disable_pwrdnb = 0; state->pdata.disable_cable_det_rst = 0; - state->pdata.default_input = -1; state->pdata.blank_data = 1; state->pdata.alt_data_sat = 1; state->pdata.op_format_mode_sel = ADV7604_OP_FORMAT_MODE0; -- cgit v1.2.3-58-ga151 From 86e46aa80d7456663afeac51971d4234dbc59e5d Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Thu, 2 Jul 2015 10:32:39 -0300 Subject: [media] DocBook: fix media-ioc-device-info.xml type The documentation had two media_version entries. The second one was a typo and it should be driver_version instead. Correct this. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/media-ioc-device-info.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/media-ioc-device-info.xml b/Documentation/DocBook/media/v4l/media-ioc-device-info.xml index 2ce521419e67..b0a21ac300b8 100644 --- a/Documentation/DocBook/media/v4l/media-ioc-device-info.xml +++ b/Documentation/DocBook/media/v4l/media-ioc-device-info.xml @@ -102,7 +102,7 @@ __u32 - media_version + driver_version Media device driver version, formatted with the KERNEL_VERSION() macro. Together with the driver field this identifies a particular -- cgit v1.2.3-58-ga151 From ee5da769b3f238f818045e7630ed9ee3788690bc Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Wed, 8 Jul 2015 05:47:08 -0300 Subject: [media] DocBook media: fix typo in V4L2_CTRL_FLAG_EXECUTE_ON_WRITE Fix small typo (missing 'it') in the documentation for V4L2_CTRL_FLAG_EXECUTE_ON_WRITE. Signed-off-by: Hans Verkuil Acked-by: Ricardo Ribalda Delgado Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-queryctrl.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml index dc83ad70f8dc..6ec39c698baf 100644 --- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml +++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml @@ -616,7 +616,7 @@ pointer to memory containing the payload of the control. V4L2_CTRL_FLAG_EXECUTE_ON_WRITE 0x0200 The value provided to the control will be propagated to the driver -even if remains constant. This is required when the control represents an action +even if it remains constant. This is required when the control represents an action on the hardware. For example: clearing an error flag or triggering the flash. All the controls of the type V4L2_CTRL_TYPE_BUTTON have this flag set. -- cgit v1.2.3-58-ga151 From 25614824685247e00b786032a504f10bfab347b1 Mon Sep 17 00:00:00 2001 From: Philipp Zabel Date: Fri, 17 Jul 2015 11:02:55 -0300 Subject: [media] tc358743: support probe from device tree Add support for probing the TC358743 subdevice from device tree. The reference clock must be supplied using the common clock bindings. MIPI CSI-2 specific properties are parsed from the OF graph endpoint node and support for a non-continuous MIPI CSI-2 clock is added. Signed-off-by: Philipp Zabel Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- .../devicetree/bindings/media/i2c/tc358743.txt | 48 +++++++ drivers/media/i2c/tc358743.c | 155 ++++++++++++++++++++- 2 files changed, 197 insertions(+), 6 deletions(-) create mode 100644 Documentation/devicetree/bindings/media/i2c/tc358743.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/media/i2c/tc358743.txt b/Documentation/devicetree/bindings/media/i2c/tc358743.txt new file mode 100644 index 000000000000..5218921629ed --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/tc358743.txt @@ -0,0 +1,48 @@ +* Toshiba TC358743 HDMI-RX to MIPI CSI2-TX Bridge + +The Toshiba TC358743 HDMI-RX to MIPI CSI2-TX (H2C) is a bridge that converts +a HDMI stream to MIPI CSI-2 TX. It is programmable through I2C. + +Required Properties: + +- compatible: value should be "toshiba,tc358743" +- clocks, clock-names: should contain a phandle link to the reference clock + source, the clock input is named "refclk". + +Optional Properties: + +- reset-gpios: gpio phandle GPIO connected to the reset pin +- interrupts, interrupt-parent: GPIO connected to the interrupt pin +- data-lanes: should be <1 2 3 4> for four-lane operation, + or <1 2> for two-lane operation +- clock-lanes: should be <0> +- clock-noncontinuous: Presence of this boolean property decides whether the + MIPI CSI-2 clock is continuous or non-continuous. +- link-frequencies: List of allowed link frequencies in Hz. Each frequency is + expressed as a 64-bit big-endian integer. The frequency + is half of the bps per lane due to DDR transmission. + +For further information on the MIPI CSI-2 endpoint node properties, see +Documentation/devicetree/bindings/media/video-interfaces.txt. + +Example: + + tc358743@0f { + compatible = "toshiba,tc358743"; + reg = <0x0f>; + clocks = <&hdmi_osc>; + clock-names = "refclk"; + reset-gpios = <&gpio6 9 GPIO_ACTIVE_LOW>; + interrupt-parent = <&gpio2>; + interrupts = <5 IRQ_TYPE_LEVEL_HIGH>; + + port { + tc358743_out: endpoint { + remote-endpoint = <&mipi_csi2_in>; + data-lanes = <1 2 3 4>; + clock-lanes = <0>; + clock-noncontinuous; + link-frequencies = /bits/ 64 <297000000>; + }; + }; + }; diff --git a/drivers/media/i2c/tc358743.c b/drivers/media/i2c/tc358743.c index 0ccae3308b68..76d0aaa19493 100644 --- a/drivers/media/i2c/tc358743.c +++ b/drivers/media/i2c/tc358743.c @@ -29,7 +29,9 @@ #include #include #include +#include #include +#include #include #include #include @@ -37,6 +39,7 @@ #include #include #include +#include #include #include "tc358743_regs.h" @@ -69,6 +72,7 @@ static const struct v4l2_dv_timings_cap tc358743_timings_cap = { struct tc358743_state { struct tc358743_platform_data pdata; + struct v4l2_of_bus_mipi_csi2 bus; struct v4l2_subdev sd; struct media_pad pad; struct v4l2_ctrl_handler hdl; @@ -90,6 +94,8 @@ struct tc358743_state { struct v4l2_dv_timings timings; u32 mbus_fmt_code; + + struct gpio_desc *reset_gpio; }; static void tc358743_enable_interrupts(struct v4l2_subdev *sd, @@ -700,7 +706,8 @@ static void tc358743_set_csi(struct v4l2_subdev *sd) ((lanes > 2) ? MASK_D2M_HSTXVREGEN : 0x0) | ((lanes > 3) ? MASK_D3M_HSTXVREGEN : 0x0)); - i2c_wr32(sd, TXOPTIONCNTRL, MASK_CONTCLKMODE); + i2c_wr32(sd, TXOPTIONCNTRL, (state->bus.flags & + V4L2_MBUS_CSI2_CONTINUOUS_CLOCK) ? MASK_CONTCLKMODE : 0); i2c_wr32(sd, STARTCNTRL, MASK_START); i2c_wr32(sd, CSI_START, MASK_STRT); @@ -1638,6 +1645,136 @@ static const struct v4l2_ctrl_config tc358743_ctrl_audio_present = { /* --------------- PROBE / REMOVE --------------- */ +#ifdef CONFIG_OF +static void tc358743_gpio_reset(struct tc358743_state *state) +{ + gpiod_set_value(state->reset_gpio, 0); + usleep_range(5000, 10000); + gpiod_set_value(state->reset_gpio, 1); + usleep_range(1000, 2000); + gpiod_set_value(state->reset_gpio, 0); + msleep(20); +} + +static int tc358743_probe_of(struct tc358743_state *state) +{ + struct device *dev = &state->i2c_client->dev; + struct v4l2_of_endpoint *endpoint; + struct device_node *ep; + struct clk *refclk; + u32 bps_pr_lane; + int ret = -EINVAL; + + refclk = devm_clk_get(dev, "refclk"); + if (IS_ERR(refclk)) { + if (PTR_ERR(refclk) != -EPROBE_DEFER) + dev_err(dev, "failed to get refclk: %ld\n", + PTR_ERR(refclk)); + return PTR_ERR(refclk); + } + + ep = of_graph_get_next_endpoint(dev->of_node, NULL); + if (!ep) { + dev_err(dev, "missing endpoint node\n"); + return -EINVAL; + } + + endpoint = v4l2_of_alloc_parse_endpoint(ep); + if (IS_ERR(endpoint)) { + dev_err(dev, "failed to parse endpoint\n"); + return PTR_ERR(endpoint); + } + + if (endpoint->bus_type != V4L2_MBUS_CSI2 || + endpoint->bus.mipi_csi2.num_data_lanes == 0 || + endpoint->nr_of_link_frequencies == 0) { + dev_err(dev, "missing CSI-2 properties in endpoint\n"); + goto free_endpoint; + } + + state->bus = endpoint->bus.mipi_csi2; + + clk_prepare_enable(refclk); + + state->pdata.refclk_hz = clk_get_rate(refclk); + state->pdata.ddc5v_delay = DDC5V_DELAY_100_MS; + state->pdata.enable_hdcp = false; + /* A FIFO level of 16 should be enough for 2-lane 720p60 at 594 MHz. */ + state->pdata.fifo_level = 16; + /* + * The PLL input clock is obtained by dividing refclk by pll_prd. + * It must be between 6 MHz and 40 MHz, lower frequency is better. + */ + switch (state->pdata.refclk_hz) { + case 26000000: + case 27000000: + case 42000000: + state->pdata.pll_prd = state->pdata.refclk_hz / 6000000; + break; + default: + dev_err(dev, "unsupported refclk rate: %u Hz\n", + state->pdata.refclk_hz); + goto disable_clk; + } + + /* + * The CSI bps per lane must be between 62.5 Mbps and 1 Gbps. + * The default is 594 Mbps for 4-lane 1080p60 or 2-lane 720p60. + */ + bps_pr_lane = 2 * endpoint->link_frequencies[0]; + if (bps_pr_lane < 62500000U || bps_pr_lane > 1000000000U) { + dev_err(dev, "unsupported bps per lane: %u bps\n", bps_pr_lane); + goto disable_clk; + } + + /* The CSI speed per lane is refclk / pll_prd * pll_fbd */ + state->pdata.pll_fbd = bps_pr_lane / + state->pdata.refclk_hz * state->pdata.pll_prd; + + /* + * FIXME: These timings are from REF_02 for 594 Mbps per lane (297 MHz + * link frequency). In principle it should be possible to calculate + * them based on link frequency and resolution. + */ + if (bps_pr_lane != 594000000U) + dev_warn(dev, "untested bps per lane: %u bps\n", bps_pr_lane); + state->pdata.lineinitcnt = 0xe80; + state->pdata.lptxtimecnt = 0x003; + /* tclk-preparecnt: 3, tclk-zerocnt: 20 */ + state->pdata.tclk_headercnt = 0x1403; + state->pdata.tclk_trailcnt = 0x00; + /* ths-preparecnt: 3, ths-zerocnt: 1 */ + state->pdata.ths_headercnt = 0x0103; + state->pdata.twakeup = 0x4882; + state->pdata.tclk_postcnt = 0x008; + state->pdata.ths_trailcnt = 0x2; + state->pdata.hstxvregcnt = 0; + + state->reset_gpio = devm_gpiod_get(dev, "reset"); + if (IS_ERR(state->reset_gpio)) { + dev_err(dev, "failed to get reset gpio\n"); + ret = PTR_ERR(state->reset_gpio); + goto disable_clk; + } + + tc358743_gpio_reset(state); + + ret = 0; + goto free_endpoint; + +disable_clk: + clk_disable_unprepare(refclk); +free_endpoint: + v4l2_of_free_endpoint(endpoint); + return ret; +} +#else +static inline int tc358743_probe_of(struct tc358743_state *state) +{ + return -ENODEV; +} +#endif + static int tc358743_probe(struct i2c_client *client, const struct i2c_device_id *id) { @@ -1658,14 +1795,20 @@ static int tc358743_probe(struct i2c_client *client, if (!state) return -ENOMEM; + state->i2c_client = client; + /* platform data */ - if (!pdata) { - v4l_err(client, "No platform data!\n"); - return -ENODEV; + if (pdata) { + state->pdata = *pdata; + state->bus.flags = V4L2_MBUS_CSI2_CONTINUOUS_CLOCK; + } else { + err = tc358743_probe_of(state); + if (err == -ENODEV) + v4l_err(client, "No platform data!\n"); + if (err) + return err; } - state->pdata = *pdata; - state->i2c_client = client; sd = &state->sd; v4l2_i2c_subdev_init(sd, client, &tc358743_ops); sd->flags |= V4L2_SUBDEV_FL_HAS_DEVNODE | V4L2_SUBDEV_FL_HAS_EVENTS; -- cgit v1.2.3-58-ga151 From 6951813e66e07f18c9a425c3fbd966947ea401ab Mon Sep 17 00:00:00 2001 From: Mikhail Ulyanov Date: Wed, 22 Jul 2015 08:23:04 -0300 Subject: [media] devicetree: bindings: Document Renesas R-Car JPEG Processing Unit Add Renesas R-Car JPEG processing unit driver device tree bindings documentation. Signed-off-by: Mikhail Ulyanov Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- .../devicetree/bindings/media/renesas,jpu.txt | 24 ++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 Documentation/devicetree/bindings/media/renesas,jpu.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/media/renesas,jpu.txt b/Documentation/devicetree/bindings/media/renesas,jpu.txt new file mode 100644 index 000000000000..0cb94201bf92 --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,jpu.txt @@ -0,0 +1,24 @@ +* Renesas JPEG Processing Unit + +The JPEG processing unit (JPU) incorporates the JPEG codec with an encoding +and decoding function conforming to the JPEG baseline process, so that the JPU +can encode image data and decode JPEG data quickly. + +Required properties: + - compatible: should containg one of the following: + - "renesas,jpu-r8a7790" for R-Car H2 + - "renesas,jpu-r8a7791" for R-Car M2-W + - "renesas,jpu-r8a7792" for R-Car V2H + - "renesas,jpu-r8a7793" for R-Car M2-N + + - reg: Base address and length of the registers block for the JPU. + - interrupts: JPU interrupt specifier. + - clocks: A phandle + clock-specifier pair for the JPU functional clock. + +Example: R8A7790 (R-Car H2) JPU node + jpeg-codec@fe980000 { + compatible = "renesas,jpu-r8a7790"; + reg = <0 0xfe980000 0 0x10300>; + interrupts = <0 272 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&mstp1_clks R8A7790_CLK_JPU>; + }; -- cgit v1.2.3-58-ga151 From ed099f66dadd8bac93571fb28b05bdae066b39a2 Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Mon, 13 Jul 2015 20:36:50 -0300 Subject: [media] DocBook: Fix typo in intro.xml This patch fix spelling typos in intro.xml. This xml file is not created from comments within source, I fix the xml file. Signed-off-by: Masanari Iida [hans.verkuil@cisco.com: removed mention of obsolete devfs] Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/dvb/intro.xml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/dvb/intro.xml b/Documentation/DocBook/media/dvb/intro.xml index bcc72c216402..d30751338493 100644 --- a/Documentation/DocBook/media/dvb/intro.xml +++ b/Documentation/DocBook/media/dvb/intro.xml @@ -163,9 +163,8 @@ are called: where N enumerates the DVB PCI cards in a system starting from 0, and M enumerates the devices of each type within each adapter, starting from 0, too. We will omit the “ -/dev/dvb/adapterN/” in the further dicussion -of these devices. The naming scheme for the devices is the same wheter -devfs is used or not. +/dev/dvb/adapterN/” in the further discussion +of these devices. More details about the data structures and function calls of all the devices are described in the following chapters. -- cgit v1.2.3-58-ga151 From 179dd8c0348af75b02c7d72eaaf1cb179f1721ef Mon Sep 17 00:00:00 2001 From: Peter Griffin Date: Thu, 30 Jul 2015 14:08:54 -0300 Subject: [media] c8sectpfe: Add DT bindings documentation for c8sectpfe driver This patch adds the DT bindings documentation for the c8sectpfe LinuxDVB demux driver whose IP is in the STiH407 family silicon SoC's. Signed-off-by: Peter Griffin Signed-off-by: Mauro Carvalho Chehab --- .../bindings/media/stih407-c8sectpfe.txt | 89 ++++++++++++++++++++++ include/dt-bindings/media/c8sectpfe.h | 12 +++ 2 files changed, 101 insertions(+) create mode 100644 Documentation/devicetree/bindings/media/stih407-c8sectpfe.txt create mode 100644 include/dt-bindings/media/c8sectpfe.h (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/media/stih407-c8sectpfe.txt b/Documentation/devicetree/bindings/media/stih407-c8sectpfe.txt new file mode 100644 index 000000000000..d4def767bdfe --- /dev/null +++ b/Documentation/devicetree/bindings/media/stih407-c8sectpfe.txt @@ -0,0 +1,89 @@ +STMicroelectronics STi c8sectpfe binding +============================================ + +This document describes the c8sectpfe device bindings that is used to get transport +stream data into the SoC on the TS pins, and into DDR for further processing. + +It is typically used in conjunction with one or more demodulator and tuner devices +which converts from the RF to digital domain. Demodulators and tuners are usually +located on an external DVB frontend card connected to SoC TS input pins. + +Currently 7 TS input (tsin) channels are supported on the stih407 family SoC. + +Required properties (controller (parent) node): +- compatible : Should be "stih407-c8sectpfe" + +- reg : Address and length of register sets for each device in + "reg-names" + +- reg-names : The names of the register addresses corresponding to the + registers filled in "reg": + - c8sectpfe: c8sectpfe registers + - c8sectpfe-ram: c8sectpfe internal sram + +- clocks : phandle list of c8sectpfe clocks +- clock-names : should be "c8sectpfe" +See: Documentation/devicetree/bindings/clock/clock-bindings.txt + +- pinctrl-names : a pinctrl state named tsin%d-serial or tsin%d-parallel (where %d is tsin-num) + must be defined for each tsin child node. +- pinctrl-0 : phandle referencing pin configuration for this tsin configuration +See: Documentation/devicetree/bindings/pinctrl/pinctrl-binding.txt + + +Required properties (tsin (child) node): + +- tsin-num : tsin id of the InputBlock (must be between 0 to 6) +- i2c-bus : phandle to the I2C bus DT node which the demodulators & tuners on this tsin channel are connected. +- rst-gpio : reset gpio for this tsin channel. + +Optional properties (tsin (child) node): + +- invert-ts-clk : Bool property to control sense of ts input clock (data stored on falling edge of clk). +- serial-not-parallel : Bool property to configure input bus width (serial on ts_data<7>). +- async-not-sync : Bool property to control if data is received in asynchronous mode + (all bits/bytes with ts_valid or ts_packet asserted are valid). + +- dvb-card : Describes the NIM card connected to this tsin channel. + +Example: + +/* stih410 SoC b2120 + b2004a + stv0367-pll(NIMB) + stv0367-tda18212 (NIMA) DT example) */ + + c8sectpfe@08a20000 { + compatible = "st,stih407-c8sectpfe"; + status = "okay"; + reg = <0x08a20000 0x10000>, <0x08a00000 0x4000>; + reg-names = "stfe", "stfe-ram"; + interrupts = <0 34 0>, <0 35 0>; + interrupt-names = "stfe-error-irq", "stfe-idle-irq"; + + pinctrl-names = "tsin0-serial", "tsin0-parallel", "tsin3-serial", + "tsin4-serial", "tsin5-serial"; + + pinctrl-0 = <&pinctrl_tsin0_serial>; + pinctrl-1 = <&pinctrl_tsin0_parallel>; + pinctrl-2 = <&pinctrl_tsin3_serial>; + pinctrl-3 = <&pinctrl_tsin4_serial_alt3>; + pinctrl-4 = <&pinctrl_tsin5_serial_alt1>; + + clocks = <&clk_s_c0_flexgen CLK_PROC_STFE>; + clock-names = "stfe"; + + /* tsin0 is TSA on NIMA */ + tsin0: port@0 { + tsin-num = <0>; + serial-not-parallel; + i2c-bus = <&ssc2>; + rst-gpio = <&pio15 4 0>; + dvb-card = ; + }; + + tsin3: port@3 { + tsin-num = <3>; + serial-not-parallel; + i2c-bus = <&ssc3>; + rst-gpio = <&pio15 7 0>; + dvb-card = ; + }; + }; diff --git a/include/dt-bindings/media/c8sectpfe.h b/include/dt-bindings/media/c8sectpfe.h new file mode 100644 index 000000000000..a0b5c7be683c --- /dev/null +++ b/include/dt-bindings/media/c8sectpfe.h @@ -0,0 +1,12 @@ +#ifndef __DT_C8SECTPFE_H +#define __DT_C8SECTPFE_H + +#define STV0367_TDA18212_NIMA_1 0 +#define STV0367_TDA18212_NIMA_2 1 +#define STV0367_TDA18212_NIMB_1 2 +#define STV0367_TDA18212_NIMB_2 3 + +#define STV0903_6110_LNB24_NIMA 4 +#define STV0903_6110_LNB24_NIMB 5 + +#endif /* __DT_C8SECTPFE_H */ -- cgit v1.2.3-58-ga151 From 88c25dcb1185f2c7041550976430e27fa9d8dcca Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 21 Aug 2015 13:37:54 -0300 Subject: [media] DocBook: fix an unbalanced tag The got lost on some change at the DVB docbook, making the tag unbalanced and causing a warning. Fix it. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet --- Documentation/DocBook/media/dvb/intro.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/dvb/intro.xml b/Documentation/DocBook/media/dvb/intro.xml index d30751338493..51db15648099 100644 --- a/Documentation/DocBook/media/dvb/intro.xml +++ b/Documentation/DocBook/media/dvb/intro.xml @@ -164,7 +164,7 @@ are called: from 0, and M enumerates the devices of each type within each adapter, starting from 0, too. We will omit the “ /dev/dvb/adapterN/” in the further discussion -of these devices. +of these devices. More details about the data structures and function calls of all the devices are described in the following chapters. -- cgit v1.2.3-58-ga151 From dc2c8bd3c9a44ed38d9af6c7243fdddc42ec391a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 21 Aug 2015 14:17:13 -0300 Subject: [media] DocBook/device-drivers: Add drivers/media core stuff There are lots of docbook marks at the media subsystem, but those aren't used. Add the core headers/code in order to start generating docs. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet --- Documentation/DocBook/device-drivers.tmpl | 30 ++++++++++++++++++++++++++++++ drivers/media/dvb-core/dvb_math.h | 10 ++++++---- 2 files changed, 36 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index faf09d4a0ea8..e3e0f4880770 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -216,6 +216,36 @@ X!Isound/sound_firmware.c --> + + Media Devices +!Iinclude/media/media-device.h +!Iinclude/media/media-devnode.h +!Iinclude/media/media-entity.h +!Iinclude/media/v4l2-async.h +!Iinclude/media/v4l2-flash-led-class.h +!Iinclude/media/v4l2-mem2mem.h +!Iinclude/media/v4l2-of.h +!Iinclude/media/v4l2-subdev.h +!Iinclude/media/rc-core.h + + + + 16x50 UART Driver !Edrivers/tty/serial/serial_core.c diff --git a/drivers/media/dvb-core/dvb_math.h b/drivers/media/dvb-core/dvb_math.h index aecc867e9404..f586aa001ede 100644 --- a/drivers/media/dvb-core/dvb_math.h +++ b/drivers/media/dvb-core/dvb_math.h @@ -30,9 +30,10 @@ * to use rational values you can use the following method: * intlog2(value) = intlog2(value * 2^x) - x * 2^24 * - * example: intlog2(8) will give 3 << 24 = 3 * 2^24 - * example: intlog2(9) will give 3 << 24 + ... = 3.16... * 2^24 - * example: intlog2(1.5) = intlog2(3) - 2^24 = 0.584... * 2^24 + * Some usecase examples: + * intlog2(8) will give 3 << 24 = 3 * 2^24 + * intlog2(9) will give 3 << 24 + ... = 3.16... * 2^24 + * intlog2(1.5) = intlog2(3) - 2^24 = 0.584... * 2^24 * * @param value The value (must be != 0) * @return log2(value) * 2^24 @@ -45,7 +46,8 @@ extern unsigned int intlog2(u32 value); * to use rational values you can use the following method: * intlog10(value) = intlog10(value * 10^x) - x * 2^24 * - * example: intlog10(1000) will give 3 << 24 = 3 * 2^24 + * An usecase example: + * intlog10(1000) will give 3 << 24 = 3 * 2^24 * due to the implementation intlog10(1000) might be not exactly 3 * 2^24 * * look at intlog2 for similar examples -- cgit v1.2.3-58-ga151 From 5240f4e68d4209588194ea1db60f7c822e2a1c6f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 22 Aug 2015 05:02:21 -0300 Subject: [media] DocBook/media/Makefile: Avoid make htmldocs to fail If make is called twice like that: make V=1 DOCBOOKS=device-drivers.xml htmldocs Make will fail with: make -f ./scripts/Makefile.build obj=scripts/basic rm -f .tmp_quiet_recordmcount make -f ./scripts/Makefile.build obj=scripts build_docproc make -f ./scripts/Makefile.build obj=Documentation/DocBook htmldocs rm -rf Documentation/DocBook/index.html; echo '

Linux Kernel HTML Documentation

' >> Documentation/DocBook/index.html && echo '

Kernel Version: 4.2.0-rc2

' >> Documentation/DocBook/index.html && cat Documentation/DocBook/device-drivers.html >> Documentation/DocBook/index.html cp ./Documentation/DocBook//bayer.png ./Documentation/DocBook//constraints.png ./Documentation/DocBook//crop.gif ./Documentation/DocBook//dvbstb.png ./Documentation/DocBook//fieldseq_bt.gif ./Documentation/DocBook//fieldseq_tb.gif ./Documentation/DocBook//nv12mt.gif ./Documentation/DocBook//nv12mt_example.gif ./Documentation/DocBook//pipeline.png ./Documentation/DocBook//selection.png ./Documentation/DocBook//vbi_525.gif ./Documentation/DocBook//vbi_625.gif ./Documentation/DocBook//vbi_hsync.gif ./Documentation/DocBook/media/*.svg ./Documentation/DocBook/media/v4l/*.svg ./Documentation/DocBook//media_api cp: target './Documentation/DocBook//media_api' is not a directory Documentation/DocBook/Makefile:53: recipe for target 'htmldocs' failed Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet --- Documentation/DocBook/media/Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 23996f88cd58..08527e7ea4d0 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -199,7 +199,8 @@ DVB_DOCUMENTED = \ # install_media_images = \ - $(Q)-cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/*.svg $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api + $(Q)-mkdir $(MEDIA_OBJ_DIR)/media_api; \ + cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/*.svg $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api $(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64 $(Q)base64 -d $< >$@ -- cgit v1.2.3-58-ga151 From fbefb1a87c7e6e24df6ca5b42b42985e2680c2ea Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 22 Aug 2015 07:09:29 -0300 Subject: [media] DocBook: add dvb_ca_en50221.h to documentation There are already some tags at dvb_ca_en50221.h, but using a different format. Convert them, fix a few entries and add to the device-drivers DocBook. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet --- Documentation/DocBook/device-drivers.tmpl | 2 +- drivers/media/dvb-core/dvb_ca_en50221.c | 167 +++++++++++++++--------------- drivers/media/dvb-core/dvb_ca_en50221.h | 34 +++--- 3 files changed, 102 insertions(+), 101 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index e3e0f4880770..e0c358760344 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -227,6 +227,7 @@ X!Isound/sound_firmware.c !Iinclude/media/v4l2-of.h !Iinclude/media/v4l2-subdev.h !Iinclude/media/rc-core.h +!Idrivers/media/dvb-core/dvb_ca_en50221.h diff --git a/drivers/media/dvb-core/dvb_ca_en50221.c b/drivers/media/dvb-core/dvb_ca_en50221.c index 72937756f60c..fb66184dc9b6 100644 --- a/drivers/media/dvb-core/dvb_ca_en50221.c +++ b/drivers/media/dvb-core/dvb_ca_en50221.c @@ -169,10 +169,10 @@ static int dvb_ca_en50221_write_data(struct dvb_ca_private *ca, int slot, u8 * e /** * Safely find needle in haystack. * - * @param haystack Buffer to look in. - * @param hlen Number of bytes in haystack. - * @param needle Buffer to find. - * @param nlen Number of bytes in needle. + * @haystack: Buffer to look in. + * @hlen: Number of bytes in haystack. + * @needle: Buffer to find. + * @nlen: Number of bytes in needle. * @return Pointer into haystack needle was found at, or NULL if not found. */ static char *findstr(char * haystack, int hlen, char * needle, int nlen) @@ -197,7 +197,7 @@ static char *findstr(char * haystack, int hlen, char * needle, int nlen) /** - * Check CAM status. + * dvb_ca_en50221_check_camstatus - Check CAM status. */ static int dvb_ca_en50221_check_camstatus(struct dvb_ca_private *ca, int slot) { @@ -240,13 +240,13 @@ static int dvb_ca_en50221_check_camstatus(struct dvb_ca_private *ca, int slot) /** - * Wait for flags to become set on the STATUS register on a CAM interface, - * checking for errors and timeout. + * dvb_ca_en50221_wait_if_status - Wait for flags to become set on the STATUS + * register on a CAM interface, checking for errors and timeout. * - * @param ca CA instance. - * @param slot Slot on interface. - * @param waitfor Flags to wait for. - * @param timeout_ms Timeout in milliseconds. + * @ca: CA instance. + * @slot: Slot on interface. + * @waitfor: Flags to wait for. + * @timeout_ms: Timeout in milliseconds. * * @return 0 on success, nonzero on error. */ @@ -290,10 +290,10 @@ static int dvb_ca_en50221_wait_if_status(struct dvb_ca_private *ca, int slot, /** - * Initialise the link layer connection to a CAM. + * dvb_ca_en50221_link_init - Initialise the link layer connection to a CAM. * - * @param ca CA instance. - * @param slot Slot id. + * @ca: CA instance. + * @slot: Slot id. * * @return 0 on success, nonzero on failure. */ @@ -346,14 +346,14 @@ static int dvb_ca_en50221_link_init(struct dvb_ca_private *ca, int slot) } /** - * Read a tuple from attribute memory. + * dvb_ca_en50221_read_tuple - Read a tuple from attribute memory. * - * @param ca CA instance. - * @param slot Slot id. - * @param address Address to read from. Updated. - * @param tupleType Tuple id byte. Updated. - * @param tupleLength Tuple length. Updated. - * @param tuple Dest buffer for tuple (must be 256 bytes). Updated. + * @ca: CA instance. + * @slot: Slot id. + * @address: Address to read from. Updated. + * @tupleType: Tuple id byte. Updated. + * @tupleLength: Tuple length. Updated. + * @tuple: Dest buffer for tuple (must be 256 bytes). Updated. * * @return 0 on success, nonzero on error. */ @@ -399,11 +399,11 @@ static int dvb_ca_en50221_read_tuple(struct dvb_ca_private *ca, int slot, /** - * Parse attribute memory of a CAM module, extracting Config register, and checking - * it is a DVB CAM module. + * dvb_ca_en50221_parse_attributes - Parse attribute memory of a CAM module, + * extracting Config register, and checking it is a DVB CAM module. * - * @param ca CA instance. - * @param slot Slot id. + * @ca: CA instance. + * @slot: Slot id. * * @return 0 on success, <0 on failure. */ @@ -546,10 +546,10 @@ static int dvb_ca_en50221_parse_attributes(struct dvb_ca_private *ca, int slot) /** - * Set CAM's configoption correctly. + * dvb_ca_en50221_set_configoption - Set CAM's configoption correctly. * - * @param ca CA instance. - * @param slot Slot containing the CAM. + * @ca: CA instance. + * @slot: Slot containing the CAM. */ static int dvb_ca_en50221_set_configoption(struct dvb_ca_private *ca, int slot) { @@ -574,15 +574,16 @@ static int dvb_ca_en50221_set_configoption(struct dvb_ca_private *ca, int slot) /** - * This function talks to an EN50221 CAM control interface. It reads a buffer of - * data from the CAM. The data can either be stored in a supplied buffer, or - * automatically be added to the slot's rx_buffer. + * dvb_ca_en50221_read_data - This function talks to an EN50221 CAM control + * interface. It reads a buffer of data from the CAM. The data can either + * be stored in a supplied buffer, or automatically be added to the slot's + * rx_buffer. * - * @param ca CA instance. - * @param slot Slot to read from. - * @param ebuf If non-NULL, the data will be written to this buffer. If NULL, + * @ca: CA instance. + * @slot: Slot to read from. + * @ebuf: If non-NULL, the data will be written to this buffer. If NULL, * the data will be added into the buffering system as a normal fragment. - * @param ecount Size of ebuf. Ignored if ebuf is NULL. + * @ecount: Size of ebuf. Ignored if ebuf is NULL. * * @return Number of bytes read, or < 0 on error */ @@ -698,14 +699,14 @@ exit: /** - * This function talks to an EN50221 CAM control interface. It writes a buffer of data - * to a CAM. + * dvb_ca_en50221_write_data - This function talks to an EN50221 CAM control + * interface. It writes a buffer of data to a CAM. * - * @param ca CA instance. - * @param slot Slot to write to. - * @param ebuf The data in this buffer is treated as a complete link-level packet to + * @ca: CA instance. + * @slot: Slot to write to. + * @ebuf: The data in this buffer is treated as a complete link-level packet to * be written. - * @param count Size of ebuf. + * @count: Size of ebuf. * * @return Number of bytes written, or < 0 on error. */ @@ -790,10 +791,10 @@ EXPORT_SYMBOL(dvb_ca_en50221_camchange_irq); /** - * A CAM has been removed => shut it down. + * dvb_ca_en50221_camready_irq - A CAM has been removed => shut it down. * - * @param ca CA instance. - * @param slot Slot to shut down. + * @ca: CA instance. + * @slot: Slot to shut down. */ static int dvb_ca_en50221_slot_shutdown(struct dvb_ca_private *ca, int slot) { @@ -815,11 +816,11 @@ EXPORT_SYMBOL(dvb_ca_en50221_camready_irq); /** - * A CAMCHANGE IRQ has occurred. + * dvb_ca_en50221_camready_irq - A CAMCHANGE IRQ has occurred. * - * @param ca CA instance. - * @param slot Slot concerned. - * @param change_type One of the DVB_CA_CAMCHANGE_* values. + * @ca: CA instance. + * @slot: Slot concerned. + * @change_type: One of the DVB_CA_CAMCHANGE_* values. */ void dvb_ca_en50221_camchange_irq(struct dvb_ca_en50221 *pubca, int slot, int change_type) { @@ -844,10 +845,10 @@ EXPORT_SYMBOL(dvb_ca_en50221_frda_irq); /** - * A CAMREADY IRQ has occurred. + * dvb_ca_en50221_camready_irq - A CAMREADY IRQ has occurred. * - * @param ca CA instance. - * @param slot Slot concerned. + * @ca: CA instance. + * @slot: Slot concerned. */ void dvb_ca_en50221_camready_irq(struct dvb_ca_en50221 *pubca, int slot) { @@ -865,8 +866,8 @@ void dvb_ca_en50221_camready_irq(struct dvb_ca_en50221 *pubca, int slot) /** * An FR or DA IRQ has occurred. * - * @param ca CA instance. - * @param slot Slot concerned. + * @ca: CA instance. + * @slot: Slot concerned. */ void dvb_ca_en50221_frda_irq(struct dvb_ca_en50221 *pubca, int slot) { @@ -899,7 +900,7 @@ void dvb_ca_en50221_frda_irq(struct dvb_ca_en50221 *pubca, int slot) /** * Wake up the DVB CA thread * - * @param ca CA instance. + * @ca: CA instance. */ static void dvb_ca_en50221_thread_wakeup(struct dvb_ca_private *ca) { @@ -914,7 +915,7 @@ static void dvb_ca_en50221_thread_wakeup(struct dvb_ca_private *ca) /** * Update the delay used by the thread. * - * @param ca CA instance. + * @ca: CA instance. */ static void dvb_ca_en50221_thread_update_delay(struct dvb_ca_private *ca) { @@ -1177,10 +1178,10 @@ static int dvb_ca_en50221_thread(void *data) * Real ioctl implementation. * NOTE: CA_SEND_MSG/CA_GET_MSG ioctls have userspace buffers passed to them. * - * @param inode Inode concerned. - * @param file File concerned. - * @param cmd IOCTL command. - * @param arg Associated argument. + * @inode: Inode concerned. + * @file: File concerned. + * @cmd: IOCTL command. + * @arg: Associated argument. * * @return 0 on success, <0 on error. */ @@ -1258,10 +1259,10 @@ out_unlock: /** * Wrapper for ioctl implementation. * - * @param inode Inode concerned. - * @param file File concerned. - * @param cmd IOCTL command. - * @param arg Associated argument. + * @inode: Inode concerned. + * @file: File concerned. + * @cmd: IOCTL command. + * @arg: Associated argument. * * @return 0 on success, <0 on error. */ @@ -1275,10 +1276,10 @@ static long dvb_ca_en50221_io_ioctl(struct file *file, /** * Implementation of write() syscall. * - * @param file File structure. - * @param buf Source buffer. - * @param count Size of source buffer. - * @param ppos Position in file (ignored). + * @file: File structure. + * @buf: Source buffer. + * @count: Size of source buffer. + * @ppos: Position in file (ignored). * * @return Number of bytes read, or <0 on error. */ @@ -1416,10 +1417,10 @@ nextslot: /** * Implementation of read() syscall. * - * @param file File structure. - * @param buf Destination buffer. - * @param count Size of destination buffer. - * @param ppos Position in file (ignored). + * @file: File structure. + * @buf: Destination buffer. + * @count: Size of destination buffer. + * @ppos: Position in file (ignored). * * @return Number of bytes read, or <0 on error. */ @@ -1519,8 +1520,8 @@ exit: /** * Implementation of file open syscall. * - * @param inode Inode concerned. - * @param file File concerned. + * @inode: Inode concerned. + * @file: File concerned. * * @return 0 on success, <0 on failure. */ @@ -1564,8 +1565,8 @@ static int dvb_ca_en50221_io_open(struct inode *inode, struct file *file) /** * Implementation of file close syscall. * - * @param inode Inode concerned. - * @param file File concerned. + * @inode: Inode concerned. + * @file: File concerned. * * @return 0 on success, <0 on failure. */ @@ -1592,8 +1593,8 @@ static int dvb_ca_en50221_io_release(struct inode *inode, struct file *file) /** * Implementation of poll() syscall. * - * @param file File concerned. - * @param wait poll wait table. + * @file: File concerned. + * @wait: poll wait table. * * @return Standard poll mask. */ @@ -1656,10 +1657,10 @@ static const struct dvb_device dvbdev_ca = { /** * Initialise a new DVB CA EN50221 interface device. * - * @param dvb_adapter DVB adapter to attach the new CA device to. - * @param ca The dvb_ca instance. - * @param flags Flags describing the CA device (DVB_CA_FLAG_*). - * @param slot_count Number of slots supported. + * @dvb_adapter: DVB adapter to attach the new CA device to. + * @ca: The dvb_ca instance. + * @flags: Flags describing the CA device (DVB_CA_FLAG_*). + * @slot_count: Number of slots supported. * * @return 0 on success, nonzero on failure */ @@ -1743,8 +1744,8 @@ EXPORT_SYMBOL(dvb_ca_en50221_release); /** * Release a DVB CA EN50221 interface device. * - * @param ca_dev The dvb_device_t instance for the CA device. - * @param ca The associated dvb_ca instance. + * @ca_dev: The dvb_device_t instance for the CA device. + * @ca: The associated dvb_ca instance. */ void dvb_ca_en50221_release(struct dvb_ca_en50221 *pubca) { diff --git a/drivers/media/dvb-core/dvb_ca_en50221.h b/drivers/media/dvb-core/dvb_ca_en50221.h index 7df2e141187a..aba3b4fbd704 100644 --- a/drivers/media/dvb-core/dvb_ca_en50221.h +++ b/drivers/media/dvb-core/dvb_ca_en50221.h @@ -83,27 +83,27 @@ struct dvb_ca_en50221 { /* Functions for reporting IRQ events */ /** - * A CAMCHANGE IRQ has occurred. + * dvb_ca_en50221_camchange_irq - A CAMCHANGE IRQ has occurred. * - * @param ca CA instance. - * @param slot Slot concerned. - * @param change_type One of the DVB_CA_CAMCHANGE_* values + * @pubca: CA instance. + * @slot: Slot concerned. + * @change_type: One of the DVB_CA_CAMCHANGE_* values */ void dvb_ca_en50221_camchange_irq(struct dvb_ca_en50221* pubca, int slot, int change_type); /** - * A CAMREADY IRQ has occurred. + * dvb_ca_en50221_camready_irq - A CAMREADY IRQ has occurred. * - * @param ca CA instance. - * @param slot Slot concerned. + * @pubca: CA instance. + * @slot: Slot concerned. */ void dvb_ca_en50221_camready_irq(struct dvb_ca_en50221* pubca, int slot); /** - * An FR or a DA IRQ has occurred. + * dvb_ca_en50221_frda_irq - An FR or a DA IRQ has occurred. * - * @param ca CA instance. - * @param slot Slot concerned. + * @ca: CA instance. + * @slot: Slot concerned. */ void dvb_ca_en50221_frda_irq(struct dvb_ca_en50221* ca, int slot); @@ -113,21 +113,21 @@ void dvb_ca_en50221_frda_irq(struct dvb_ca_en50221* ca, int slot); /* Initialisation/shutdown functions */ /** - * Initialise a new DVB CA device. + * dvb_ca_en50221_init - Initialise a new DVB CA device. * - * @param dvb_adapter DVB adapter to attach the new CA device to. - * @param ca The dvb_ca instance. - * @param flags Flags describing the CA device (DVB_CA_EN50221_FLAG_*). - * @param slot_count Number of slots supported. + * @dvb_adapter: DVB adapter to attach the new CA device to. + * @ca: The dvb_ca instance. + * @flags: Flags describing the CA device (DVB_CA_EN50221_FLAG_*). + * @slot_count: Number of slots supported. * * @return 0 on success, nonzero on failure */ extern int dvb_ca_en50221_init(struct dvb_adapter *dvb_adapter, struct dvb_ca_en50221* ca, int flags, int slot_count); /** - * Release a DVB CA device. + * dvb_ca_en50221_release - Release a DVB CA device. * - * @param ca The associated dvb_ca instance. + * @ca: The associated dvb_ca instance. */ extern void dvb_ca_en50221_release(struct dvb_ca_en50221* ca); -- cgit v1.2.3-58-ga151 From 4f1c1868e8d4e493d66b8e11eebbc95abdbaf444 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 22 Aug 2015 07:19:20 -0300 Subject: [media] DocBook: add dvb_frontend.h to documentation There are already some comments at dvb_frontend.h that are ready for DocBook, although not properly formatted. Convert them, and add this file to the device-drivers DocBook. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet --- Documentation/DocBook/device-drivers.tmpl | 2 +- drivers/media/dvb-core/dvb_frontend.h | 68 +++++++++++++++---------------- 2 files changed, 34 insertions(+), 36 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index e0c358760344..fb5c16a24e4b 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -228,6 +228,7 @@ X!Isound/sound_firmware.c !Iinclude/media/v4l2-subdev.h !Iinclude/media/rc-core.h !Idrivers/media/dvb-core/dvb_ca_en50221.h +!Idrivers/media/dvb-core/dvb_frontend.h diff --git a/drivers/media/dvb-core/dvb_math.h b/drivers/media/dvb-core/dvb_math.h index f586aa001ede..34dc1df03cab 100644 --- a/drivers/media/dvb-core/dvb_math.h +++ b/drivers/media/dvb-core/dvb_math.h @@ -25,7 +25,9 @@ #include /** - * computes log2 of a value; the result is shifted left by 24 bits + * cintlog2 - computes log2 of a value; the result is shifted left by 24 bits + * + * @value: The value (must be != 0) * * to use rational values you can use the following method: * intlog2(value) = intlog2(value * 2^x) - x * 2^24 @@ -35,13 +37,15 @@ * intlog2(9) will give 3 << 24 + ... = 3.16... * 2^24 * intlog2(1.5) = intlog2(3) - 2^24 = 0.584... * 2^24 * - * @param value The value (must be != 0) - * @return log2(value) * 2^24 + * + * return: log2(value) * 2^24 */ extern unsigned int intlog2(u32 value); /** - * computes log10 of a value; the result is shifted left by 24 bits + * intlog10 - computes log10 of a value; the result is shifted left by 24 bits + * + * @value: The value (must be != 0) * * to use rational values you can use the following method: * intlog10(value) = intlog10(value * 10^x) - x * 2^24 @@ -52,8 +56,7 @@ extern unsigned int intlog2(u32 value); * * look at intlog2 for similar examples * - * @param value The value (must be != 0) - * @return log10(value) * 2^24 + * return: log10(value) * 2^24 */ extern unsigned int intlog10(u32 value); -- cgit v1.2.3-58-ga151 From 2a86e373e0cf926f5cb41725f1b0ce3874e7b1cf Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 22 Aug 2015 07:38:51 -0300 Subject: [media] DocBook: add dvb_ringbuffer.h to documentation There are already some comments at dvb_ringbuffer.h that are ready for DocBook, although not properly formatted. Convert them, fix some issues and add this file to the device-drivers DocBook. While here, put multi-line comments on the right format. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet --- Documentation/DocBook/device-drivers.tmpl | 2 +- drivers/media/dvb-core/dvb_ringbuffer.h | 135 +++++++++++++++++------------- 2 files changed, 76 insertions(+), 61 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 21fc7684d706..030b3803cc68 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -230,6 +230,7 @@ X!Isound/sound_firmware.c !Idrivers/media/dvb-core/dvb_ca_en50221.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/drivers/media/dvb-core/dvb_ringbuffer.h b/drivers/media/dvb-core/dvb_ringbuffer.h index 9e1e11b7c39c..3ebc2d34b4a2 100644 --- a/drivers/media/dvb-core/dvb_ringbuffer.h +++ b/drivers/media/dvb-core/dvb_ringbuffer.h @@ -45,33 +45,33 @@ struct dvb_ringbuffer { /* -** Notes: -** ------ -** (1) For performance reasons read and write routines don't check buffer sizes -** and/or number of bytes free/available. This has to be done before these -** routines are called. For example: -** -** *** write bytes *** -** free = dvb_ringbuffer_free(rbuf); -** if (free >= buflen) -** count = dvb_ringbuffer_write(rbuf, buffer, buflen); -** else -** ... -** -** *** read min. 1000, max. bytes *** -** avail = dvb_ringbuffer_avail(rbuf); -** if (avail >= 1000) -** count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize)); -** else -** ... -** -** (2) If there is exactly one reader and one writer, there is no need -** to lock read or write operations. -** Two or more readers must be locked against each other. -** Flushing the buffer counts as a read operation. -** Resetting the buffer counts as a read and write operation. -** Two or more writers must be locked against each other. -*/ + * Notes: + * ------ + * (1) For performance reasons read and write routines don't check buffer sizes + * and/or number of bytes free/available. This has to be done before these + * routines are called. For example: + * + * *** write @buflen: bytes *** + * free = dvb_ringbuffer_free(rbuf); + * if (free >= buflen) + * count = dvb_ringbuffer_write(rbuf, buffer, buflen); + * else + * ... + * + * *** read min. 1000, max. @bufsize: bytes *** + * avail = dvb_ringbuffer_avail(rbuf); + * if (avail >= 1000) + * count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize)); + * else + * ... + * + * (2) If there is exactly one reader and one writer, there is no need + * to lock read or write operations. + * Two or more readers must be locked against each other. + * Flushing the buffer counts as a read operation. + * Resetting the buffer counts as a read and write operation. + * Two or more writers must be locked against each other. + */ /* initialize ring buffer, lock and queue */ extern void dvb_ringbuffer_init(struct dvb_ringbuffer *rbuf, void *data, size_t len); @@ -87,9 +87,9 @@ extern ssize_t dvb_ringbuffer_avail(struct dvb_ringbuffer *rbuf); /* -** Reset the read and write pointers to zero and flush the buffer -** This counts as a read and write operation -*/ + * Reset the read and write pointers to zero and flush the buffer + * This counts as a read and write operation + */ extern void dvb_ringbuffer_reset(struct dvb_ringbuffer *rbuf); @@ -101,19 +101,19 @@ extern void dvb_ringbuffer_flush(struct dvb_ringbuffer *rbuf); /* flush buffer protected by spinlock and wake-up waiting task(s) */ extern void dvb_ringbuffer_flush_spinlock_wakeup(struct dvb_ringbuffer *rbuf); -/* peek at byte in the buffer */ +/* peek at byte @offs: in the buffer */ #define DVB_RINGBUFFER_PEEK(rbuf,offs) \ (rbuf)->data[((rbuf)->pread+(offs))%(rbuf)->size] -/* advance read ptr by bytes */ +/* advance read ptr by @num: bytes */ #define DVB_RINGBUFFER_SKIP(rbuf,num) \ (rbuf)->pread=((rbuf)->pread+(num))%(rbuf)->size /* -** read bytes from ring buffer into -** specifies whether resides in user space -** returns number of bytes transferred or -EFAULT -*/ + * read @len: bytes from ring buffer into @buf: + * @usermem: specifies whether @buf: resides in user space + * returns number of bytes transferred or -EFAULT + */ extern ssize_t dvb_ringbuffer_read_user(struct dvb_ringbuffer *rbuf, u8 __user *buf, size_t len); extern void dvb_ringbuffer_read(struct dvb_ringbuffer *rbuf, @@ -127,9 +127,9 @@ extern void dvb_ringbuffer_read(struct dvb_ringbuffer *rbuf, { (rbuf)->data[(rbuf)->pwrite]=(byte); \ (rbuf)->pwrite=((rbuf)->pwrite+1)%(rbuf)->size; } /* -** write bytes to ring buffer -** specifies whether resides in user space -** returns number of bytes transferred or -EFAULT + * write @len: bytes to ring buffer + * @usermem: specifies whether @buf: resides in user space + * returns number of bytes transferred or -EFAULT */ extern ssize_t dvb_ringbuffer_write(struct dvb_ringbuffer *rbuf, const u8 *buf, size_t len); @@ -138,48 +138,63 @@ extern ssize_t dvb_ringbuffer_write_user(struct dvb_ringbuffer *rbuf, /** - * Write a packet into the ringbuffer. + * dvb_ringbuffer_pkt_write - Write a packet into the ringbuffer. * - * Ringbuffer to write to. - * Buffer to write. - * Length of buffer (currently limited to 65535 bytes max). + * @rbuf: Ringbuffer to write to. + * @buf: Buffer to write. + * @len: Length of buffer (currently limited to 65535 bytes max). * returns Number of bytes written, or -EFAULT, -ENOMEM, -EVINAL. */ extern ssize_t dvb_ringbuffer_pkt_write(struct dvb_ringbuffer *rbuf, u8* buf, size_t len); /** - * Read from a packet in the ringbuffer. Note: unlike dvb_ringbuffer_read(), this - * does NOT update the read pointer in the ringbuffer. You must use - * dvb_ringbuffer_pkt_dispose() to mark a packet as no longer required. - * - * Ringbuffer concerned. - * Packet index as returned by dvb_ringbuffer_pkt_next(). - * Offset into packet to read from. - * Destination buffer for data. - * Size of destination buffer. - * Set to 1 if is in userspace. + * dvb_ringbuffer_pkt_read_user - Read from a packet in the ringbuffer. + * Note: unlike dvb_ringbuffer_read(), this does NOT update the read pointer + * in the ringbuffer. You must use dvb_ringbuffer_pkt_dispose() to mark a + * packet as no longer required. + * + * @rbuf: Ringbuffer concerned. + * @idx: Packet index as returned by dvb_ringbuffer_pkt_next(). + * @offset: Offset into packet to read from. + * @buf: Destination buffer for data. + * @len: Size of destination buffer. + * * returns Number of bytes read, or -EFAULT. */ extern ssize_t dvb_ringbuffer_pkt_read_user(struct dvb_ringbuffer *rbuf, size_t idx, int offset, u8 __user *buf, size_t len); + +/** + * dvb_ringbuffer_pkt_read - Read from a packet in the ringbuffer. + * Note: unlike dvb_ringbuffer_read_user(), this DOES update the read pointer + * in the ringbuffer. + * + * @rbuf: Ringbuffer concerned. + * @idx: Packet index as returned by dvb_ringbuffer_pkt_next(). + * @offset: Offset into packet to read from. + * @buf: Destination buffer for data. + * @len: Size of destination buffer. + * + * returns Number of bytes read, or -EFAULT. + */ extern ssize_t dvb_ringbuffer_pkt_read(struct dvb_ringbuffer *rbuf, size_t idx, int offset, u8 *buf, size_t len); /** - * Dispose of a packet in the ring buffer. + * dvb_ringbuffer_pkt_dispose - Dispose of a packet in the ring buffer. * - * Ring buffer concerned. - * Packet index as returned by dvb_ringbuffer_pkt_next(). + * @rbuf: Ring buffer concerned. + * @idx: Packet index as returned by dvb_ringbuffer_pkt_next(). */ extern void dvb_ringbuffer_pkt_dispose(struct dvb_ringbuffer *rbuf, size_t idx); /** - * Get the index of the next packet in a ringbuffer. + * dvb_ringbuffer_pkt_next - Get the index of the next packet in a ringbuffer. * - * Ringbuffer concerned. - * Previous packet index, or -1 to return the first packet index. - * On success, will be updated to contain the length of the packet in bytes. + * @rbuf: Ringbuffer concerned. + * @idx: Previous packet index, or -1 to return the first packet index. + * @pktlen: On success, will be updated to contain the length of the packet in bytes. * returns Packet index (if >=0), or -1 if no packets available. */ extern ssize_t dvb_ringbuffer_pkt_next(struct dvb_ringbuffer *rbuf, size_t idx, size_t* pktlen); -- cgit v1.2.3-58-ga151 From 8c2721d57a4bac055ae7bb1874a13a928277d5ff Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 22 Aug 2015 08:03:49 -0300 Subject: [media] v4l2-ctrls.h: add to device-drivers DocBook The comments there are using a wrong format. Due to that, DocBook were unable to parse it. Fix the tags format, and add it to device-drivers.xml. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet --- Documentation/DocBook/device-drivers.tmpl | 6 +- include/media/v4l2-ctrls.h | 1011 ++++++++++++++++------------- 2 files changed, 552 insertions(+), 465 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 030b3803cc68..5f01f7ad15dc 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -231,17 +231,13 @@ X!Isound/sound_firmware.c !Idrivers/media/dvb-core/dvb_frontend.h !Idrivers/media/dvb-core/dvb_math.h !Idrivers/media/dvb-core/dvb_ringbuffer.h +!Iinclude/media/v4l2-ctrls.h diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h index 911f3e542834..88f736661c06 100644 --- a/include/media/v4l2-ctrls.h +++ b/include/media/v4l2-ctrls.h @@ -36,7 +36,8 @@ struct v4l2_subscribed_event; struct v4l2_fh; struct poll_table_struct; -/** union v4l2_ctrl_ptr - A pointer to a control value. +/** + * union v4l2_ctrl_ptr - A pointer to a control value. * @p_s32: Pointer to a 32-bit signed value. * @p_s64: Pointer to a 64-bit signed value. * @p_u8: Pointer to a 8-bit unsigned value. @@ -55,30 +56,34 @@ union v4l2_ctrl_ptr { void *p; }; -/** struct v4l2_ctrl_ops - The control operations that the driver has to provide. - * @g_volatile_ctrl: Get a new value for this control. Generally only relevant - * for volatile (and usually read-only) controls such as a control - * that returns the current signal strength which changes - * continuously. - * If not set, then the currently cached value will be returned. - * @try_ctrl: Test whether the control's value is valid. Only relevant when - * the usual min/max/step checks are not sufficient. - * @s_ctrl: Actually set the new control value. s_ctrl is compulsory. The - * ctrl->handler->lock is held when these ops are called, so no - * one else can access controls owned by that handler. - */ +/** + * struct v4l2_ctrl_ops - The control operations that the driver has to provide. + * @g_volatile_ctrl: Get a new value for this control. Generally only relevant + * for volatile (and usually read-only) controls such as a control + * that returns the current signal strength which changes + * continuously. + * If not set, then the currently cached value will be returned. + * @try_ctrl: Test whether the control's value is valid. Only relevant when + * the usual min/max/step checks are not sufficient. + * @s_ctrl: Actually set the new control value. s_ctrl is compulsory. The + * ctrl->handler->lock is held when these ops are called, so no + * one else can access controls owned by that handler. + */ struct v4l2_ctrl_ops { int (*g_volatile_ctrl)(struct v4l2_ctrl *ctrl); int (*try_ctrl)(struct v4l2_ctrl *ctrl); int (*s_ctrl)(struct v4l2_ctrl *ctrl); }; -/** struct v4l2_ctrl_type_ops - The control type operations that the driver has to provide. - * @equal: return true if both values are equal. - * @init: initialize the value. - * @log: log the value. - * @validate: validate the value. Return 0 on success and a negative value otherwise. - */ +/** + * struct v4l2_ctrl_type_ops - The control type operations that the driver + * has to provide. + * + * @equal: return true if both values are equal. + * @init: initialize the value. + * @log: log the value. + * @validate: validate the value. Return 0 on success and a negative value otherwise. + */ struct v4l2_ctrl_type_ops { bool (*equal)(const struct v4l2_ctrl *ctrl, u32 idx, union v4l2_ctrl_ptr ptr1, @@ -92,74 +97,75 @@ struct v4l2_ctrl_type_ops { typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv); -/** struct v4l2_ctrl - The control structure. - * @node: The list node. - * @ev_subs: The list of control event subscriptions. - * @handler: The handler that owns the control. - * @cluster: Point to start of cluster array. - * @ncontrols: Number of controls in cluster array. - * @done: Internal flag: set for each processed control. - * @is_new: Set when the user specified a new value for this control. It - * is also set when called from v4l2_ctrl_handler_setup. Drivers - * should never set this flag. - * @has_changed: Set when the current value differs from the new value. Drivers - * should never use this flag. - * @is_private: If set, then this control is private to its handler and it - * will not be added to any other handlers. Drivers can set - * this flag. - * @is_auto: If set, then this control selects whether the other cluster - * members are in 'automatic' mode or 'manual' mode. This is - * used for autogain/gain type clusters. Drivers should never - * set this flag directly. - * @is_int: If set, then this control has a simple integer value (i.e. it - * uses ctrl->val). - * @is_string: If set, then this control has type V4L2_CTRL_TYPE_STRING. - * @is_ptr: If set, then this control is an array and/or has type >= V4L2_CTRL_COMPOUND_TYPES - * and/or has type V4L2_CTRL_TYPE_STRING. In other words, struct - * v4l2_ext_control uses field p to point to the data. - * @is_array: If set, then this control contains an N-dimensional array. - * @has_volatiles: If set, then one or more members of the cluster are volatile. - * Drivers should never touch this flag. - * @call_notify: If set, then call the handler's notify function whenever the - * control's value changes. - * @manual_mode_value: If the is_auto flag is set, then this is the value - * of the auto control that determines if that control is in - * manual mode. So if the value of the auto control equals this - * value, then the whole cluster is in manual mode. Drivers should - * never set this flag directly. - * @ops: The control ops. - * @type_ops: The control type ops. - * @id: The control ID. - * @name: The control name. - * @type: The control type. - * @minimum: The control's minimum value. - * @maximum: The control's maximum value. - * @default_value: The control's default value. - * @step: The control's step value for non-menu controls. - * @elems: The number of elements in the N-dimensional array. - * @elem_size: The size in bytes of the control. - * @dims: The size of each dimension. - * @nr_of_dims:The number of dimensions in @dims. - * @menu_skip_mask: The control's skip mask for menu controls. This makes it - * easy to skip menu items that are not valid. If bit X is set, - * then menu item X is skipped. Of course, this only works for - * menus with <= 32 menu items. There are no menus that come - * close to that number, so this is OK. Should we ever need more, - * then this will have to be extended to a u64 or a bit array. - * @qmenu: A const char * array for all menu items. Array entries that are - * empty strings ("") correspond to non-existing menu items (this - * is in addition to the menu_skip_mask above). The last entry - * must be NULL. - * @flags: The control's flags. - * @cur: The control's current value. - * @val: The control's new s32 value. - * @val64: The control's new s64 value. - * @priv: The control's private pointer. For use by the driver. It is - * untouched by the control framework. Note that this pointer is - * not freed when the control is deleted. Should this be needed - * then a new internal bitfield can be added to tell the framework - * to free this pointer. - */ +/** + * struct v4l2_ctrl - The control structure. + * @node: The list node. + * @ev_subs: The list of control event subscriptions. + * @handler: The handler that owns the control. + * @cluster: Point to start of cluster array. + * @ncontrols: Number of controls in cluster array. + * @done: Internal flag: set for each processed control. + * @is_new: Set when the user specified a new value for this control. It + * is also set when called from v4l2_ctrl_handler_setup. Drivers + * should never set this flag. + * @has_changed: Set when the current value differs from the new value. Drivers + * should never use this flag. + * @is_private: If set, then this control is private to its handler and it + * will not be added to any other handlers. Drivers can set + * this flag. + * @is_auto: If set, then this control selects whether the other cluster + * members are in 'automatic' mode or 'manual' mode. This is + * used for autogain/gain type clusters. Drivers should never + * set this flag directly. + * @is_int: If set, then this control has a simple integer value (i.e. it + * uses ctrl->val). + * @is_string: If set, then this control has type V4L2_CTRL_TYPE_STRING. + * @is_ptr: If set, then this control is an array and/or has type >= V4L2_CTRL_COMPOUND_TYPES + * and/or has type V4L2_CTRL_TYPE_STRING. In other words, struct + * v4l2_ext_control uses field p to point to the data. + * @is_array: If set, then this control contains an N-dimensional array. + * @has_volatiles: If set, then one or more members of the cluster are volatile. + * Drivers should never touch this flag. + * @call_notify: If set, then call the handler's notify function whenever the + * control's value changes. + * @manual_mode_value: If the is_auto flag is set, then this is the value + * of the auto control that determines if that control is in + * manual mode. So if the value of the auto control equals this + * value, then the whole cluster is in manual mode. Drivers should + * never set this flag directly. + * @ops: The control ops. + * @type_ops: The control type ops. + * @id: The control ID. + * @name: The control name. + * @type: The control type. + * @minimum: The control's minimum value. + * @maximum: The control's maximum value. + * @default_value: The control's default value. + * @step: The control's step value for non-menu controls. + * @elems: The number of elements in the N-dimensional array. + * @elem_size: The size in bytes of the control. + * @dims: The size of each dimension. + * @nr_of_dims:The number of dimensions in @dims. + * @menu_skip_mask: The control's skip mask for menu controls. This makes it + * easy to skip menu items that are not valid. If bit X is set, + * then menu item X is skipped. Of course, this only works for + * menus with <= 32 menu items. There are no menus that come + * close to that number, so this is OK. Should we ever need more, + * then this will have to be extended to a u64 or a bit array. + * @qmenu: A const char * array for all menu items. Array entries that are + * empty strings ("") correspond to non-existing menu items (this + * is in addition to the menu_skip_mask above). The last entry + * must be NULL. + * @flags: The control's flags. + * @cur: The control's current value. + * @val: The control's new s32 value. + * @val64: The control's new s64 value. + * @priv: The control's private pointer. For use by the driver. It is + * untouched by the control framework. Note that this pointer is + * not freed when the control is deleted. Should this be needed + * then a new internal bitfield can be added to tell the framework + * to free this pointer. + */ struct v4l2_ctrl { /* Administrative fields */ struct list_head node; @@ -210,16 +216,17 @@ struct v4l2_ctrl { union v4l2_ctrl_ptr p_cur; }; -/** struct v4l2_ctrl_ref - The control reference. - * @node: List node for the sorted list. - * @next: Single-link list node for the hash. - * @ctrl: The actual control information. - * @helper: Pointer to helper struct. Used internally in prepare_ext_ctrls(). - * - * Each control handler has a list of these refs. The list_head is used to - * keep a sorted-by-control-ID list of all controls, while the next pointer - * is used to link the control in the hash's bucket. - */ +/** + * struct v4l2_ctrl_ref - The control reference. + * @node: List node for the sorted list. + * @next: Single-link list node for the hash. + * @ctrl: The actual control information. + * @helper: Pointer to helper struct. Used internally in prepare_ext_ctrls(). + * + * Each control handler has a list of these refs. The list_head is used to + * keep a sorted-by-control-ID list of all controls, while the next pointer + * is used to link the control in the hash's bucket. + */ struct v4l2_ctrl_ref { struct list_head node; struct v4l2_ctrl_ref *next; @@ -227,25 +234,26 @@ struct v4l2_ctrl_ref { struct v4l2_ctrl_helper *helper; }; -/** struct v4l2_ctrl_handler - The control handler keeps track of all the - * controls: both the controls owned by the handler and those inherited - * from other handlers. - * @_lock: Default for "lock". - * @lock: Lock to control access to this handler and its controls. - * May be replaced by the user right after init. - * @ctrls: The list of controls owned by this handler. - * @ctrl_refs: The list of control references. - * @cached: The last found control reference. It is common that the same - * control is needed multiple times, so this is a simple - * optimization. - * @buckets: Buckets for the hashing. Allows for quick control lookup. - * @notify: A notify callback that is called whenever the control changes value. - * Note that the handler's lock is held when the notify function - * is called! - * @notify_priv: Passed as argument to the v4l2_ctrl notify callback. - * @nr_of_buckets: Total number of buckets in the array. - * @error: The error code of the first failed control addition. - */ +/** + * struct v4l2_ctrl_handler - The control handler keeps track of all the + * controls: both the controls owned by the handler and those inherited + * from other handlers. + * @_lock: Default for "lock". + * @lock: Lock to control access to this handler and its controls. + * May be replaced by the user right after init. + * @ctrls: The list of controls owned by this handler. + * @ctrl_refs: The list of control references. + * @cached: The last found control reference. It is common that the same + * control is needed multiple times, so this is a simple + * optimization. + * @buckets: Buckets for the hashing. Allows for quick control lookup. + * @notify: A notify callback that is called whenever the control changes value. + * Note that the handler's lock is held when the notify function + * is called! + * @notify_priv: Passed as argument to the v4l2_ctrl notify callback. + * @nr_of_buckets: Total number of buckets in the array. + * @error: The error code of the first failed control addition. + */ struct v4l2_ctrl_handler { struct mutex _lock; struct mutex *lock; @@ -259,32 +267,33 @@ struct v4l2_ctrl_handler { int error; }; -/** struct v4l2_ctrl_config - Control configuration structure. - * @ops: The control ops. - * @type_ops: The control type ops. Only needed for compound controls. - * @id: The control ID. - * @name: The control name. - * @type: The control type. - * @min: The control's minimum value. - * @max: The control's maximum value. - * @step: The control's step value for non-menu controls. - * @def: The control's default value. - * @dims: The size of each dimension. - * @elem_size: The size in bytes of the control. - * @flags: The control's flags. - * @menu_skip_mask: The control's skip mask for menu controls. This makes it - * easy to skip menu items that are not valid. If bit X is set, - * then menu item X is skipped. Of course, this only works for - * menus with <= 64 menu items. There are no menus that come - * close to that number, so this is OK. Should we ever need more, - * then this will have to be extended to a bit array. - * @qmenu: A const char * array for all menu items. Array entries that are - * empty strings ("") correspond to non-existing menu items (this - * is in addition to the menu_skip_mask above). The last entry - * must be NULL. - * @is_private: If set, then this control is private to its handler and it - * will not be added to any other handlers. - */ +/** + * struct v4l2_ctrl_config - Control configuration structure. + * @ops: The control ops. + * @type_ops: The control type ops. Only needed for compound controls. + * @id: The control ID. + * @name: The control name. + * @type: The control type. + * @min: The control's minimum value. + * @max: The control's maximum value. + * @step: The control's step value for non-menu controls. + * @def: The control's default value. + * @dims: The size of each dimension. + * @elem_size: The size in bytes of the control. + * @flags: The control's flags. + * @menu_skip_mask: The control's skip mask for menu controls. This makes it + * easy to skip menu items that are not valid. If bit X is set, + * then menu item X is skipped. Of course, this only works for + * menus with <= 64 menu items. There are no menus that come + * close to that number, so this is OK. Should we ever need more, + * then this will have to be extended to a bit array. + * @qmenu: A const char * array for all menu items. Array entries that are + * empty strings ("") correspond to non-existing menu items (this + * is in addition to the menu_skip_mask above). The last entry + * must be NULL. + * @is_private: If set, then this control is private to its handler and it + * will not be added to any other handlers. + */ struct v4l2_ctrl_config { const struct v4l2_ctrl_ops *ops; const struct v4l2_ctrl_type_ops *type_ops; @@ -304,42 +313,44 @@ struct v4l2_ctrl_config { unsigned int is_private:1; }; -/** v4l2_ctrl_fill() - Fill in the control fields based on the control ID. - * - * This works for all standard V4L2 controls. - * For non-standard controls it will only fill in the given arguments - * and @name will be NULL. - * - * This function will overwrite the contents of @name, @type and @flags. - * The contents of @min, @max, @step and @def may be modified depending on - * the type. - * - * Do not use in drivers! It is used internally for backwards compatibility - * control handling only. Once all drivers are converted to use the new - * control framework this function will no longer be exported. - */ +/** + * v4l2_ctrl_fill() - Fill in the control fields based on the control ID. + * + * This works for all standard V4L2 controls. + * For non-standard controls it will only fill in the given arguments + * and @name will be NULL. + * + * This function will overwrite the contents of @name, @type and @flags. + * The contents of @min, @max, @step and @def may be modified depending on + * the type. + * + * Do not use in drivers! It is used internally for backwards compatibility + * control handling only. Once all drivers are converted to use the new + * control framework this function will no longer be exported. + */ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type, s64 *min, s64 *max, u64 *step, s64 *def, u32 *flags); -/** v4l2_ctrl_handler_init_class() - Initialize the control handler. - * @hdl: The control handler. - * @nr_of_controls_hint: A hint of how many controls this handler is - * expected to refer to. This is the total number, so including - * any inherited controls. It doesn't have to be precise, but if - * it is way off, then you either waste memory (too many buckets - * are allocated) or the control lookup becomes slower (not enough - * buckets are allocated, so there are more slow list lookups). - * It will always work, though. - * @key: Used by the lock validator if CONFIG_LOCKDEP is set. - * @name: Used by the lock validator if CONFIG_LOCKDEP is set. - * - * Returns an error if the buckets could not be allocated. This error will - * also be stored in @hdl->error. - * - * Never use this call directly, always use the v4l2_ctrl_handler_init - * macro that hides the @key and @name arguments. - */ +/** + * v4l2_ctrl_handler_init_class() - Initialize the control handler. + * @hdl: The control handler. + * @nr_of_controls_hint: A hint of how many controls this handler is + * expected to refer to. This is the total number, so including + * any inherited controls. It doesn't have to be precise, but if + * it is way off, then you either waste memory (too many buckets + * are allocated) or the control lookup becomes slower (not enough + * buckets are allocated, so there are more slow list lookups). + * It will always work, though. + * @key: Used by the lock validator if CONFIG_LOCKDEP is set. + * @name: Used by the lock validator if CONFIG_LOCKDEP is set. + * + * Returns an error if the buckets could not be allocated. This error will + * also be stored in @hdl->error. + * + * Never use this call directly, always use the v4l2_ctrl_handler_init + * macro that hides the @key and @name arguments. + */ int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl, unsigned nr_of_controls_hint, struct lock_class_key *key, const char *name); @@ -361,289 +372,326 @@ int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl, v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint, NULL, NULL) #endif -/** v4l2_ctrl_handler_free() - Free all controls owned by the handler and free - * the control list. - * @hdl: The control handler. - * - * Does nothing if @hdl == NULL. - */ +/** + * v4l2_ctrl_handler_free() - Free all controls owned by the handler and free + * the control list. + * @hdl: The control handler. + * + * Does nothing if @hdl == NULL. + */ void v4l2_ctrl_handler_free(struct v4l2_ctrl_handler *hdl); -/** v4l2_ctrl_lock() - Helper function to lock the handler - * associated with the control. - * @ctrl: The control to lock. - */ +/** + * v4l2_ctrl_lock() - Helper function to lock the handler + * associated with the control. + * @ctrl: The control to lock. + */ static inline void v4l2_ctrl_lock(struct v4l2_ctrl *ctrl) { mutex_lock(ctrl->handler->lock); } -/** v4l2_ctrl_unlock() - Helper function to unlock the handler - * associated with the control. - * @ctrl: The control to unlock. - */ +/** + * v4l2_ctrl_unlock() - Helper function to unlock the handler + * associated with the control. + * @ctrl: The control to unlock. + */ static inline void v4l2_ctrl_unlock(struct v4l2_ctrl *ctrl) { mutex_unlock(ctrl->handler->lock); } -/** v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging - * to the handler to initialize the hardware to the current control values. - * @hdl: The control handler. - * - * Button controls will be skipped, as are read-only controls. - * - * If @hdl == NULL, then this just returns 0. - */ +/** + * v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging + * to the handler to initialize the hardware to the current control values. + * @hdl: The control handler. + * + * Button controls will be skipped, as are read-only controls. + * + * If @hdl == NULL, then this just returns 0. + */ int v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl); -/** v4l2_ctrl_handler_log_status() - Log all controls owned by the handler. - * @hdl: The control handler. - * @prefix: The prefix to use when logging the control values. If the - * prefix does not end with a space, then ": " will be added - * after the prefix. If @prefix == NULL, then no prefix will be - * used. - * - * For use with VIDIOC_LOG_STATUS. - * - * Does nothing if @hdl == NULL. - */ +/** + * v4l2_ctrl_handler_log_status() - Log all controls owned by the handler. + * @hdl: The control handler. + * @prefix: The prefix to use when logging the control values. If the + * prefix does not end with a space, then ": " will be added + * after the prefix. If @prefix == NULL, then no prefix will be + * used. + * + * For use with VIDIOC_LOG_STATUS. + * + * Does nothing if @hdl == NULL. + */ void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl, const char *prefix); -/** v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2 - * control. - * @hdl: The control handler. - * @cfg: The control's configuration data. - * @priv: The control's driver-specific private data. - * - * If the &v4l2_ctrl struct could not be allocated then NULL is returned - * and @hdl->error is set to the error code (if it wasn't set already). - */ +/** + * v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2 + * control. + * @hdl: The control handler. + * @cfg: The control's configuration data. + * @priv: The control's driver-specific private data. + * + * If the &v4l2_ctrl struct could not be allocated then NULL is returned + * and @hdl->error is set to the error code (if it wasn't set already). + */ struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_config *cfg, void *priv); -/** v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu control. - * @hdl: The control handler. - * @ops: The control ops. - * @id: The control ID. - * @min: The control's minimum value. - * @max: The control's maximum value. - * @step: The control's step value - * @def: The control's default value. - * - * If the &v4l2_ctrl struct could not be allocated, or the control - * ID is not known, then NULL is returned and @hdl->error is set to the - * appropriate error code (if it wasn't set already). - * - * If @id refers to a menu control, then this function will return NULL. - * - * Use v4l2_ctrl_new_std_menu() when adding menu controls. - */ +/** + * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu control. + * @hdl: The control handler. + * @ops: The control ops. + * @id: The control ID. + * @min: The control's minimum value. + * @max: The control's maximum value. + * @step: The control's step value + * @def: The control's default value. + * + * If the &v4l2_ctrl struct could not be allocated, or the control + * ID is not known, then NULL is returned and @hdl->error is set to the + * appropriate error code (if it wasn't set already). + * + * If @id refers to a menu control, then this function will return NULL. + * + * Use v4l2_ctrl_new_std_menu() when adding menu controls. + */ struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, u32 id, s64 min, s64 max, u64 step, s64 def); -/** v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2 menu control. - * @hdl: The control handler. - * @ops: The control ops. - * @id: The control ID. - * @max: The control's maximum value. - * @mask: The control's skip mask for menu controls. This makes it - * easy to skip menu items that are not valid. If bit X is set, - * then menu item X is skipped. Of course, this only works for - * menus with <= 64 menu items. There are no menus that come - * close to that number, so this is OK. Should we ever need more, - * then this will have to be extended to a bit array. - * @def: The control's default value. - * - * Same as v4l2_ctrl_new_std(), but @min is set to 0 and the @mask value - * determines which menu items are to be skipped. - * - * If @id refers to a non-menu control, then this function will return NULL. - */ +/** + * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2 menu control. + * @hdl: The control handler. + * @ops: The control ops. + * @id: The control ID. + * @max: The control's maximum value. + * @mask: The control's skip mask for menu controls. This makes it + * easy to skip menu items that are not valid. If bit X is set, + * then menu item X is skipped. Of course, this only works for + * menus with <= 64 menu items. There are no menus that come + * close to that number, so this is OK. Should we ever need more, + * then this will have to be extended to a bit array. + * @def: The control's default value. + * + * Same as v4l2_ctrl_new_std(), but @min is set to 0 and the @mask value + * determines which menu items are to be skipped. + * + * If @id refers to a non-menu control, then this function will return NULL. + */ struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, u32 id, u8 max, u64 mask, u8 def); -/** v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control - * with driver specific menu. - * @hdl: The control handler. - * @ops: The control ops. - * @id: The control ID. - * @max: The control's maximum value. - * @mask: The control's skip mask for menu controls. This makes it - * easy to skip menu items that are not valid. If bit X is set, - * then menu item X is skipped. Of course, this only works for - * menus with <= 64 menu items. There are no menus that come - * close to that number, so this is OK. Should we ever need more, - * then this will have to be extended to a bit array. - * @def: The control's default value. - * @qmenu: The new menu. - * - * Same as v4l2_ctrl_new_std_menu(), but @qmenu will be the driver specific - * menu of this control. - * - */ +/** + * v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control + * with driver specific menu. + * @hdl: The control handler. + * @ops: The control ops. + * @id: The control ID. + * @max: The control's maximum value. + * @mask: The control's skip mask for menu controls. This makes it + * easy to skip menu items that are not valid. If bit X is set, + * then menu item X is skipped. Of course, this only works for + * menus with <= 64 menu items. There are no menus that come + * close to that number, so this is OK. Should we ever need more, + * then this will have to be extended to a bit array. + * @def: The control's default value. + * @qmenu: The new menu. + * + * Same as v4l2_ctrl_new_std_menu(), but @qmenu will be the driver specific + * menu of this control. + * + */ struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, u32 id, u8 max, u64 mask, u8 def, const char * const *qmenu); -/** v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control. - * @hdl: The control handler. - * @ops: The control ops. - * @id: The control ID. - * @max: The control's maximum value. - * @def: The control's default value. - * @qmenu_int: The control's menu entries. - * - * Same as v4l2_ctrl_new_std_menu(), but @mask is set to 0 and it additionaly - * takes as an argument an array of integers determining the menu items. - * - * If @id refers to a non-integer-menu control, then this function will return NULL. - */ +/** + * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control. + * @hdl: The control handler. + * @ops: The control ops. + * @id: The control ID. + * @max: The control's maximum value. + * @def: The control's default value. + * @qmenu_int: The control's menu entries. + * + * Same as v4l2_ctrl_new_std_menu(), but @mask is set to 0 and it additionaly + * takes as an argument an array of integers determining the menu items. + * + * If @id refers to a non-integer-menu control, then this function will return NULL. + */ struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, u32 id, u8 max, u8 def, const s64 *qmenu_int); -/** v4l2_ctrl_add_ctrl() - Add a control from another handler to this handler. - * @hdl: The control handler. - * @ctrl: The control to add. - * - * It will return NULL if it was unable to add the control reference. - * If the control already belonged to the handler, then it will do - * nothing and just return @ctrl. - */ +/** + * v4l2_ctrl_add_ctrl() - Add a control from another handler to this handler. + * @hdl: The control handler. + * @ctrl: The control to add. + * + * It will return NULL if it was unable to add the control reference. + * If the control already belonged to the handler, then it will do + * nothing and just return @ctrl. + */ struct v4l2_ctrl *v4l2_ctrl_add_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_ctrl *ctrl); -/** v4l2_ctrl_add_handler() - Add all controls from handler @add to - * handler @hdl. - * @hdl: The control handler. - * @add: The control handler whose controls you want to add to - * the @hdl control handler. - * @filter: This function will filter which controls should be added. - * - * Does nothing if either of the two handlers is a NULL pointer. - * If @filter is NULL, then all controls are added. Otherwise only those - * controls for which @filter returns true will be added. - * In case of an error @hdl->error will be set to the error code (if it - * wasn't set already). - */ +/** + * v4l2_ctrl_add_handler() - Add all controls from handler @add to + * handler @hdl. + * @hdl: The control handler. + * @add: The control handler whose controls you want to add to + * the @hdl control handler. + * @filter: This function will filter which controls should be added. + * + * Does nothing if either of the two handlers is a NULL pointer. + * If @filter is NULL, then all controls are added. Otherwise only those + * controls for which @filter returns true will be added. + * In case of an error @hdl->error will be set to the error code (if it + * wasn't set already). + */ int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl, struct v4l2_ctrl_handler *add, bool (*filter)(const struct v4l2_ctrl *ctrl)); -/** v4l2_ctrl_radio_filter() - Standard filter for radio controls. - * @ctrl: The control that is filtered. - * - * This will return true for any controls that are valid for radio device - * nodes. Those are all of the V4L2_CID_AUDIO_* user controls and all FM - * transmitter class controls. - * - * This function is to be used with v4l2_ctrl_add_handler(). - */ +/** + * v4l2_ctrl_radio_filter() - Standard filter for radio controls. + * @ctrl: The control that is filtered. + * + * This will return true for any controls that are valid for radio device + * nodes. Those are all of the V4L2_CID_AUDIO_* user controls and all FM + * transmitter class controls. + * + * This function is to be used with v4l2_ctrl_add_handler(). + */ bool v4l2_ctrl_radio_filter(const struct v4l2_ctrl *ctrl); -/** v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging to that cluster. - * @ncontrols: The number of controls in this cluster. - * @controls: The cluster control array of size @ncontrols. - */ +/** + * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging to that cluster. + * @ncontrols: The number of controls in this cluster. + * @controls: The cluster control array of size @ncontrols. + */ void v4l2_ctrl_cluster(unsigned ncontrols, struct v4l2_ctrl **controls); -/** v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging to - * that cluster and set it up for autofoo/foo-type handling. - * @ncontrols: The number of controls in this cluster. - * @controls: The cluster control array of size @ncontrols. The first control - * must be the 'auto' control (e.g. autogain, autoexposure, etc.) - * @manual_val: The value for the first control in the cluster that equals the - * manual setting. - * @set_volatile: If true, then all controls except the first auto control will - * be volatile. - * - * Use for control groups where one control selects some automatic feature and - * the other controls are only active whenever the automatic feature is turned - * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs - * red and blue balance, etc. - * - * The behavior of such controls is as follows: - * - * When the autofoo control is set to automatic, then any manual controls - * are set to inactive and any reads will call g_volatile_ctrl (if the control - * was marked volatile). - * - * When the autofoo control is set to manual, then any manual controls will - * be marked active, and any reads will just return the current value without - * going through g_volatile_ctrl. - * - * In addition, this function will set the V4L2_CTRL_FLAG_UPDATE flag - * on the autofoo control and V4L2_CTRL_FLAG_INACTIVE on the foo control(s) - * if autofoo is in auto mode. - */ +/** + * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging to + * that cluster and set it up for autofoo/foo-type handling. + * @ncontrols: The number of controls in this cluster. + * @controls: The cluster control array of size @ncontrols. The first control + * must be the 'auto' control (e.g. autogain, autoexposure, etc.) + * @manual_val: The value for the first control in the cluster that equals the + * manual setting. + * @set_volatile: If true, then all controls except the first auto control will + * be volatile. + * + * Use for control groups where one control selects some automatic feature and + * the other controls are only active whenever the automatic feature is turned + * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs + * red and blue balance, etc. + * + * The behavior of such controls is as follows: + * + * When the autofoo control is set to automatic, then any manual controls + * are set to inactive and any reads will call g_volatile_ctrl (if the control + * was marked volatile). + * + * When the autofoo control is set to manual, then any manual controls will + * be marked active, and any reads will just return the current value without + * going through g_volatile_ctrl. + * + * In addition, this function will set the V4L2_CTRL_FLAG_UPDATE flag + * on the autofoo control and V4L2_CTRL_FLAG_INACTIVE on the foo control(s) + * if autofoo is in auto mode. + */ void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls, u8 manual_val, bool set_volatile); -/** v4l2_ctrl_find() - Find a control with the given ID. - * @hdl: The control handler. - * @id: The control ID to find. - * - * If @hdl == NULL this will return NULL as well. Will lock the handler so - * do not use from inside &v4l2_ctrl_ops. - */ +/** + * v4l2_ctrl_find() - Find a control with the given ID. + * @hdl: The control handler. + * @id: The control ID to find. + * + * If @hdl == NULL this will return NULL as well. Will lock the handler so + * do not use from inside &v4l2_ctrl_ops. + */ struct v4l2_ctrl *v4l2_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id); -/** v4l2_ctrl_activate() - Make the control active or inactive. - * @ctrl: The control to (de)activate. - * @active: True if the control should become active. - * - * This sets or clears the V4L2_CTRL_FLAG_INACTIVE flag atomically. - * Does nothing if @ctrl == NULL. - * This will usually be called from within the s_ctrl op. - * The V4L2_EVENT_CTRL event will be generated afterwards. - * - * This function assumes that the control handler is locked. - */ +/** + * v4l2_ctrl_activate() - Make the control active or inactive. + * @ctrl: The control to (de)activate. + * @active: True if the control should become active. + * + * This sets or clears the V4L2_CTRL_FLAG_INACTIVE flag atomically. + * Does nothing if @ctrl == NULL. + * This will usually be called from within the s_ctrl op. + * The V4L2_EVENT_CTRL event will be generated afterwards. + * + * This function assumes that the control handler is locked. + */ void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active); -/** v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed. - * @ctrl: The control to (de)activate. - * @grabbed: True if the control should become grabbed. - * - * This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically. - * Does nothing if @ctrl == NULL. - * The V4L2_EVENT_CTRL event will be generated afterwards. - * This will usually be called when starting or stopping streaming in the - * driver. - * - * This function assumes that the control handler is not locked and will - * take the lock itself. - */ +/** + * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed. + * @ctrl: The control to (de)activate. + * @grabbed: True if the control should become grabbed. + * + * This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically. + * Does nothing if @ctrl == NULL. + * The V4L2_EVENT_CTRL event will be generated afterwards. + * This will usually be called when starting or stopping streaming in the + * driver. + * + * This function assumes that the control handler is not locked and will + * take the lock itself. + */ void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed); -/** __v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range() */ +/** + *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range() + * + * @ctrl: The control to update. + * @min: The control's minimum value. + * @max: The control's maximum value. + * @step: The control's step value + * @def: The control's default value. + * + * Update the range of a control on the fly. This works for control types + * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the + * @step value is interpreted as a menu_skip_mask. + * + * An error is returned if one of the range arguments is invalid for this + * control type. + * + * This function assumes that the control handler is not locked and will + * take the lock itself. + */ int __v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl, s64 min, s64 max, u64 step, s64 def); -/** v4l2_ctrl_modify_range() - Update the range of a control. - * @ctrl: The control to update. - * @min: The control's minimum value. - * @max: The control's maximum value. - * @step: The control's step value - * @def: The control's default value. - * - * Update the range of a control on the fly. This works for control types - * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the - * @step value is interpreted as a menu_skip_mask. - * - * An error is returned if one of the range arguments is invalid for this - * control type. - * - * This function assumes that the control handler is not locked and will - * take the lock itself. - */ +/** + * v4l2_ctrl_modify_range() - Update the range of a control. + * @ctrl: The control to update. + * @min: The control's minimum value. + * @max: The control's maximum value. + * @step: The control's step value + * @def: The control's default value. + * + * Update the range of a control on the fly. This works for control types + * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the + * @step value is interpreted as a menu_skip_mask. + * + * An error is returned if one of the range arguments is invalid for this + * control type. + * + * This function assumes that the control handler is not locked and will + * take the lock itself. + */ static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl, s64 min, s64 max, u64 step, s64 def) { @@ -656,21 +704,23 @@ static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl, return rval; } -/** v4l2_ctrl_notify() - Function to set a notify callback for a control. - * @ctrl: The control. - * @notify: The callback function. - * @priv: The callback private handle, passed as argument to the callback. - * - * This function sets a callback function for the control. If @ctrl is NULL, - * then it will do nothing. If @notify is NULL, then the notify callback will - * be removed. - * - * There can be only one notify. If another already exists, then a WARN_ON - * will be issued and the function will do nothing. - */ +/** + * v4l2_ctrl_notify() - Function to set a notify callback for a control. + * @ctrl: The control. + * @notify: The callback function. + * @priv: The callback private handle, passed as argument to the callback. + * + * This function sets a callback function for the control. If @ctrl is NULL, + * then it will do nothing. If @notify is NULL, then the notify callback will + * be removed. + * + * There can be only one notify. If another already exists, then a WARN_ON + * will be issued and the function will do nothing. + */ void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify, void *priv); -/** v4l2_ctrl_get_name() - Get the name of the control +/** + * v4l2_ctrl_get_name() - Get the name of the control * @id: The control ID. * * This function returns the name of the given control ID or NULL if it isn't @@ -678,7 +728,8 @@ void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify, void */ const char *v4l2_ctrl_get_name(u32 id); -/** v4l2_ctrl_get_menu() - Get the menu string array of the control +/** + * v4l2_ctrl_get_menu() - Get the menu string array of the control * @id: The control ID. * * This function returns the NULL-terminated menu string array name of the @@ -686,7 +737,8 @@ const char *v4l2_ctrl_get_name(u32 id); */ const char * const *v4l2_ctrl_get_menu(u32 id); -/** v4l2_ctrl_get_int_menu() - Get the integer menu array of the control +/** + * v4l2_ctrl_get_int_menu() - Get the integer menu array of the control * @id: The control ID. * @len: The size of the integer array. * @@ -695,29 +747,41 @@ const char * const *v4l2_ctrl_get_menu(u32 id); */ const s64 *v4l2_ctrl_get_int_menu(u32 id, u32 *len); -/** v4l2_ctrl_g_ctrl() - Helper function to get the control's value from within a driver. - * @ctrl: The control. - * - * This returns the control's value safely by going through the control - * framework. This function will lock the control's handler, so it cannot be - * used from within the &v4l2_ctrl_ops functions. - * - * This function is for integer type controls only. - */ +/** + * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from within a driver. + * @ctrl: The control. + * + * This returns the control's value safely by going through the control + * framework. This function will lock the control's handler, so it cannot be + * used from within the &v4l2_ctrl_ops functions. + * + * This function is for integer type controls only. + */ s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl); -/** __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl(). */ +/** + * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl(). + * @ctrl: The control. + * @val: The new value. + * + * This set the control's new value safely by going through the control + * framework. This function will lock the control's handler, so it cannot be + * used from within the &v4l2_ctrl_ops functions. + * + * This function is for integer type controls only. + */ int __v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val); + /** v4l2_ctrl_s_ctrl() - Helper function to set the control's value from within a driver. - * @ctrl: The control. - * @val: The new value. - * - * This set the control's new value safely by going through the control - * framework. This function will lock the control's handler, so it cannot be - * used from within the &v4l2_ctrl_ops functions. - * - * This function is for integer type controls only. - */ + * @ctrl: The control. + * @val: The new value. + * + * This set the control's new value safely by going through the control + * framework. This function will lock the control's handler, so it cannot be + * used from within the &v4l2_ctrl_ops functions. + * + * This function is for integer type controls only. + */ static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val) { int rval; @@ -729,30 +793,45 @@ static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val) return rval; } -/** v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value from within a driver. - * @ctrl: The control. - * - * This returns the control's value safely by going through the control - * framework. This function will lock the control's handler, so it cannot be - * used from within the &v4l2_ctrl_ops functions. - * - * This function is for 64-bit integer type controls only. - */ +/** + * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value + * from within a driver. + * @ctrl: The control. + * + * This returns the control's value safely by going through the control + * framework. This function will lock the control's handler, so it cannot be + * used from within the &v4l2_ctrl_ops functions. + * + * This function is for 64-bit integer type controls only. + */ s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl); -/** __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64(). */ +/** + * __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64(). + * + * @ctrl: The control. + * @val: The new value. + * + * This set the control's new value safely by going through the control + * framework. This function will lock the control's handler, so it cannot be + * used from within the &v4l2_ctrl_ops functions. + * + * This function is for 64-bit integer type controls only. + */ int __v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val); -/** v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value from within a driver. - * @ctrl: The control. - * @val: The new value. - * - * This set the control's new value safely by going through the control - * framework. This function will lock the control's handler, so it cannot be - * used from within the &v4l2_ctrl_ops functions. - * - * This function is for 64-bit integer type controls only. - */ +/** v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value + * from within a driver. + * + * @ctrl: The control. + * @val: The new value. + * + * This set the control's new value safely by going through the control + * framework. This function will lock the control's handler, so it cannot be + * used from within the &v4l2_ctrl_ops functions. + * + * This function is for 64-bit integer type controls only. + */ static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val) { int rval; @@ -764,19 +843,31 @@ static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val) return rval; } -/** __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string(). */ +/** __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string(). + * + * @ctrl: The control. + * @s: The new string. + * + * This set the control's new string safely by going through the control + * framework. This function will lock the control's handler, so it cannot be + * used from within the &v4l2_ctrl_ops functions. + * + * This function is for string type controls only. + */ int __v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s); -/** v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value from within a driver. - * @ctrl: The control. - * @s: The new string. - * - * This set the control's new string safely by going through the control - * framework. This function will lock the control's handler, so it cannot be - * used from within the &v4l2_ctrl_ops functions. - * - * This function is for string type controls only. - */ +/** v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value + * from within a driver. + * + * @ctrl: The control. + * @s: The new string. + * + * This set the control's new string safely by going through the control + * framework. This function will lock the control's handler, so it cannot be + * used from within the &v4l2_ctrl_ops functions. + * + * This function is for string type controls only. + */ static inline int v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s) { int rval; -- cgit v1.2.3-58-ga151 From b6fce850d9fa46eefdaa7ef28ac1f3fce7c803d2 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 22 Aug 2015 08:28:39 -0300 Subject: [media] v4l2-event.h: fix comments and add to DocBook The comments there are good enough for DocBook, however they're using a wrong format. Fix and add to device-drivers.xml. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet --- Documentation/DocBook/device-drivers.tmpl | 2 +- include/media/v4l2-event.h | 47 ++++++++++++++++--------------- 2 files changed, 26 insertions(+), 23 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 5f01f7ad15dc..46e6818b95ce 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -232,9 +232,9 @@ X!Isound/sound_firmware.c !Idrivers/media/dvb-core/dvb_math.h !Idrivers/media/dvb-core/dvb_ringbuffer.h !Iinclude/media/v4l2-ctrls.h +!Iinclude/media/v4l2-event.h diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h index 22a44c2f5963..4f7f7aed9157 100644 --- a/include/media/videobuf2-core.h +++ b/include/media/videobuf2-core.h @@ -362,7 +362,9 @@ struct v4l2_fh; * start_streaming() can be called. Used when a DMA engine * cannot be started unless at least this number of buffers * have been queued into the driver. - * + */ +/* + * Private elements (won't appear at the DocBook): * @mmap_lock: private mutex used when buffers are allocated/freed/mmapped * @memory: current memory type used * @bufs: videobuf buffer structures @@ -405,7 +407,7 @@ struct vb2_queue { gfp_t gfp_flags; u32 min_buffers_needed; -/* private: internal use only */ + /* private: internal use only */ struct mutex mmap_lock; enum v4l2_memory memory; struct vb2_buffer *bufs[VIDEO_MAX_FRAME]; @@ -482,7 +484,8 @@ size_t vb2_read(struct vb2_queue *q, char __user *data, size_t count, loff_t *ppos, int nonblock); size_t vb2_write(struct vb2_queue *q, const char __user *data, size_t count, loff_t *ppos, int nonblock); -/** + +/* * vb2_thread_fnc - callback function for use with vb2_thread * * This is called whenever a buffer is dequeued in the thread. @@ -575,7 +578,6 @@ static inline void vb2_set_plane_payload(struct vb2_buffer *vb, * vb2_get_plane_payload() - get bytesused for the plane plane_no * @vb: buffer for which plane payload should be set * @plane_no: plane number for which payload should be set - * @size: payload in bytes */ static inline unsigned long vb2_get_plane_payload(struct vb2_buffer *vb, unsigned int plane_no) -- cgit v1.2.3-58-ga151 From b6836a6fbc4b7e35679bf7bb8b54bad294ae0b10 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 22 Aug 2015 09:01:58 -0300 Subject: [media] videobuf2-memops.h: add to device-drivers DocBook The comment metadata was wrong: Warning(.//include/media/videobuf2-memops.h:25): cannot understand function prototype: 'struct vb2_vmarea_handler ' Warning(.//include/media/videobuf2-memops.h): no structured comments found Fix and add to DocBook. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet --- Documentation/DocBook/device-drivers.tmpl | 2 +- include/media/videobuf2-memops.h | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index e636bbd41933..8d1e04c94dce 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -235,9 +235,9 @@ X!Isound/sound_firmware.c !Iinclude/media/v4l2-event.h !Iinclude/media/v4l2-dv-timings.h !Iinclude/media/videobuf2-core.h +!Iinclude/media/videobuf2-memops.h diff --git a/include/media/videobuf2-memops.h b/include/media/videobuf2-memops.h index f05444ca8c0c..9f36641a6781 100644 --- a/include/media/videobuf2-memops.h +++ b/include/media/videobuf2-memops.h @@ -17,7 +17,8 @@ #include /** - * vb2_vmarea_handler - common vma refcount tracking handler + * struct vb2_vmarea_handler - common vma refcount tracking handler + * * @refcount: pointer to refcount entry in the buffer * @put: callback to function that decreases buffer refcount * @arg: argument for @put callback -- cgit v1.2.3-58-ga151 From 98d00bd7a2477ffce8010458938425095345f470 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 22 Aug 2015 09:04:46 -0300 Subject: [media] v4l2-mediabus: Add to DocBook Fix the format of the comments and add to DocBook. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet --- Documentation/DocBook/device-drivers.tmpl | 4 +--- include/media/v4l2-mediabus.h | 4 ++-- 2 files changed, 3 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 8d1e04c94dce..53a7c5d8b996 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -236,9 +236,7 @@ X!Isound/sound_firmware.c !Iinclude/media/v4l2-dv-timings.h !Iinclude/media/videobuf2-core.h !Iinclude/media/videobuf2-memops.h - +!Iinclude/media/v4l2-mediabus.h diff --git a/include/media/v4l2-mediabus.h b/include/media/v4l2-mediabus.h index 73069e4c2796..34cc99e093ef 100644 --- a/include/media/v4l2-mediabus.h +++ b/include/media/v4l2-mediabus.h @@ -65,7 +65,7 @@ V4L2_MBUS_CSI2_CHANNEL_2 | V4L2_MBUS_CSI2_CHANNEL_3) /** - * v4l2_mbus_type - media bus type + * enum v4l2_mbus_type - media bus type * @V4L2_MBUS_PARALLEL: parallel interface with hsync and vsync * @V4L2_MBUS_BT656: parallel interface with embedded synchronisation, can * also be used for BT.1120 @@ -78,7 +78,7 @@ enum v4l2_mbus_type { }; /** - * v4l2_mbus_config - media bus configuration + * struct v4l2_mbus_config - media bus configuration * @type: in: interface type * @flags: in / out: configuration flags, depending on @type */ -- cgit v1.2.3-58-ga151 From 04ffb9c126d6d887b08b68bbe0c0842ec9def78d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 22 Aug 2015 09:22:25 -0300 Subject: [media] DocBook: Better organize media devices Instead of putting all media devices on a flat structure, split them on 4 types, just like we do with the userspace API: Video2Linux devices Digital TV (DVB) devices Remote Controller devices Media Controller devices Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet --- Documentation/DocBook/device-drivers.tmpl | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 53a7c5d8b996..5c9375b98303 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -218,25 +218,34 @@ X!Isound/sound_firmware.c Media Devices -!Iinclude/media/media-device.h -!Iinclude/media/media-devnode.h -!Iinclude/media/media-entity.h + + Video2Linux devices !Iinclude/media/v4l2-async.h +!Iinclude/media/v4l2-ctrls.h +!Iinclude/media/v4l2-dv-timings.h +!Iinclude/media/v4l2-event.h !Iinclude/media/v4l2-flash-led-class.h +!Iinclude/media/v4l2-mediabus.h !Iinclude/media/v4l2-mem2mem.h !Iinclude/media/v4l2-of.h !Iinclude/media/v4l2-subdev.h -!Iinclude/media/rc-core.h +!Iinclude/media/videobuf2-core.h +!Iinclude/media/videobuf2-memops.h + + Digital TV (DVB) devices !Idrivers/media/dvb-core/dvb_ca_en50221.h !Idrivers/media/dvb-core/dvb_frontend.h !Idrivers/media/dvb-core/dvb_math.h !Idrivers/media/dvb-core/dvb_ringbuffer.h -!Iinclude/media/v4l2-ctrls.h -!Iinclude/media/v4l2-event.h -!Iinclude/media/v4l2-dv-timings.h -!Iinclude/media/videobuf2-core.h -!Iinclude/media/videobuf2-memops.h -!Iinclude/media/v4l2-mediabus.h + + Remote Controller devices +!Iinclude/media/rc-core.h + + Media Controller devices +!Iinclude/media/media-device.h +!Iinclude/media/media-devnode.h +!Iinclude/media/media-entity.h + -- cgit v1.2.3-58-ga151 From d071c833a0d30e7aae0ea565d92ef83c79106d6f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 22 Aug 2015 19:39:38 -0300 Subject: [media] dvbdev: document most of the functions/data structs Document the most relevant functions and data structs for developers that are working with the DVB subsystem. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Corbet --- Documentation/DocBook/device-drivers.tmpl | 1 + drivers/media/dvb-core/dvbdev.h | 116 +++++++++++++++++++++++++----- 2 files changed, 100 insertions(+), 17 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 5c9375b98303..93b74884ae24 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -237,6 +237,7 @@ X!Isound/sound_firmware.c !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 !Iinclude/media/rc-core.h diff --git a/drivers/media/dvb-core/dvbdev.h b/drivers/media/dvb-core/dvbdev.h index 12629b8ecb0c..c61a4f03a66f 100644 --- a/drivers/media/dvb-core/dvbdev.h +++ b/drivers/media/dvb-core/dvbdev.h @@ -57,6 +57,25 @@ struct dvb_frontend; +/** + * struct dvb_adapter - represents a Digital TV adapter using Linux DVB API + * + * @num: Number of the adapter + * @list_head: List with the DVB adapters + * @device_list: List with the DVB devices + * @name: Name of the adapter + * @proposed_mac: proposed MAC address for the adapter + * @priv: private data + * @device: pointer to struct device + * @module: pointer to struct module + * @mfe_shared: mfe shared: indicates mutually exclusive frontends + * Thie usage of this flag is currently deprecated + * @mfe_dvbdev: Frontend device in use, in the case of MFE + * @mfe_lock: Lock to prevent using the other frontends when MFE is + * used. + * @mdev: pointer to struct media_device, used when the media + * controller is used. + */ struct dvb_adapter { int num; struct list_head list_head; @@ -78,7 +97,34 @@ struct dvb_adapter { #endif }; - +/** + * struct dvb_device - represents a DVB device node + * + * @list_head: List head with all DVB devices + * @fops: pointer to struct file_operations + * @adapter: pointer to the adapter that holds this device node + * @type: type of the device: DVB_DEVICE_SEC, DVB_DEVICE_FRONTEND, + * DVB_DEVICE_DEMUX, DVB_DEVICE_DVR, DVB_DEVICE_CA, DVB_DEVICE_NET + * @minor: devnode minor number. Major number is always DVB_MAJOR. + * @id: device ID number, inside the adapter + * @readers: Initialized by the caller. Each call to open() in Read Only mode + * decreases this counter by one. + * @writers: Initialized by the caller. Each call to open() in Read/Write + * mode decreases this counter by one. + * @users: Initialized by the caller. Each call to open() in any mode + * decreases this counter by one. + * @wait_queue: wait queue, used to wait for certain events inside one of + * the DVB API callers + * @kernel_ioctl: callback function used to handle ioctl calls from userspace. + * @name: Name to be used for the device at the Media Controller + * @entity: pointer to struct media_entity associated with the device node + * @pads: pointer to struct media_pad associated with @entity; + * @priv: private data + * + * This structure is used by the DVB core (frontend, CA, net, demux) in + * order to create the device nodes. Usually, driver should not initialize + * this struct diretly. + */ struct dvb_device { struct list_head list_head; const struct file_operations *fops; @@ -109,19 +155,55 @@ struct dvb_device { void *priv; }; +/** + * dvb_register_adapter - Registers a new DVB adapter + * + * @adap: pointer to struct dvb_adapter + * @name: Adapter's name + * @module: initialized with THIS_MODULE at the caller + * @device: pointer to struct device that corresponds to the device driver + * @adapter_nums: Array with a list of the numbers for @dvb_register_adapter; + * to select among them. Typically, initialized with: + * DVB_DEFINE_MOD_OPT_ADAPTER_NR(adapter_nums) + */ +int dvb_register_adapter(struct dvb_adapter *adap, const char *name, + struct module *module, struct device *device, + short *adapter_nums); -extern int dvb_register_adapter(struct dvb_adapter *adap, const char *name, - struct module *module, struct device *device, - short *adapter_nums); -extern int dvb_unregister_adapter (struct dvb_adapter *adap); - -extern int dvb_register_device (struct dvb_adapter *adap, - struct dvb_device **pdvbdev, - const struct dvb_device *template, - void *priv, - int type); +/** + * dvb_unregister_adapter - Unregisters a DVB adapter + * + * @adap: pointer to struct dvb_adapter + */ +int dvb_unregister_adapter(struct dvb_adapter *adap); -extern void dvb_unregister_device (struct dvb_device *dvbdev); +/** + * dvb_register_device - Registers a new DVB device + * + * @adap: pointer to struct dvb_adapter + * @pdvbdev: pointer to the place where the new struct dvb_device will be + * stored + * @template: Template used to create &pdvbdev; + * @device: pointer to struct device that corresponds to the device driver + * @adapter_nums: Array with a list of the numbers for @dvb_register_adapter; + * to select among them. Typically, initialized with: + * DVB_DEFINE_MOD_OPT_ADAPTER_NR(adapter_nums) + * @priv: private data + * @type: type of the device: DVB_DEVICE_SEC, DVB_DEVICE_FRONTEND, + * DVB_DEVICE_DEMUX, DVB_DEVICE_DVR, DVB_DEVICE_CA, DVB_DEVICE_NET + */ +int dvb_register_device(struct dvb_adapter *adap, + struct dvb_device **pdvbdev, + const struct dvb_device *template, + void *priv, + int type); + +/** + * dvb_unregister_device - Unregisters a DVB device + * + * @dvbdev: pointer to struct dvb_device + */ +void dvb_unregister_device(struct dvb_device *dvbdev); #ifdef CONFIG_MEDIA_CONTROLLER_DVB void dvb_create_media_graph(struct dvb_adapter *adap); @@ -136,17 +218,17 @@ static inline void dvb_create_media_graph(struct dvb_adapter *adap) {} #define dvb_register_media_controller(a, b) {} #endif -extern int dvb_generic_open (struct inode *inode, struct file *file); -extern int dvb_generic_release (struct inode *inode, struct file *file); -extern long dvb_generic_ioctl (struct file *file, +int dvb_generic_open (struct inode *inode, struct file *file); +int dvb_generic_release (struct inode *inode, struct file *file); +long dvb_generic_ioctl (struct file *file, unsigned int cmd, unsigned long arg); /* we don't mess with video_usercopy() any more, we simply define out own dvb_usercopy(), which will hopefully become generic_usercopy() someday... */ -extern int dvb_usercopy(struct file *file, unsigned int cmd, unsigned long arg, - int (*func)(struct file *file, unsigned int cmd, void *arg)); +int dvb_usercopy(struct file *file, unsigned int cmd, unsigned long arg, + int (*func)(struct file *file, unsigned int cmd, void *arg)); /** generic DVB attach function. */ #ifdef CONFIG_MEDIA_ATTACH -- cgit v1.2.3-58-ga151 From 062683901ad5c29ac375e6b7c7bca2737d41e11a Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Mon, 17 Aug 2015 08:20:56 -0300 Subject: [media] DocBook media: Fix typo "the the" in xml files This patch fix spelling typo "the the" found in controls.xml and vidioc-g-param.xml. These xml files are'nt generated from any source files, so I have to fix these xml files directly. Signed-off-by: Masanari Iida Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/controls.xml | 2 +- Documentation/DocBook/media/v4l/vidioc-g-parm.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 6e1667b5f3eb..33aece541880 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -3414,7 +3414,7 @@ giving priority to the center of the metered area. V4L2_EXPOSURE_METERING_MATRIX  A multi-zone metering. The light intensity is measured -in several points of the frame and the the results are combined. The +in several points of the frame and the results are combined. The algorithm of the zones selection and their significance in calculating the final value is device dependent. diff --git a/Documentation/DocBook/media/v4l/vidioc-g-parm.xml b/Documentation/DocBook/media/v4l/vidioc-g-parm.xml index f4e28e7d4751..721728745407 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-parm.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-parm.xml @@ -267,7 +267,7 @@ is intended for still imaging applications. The idea is to get the best possible image quality that the hardware can deliver. It is not defined how the driver writer may achieve that; it will depend on the hardware and the ingenuity of the driver writer. High quality mode is -a different mode from the the regular motion video capture modes. In +a different mode from the regular motion video capture modes. In high quality mode: The driver may be able to capture higher -- cgit v1.2.3-58-ga151