From b2fe22d0cf64708c50c26f11b3da8b79809c699b Mon Sep 17 00:00:00 2001 From: Nick Dyer Date: Mon, 18 Jul 2016 18:10:30 -0300 Subject: [media] v4l2-core: Add support for touch devices Some touch controllers send out touch data in a similar way to a greyscale frame grabber. Add new device type VFL_TYPE_TOUCH: - This uses a new device prefix v4l-touch for these devices, to stop generic capture software from treating them as webcams. Otherwise, touch is treated similarly to video capture. - Add V4L2_INPUT_TYPE_TOUCH - Add MEDIA_INTF_T_V4L_TOUCH - Add V4L2_CAP_TOUCH to indicate device is a touch device Add formats: - V4L2_TCH_FMT_DELTA_TD16 for signed 16-bit touch deltas - V4L2_TCH_FMT_DELTA_TD08 for signed 16-bit touch deltas - V4L2_TCH_FMT_TU16 for unsigned 16-bit touch data - V4L2_TCH_FMT_TU08 for unsigned 8-bit touch data This support will be used by: - Atmel maXTouch (atmel_mxt_ts) - Synaptics RMI4. - sur40 Signed-off-by: Nick Dyer Tested-by: Chris Healy Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab Acked-by: Dmitry Torokhov --- include/media/v4l2-dev.h | 4 +++- include/uapi/linux/media.h | 1 + include/uapi/linux/videodev2.h | 9 +++++++++ 3 files changed, 13 insertions(+), 1 deletion(-) (limited to 'include') diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h index a122b1bd40f9..5272aeec0cec 100644 --- a/include/media/v4l2-dev.h +++ b/include/media/v4l2-dev.h @@ -25,7 +25,8 @@ #define VFL_TYPE_RADIO 2 #define VFL_TYPE_SUBDEV 3 #define VFL_TYPE_SDR 4 -#define VFL_TYPE_MAX 5 +#define VFL_TYPE_TOUCH 5 +#define VFL_TYPE_MAX 6 /* Is this a receiver, transmitter or mem-to-mem? */ /* Ignored for VFL_TYPE_SUBDEV. */ @@ -294,6 +295,7 @@ struct video_device * - %VFL_TYPE_RADIO - A radio card * - %VFL_TYPE_SUBDEV - A subdevice * - %VFL_TYPE_SDR - Software Defined Radio + * - %VFL_TYPE_TOUCH - A touch sensor * * .. note:: * diff --git a/include/uapi/linux/media.h b/include/uapi/linux/media.h index 7acf0f634f70..4890787731b8 100644 --- a/include/uapi/linux/media.h +++ b/include/uapi/linux/media.h @@ -307,6 +307,7 @@ struct media_links_enum { #define MEDIA_INTF_T_V4L_RADIO (MEDIA_INTF_T_V4L_BASE + 2) #define MEDIA_INTF_T_V4L_SUBDEV (MEDIA_INTF_T_V4L_BASE + 3) #define MEDIA_INTF_T_V4L_SWRADIO (MEDIA_INTF_T_V4L_BASE + 4) +#define MEDIA_INTF_T_V4L_TOUCH (MEDIA_INTF_T_V4L_BASE + 5) #define MEDIA_INTF_T_ALSA_PCM_CAPTURE (MEDIA_INTF_T_ALSA_BASE) #define MEDIA_INTF_T_ALSA_PCM_PLAYBACK (MEDIA_INTF_T_ALSA_BASE + 1) diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h index 724f43e69d03..22bad8c741fe 100644 --- a/include/uapi/linux/videodev2.h +++ b/include/uapi/linux/videodev2.h @@ -440,6 +440,8 @@ struct v4l2_capability { #define V4L2_CAP_ASYNCIO 0x02000000 /* async I/O */ #define V4L2_CAP_STREAMING 0x04000000 /* streaming I/O ioctls */ +#define V4L2_CAP_TOUCH 0x10000000 /* Is a touch device */ + #define V4L2_CAP_DEVICE_CAPS 0x80000000 /* sets device capabilities field */ /* @@ -635,6 +637,12 @@ struct v4l2_pix_format { #define V4L2_SDR_FMT_CS14LE v4l2_fourcc('C', 'S', '1', '4') /* complex s14le */ #define V4L2_SDR_FMT_RU12LE v4l2_fourcc('R', 'U', '1', '2') /* real u12le */ +/* Touch formats - used for Touch devices */ +#define V4L2_TCH_FMT_DELTA_TD16 v4l2_fourcc('T', 'D', '1', '6') /* 16-bit signed deltas */ +#define V4L2_TCH_FMT_DELTA_TD08 v4l2_fourcc('T', 'D', '0', '8') /* 8-bit signed deltas */ +#define V4L2_TCH_FMT_TU16 v4l2_fourcc('T', 'U', '1', '6') /* 16-bit unsigned touch data */ +#define V4L2_TCH_FMT_TU08 v4l2_fourcc('T', 'U', '0', '8') /* 8-bit unsigned touch data */ + /* priv field value to indicates that subsequent fields are valid. */ #define V4L2_PIX_FMT_PRIV_MAGIC 0xfeedcafe @@ -1401,6 +1409,7 @@ struct v4l2_input { /* Values for the 'type' field */ #define V4L2_INPUT_TYPE_TUNER 1 #define V4L2_INPUT_TYPE_CAMERA 2 +#define V4L2_INPUT_TYPE_TOUCH 3 /* field 'status' - general */ #define V4L2_IN_ST_NO_POWER 0x00000001 /* Attached device is off */ -- cgit v1.2.3 From f304562ed3c97e237a77b3da57b0e43f264bd82a Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sun, 31 Jul 2016 08:12:22 -0300 Subject: [media] soc-camera/sh_mobile_csi2: remove unused driver The sh_mobile_csi2 isn't used anymore (was it ever?), so remove it. Especially since the soc-camera framework is being deprecated. Signed-off-by: Hans Verkuil Acked-by: Laurent Pinchart Cc: Guennadi Liakhovetski Signed-off-by: Mauro Carvalho Chehab --- include/media/drv-intf/sh_mobile_ceu.h | 1 - include/media/drv-intf/sh_mobile_csi2.h | 48 --------------------------------- 2 files changed, 49 deletions(-) delete mode 100644 include/media/drv-intf/sh_mobile_csi2.h (limited to 'include') diff --git a/include/media/drv-intf/sh_mobile_ceu.h b/include/media/drv-intf/sh_mobile_ceu.h index 7f57056c22ba..2f43f7d9e28d 100644 --- a/include/media/drv-intf/sh_mobile_ceu.h +++ b/include/media/drv-intf/sh_mobile_ceu.h @@ -21,7 +21,6 @@ struct sh_mobile_ceu_info { unsigned long flags; int max_width; int max_height; - struct sh_mobile_ceu_companion *csi2; struct v4l2_async_subdev **asd; /* Flat array, arranged in groups */ unsigned int *asd_sizes; /* 0-terminated array pf asd group sizes */ }; diff --git a/include/media/drv-intf/sh_mobile_csi2.h b/include/media/drv-intf/sh_mobile_csi2.h deleted file mode 100644 index 14030db51f13..000000000000 --- a/include/media/drv-intf/sh_mobile_csi2.h +++ /dev/null @@ -1,48 +0,0 @@ -/* - * Driver header for the SH-Mobile MIPI CSI-2 unit - * - * Copyright (C) 2010, Guennadi Liakhovetski - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 as - * published by the Free Software Foundation. - */ - -#ifndef SH_MIPI_CSI -#define SH_MIPI_CSI - -#include - -enum sh_csi2_phy { - SH_CSI2_PHY_MAIN, - SH_CSI2_PHY_SUB, -}; - -enum sh_csi2_type { - SH_CSI2C, - SH_CSI2I, -}; - -#define SH_CSI2_CRC (1 << 0) -#define SH_CSI2_ECC (1 << 1) - -struct platform_device; - -struct sh_csi2_client_config { - enum sh_csi2_phy phy; - unsigned char lanes; /* bitmask[3:0] */ - unsigned char channel; /* 0..3 */ - struct platform_device *pdev; /* client platform device */ - const char *name; /* async matching: client name */ -}; - -struct v4l2_device; - -struct sh_csi2_pdata { - enum sh_csi2_type type; - unsigned int flags; - struct sh_csi2_client_config *clients; - int num_clients; -}; - -#endif -- cgit v1.2.3 From 7e0739cd9c40752fc9d31cac86e3a31d5537be18 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Thu, 4 Aug 2016 05:51:12 -0300 Subject: [media] videodev2.h: fix sYCC/AdobeYCC default quantization range The default quantization range of the Y'CbCr encodings of sRGB and AdobeRGB are full range instead of limited range according to the corresponding standards. Fix this in the V4L2_MAP_QUANTIZATION_DEFAULT macro. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- include/uapi/linux/videodev2.h | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'include') diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h index 22bad8c741fe..0ec15222a6ca 100644 --- a/include/uapi/linux/videodev2.h +++ b/include/uapi/linux/videodev2.h @@ -345,8 +345,8 @@ enum v4l2_quantization { /* * The default for R'G'B' quantization is always full range, except * for the BT2020 colorspace. For Y'CbCr the quantization is always - * limited range, except for COLORSPACE_JPEG, SYCC, XV601 or XV709: - * those are full range. + * limited range, except for COLORSPACE_JPEG, SRGB, ADOBERGB, + * XV601 or XV709: those are full range. */ V4L2_QUANTIZATION_DEFAULT = 0, V4L2_QUANTIZATION_FULL_RANGE = 1, @@ -361,7 +361,8 @@ enum v4l2_quantization { #define V4L2_MAP_QUANTIZATION_DEFAULT(is_rgb, colsp, ycbcr_enc) \ (((is_rgb) && (colsp) == V4L2_COLORSPACE_BT2020) ? V4L2_QUANTIZATION_LIM_RANGE : \ (((is_rgb) || (ycbcr_enc) == V4L2_YCBCR_ENC_XV601 || \ - (ycbcr_enc) == V4L2_YCBCR_ENC_XV709 || (colsp) == V4L2_COLORSPACE_JPEG) ? \ + (ycbcr_enc) == V4L2_YCBCR_ENC_XV709 || (colsp) == V4L2_COLORSPACE_JPEG) || \ + (colsp) == V4L2_COLORSPACE_ADOBERGB || (colsp) == V4L2_COLORSPACE_SRGB ? \ V4L2_QUANTIZATION_FULL_RANGE : V4L2_QUANTIZATION_LIM_RANGE)) enum v4l2_priority { -- cgit v1.2.3 From adca8c8e251fdbdb6b28e3ef7a5ca24b597b82d8 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Thu, 4 Aug 2016 06:01:48 -0300 Subject: [media] videodev2.h: put V4L2_YCBCR_ENC_SYCC under #ifndef __KERNEL__ This define is a duplicate of V4L2_YCBCR_ENC_601. So mark it as 'should not be used' and put it under #ifndef __KERNEL__ to prevent drivers from referring to it. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- include/uapi/linux/videodev2.h | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'include') diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h index 0ec15222a6ca..5529741202b5 100644 --- a/include/uapi/linux/videodev2.h +++ b/include/uapi/linux/videodev2.h @@ -292,13 +292,11 @@ enum v4l2_ycbcr_encoding { * various colorspaces: * * V4L2_COLORSPACE_SMPTE170M, V4L2_COLORSPACE_470_SYSTEM_M, - * V4L2_COLORSPACE_470_SYSTEM_BG, V4L2_COLORSPACE_ADOBERGB and - * V4L2_COLORSPACE_JPEG: V4L2_YCBCR_ENC_601 + * V4L2_COLORSPACE_470_SYSTEM_BG, V4L2_COLORSPACE_SRGB, + * V4L2_COLORSPACE_ADOBERGB and V4L2_COLORSPACE_JPEG: V4L2_YCBCR_ENC_601 * * V4L2_COLORSPACE_REC709 and V4L2_COLORSPACE_DCI_P3: V4L2_YCBCR_ENC_709 * - * V4L2_COLORSPACE_SRGB: V4L2_YCBCR_ENC_SYCC - * * V4L2_COLORSPACE_BT2020: V4L2_YCBCR_ENC_BT2020 * * V4L2_COLORSPACE_SMPTE240M: V4L2_YCBCR_ENC_SMPTE240M @@ -317,8 +315,14 @@ enum v4l2_ycbcr_encoding { /* Rec. 709/EN 61966-2-4 Extended Gamut -- HDTV */ V4L2_YCBCR_ENC_XV709 = 4, - /* sYCC (Y'CbCr encoding of sRGB) */ +#ifndef __KERNEL__ + /* + * sYCC (Y'CbCr encoding of sRGB), identical to ENC_601. It was added + * originally due to a misunderstanding of the sYCC standard. It should + * not be used, instead use V4L2_YCBCR_ENC_601. + */ V4L2_YCBCR_ENC_SYCC = 5, +#endif /* BT.2020 Non-constant Luminance Y'CbCr */ V4L2_YCBCR_ENC_BT2020 = 6, -- cgit v1.2.3 From 10d5509c8d50a2c2f761a08a616530dced35e2d8 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 14 Dec 2015 08:25:32 -0200 Subject: [media] v4l2: remove g/s_crop from video ops Replace all calls to g/s_crop by calls to the get/set_selection pad ops. Remove the old g/s_crop video ops since they are now no longer used. The cropcap video op is now only used to pass pixelaspect information, and is only needed if the pixelaspect is not 1:1. Signed-off-by: Hans Verkuil Cc: Guennadi Liakhovetski Acked-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- include/media/soc_camera.h | 7 ++----- include/media/v4l2-subdev.h | 6 ------ 2 files changed, 2 insertions(+), 11 deletions(-) (limited to 'include') diff --git a/include/media/soc_camera.h b/include/media/soc_camera.h index 97aa13314bfd..1a15c3e4efd3 100644 --- a/include/media/soc_camera.h +++ b/include/media/soc_camera.h @@ -105,16 +105,13 @@ struct soc_camera_host_ops { int (*get_formats)(struct soc_camera_device *, unsigned int, struct soc_camera_format_xlate *); void (*put_formats)(struct soc_camera_device *); - int (*cropcap)(struct soc_camera_device *, struct v4l2_cropcap *); - int (*get_crop)(struct soc_camera_device *, struct v4l2_crop *); - int (*set_crop)(struct soc_camera_device *, const struct v4l2_crop *); int (*get_selection)(struct soc_camera_device *, struct v4l2_selection *); int (*set_selection)(struct soc_camera_device *, struct v4l2_selection *); /* - * The difference to .set_crop() is, that .set_livecrop is not allowed + * The difference to .set_selection() is, that .set_liveselection is not allowed * to change the output sizes */ - int (*set_livecrop)(struct soc_camera_device *, const struct v4l2_crop *); + int (*set_liveselection)(struct soc_camera_device *, struct v4l2_selection *); int (*set_fmt)(struct soc_camera_device *, struct v4l2_format *); int (*try_fmt)(struct soc_camera_device *, struct v4l2_format *); void (*init_videobuf)(struct videobuf_queue *, diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h index 2a2240c99b30..22ea819ada95 100644 --- a/include/media/v4l2-subdev.h +++ b/include/media/v4l2-subdev.h @@ -360,10 +360,6 @@ struct v4l2_mbus_frame_desc { * * @cropcap: callback for %VIDIOC_CROPCAP ioctl handler code. * - * @g_crop: callback for %VIDIOC_G_CROP ioctl handler code. - * - * @s_crop: callback for %VIDIOC_S_CROP ioctl handler code. - * * @g_parm: callback for %VIDIOC_G_PARM ioctl handler code. * * @s_parm: callback for %VIDIOC_S_PARM ioctl handler code. @@ -403,8 +399,6 @@ struct v4l2_subdev_video_ops { int (*g_input_status)(struct v4l2_subdev *sd, u32 *status); int (*s_stream)(struct v4l2_subdev *sd, int enable); int (*cropcap)(struct v4l2_subdev *sd, struct v4l2_cropcap *cc); - int (*g_crop)(struct v4l2_subdev *sd, struct v4l2_crop *crop); - int (*s_crop)(struct v4l2_subdev *sd, const struct v4l2_crop *crop); int (*g_parm)(struct v4l2_subdev *sd, struct v4l2_streamparm *param); int (*s_parm)(struct v4l2_subdev *sd, struct v4l2_streamparm *param); int (*g_frame_interval)(struct v4l2_subdev *sd, -- cgit v1.2.3 From ecf37493f4bda87b77c83a4f64132e287cb55fc8 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 4 Jul 2016 05:08:01 -0300 Subject: [media] v4l2-subdev: rename cropcap to g_pixelaspect The old cropcap video op is now only used to pass the pixelaspect ratio, so rename it. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-subdev.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h index 22ea819ada95..de5117a01b98 100644 --- a/include/media/v4l2-subdev.h +++ b/include/media/v4l2-subdev.h @@ -358,7 +358,7 @@ struct v4l2_mbus_frame_desc { * @s_stream: used to notify the driver that a video stream will start or has * stopped. * - * @cropcap: callback for %VIDIOC_CROPCAP ioctl handler code. + * @g_pixelaspect: callback to return the pixelaspect ratio. * * @g_parm: callback for %VIDIOC_G_PARM ioctl handler code. * @@ -398,7 +398,7 @@ struct v4l2_subdev_video_ops { int (*g_tvnorms_output)(struct v4l2_subdev *sd, v4l2_std_id *std); int (*g_input_status)(struct v4l2_subdev *sd, u32 *status); int (*s_stream)(struct v4l2_subdev *sd, int enable); - int (*cropcap)(struct v4l2_subdev *sd, struct v4l2_cropcap *cc); + int (*g_pixelaspect)(struct v4l2_subdev *sd, struct v4l2_fract *aspect); int (*g_parm)(struct v4l2_subdev *sd, struct v4l2_streamparm *param); int (*s_parm)(struct v4l2_subdev *sd, struct v4l2_streamparm *param); int (*g_frame_interval)(struct v4l2_subdev *sd, -- cgit v1.2.3 From 0ff657b0f6120cb53f98b1b42c87af34670edff5 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Thu, 21 Jul 2016 09:14:02 -0300 Subject: [media] vb2: don't return NULL for alloc and get_userptr ops Always return an ERR_PTR() instead of NULL. This makes the behavior of alloc, get_userptr and attach_dmabuf the same. Update the documentation in videobuf2-core.h as well. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- include/media/videobuf2-core.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'include') diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h index a4a9a55a0c42..b6546db670ca 100644 --- a/include/media/videobuf2-core.h +++ b/include/media/videobuf2-core.h @@ -33,7 +33,7 @@ struct vb2_threadio_data; /** * struct vb2_mem_ops - memory handling/memory allocator operations * @alloc: allocate video memory and, optionally, allocator private data, - * return NULL on failure or a pointer to allocator private, + * return ERR_PTR() on failure or a pointer to allocator private, * per-buffer data on success; the returned private structure * will then be passed as buf_priv argument to other ops in this * structure. Additional gfp_flags to use when allocating the @@ -50,14 +50,14 @@ struct vb2_threadio_data; * USERPTR memory types; vaddr is the address passed to the * videobuf layer when queuing a video buffer of USERPTR type; * should return an allocator private per-buffer structure - * associated with the buffer on success, NULL on failure; + * associated with the buffer on success, ERR_PTR() on failure; * the returned private structure will then be passed as buf_priv * argument to other ops in this structure. * @put_userptr: inform the allocator that a USERPTR buffer will no longer * be used. * @attach_dmabuf: attach a shared struct dma_buf for a hardware operation; * used for DMABUF memory types; dev is the alloc device - * dbuf is the shared dma_buf; returns NULL on failure; + * dbuf is the shared dma_buf; returns ERR_PTR() on failure; * allocator private per-buffer structure on success; * this needs to be used for further accesses to the buffer. * @detach_dmabuf: inform the exporter of the buffer that the current DMABUF -- cgit v1.2.3 From bb5147aa42777efe8fec262eab579cfba4500133 Mon Sep 17 00:00:00 2001 From: Liu Ying Date: Thu, 11 Aug 2016 02:10:10 -0300 Subject: [media] media-entity.h: remove redundant macro definition for gobj_to_link() The macro gobj_to_link() is defined twice in media-entity.h. Let's remove one. Signed-off-by: Liu Ying Signed-off-by: Mauro Carvalho Chehab --- include/media/media-entity.h | 3 --- 1 file changed, 3 deletions(-) (limited to 'include') diff --git a/include/media/media-entity.h b/include/media/media-entity.h index 09b03c17784d..afd61713ea3b 100644 --- a/include/media/media-entity.h +++ b/include/media/media-entity.h @@ -520,9 +520,6 @@ static inline bool media_entity_enum_intersects( #define gobj_to_link(gobj) \ container_of(gobj, struct media_link, graph_obj) -#define gobj_to_link(gobj) \ - container_of(gobj, struct media_link, graph_obj) - #define gobj_to_pad(gobj) \ container_of(gobj, struct media_pad, graph_obj) -- cgit v1.2.3 From f598a6e362bb287a50085ffe0c3c8506127919f9 Mon Sep 17 00:00:00 2001 From: Liu Ying Date: Thu, 11 Aug 2016 02:10:09 -0300 Subject: [media] media-entity.h: Correct KernelDoc of media_entity_enum_empty() The function media_entity_enum_empty() returns true when the bitmap of the input parameter media entity enumeration is empty instead of marked. This patch corrects the return value description of the function. Signed-off-by: Liu Ying Signed-off-by: Mauro Carvalho Chehab --- include/media/media-entity.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/media/media-entity.h b/include/media/media-entity.h index afd61713ea3b..fa874ad4870e 100644 --- a/include/media/media-entity.h +++ b/include/media/media-entity.h @@ -486,7 +486,7 @@ media_entity_enum_test_and_set(struct media_entity_enum *ent_enum, * * @ent_enum: Entity enumeration * - * Returns true if the entity was marked. + * Returns true if the entity was empty. */ static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum) { -- cgit v1.2.3 From 6a21b728732390deb75536dd9253d958ca9223d0 Mon Sep 17 00:00:00 2001 From: Liu Ying Date: Thu, 11 Aug 2016 02:10:11 -0300 Subject: [media] media-entity.h: remove redundant macro definition for gobj_to_pad() The macro gobj_to_pad() is defined twice in media-entity.h. Let's remove one. Signed-off-by: Liu Ying Signed-off-by: Mauro Carvalho Chehab --- include/media/media-entity.h | 3 --- 1 file changed, 3 deletions(-) (limited to 'include') diff --git a/include/media/media-entity.h b/include/media/media-entity.h index fa874ad4870e..7bf6885dd37f 100644 --- a/include/media/media-entity.h +++ b/include/media/media-entity.h @@ -520,9 +520,6 @@ static inline bool media_entity_enum_intersects( #define gobj_to_link(gobj) \ container_of(gobj, struct media_link, graph_obj) -#define gobj_to_pad(gobj) \ - container_of(gobj, struct media_pad, graph_obj) - #define gobj_to_intf(gobj) \ container_of(gobj, struct media_interface, graph_obj) -- cgit v1.2.3 From a53d2f299dc83340c695e153363a2f21641d5f58 Mon Sep 17 00:00:00 2001 From: Javier Martinez Canillas Date: Thu, 11 Aug 2016 13:28:16 -0300 Subject: [media] v4l2-async: remove unneeded .registered_async callback The v4l2_subdev_core_ops .registered_async callback was added to notify a subdev when its entity has been registered with the media device, to allow for example to modify the media graph (i.e: adding entities/links). But that's not needed since there is already a .registered callback in struct v4l2_subdev_internal_ops that's called after the entity has been registered with the media device in v4l2_device_register_subdev(). Suggested-by: Sakari Ailus Signed-off-by: Javier Martinez Canillas Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-subdev.h | 3 --- 1 file changed, 3 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h index de5117a01b98..6e1d044e3ee8 100644 --- a/include/media/v4l2-subdev.h +++ b/include/media/v4l2-subdev.h @@ -184,8 +184,6 @@ struct v4l2_subdev_io_pin_config { * for it to be warned when the value of a control changes. * * @unsubscribe_event: remove event subscription from the control framework. - * - * @registered_async: the subdevice has been registered async. */ struct v4l2_subdev_core_ops { int (*log_status)(struct v4l2_subdev *sd); @@ -211,7 +209,6 @@ struct v4l2_subdev_core_ops { struct v4l2_event_subscription *sub); int (*unsubscribe_event)(struct v4l2_subdev *sd, struct v4l2_fh *fh, struct v4l2_event_subscription *sub); - int (*registered_async)(struct v4l2_subdev *sd); }; /** -- cgit v1.2.3 From 697a521fbc6dd6f64489d0feeb09631b227fcd67 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Thu, 11 Aug 2016 07:43:50 -0300 Subject: [media] smiapp: Rename smiapp_platform_data as smiapp_hwconfig This is really configuration to the driver originating from DT or elsewhere. Do not call it platform data. Signed-off-by: Sakari Ailus Reviewed-by: Sebastian Reichel Signed-off-by: Mauro Carvalho Chehab --- include/media/i2c/smiapp.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/media/i2c/smiapp.h b/include/media/i2c/smiapp.h index 029142ddb95c..a4a1b510c9d3 100644 --- a/include/media/i2c/smiapp.h +++ b/include/media/i2c/smiapp.h @@ -57,7 +57,7 @@ struct smiapp_flash_strobe_parms { u8 trigger; }; -struct smiapp_platform_data { +struct smiapp_hwconfig { /* * Change the cci address if i2c_addr_alt is set. * Both default and alternate cci addr need to be present -- cgit v1.2.3 From 567716c5817cbcc482f70724d7f98aa6702c6e4c Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Sat, 13 Aug 2016 12:46:50 -0300 Subject: [media] smiapp: Switch to gpiod API for GPIO control Switch from the old gpio API to the new descriptor based gpiod API. Signed-off-by: Sakari Ailus Reviewed-by: Sebastian Reichel Signed-off-by: Mauro Carvalho Chehab --- include/media/i2c/smiapp.h | 3 --- 1 file changed, 3 deletions(-) (limited to 'include') diff --git a/include/media/i2c/smiapp.h b/include/media/i2c/smiapp.h index a4a1b510c9d3..eacc3f4e3deb 100644 --- a/include/media/i2c/smiapp.h +++ b/include/media/i2c/smiapp.h @@ -36,8 +36,6 @@ #define SMIAPP_CSI_SIGNALLING_MODE_CCP2_DATA_STROBE 1 #define SMIAPP_CSI_SIGNALLING_MODE_CSI2 2 -#define SMIAPP_NO_XSHUTDOWN -1 - /* * Sometimes due to board layout considerations the camera module can be * mounted rotated. The typical rotation used is 180 degrees which can be @@ -77,7 +75,6 @@ struct smiapp_hwconfig { struct smiapp_flash_strobe_parms *strobe_setup; int (*set_xclk)(struct v4l2_subdev *sd, int hz); - int32_t xshutdown; /* gpio or SMIAPP_NO_XSHUTDOWN */ }; #endif /* __SMIAPP_H_ */ -- cgit v1.2.3 From e62c30e76829d46bf11d170fd81b735f13a014ac Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Wed, 31 Aug 2016 09:38:54 -0300 Subject: [media] smiapp: Remove set_xclk() callback from hwconfig The clock framework is generally so well supported that there's no reason to keep this one around. Signed-off-by: Sakari Ailus Reviewed-by: Sebastian Reichel Signed-off-by: Mauro Carvalho Chehab --- include/media/i2c/smiapp.h | 2 -- 1 file changed, 2 deletions(-) (limited to 'include') diff --git a/include/media/i2c/smiapp.h b/include/media/i2c/smiapp.h index eacc3f4e3deb..635007e7441a 100644 --- a/include/media/i2c/smiapp.h +++ b/include/media/i2c/smiapp.h @@ -73,8 +73,6 @@ struct smiapp_hwconfig { enum smiapp_module_board_orient module_board_orient; struct smiapp_flash_strobe_parms *strobe_setup; - - int (*set_xclk)(struct v4l2_subdev *sd, int hz); }; #endif /* __SMIAPP_H_ */ -- cgit v1.2.3 From 48a7c4bac94dfb367d1d64123b5182536912c03e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 29 Aug 2016 16:09:11 -0300 Subject: [media] docs-rst: improve the kAPI documentation for the mediactl There are several issues on the documentation: - the media.h header were not properly referenced; - verbatim expressions were not properly marked as such; - struct member references were wrong; - some notes were not using the right markup; - a comment that were moved to the kernel-doc markup were duplicated as a comment inside the struct media_entity; - some args were not pointing to the struct they're using; - macros weren't documented. Signed-off-by: Mauro Carvalho Chehab --- include/media/media-device.h | 115 ++++++++++++-------- include/media/media-devnode.h | 2 +- include/media/media-entity.h | 237 ++++++++++++++++++++++++++++-------------- 3 files changed, 231 insertions(+), 123 deletions(-) (limited to 'include') diff --git a/include/media/media-device.h b/include/media/media-device.h index 28195242386c..481dd6c672cb 100644 --- a/include/media/media-device.h +++ b/include/media/media-device.h @@ -53,7 +53,7 @@ struct media_entity_notify { * @dev: Parent device * @devnode: Media device node * @driver_name: Optional device driver name. If not set, calls to - * %MEDIA_IOC_DEVICE_INFO will return dev->driver->name. + * %MEDIA_IOC_DEVICE_INFO will return ``dev->driver->name``. * This is needed for USB drivers for example, as otherwise * they'll all appear as if the driver name was "usb". * @model: Device model name @@ -102,16 +102,18 @@ struct media_entity_notify { * sink entity and deactivate the link between them. Drivers * should call this handler to release the source. * - * Note: Bridge driver is expected to implement and set the - * handler when media_device is registered or when - * bridge driver finds the media_device during probe. - * Bridge driver sets source_priv with information - * necessary to run enable/disable source handlers. - * * Use-case: find tuner entity connected to the decoder * entity and check if it is available, and activate the - * the link between them from enable_source and deactivate - * from disable_source. + * the link between them from @enable_source and deactivate + * from @disable_source. + * + * .. note:: + * + * Bridge driver is expected to implement and set the + * handler when &media_device is registered or when + * bridge driver finds the media_device during probe. + * Bridge driver sets source_priv with information + * necessary to run @enable_source and @disable_source handlers. */ struct media_device { /* dev->driver_data points to this struct. */ @@ -168,7 +170,7 @@ struct usb_device; * @ent_enum: Entity enumeration to be initialised * @mdev: The related media device * - * Returns zero on success or a negative error code. + * Return: zero on success or a negative error code. */ static inline __must_check int media_entity_enum_init( struct media_entity_enum *ent_enum, struct media_device *mdev) @@ -211,36 +213,38 @@ void media_device_cleanup(struct media_device *mdev); * * Users, should, instead, call the media_device_register() macro. * - * The caller is responsible for initializing the media_device structure before - * registration. The following fields must be set: + * The caller is responsible for initializing the &media_device structure + * before registration. The following fields of &media_device must be set: * - * - dev must point to the parent device (usually a &pci_dev, &usb_interface or - * &platform_device instance). + * - &media_entity.dev must point to the parent device (usually a &pci_dev, + * &usb_interface or &platform_device instance). * - * - model must be filled with the device model name as a NUL-terminated UTF-8 - * string. The device/model revision must not be stored in this field. + * - &media_entity.model must be filled with the device model name as a + * NUL-terminated UTF-8 string. The device/model revision must not be + * stored in this field. * * The following fields are optional: * - * - serial is a unique serial number stored as a NUL-terminated ASCII string. - * The field is big enough to store a GUID in text form. If the hardware - * doesn't provide a unique serial number this field must be left empty. + * - &media_entity.serial is a unique serial number stored as a + * NUL-terminated ASCII string. The field is big enough to store a GUID + * in text form. If the hardware doesn't provide a unique serial number + * this field must be left empty. * - * - bus_info represents the location of the device in the system as a - * NUL-terminated ASCII string. For PCI/PCIe devices bus_info must be set to - * "PCI:" (or "PCIe:") followed by the value of pci_name(). For USB devices, - * the usb_make_path() function must be used. This field is used by - * applications to distinguish between otherwise identical devices that don't - * provide a serial number. + * - &media_entity.bus_info represents the location of the device in the + * system as a NUL-terminated ASCII string. For PCI/PCIe devices + * &media_entity.bus_info must be set to "PCI:" (or "PCIe:") followed by + * the value of pci_name(). For USB devices,the usb_make_path() function + * must be used. This field is used by applications to distinguish between + * otherwise identical devices that don't provide a serial number. * - * - hw_revision is the hardware device revision in a driver-specific format. - * When possible the revision should be formatted with the KERNEL_VERSION - * macro. + * - &media_entity.hw_revision is the hardware device revision in a + * driver-specific format. When possible the revision should be formatted + * with the KERNEL_VERSION() macro. * - * - driver_version is formatted with the KERNEL_VERSION macro. The version - * minor must be incremented when new features are added to the userspace API - * without breaking binary compatibility. The version major must be - * incremented when binary compatibility is broken. + * - &media_entity.driver_version is formatted with the KERNEL_VERSION() + * macro. The version minor must be incremented when new features are added + * to the userspace API without breaking binary compatibility. The version + * major must be incremented when binary compatibility is broken. * * .. note:: * @@ -252,6 +256,16 @@ void media_device_cleanup(struct media_device *mdev); */ int __must_check __media_device_register(struct media_device *mdev, struct module *owner); + + +/** + * media_device_register() - Registers a media device element + * + * @mdev: pointer to struct &media_device + * + * This macro calls __media_device_register() passing %THIS_MODULE as + * the __media_device_register() second argument (**owner**). + */ #define media_device_register(mdev) __media_device_register(mdev, THIS_MODULE) /** @@ -259,7 +273,6 @@ int __must_check __media_device_register(struct media_device *mdev, * * @mdev: pointer to struct &media_device * - * * It is safe to call this function on an unregistered (but initialised) * media device. */ @@ -285,14 +298,15 @@ void media_device_unregister(struct media_device *mdev); * framework. * * If the device has pads, media_entity_pads_init() should be called before - * this function. Otherwise, the &media_entity.@pad and &media_entity.@num_pads + * this function. Otherwise, the &media_entity.pad and &media_entity.num_pads * should be zeroed before calling this function. * * Entities have flags that describe the entity capabilities and state: * - * %MEDIA_ENT_FL_DEFAULT indicates the default entity for a given type. - * This can be used to report the default audio and video devices or the - * default camera sensor. + * %MEDIA_ENT_FL_DEFAULT + * indicates the default entity for a given type. + * This can be used to report the default audio and video devices or the + * default camera sensor. * * .. note:: * @@ -331,8 +345,10 @@ void media_device_unregister_entity(struct media_entity *entity); * @mdev: The media device * @nptr: The media_entity_notify * - * Note: When a new entity is registered, all the registered - * media_entity_notify callbacks are invoked. + * .. note:: + * + * When a new entity is registered, all the registered + * media_entity_notify callbacks are invoked. */ int __must_check media_device_register_entity_notify(struct media_device *mdev, @@ -410,11 +426,13 @@ void media_device_pci_init(struct media_device *mdev, * @board_name: media device name. If %NULL, the routine will use the usb * product name, if available. * @driver_name: name of the driver. if %NULL, the routine will use the name - * given by udev->dev->driver->name, with is usually the wrong + * given by ``udev->dev->driver->name``, with is usually the wrong * thing to do. * - * NOTE: It is better to call media_device_usb_init() instead, as - * such macro fills driver_name with %KBUILD_MODNAME. + * .. note:: + * + * It is better to call media_device_usb_init() instead, as + * such macro fills driver_name with %KBUILD_MODNAME. */ void __media_device_usb_init(struct media_device *mdev, struct usb_device *udev, @@ -472,6 +490,19 @@ static inline void __media_device_usb_init(struct media_device *mdev, #endif /* CONFIG_MEDIA_CONTROLLER */ +/** + * media_device_usb_init() - create and initialize a + * struct &media_device from a PCI device. + * + * @mdev: pointer to struct &media_device + * @udev: pointer to struct usb_device + * @name: media device name. If %NULL, the routine will use the usb + * product name, if available. + * + * This macro calls media_device_usb_init() passing the + * media_device_usb_init() **driver_name** parameter filled with + * %KBUILD_MODNAME. + */ #define media_device_usb_init(mdev, udev, name) \ __media_device_usb_init(mdev, udev, name, KBUILD_MODNAME) diff --git a/include/media/media-devnode.h b/include/media/media-devnode.h index 37d494805944..972168e90413 100644 --- a/include/media/media-devnode.h +++ b/include/media/media-devnode.h @@ -75,7 +75,7 @@ struct media_file_operations { * @cdev: struct cdev pointer character device * @parent: parent device * @minor: device node minor number - * @flags: flags, combination of the MEDIA_FLAG_* constants + * @flags: flags, combination of the ``MEDIA_FLAG_*`` constants * @release: release callback called at the end of media_devnode_release() * * This structure represents a media-related device node. diff --git a/include/media/media-entity.h b/include/media/media-entity.h index 7bf6885dd37f..e21958c7c5d9 100644 --- a/include/media/media-entity.h +++ b/include/media/media-entity.h @@ -56,7 +56,7 @@ enum media_gobj_type { /** * struct media_gobj - Define a graph object. * - * @mdev: Pointer to the struct media_device that owns the object + * @mdev: Pointer to the struct &media_device that owns the object * @id: Non-zero object ID identifier. The ID should be unique * inside a media_device, as it is composed by * %MEDIA_BITS_PER_TYPE to store the type plus @@ -162,7 +162,9 @@ struct media_link { * @graph_obj: Embedded structure containing the media object common data * @entity: Entity this pad belongs to * @index: Pad index in the entity pads array, numbered from 0 to n - * @flags: Pad flags, as defined in uapi/media.h (MEDIA_PAD_FL_*) + * @flags: Pad flags, as defined in + * :ref:`include/uapi/linux/media.h ` + * (seek for ``MEDIA_PAD_FL_*``) */ struct media_pad { struct media_gobj graph_obj; /* must be first field in struct */ @@ -182,7 +184,7 @@ struct media_pad { * * .. note:: * - * Those these callbacks are called with struct media_device.@graph_mutex + * Those these callbacks are called with struct &media_device.graph_mutex * mutex held. */ struct media_entity_operations { @@ -210,7 +212,7 @@ struct media_entity_operations { * This allows runtime type identification of media entities and safe casting to * the correct object type. For instance, a media entity structure instance * embedded in a v4l2_subdev structure instance will have the type - * MEDIA_ENTITY_TYPE_V4L2_SUBDEV and can safely be cast to a v4l2_subdev + * %MEDIA_ENTITY_TYPE_V4L2_SUBDEV and can safely be cast to a &v4l2_subdev * structure using the container_of() macro. */ enum media_entity_type { @@ -225,9 +227,12 @@ enum media_entity_type { * @graph_obj: Embedded structure containing the media object common data. * @name: Entity name. * @obj_type: Type of the object that implements the media_entity. - * @function: Entity main function, as defined in uapi/media.h - * (MEDIA_ENT_F_*) - * @flags: Entity flags, as defined in uapi/media.h (MEDIA_ENT_FL_*) + * @function: Entity main function, as defined in + * :ref:`include/uapi/linux/media.h ` + * (seek for ``MEDIA_ENT_F_*``) + * @flags: Entity flags, as defined in + * :ref:`include/uapi/linux/media.h ` + * (seek for ``MEDIA_ENT_FL_*``) * @num_pads: Number of sink and source pads. * @num_links: Total number of links, forward and back, enabled and disabled. * @num_backlinks: Number of backlinks @@ -246,9 +251,12 @@ enum media_entity_type { * @minor: Devnode minor number (zero if not applicable). Kept just * for backward compatibility. * - * NOTE: @stream_count and @use_count reference counts must never be - * negative, but are signed integers on purpose: a simple WARN_ON(<0) check - * can be used to detect reference count bugs that would make them negative. + * .. note:: + * + * @stream_count and @use_count reference counts must never be + * negative, but are signed integers on purpose: a simple ``WARN_ON(<0)`` + * check can be used to detect reference count bugs that would make them + * negative. */ struct media_entity { struct media_gobj graph_obj; /* must be first field in struct */ @@ -267,10 +275,6 @@ struct media_entity { const struct media_entity_operations *ops; - /* Reference counts must never be negative, but are signed integers on - * purpose: a simple WARN_ON(<0) check can be used to detect reference - * count bugs that would make them negative. - */ int stream_count; int use_count; @@ -289,10 +293,16 @@ struct media_entity { * * @graph_obj: embedded graph object * @links: List of links pointing to graph entities - * @type: Type of the interface as defined in the - * uapi/media/media.h header, e. g. - * MEDIA_INTF_T_* - * @flags: Interface flags as defined in uapi/media/media.h + * @type: Type of the interface as defined in + * :ref:`include/uapi/linux/media.h ` + * (seek for ``MEDIA_INTF_T_*``) + * @flags: Interface flags as defined in + * :ref:`include/uapi/linux/media.h ` + * (seek for ``MEDIA_INTF_FL_*``) + * + * .. note:: + * + * Currently, no flags for &media_interface is defined. */ struct media_interface { struct media_gobj graph_obj; @@ -319,7 +329,7 @@ struct media_intf_devnode { /** * media_entity_id() - return the media entity graph object id * - * @entity: pointer to entity + * @entity: pointer to &media_entity */ static inline u32 media_entity_id(struct media_entity *entity) { @@ -329,7 +339,7 @@ static inline u32 media_entity_id(struct media_entity *entity) /** * media_type() - return the media object type * - * @gobj: pointer to the media graph object + * @gobj: Pointer to the struct &media_gobj graph object */ static inline enum media_gobj_type media_type(struct media_gobj *gobj) { @@ -339,7 +349,7 @@ static inline enum media_gobj_type media_type(struct media_gobj *gobj) /** * media_id() - return the media object ID * - * @gobj: pointer to the media graph object + * @gobj: Pointer to the struct &media_gobj graph object */ static inline u32 media_id(struct media_gobj *gobj) { @@ -350,7 +360,7 @@ static inline u32 media_id(struct media_gobj *gobj) * media_gobj_gen_id() - encapsulates type and ID on at the object ID * * @type: object type as define at enum &media_gobj_type. - * @local_id: next ID, from struct &media_device.@id. + * @local_id: next ID, from struct &media_device.id. */ static inline u32 media_gobj_gen_id(enum media_gobj_type type, u64 local_id) { @@ -366,9 +376,9 @@ static inline u32 media_gobj_gen_id(enum media_gobj_type type, u64 local_id) * is_media_entity_v4l2_video_device() - Check if the entity is a video_device * @entity: pointer to entity * - * Return: true if the entity is an instance of a video_device object and can + * Return: %true if the entity is an instance of a video_device object and can * safely be cast to a struct video_device using the container_of() macro, or - * false otherwise. + * %false otherwise. */ static inline bool is_media_entity_v4l2_video_device(struct media_entity *entity) { @@ -379,9 +389,9 @@ static inline bool is_media_entity_v4l2_video_device(struct media_entity *entity * is_media_entity_v4l2_subdev() - Check if the entity is a v4l2_subdev * @entity: pointer to entity * - * Return: true if the entity is an instance of a v4l2_subdev object and can - * safely be cast to a struct v4l2_subdev using the container_of() macro, or - * false otherwise. + * Return: %true if the entity is an instance of a &v4l2_subdev object and can + * safely be cast to a struct &v4l2_subdev using the container_of() macro, or + * %false otherwise. */ static inline bool is_media_entity_v4l2_subdev(struct media_entity *entity) { @@ -452,7 +462,7 @@ static inline void media_entity_enum_clear(struct media_entity_enum *ent_enum, * @ent_enum: Entity enumeration * @entity: Entity to be tested * - * Returns true if the entity was marked. + * Returns %true if the entity was marked. */ static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum, struct media_entity *entity) @@ -469,7 +479,7 @@ static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum, * @ent_enum: Entity enumeration * @entity: Entity to be tested * - * Returns true if the entity was marked, and mark it before doing so. + * Returns %true if the entity was marked, and mark it before doing so. */ static inline bool media_entity_enum_test_and_set(struct media_entity_enum *ent_enum, @@ -486,7 +496,7 @@ media_entity_enum_test_and_set(struct media_entity_enum *ent_enum, * * @ent_enum: Entity enumeration * - * Returns true if the entity was empty. + * Return: %true if the entity was empty. */ static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum) { @@ -499,7 +509,8 @@ static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum) * @ent_enum1: First entity enumeration * @ent_enum2: Second entity enumeration * - * Returns true if entity enumerations e and f intersect, otherwise false. + * Return: %true if entity enumerations @ent_enum1 and @ent_enum2 intersect, + * otherwise %false. */ static inline bool media_entity_enum_intersects( struct media_entity_enum *ent_enum1, @@ -511,33 +522,63 @@ static inline bool media_entity_enum_intersects( min(ent_enum1->idx_max, ent_enum2->idx_max)); } +/** + * gobj_to_entity - returns the struct &media_entity pointer from the + * @gobj contained on it. + * + * @gobj: Pointer to the struct &media_gobj graph object + */ #define gobj_to_entity(gobj) \ container_of(gobj, struct media_entity, graph_obj) +/** + * gobj_to_entity - returns the struct &media_pad pointer from the + * @gobj contained on it. + * + * @gobj: Pointer to the struct &media_gobj graph object + */ #define gobj_to_pad(gobj) \ container_of(gobj, struct media_pad, graph_obj) +/** + * gobj_to_entity - returns the struct &media_link pointer from the + * @gobj contained on it. + * + * @gobj: Pointer to the struct &media_gobj graph object + */ #define gobj_to_link(gobj) \ container_of(gobj, struct media_link, graph_obj) +/** + * gobj_to_entity - returns the struct &media_interface pointer from the + * @gobj contained on it. + * + * @gobj: Pointer to the struct &media_gobj graph object + */ #define gobj_to_intf(gobj) \ container_of(gobj, struct media_interface, graph_obj) +/** + * gobj_to_entity - returns the struct media_intf_devnode pointer from the + * @intf contained on it. + * + * @intf: Pointer to struct &media_intf_devnode + */ #define intf_to_devnode(intf) \ container_of(intf, struct media_intf_devnode, intf) /** * media_gobj_create - Initialize a graph object * - * @mdev: Pointer to the media_device that contains the object + * @mdev: Pointer to the &media_device that contains the object * @type: Type of the object - * @gobj: Pointer to the graph object + * @gobj: Pointer to the struct &media_gobj graph object * - * This routine initializes the embedded struct media_gobj inside a - * media graph object. It is called automatically if media_*_create\(\) - * calls are used. However, if the object (entity, link, pad, interface) - * is embedded on some other object, this function should be called before - * registering the object at the media controller. + * This routine initializes the embedded struct &media_gobj inside a + * media graph object. It is called automatically if ``media_*_create`` + * function calls are used. However, if the object (entity, link, pad, + * interface) is embedded on some other object, this function should be + * called before registering the object at the media controller. */ void media_gobj_create(struct media_device *mdev, enum media_gobj_type type, @@ -546,7 +587,7 @@ void media_gobj_create(struct media_device *mdev, /** * media_gobj_destroy - Stop using a graph object on a media device * - * @gobj: Pointer to the graph object + * @gobj: Pointer to the struct &media_gobj graph object * * This should be called by all routines like media_device_unregister() * that remove/destroy media graph objects. @@ -561,11 +602,11 @@ void media_gobj_destroy(struct media_gobj *gobj); * @pads: Array of @num_pads pads. * * The pads array is managed by the entity driver and passed to - * media_entity_pads_init() where its pointer will be stored in the entity - * structure. + * media_entity_pads_init() where its pointer will be stored in the + * &media_entity structure. * * If no pads are needed, drivers could either directly fill - * &media_entity->@num_pads with 0 and &media_entity->@pads with NULL or call + * &media_entity->num_pads with 0 and &media_entity->pads with %NULL or call * this function that will do the same. * * As the number of pads is known in advance, the pads array is not allocated @@ -595,18 +636,21 @@ static inline void media_entity_cleanup(struct media_entity *entity) {}; * @source_pad: number of the source pad in the pads array * @sink: pointer to &media_entity of the sink pad. * @sink_pad: number of the sink pad in the pads array. - * @flags: Link flags, as defined in include/uapi/linux/media.h. + * @flags: Link flags, as defined in + * :ref:`include/uapi/linux/media.h ` + * ( seek for ``MEDIA_LNK_FL_*``) * * Valid values for flags: * - * - A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can - * be used to transfer media data. When two or more links target a sink pad, - * only one of them can be enabled at a time. + * %MEDIA_LNK_FL_ENABLED + * Indicates that the link is enabled and can be used to transfer media data. + * When two or more links target a sink pad, only one of them can be + * enabled at a time. * - * - A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't - * be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then - * %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is - * always enabled. + * %MEDIA_LNK_FL_IMMUTABLE + * Indicates that the link enabled state can't be modified at runtime. If + * %MEDIA_LNK_FL_IMMUTABLE is set, then %MEDIA_LNK_FL_ENABLED must also be + * set, since an immutable link is always enabled. * * .. note:: * @@ -624,17 +668,17 @@ __must_check int media_create_pad_link(struct media_entity *source, * @source_function: Function of the source entities. Used only if @source is * NULL. * @source: pointer to &media_entity of the source pad. If NULL, it will use - * all entities that matches the @sink_function. + * all entities that matches the @sink_function. * @source_pad: number of the source pad in the pads array * @sink_function: Function of the sink entities. Used only if @sink is NULL. * @sink: pointer to &media_entity of the sink pad. If NULL, it will use - * all entities that matches the @sink_function. + * all entities that matches the @sink_function. * @sink_pad: number of the sink pad in the pads array. * @flags: Link flags, as defined in include/uapi/linux/media.h. - * @allow_both_undefined: if true, then both @source and @sink can be NULL. + * @allow_both_undefined: if %true, then both @source and @sink can be NULL. * In such case, it will create a crossbar between all entities that * matches @source_function to all entities that matches @sink_function. - * If false, it will return 0 and won't create any link if both @source + * If %false, it will return 0 and won't create any link if both @source * and @sink are NULL. * * Valid values for flags: @@ -654,9 +698,11 @@ __must_check int media_create_pad_link(struct media_entity *source, * creates link by link, this function is meant to allow 1:n, n:1 and even * cross-bar (n:n) links. * - * NOTE: Before calling this function, media_entity_pads_init() and - * media_device_register_entity() should be called previously for the entities - * to be linked. + * .. note:: + * + * Before calling this function, media_entity_pads_init() and + * media_device_register_entity() should be called previously for the + * entities to be linked. */ int media_create_pad_links(const struct media_device *mdev, const u32 source_function, @@ -715,7 +761,7 @@ int __media_entity_setup_link(struct media_link *link, u32 flags); * flags. * * Media device drivers can be notified of link setup operations by setting the - * media_device::link_notify pointer to a callback function. If provided, the + * &media_device.link_notify pointer to a callback function. If provided, the * notification callback will be called before enabling and after disabling * links. * @@ -725,7 +771,7 @@ int __media_entity_setup_link(struct media_link *link, u32 flags); * * Link configuration must not have any side effect on other links. If an * enabled link at a sink pad prevents another link at the same pad from - * being enabled, the link_setup operation must return -EBUSY and can't + * being enabled, the link_setup operation must return %-EBUSY and can't * implicitly disable the first enabled link. * * .. note:: @@ -741,8 +787,8 @@ int media_entity_setup_link(struct media_link *link, u32 flags); * @source: Source pad * @sink: Sink pad * - * Return a pointer to the link between the two entities. If no such link - * exists, return NULL. + * Return: returns a pointer to the link between the two entities. If no + * such link exists, return %NULL. */ struct media_link *media_entity_find_link(struct media_pad *source, struct media_pad *sink); @@ -754,8 +800,8 @@ struct media_link *media_entity_find_link(struct media_pad *source, * Search for a remote pad connected to the given pad by iterating over all * links originating or terminating at that pad until an enabled link is found. * - * Return a pointer to the pad at the remote end of the first found enabled - * link, or NULL if no enabled link has been found. + * Return: returns a pointer to the pad at the remote end of the first found + * enabled link, or %NULL if no enabled link has been found. */ struct media_pad *media_entity_remote_pad(struct media_pad *pad); @@ -766,12 +812,18 @@ struct media_pad *media_entity_remote_pad(struct media_pad *pad); * * Get a reference to the parent media device module. * - * The function will return immediately if @entity is NULL. + * The function will return immediately if @entity is %NULL. * - * Return a pointer to the entity on success or NULL on failure. + * Return: returns a pointer to the entity on success or %NULL on failure. */ struct media_entity *media_entity_get(struct media_entity *entity); +/** + * media_entity_graph_walk_init - Allocate resources used by graph walk. + * + * @graph: Media graph structure that will be used to walk the graph + * @mdev: Pointer to the &media_device that contains the object + */ __must_check int media_entity_graph_walk_init( struct media_entity_graph *graph, struct media_device *mdev); @@ -789,12 +841,14 @@ void media_entity_graph_walk_cleanup(struct media_entity_graph *graph); * * Release the reference count acquired by media_entity_get(). * - * The function will return immediately if @entity is NULL. + * The function will return immediately if @entity is %NULL. */ void media_entity_put(struct media_entity *entity); /** - * media_entity_graph_walk_start - Start walking the media graph at a given entity + * media_entity_graph_walk_start - Start walking the media graph at a + * given entity + * * @graph: Media graph structure that will be used to walk the graph * @entity: Starting entity * @@ -818,8 +872,8 @@ void media_entity_graph_walk_start(struct media_entity_graph *graph, * The graph structure must have been previously initialized with a call to * media_entity_graph_walk_start(). * - * Return the next entity in the graph or NULL if the whole graph have been - * traversed. + * Return: returns the next entity in the graph or %NULL if the whole graph + * have been traversed. */ struct media_entity * media_entity_graph_walk_next(struct media_entity_graph *graph); @@ -830,8 +884,8 @@ media_entity_graph_walk_next(struct media_entity_graph *graph); * @pipe: Media pipeline to be assigned to all entities in the pipeline. * * Mark all entities connected to a given entity through enabled links, either - * directly or indirectly, as streaming. The given pipeline object is assigned to - * every entity in the pipeline and stored in the media_entity pipe field. + * directly or indirectly, as streaming. The given pipeline object is assigned + * to every entity in the pipeline and stored in the media_entity pipe field. * * Calls to this function can be nested, in which case the same number of * media_entity_pipeline_stop() calls will be required to stop streaming. The @@ -857,7 +911,7 @@ __must_check int __media_entity_pipeline_start(struct media_entity *entity, * * Mark all entities connected to a given entity through enabled links, either * directly or indirectly, as not streaming. The media_entity pipe field is - * reset to NULL. + * reset to %NULL. * * If multiple calls to media_entity_pipeline_start() have been made, the same * number of calls to this function are required to mark the pipeline as not @@ -878,14 +932,21 @@ void __media_entity_pipeline_stop(struct media_entity *entity); * media_devnode_create() - creates and initializes a device node interface * * @mdev: pointer to struct &media_device - * @type: type of the interface, as given by MEDIA_INTF_T_* macros - * as defined in the uapi/media/media.h header. - * @flags: Interface flags as defined in uapi/media/media.h. + * @type: type of the interface, as given by + * :ref:`include/uapi/linux/media.h ` + * ( seek for ``MEDIA_INTF_T_*``) macros. + * @flags: Interface flags, as defined in + * :ref:`include/uapi/linux/media.h ` + * ( seek for ``MEDIA_INTF_FL_*``) * @major: Device node major number. * @minor: Device node minor number. * * Return: if succeeded, returns a pointer to the newly allocated * &media_intf_devnode pointer. + * + * .. note:: + * + * Currently, no flags for &media_interface is defined. */ struct media_intf_devnode * __must_check media_devnode_create(struct media_device *mdev, @@ -907,15 +968,19 @@ struct media_link * * * @entity: pointer to %media_entity * @intf: pointer to %media_interface - * @flags: Link flags, as defined in include/uapi/linux/media.h. + * @flags: Link flags, as defined in + * :ref:`include/uapi/linux/media.h ` + * ( seek for ``MEDIA_LNK_FL_*``) * * * Valid values for flags: * - * - The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to - * the entity hardware. That's the default value for interfaces. An - * interface may be disabled if the hardware is busy due to the usage - * of some other interface that it is currently controlling the hardware. + * %MEDIA_LNK_FL_ENABLED + * Indicates that the interface is connected to the entity hardware. + * That's the default value for interfaces. An interface may be disabled if + * the hardware is busy due to the usage of some other interface that it is + * currently controlling the hardware. + * * A typical example is an hybrid TV device that handle only one type of * stream on a given time. So, when the digital TV is streaming, * the V4L2 interfaces won't be enabled, as such device is not able to @@ -971,6 +1036,18 @@ void __media_remove_intf_links(struct media_interface *intf); */ void media_remove_intf_links(struct media_interface *intf); +/** + * media_entity_call - Calls a struct media_entity_operations operation on + * an entity + * + * @entity: entity where the @operation will be called + * @operation: type of the operation. Should be the name of a member of + * struct &media_entity_operations. + * + * This helper function will check if @operation is not %NULL. On such case, + * it will issue a call to @operation\(@entity, @args\). + */ + #define media_entity_call(entity, operation, args...) \ (((entity)->ops && (entity)->ops->operation) ? \ (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD) -- cgit v1.2.3 From 9fa7235f88386c9a5f5013a90f0c6fe8aa6fe828 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 29 Aug 2016 17:00:22 -0300 Subject: [media] rc-map.h: document structs/enums on it There are some structs/enums that aren't documented via kernel-doc markup. Add documentation for them. Fix those warnings: ./include/media/rc-map.h:103: WARNING: c:type reference target not found: rc_map_list ./include/media/rc-map.h:110: WARNING: c:type reference target not found: rc_map_list ./include/media/rc-map.h:117: WARNING: c:type reference target not found: rc_map Signed-off-by: Mauro Carvalho Chehab --- include/media/rc-map.h | 94 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 71 insertions(+), 23 deletions(-) (limited to 'include') diff --git a/include/media/rc-map.h b/include/media/rc-map.h index daa75fcc1ff1..173ad58fb61b 100644 --- a/include/media/rc-map.h +++ b/include/media/rc-map.h @@ -11,27 +11,51 @@ #include +/** + * enum rc_type - type of the Remote Controller protocol + * + * @RC_TYPE_UNKNOWN: Protocol not known + * @RC_TYPE_OTHER: Protocol known but proprietary + * @RC_TYPE_RC5: Philips RC5 protocol + * @RC_TYPE_RC5X: Philips RC5x protocol + * @RC_TYPE_RC5_SZ: StreamZap variant of RC5 + * @RC_TYPE_JVC: JVC protocol + * @RC_TYPE_SONY12: Sony 12 bit protocol + * @RC_TYPE_SONY15: Sony 15 bit protocol + * @RC_TYPE_SONY20: Sony 20 bit protocol + * @RC_TYPE_NEC: NEC protocol + * @RC_TYPE_SANYO: Sanyo protocol + * @RC_TYPE_MCE_KBD: RC6-ish MCE keyboard/mouse + * @RC_TYPE_RC6_0: Philips RC6-0-16 protocol + * @RC_TYPE_RC6_6A_20: Philips RC6-6A-20 protocol + * @RC_TYPE_RC6_6A_24: Philips RC6-6A-24 protocol + * @RC_TYPE_RC6_6A_32: Philips RC6-6A-32 protocol + * @RC_TYPE_RC6_MCE: MCE (Philips RC6-6A-32 subtype) protocol + * @RC_TYPE_SHARP: Sharp protocol + * @RC_TYPE_XMP: XMP protocol + * @RC_TYPE_CEC: CEC protocol + */ enum rc_type { - RC_TYPE_UNKNOWN = 0, /* Protocol not known */ - RC_TYPE_OTHER = 1, /* Protocol known but proprietary */ - RC_TYPE_RC5 = 2, /* Philips RC5 protocol */ - RC_TYPE_RC5X = 3, /* Philips RC5x protocol */ - RC_TYPE_RC5_SZ = 4, /* StreamZap variant of RC5 */ - RC_TYPE_JVC = 5, /* JVC protocol */ - RC_TYPE_SONY12 = 6, /* Sony 12 bit protocol */ - RC_TYPE_SONY15 = 7, /* Sony 15 bit protocol */ - RC_TYPE_SONY20 = 8, /* Sony 20 bit protocol */ - RC_TYPE_NEC = 9, /* NEC protocol */ - RC_TYPE_SANYO = 10, /* Sanyo protocol */ - RC_TYPE_MCE_KBD = 11, /* RC6-ish MCE keyboard/mouse */ - RC_TYPE_RC6_0 = 12, /* Philips RC6-0-16 protocol */ - RC_TYPE_RC6_6A_20 = 13, /* Philips RC6-6A-20 protocol */ - RC_TYPE_RC6_6A_24 = 14, /* Philips RC6-6A-24 protocol */ - RC_TYPE_RC6_6A_32 = 15, /* Philips RC6-6A-32 protocol */ - RC_TYPE_RC6_MCE = 16, /* MCE (Philips RC6-6A-32 subtype) protocol */ - RC_TYPE_SHARP = 17, /* Sharp protocol */ - RC_TYPE_XMP = 18, /* XMP protocol */ - RC_TYPE_CEC = 19, /* CEC protocol */ + RC_TYPE_UNKNOWN = 0, + RC_TYPE_OTHER = 1, + RC_TYPE_RC5 = 2, + RC_TYPE_RC5X = 3, + RC_TYPE_RC5_SZ = 4, + RC_TYPE_JVC = 5, + RC_TYPE_SONY12 = 6, + RC_TYPE_SONY15 = 7, + RC_TYPE_SONY20 = 8, + RC_TYPE_NEC = 9, + RC_TYPE_SANYO = 10, + RC_TYPE_MCE_KBD = 11, + RC_TYPE_RC6_0 = 12, + RC_TYPE_RC6_6A_20 = 13, + RC_TYPE_RC6_6A_24 = 14, + RC_TYPE_RC6_6A_32 = 15, + RC_TYPE_RC6_MCE = 16, + RC_TYPE_SHARP = 17, + RC_TYPE_XMP = 18, + RC_TYPE_CEC = 19, }; #define RC_BIT_NONE 0ULL @@ -76,21 +100,45 @@ enum rc_type { #define RC_SCANCODE_RC6_0(sys, cmd) (((sys) << 8) | (cmd)) #define RC_SCANCODE_RC6_6A(vendor, sys, cmd) (((vendor) << 16) | ((sys) << 8) | (cmd)) +/** + * struct rc_map_table - represents a scancode/keycode pair + * + * @scancode: scan code (u32) + * @keycode: Linux input keycode + */ struct rc_map_table { u32 scancode; u32 keycode; }; +/** + * struct rc_map - represents a keycode map table + * + * @scan: pointer to struct &rc_map_table + * @size: Max number of entries + * @len: Number of entries that are in use + * @alloc: size of *scan, in bytes + * @rc_type: type of the remote controller protocol, as defined at + * enum &rc_type + * @name: name of the key map table + * @lock: lock to protect access to this structure + */ struct rc_map { struct rc_map_table *scan; - unsigned int size; /* Max number of entries */ - unsigned int len; /* Used number of entries */ - unsigned int alloc; /* Size of *scan in bytes */ + unsigned int size; + unsigned int len; + unsigned int alloc; enum rc_type rc_type; const char *name; spinlock_t lock; }; +/** + * struct rc_map_list - list of the registered &rc_map maps + * + * @list: pointer to struct &list_head + * @map: pointer to struct &rc_map + */ struct rc_map_list { struct list_head list; struct rc_map map; -- cgit v1.2.3 From 2257e180101c910c2d93dd226ab1e500e4a6813c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 29 Aug 2016 17:26:15 -0300 Subject: [media] v4l2-ctrls: document some extra data structures The typedefs and a macro are not defined. While here, improve a few bits on the documentation. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-ctrls.h | 51 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 44 insertions(+), 7 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h index 178a88d45aea..b8e043f63825 100644 --- a/include/media/v4l2-ctrls.h +++ b/include/media/v4l2-ctrls.h @@ -93,6 +93,16 @@ struct v4l2_ctrl_type_ops { union v4l2_ctrl_ptr ptr); }; +/** + * typedef v4l2_ctrl_notify_fnc - typedef for a notify argument with a function + * that should be called when a control value has changed. + * + * @ctrl: pointer to struct &v4l2_ctrl + * @priv: control private data + * + * This typedef definition is used as an argument to v4l2_ctrl_notify() + * and as an argument at struct &v4l2_ctrl_handler. + */ typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv); /** @@ -369,17 +379,38 @@ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type, * @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. + * .. attention:: + * + * Never use this call directly, always use the v4l2_ctrl_handler_init() + * macro that hides the @key and @name arguments. * - * Never use this call directly, always use the v4l2_ctrl_handler_init - * macro that hides the @key and @name arguments. + * Return: returns an error if the buckets could not be allocated. This + * error will also be stored in @hdl->error. */ int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl, unsigned int nr_of_controls_hint, struct lock_class_key *key, const char *name); #ifdef CONFIG_LOCKDEP + +/** + * v4l2_ctrl_handler_init - + * + * @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. + * + * This helper function creates a static struct &lock_class_key and + * calls v4l2_ctrl_handler_init_class(), providing a proper name for the lock + * validador. + * + * Use this helper function to initialize a control handler. + */ #define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint) \ ( \ ({ \ @@ -564,6 +595,13 @@ struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl, u32 id, u8 max, u8 def, const s64 *qmenu_int); +/** + * typedef v4l2_ctrl_filter - Typedef to define the filter function to be + * used when adding a control handler. + * + * @ctrl: pointer to struct &v4l2_ctrl. + */ + typedef bool (*v4l2_ctrl_filter)(const struct v4l2_ctrl *ctrl); /** @@ -635,8 +673,8 @@ void v4l2_ctrl_cluster(unsigned int ncontrols, struct v4l2_ctrl **controls); * 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) + * 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 int ncontrols, @@ -686,7 +724,6 @@ void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active); */ void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed); - /** *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range() * -- cgit v1.2.3 From fb91161a32bfe907720aff92318660ca8f6b9e71 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 29 Aug 2016 18:43:02 -0300 Subject: [media] v4l2-ctrls.h: fix doc reference for prepare_ext_ctrls() The prepare_ext_ctrls() function is actually internal to the v4l2-ctrls.c implementation, so it doesn't have a declaration for the kAPI header to reference it. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-ctrls.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h index b8e043f63825..3207449327d7 100644 --- a/include/media/v4l2-ctrls.h +++ b/include/media/v4l2-ctrls.h @@ -239,7 +239,7 @@ struct v4l2_ctrl { * @next: Single-link list node for the hash. * @ctrl: The actual control information. * @helper: Pointer to helper struct. Used internally in - * prepare_ext_ctrls(). + * ``prepare_ext_ctrls`` function at ``v4l2-ctrl.c``. * * 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 -- cgit v1.2.3 From ffa0441edca1ae462bdafe2743a4cde16f407f3a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 29 Aug 2016 18:40:21 -0300 Subject: [media] docs-rst: use C domain for enum references on uapi Change the parse-headers.pl and the corresponding files to use the C domain for enum references. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-dev.h | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h index 5272aeec0cec..477e90d89a04 100644 --- a/include/media/v4l2-dev.h +++ b/include/media/v4l2-dev.h @@ -56,7 +56,7 @@ struct v4l2_ctrl_handler; * * .. note:: * The size of @prios array matches the number of priority types defined - * by :ref:`enum v4l2_priority `. + * by enum &v4l2_priority. */ struct v4l2_prio_state { atomic_t prios[4]; @@ -73,8 +73,8 @@ void v4l2_prio_init(struct v4l2_prio_state *global); * v4l2_prio_change - changes the v4l2 file handler priority * * @global: pointer to the &struct v4l2_prio_state of the device node. - * @local: pointer to the desired priority, as defined by :ref:`enum v4l2_priority ` - * @new: Priority type requested, as defined by :ref:`enum v4l2_priority `. + * @local: pointer to the desired priority, as defined by enum &v4l2_priority + * @new: Priority type requested, as defined by enum &v4l2_priority. * * .. note:: * This function should be used only by the V4L2 core. @@ -86,7 +86,7 @@ int v4l2_prio_change(struct v4l2_prio_state *global, enum v4l2_priority *local, * v4l2_prio_open - Implements the priority logic for a file handler open * * @global: pointer to the &struct v4l2_prio_state of the device node. - * @local: pointer to the desired priority, as defined by :ref:`enum v4l2_priority ` + * @local: pointer to the desired priority, as defined by enum &v4l2_priority * * .. note:: * This function should be used only by the V4L2 core. @@ -97,7 +97,7 @@ void v4l2_prio_open(struct v4l2_prio_state *global, enum v4l2_priority *local); * v4l2_prio_close - Implements the priority logic for a file handler close * * @global: pointer to the &struct v4l2_prio_state of the device node. - * @local: priority to be released, as defined by :ref:`enum v4l2_priority ` + * @local: priority to be released, as defined by enum &v4l2_priority * * .. note:: * This function should be used only by the V4L2 core. @@ -118,7 +118,7 @@ enum v4l2_priority v4l2_prio_max(struct v4l2_prio_state *global); * v4l2_prio_close - Implements the priority logic for a file handler close * * @global: pointer to the &struct v4l2_prio_state of the device node. - * @local: desired priority, as defined by :ref:`enum v4l2_priority ` local + * @local: desired priority, as defined by enum &v4l2_priority local * * .. note:: * This function should be used only by the V4L2 core. -- cgit v1.2.3 From f8441a4334107ccd69c07164a38d9dde451cd85d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 29 Aug 2016 19:29:58 -0300 Subject: [media] v4l2-ctrls.h: Fix some c:type references Now that the uAPI is using c:type, let's use it here too. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-ctrls.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h index 3207449327d7..beea0a2c0894 100644 --- a/include/media/v4l2-ctrls.h +++ b/include/media/v4l2-ctrls.h @@ -973,9 +973,9 @@ extern const struct v4l2_subscribed_event_ops v4l2_ctrl_sub_ev_ops; * v4l2_ctrl_replace - Function to be used as a callback to * &struct v4l2_subscribed_event_ops replace\(\) * - * @old: pointer to :ref:`struct v4l2_event ` with the reported + * @old: pointer to struct &v4l2_event with the reported * event; - * @new: pointer to :ref:`struct v4l2_event ` with the modified + * @new: pointer to struct &v4l2_event with the modified * event; */ void v4l2_ctrl_replace(struct v4l2_event *old, const struct v4l2_event *new); @@ -984,9 +984,9 @@ void v4l2_ctrl_replace(struct v4l2_event *old, const struct v4l2_event *new); * v4l2_ctrl_merge - Function to be used as a callback to * &struct v4l2_subscribed_event_ops merge(\) * - * @old: pointer to :ref:`struct v4l2_event ` with the reported + * @old: pointer to struct &v4l2_event with the reported * event; - * @new: pointer to :ref:`struct v4l2_event ` with the merged + * @new: pointer to struct &v4l2_event with the merged * event; */ void v4l2_ctrl_merge(const struct v4l2_event *old, struct v4l2_event *new); -- cgit v1.2.3 From bba65c132fe4e57682861ff826e259efd7845492 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 30 Aug 2016 12:18:09 -0300 Subject: [media] v4l2-ioctl.h: document the remaining functions There are several undocumented functions here; document them. While here, make checkpatch.pl happy. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-ioctl.h | 510 +++++++++++++++++++++++++++------------------ 1 file changed, 304 insertions(+), 206 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-ioctl.h b/include/media/v4l2-ioctl.h index 8b1d19bc9b0e..574ff2ae94be 100644 --- a/include/media/v4l2-ioctl.h +++ b/include/media/v4l2-ioctl.h @@ -287,273 +287,286 @@ struct v4l2_ioctl_ops { /* ioctl callbacks */ /* VIDIOC_QUERYCAP handler */ - int (*vidioc_querycap)(struct file *file, void *fh, struct v4l2_capability *cap); + int (*vidioc_querycap)(struct file *file, void *fh, + struct v4l2_capability *cap); /* VIDIOC_ENUM_FMT handlers */ - int (*vidioc_enum_fmt_vid_cap) (struct file *file, void *fh, - struct v4l2_fmtdesc *f); - int (*vidioc_enum_fmt_vid_overlay) (struct file *file, void *fh, - struct v4l2_fmtdesc *f); - int (*vidioc_enum_fmt_vid_out) (struct file *file, void *fh, - struct v4l2_fmtdesc *f); + int (*vidioc_enum_fmt_vid_cap)(struct file *file, void *fh, + struct v4l2_fmtdesc *f); + int (*vidioc_enum_fmt_vid_overlay)(struct file *file, void *fh, + struct v4l2_fmtdesc *f); + int (*vidioc_enum_fmt_vid_out)(struct file *file, void *fh, + struct v4l2_fmtdesc *f); int (*vidioc_enum_fmt_vid_cap_mplane)(struct file *file, void *fh, struct v4l2_fmtdesc *f); int (*vidioc_enum_fmt_vid_out_mplane)(struct file *file, void *fh, struct v4l2_fmtdesc *f); - int (*vidioc_enum_fmt_sdr_cap) (struct file *file, void *fh, - struct v4l2_fmtdesc *f); - int (*vidioc_enum_fmt_sdr_out) (struct file *file, void *fh, - struct v4l2_fmtdesc *f); + int (*vidioc_enum_fmt_sdr_cap)(struct file *file, void *fh, + struct v4l2_fmtdesc *f); + int (*vidioc_enum_fmt_sdr_out)(struct file *file, void *fh, + struct v4l2_fmtdesc *f); /* VIDIOC_G_FMT handlers */ - int (*vidioc_g_fmt_vid_cap) (struct file *file, void *fh, - struct v4l2_format *f); + int (*vidioc_g_fmt_vid_cap)(struct file *file, void *fh, + struct v4l2_format *f); int (*vidioc_g_fmt_vid_overlay)(struct file *file, void *fh, struct v4l2_format *f); - int (*vidioc_g_fmt_vid_out) (struct file *file, void *fh, - struct v4l2_format *f); + int (*vidioc_g_fmt_vid_out)(struct file *file, void *fh, + struct v4l2_format *f); int (*vidioc_g_fmt_vid_out_overlay)(struct file *file, void *fh, - struct v4l2_format *f); - int (*vidioc_g_fmt_vbi_cap) (struct file *file, void *fh, - struct v4l2_format *f); - int (*vidioc_g_fmt_vbi_out) (struct file *file, void *fh, - struct v4l2_format *f); + struct v4l2_format *f); + int (*vidioc_g_fmt_vbi_cap)(struct file *file, void *fh, + struct v4l2_format *f); + int (*vidioc_g_fmt_vbi_out)(struct file *file, void *fh, + struct v4l2_format *f); int (*vidioc_g_fmt_sliced_vbi_cap)(struct file *file, void *fh, - struct v4l2_format *f); + struct v4l2_format *f); int (*vidioc_g_fmt_sliced_vbi_out)(struct file *file, void *fh, - struct v4l2_format *f); + struct v4l2_format *f); int (*vidioc_g_fmt_vid_cap_mplane)(struct file *file, void *fh, struct v4l2_format *f); int (*vidioc_g_fmt_vid_out_mplane)(struct file *file, void *fh, struct v4l2_format *f); - int (*vidioc_g_fmt_sdr_cap) (struct file *file, void *fh, - struct v4l2_format *f); - int (*vidioc_g_fmt_sdr_out) (struct file *file, void *fh, - struct v4l2_format *f); + int (*vidioc_g_fmt_sdr_cap)(struct file *file, void *fh, + struct v4l2_format *f); + int (*vidioc_g_fmt_sdr_out)(struct file *file, void *fh, + struct v4l2_format *f); /* VIDIOC_S_FMT handlers */ - int (*vidioc_s_fmt_vid_cap) (struct file *file, void *fh, - struct v4l2_format *f); + int (*vidioc_s_fmt_vid_cap)(struct file *file, void *fh, + struct v4l2_format *f); int (*vidioc_s_fmt_vid_overlay)(struct file *file, void *fh, struct v4l2_format *f); - int (*vidioc_s_fmt_vid_out) (struct file *file, void *fh, - struct v4l2_format *f); + int (*vidioc_s_fmt_vid_out)(struct file *file, void *fh, + struct v4l2_format *f); int (*vidioc_s_fmt_vid_out_overlay)(struct file *file, void *fh, - struct v4l2_format *f); - int (*vidioc_s_fmt_vbi_cap) (struct file *file, void *fh, - struct v4l2_format *f); - int (*vidioc_s_fmt_vbi_out) (struct file *file, void *fh, - struct v4l2_format *f); + struct v4l2_format *f); + int (*vidioc_s_fmt_vbi_cap)(struct file *file, void *fh, + struct v4l2_format *f); + int (*vidioc_s_fmt_vbi_out)(struct file *file, void *fh, + struct v4l2_format *f); int (*vidioc_s_fmt_sliced_vbi_cap)(struct file *file, void *fh, - struct v4l2_format *f); + struct v4l2_format *f); int (*vidioc_s_fmt_sliced_vbi_out)(struct file *file, void *fh, - struct v4l2_format *f); + struct v4l2_format *f); int (*vidioc_s_fmt_vid_cap_mplane)(struct file *file, void *fh, struct v4l2_format *f); int (*vidioc_s_fmt_vid_out_mplane)(struct file *file, void *fh, struct v4l2_format *f); - int (*vidioc_s_fmt_sdr_cap) (struct file *file, void *fh, - struct v4l2_format *f); - int (*vidioc_s_fmt_sdr_out) (struct file *file, void *fh, - struct v4l2_format *f); + int (*vidioc_s_fmt_sdr_cap)(struct file *file, void *fh, + struct v4l2_format *f); + int (*vidioc_s_fmt_sdr_out)(struct file *file, void *fh, + struct v4l2_format *f); /* VIDIOC_TRY_FMT handlers */ - int (*vidioc_try_fmt_vid_cap) (struct file *file, void *fh, - struct v4l2_format *f); + int (*vidioc_try_fmt_vid_cap)(struct file *file, void *fh, + struct v4l2_format *f); int (*vidioc_try_fmt_vid_overlay)(struct file *file, void *fh, struct v4l2_format *f); - int (*vidioc_try_fmt_vid_out) (struct file *file, void *fh, - struct v4l2_format *f); + int (*vidioc_try_fmt_vid_out)(struct file *file, void *fh, + struct v4l2_format *f); int (*vidioc_try_fmt_vid_out_overlay)(struct file *file, void *fh, - struct v4l2_format *f); - int (*vidioc_try_fmt_vbi_cap) (struct file *file, void *fh, - struct v4l2_format *f); - int (*vidioc_try_fmt_vbi_out) (struct file *file, void *fh, - struct v4l2_format *f); + struct v4l2_format *f); + int (*vidioc_try_fmt_vbi_cap)(struct file *file, void *fh, + struct v4l2_format *f); + int (*vidioc_try_fmt_vbi_out)(struct file *file, void *fh, + struct v4l2_format *f); int (*vidioc_try_fmt_sliced_vbi_cap)(struct file *file, void *fh, - struct v4l2_format *f); + struct v4l2_format *f); int (*vidioc_try_fmt_sliced_vbi_out)(struct file *file, void *fh, - struct v4l2_format *f); + struct v4l2_format *f); int (*vidioc_try_fmt_vid_cap_mplane)(struct file *file, void *fh, struct v4l2_format *f); int (*vidioc_try_fmt_vid_out_mplane)(struct file *file, void *fh, struct v4l2_format *f); - int (*vidioc_try_fmt_sdr_cap) (struct file *file, void *fh, - struct v4l2_format *f); - int (*vidioc_try_fmt_sdr_out) (struct file *file, void *fh, - struct v4l2_format *f); + int (*vidioc_try_fmt_sdr_cap)(struct file *file, void *fh, + struct v4l2_format *f); + int (*vidioc_try_fmt_sdr_out)(struct file *file, void *fh, + struct v4l2_format *f); /* Buffer handlers */ - int (*vidioc_reqbufs) (struct file *file, void *fh, struct v4l2_requestbuffers *b); - int (*vidioc_querybuf)(struct file *file, void *fh, struct v4l2_buffer *b); - int (*vidioc_qbuf) (struct file *file, void *fh, struct v4l2_buffer *b); - int (*vidioc_expbuf) (struct file *file, void *fh, - struct v4l2_exportbuffer *e); - int (*vidioc_dqbuf) (struct file *file, void *fh, struct v4l2_buffer *b); - - int (*vidioc_create_bufs)(struct file *file, void *fh, struct v4l2_create_buffers *b); - int (*vidioc_prepare_buf)(struct file *file, void *fh, struct v4l2_buffer *b); - - int (*vidioc_overlay) (struct file *file, void *fh, unsigned int i); - int (*vidioc_g_fbuf) (struct file *file, void *fh, - struct v4l2_framebuffer *a); - int (*vidioc_s_fbuf) (struct file *file, void *fh, - const struct v4l2_framebuffer *a); + int (*vidioc_reqbufs)(struct file *file, void *fh, + struct v4l2_requestbuffers *b); + int (*vidioc_querybuf)(struct file *file, void *fh, + struct v4l2_buffer *b); + int (*vidioc_qbuf)(struct file *file, void *fh, + struct v4l2_buffer *b); + int (*vidioc_expbuf)(struct file *file, void *fh, + struct v4l2_exportbuffer *e); + int (*vidioc_dqbuf)(struct file *file, void *fh, + struct v4l2_buffer *b); + + int (*vidioc_create_bufs)(struct file *file, void *fh, + struct v4l2_create_buffers *b); + int (*vidioc_prepare_buf)(struct file *file, void *fh, + struct v4l2_buffer *b); + + int (*vidioc_overlay)(struct file *file, void *fh, unsigned int i); + int (*vidioc_g_fbuf)(struct file *file, void *fh, + struct v4l2_framebuffer *a); + int (*vidioc_s_fbuf)(struct file *file, void *fh, + const struct v4l2_framebuffer *a); /* Stream on/off */ - int (*vidioc_streamon) (struct file *file, void *fh, enum v4l2_buf_type i); - int (*vidioc_streamoff)(struct file *file, void *fh, enum v4l2_buf_type i); - - /* Standard handling - ENUMSTD is handled by videodev.c + int (*vidioc_streamon)(struct file *file, void *fh, + enum v4l2_buf_type i); + int (*vidioc_streamoff)(struct file *file, void *fh, + enum v4l2_buf_type i); + + /* + * Standard handling + * + * Note: ENUMSTD is handled by videodev.c */ - int (*vidioc_g_std) (struct file *file, void *fh, v4l2_std_id *norm); - int (*vidioc_s_std) (struct file *file, void *fh, v4l2_std_id norm); - int (*vidioc_querystd) (struct file *file, void *fh, v4l2_std_id *a); + int (*vidioc_g_std)(struct file *file, void *fh, v4l2_std_id *norm); + int (*vidioc_s_std)(struct file *file, void *fh, v4l2_std_id norm); + int (*vidioc_querystd)(struct file *file, void *fh, v4l2_std_id *a); /* Input handling */ int (*vidioc_enum_input)(struct file *file, void *fh, struct v4l2_input *inp); - int (*vidioc_g_input) (struct file *file, void *fh, unsigned int *i); - int (*vidioc_s_input) (struct file *file, void *fh, unsigned int i); + int (*vidioc_g_input)(struct file *file, void *fh, unsigned int *i); + int (*vidioc_s_input)(struct file *file, void *fh, unsigned int i); /* Output handling */ - int (*vidioc_enum_output) (struct file *file, void *fh, + int (*vidioc_enum_output)(struct file *file, void *fh, struct v4l2_output *a); - int (*vidioc_g_output) (struct file *file, void *fh, unsigned int *i); - int (*vidioc_s_output) (struct file *file, void *fh, unsigned int i); + int (*vidioc_g_output)(struct file *file, void *fh, unsigned int *i); + int (*vidioc_s_output)(struct file *file, void *fh, unsigned int i); /* Control handling */ - int (*vidioc_queryctrl) (struct file *file, void *fh, - struct v4l2_queryctrl *a); - int (*vidioc_query_ext_ctrl) (struct file *file, void *fh, - struct v4l2_query_ext_ctrl *a); - int (*vidioc_g_ctrl) (struct file *file, void *fh, - struct v4l2_control *a); - int (*vidioc_s_ctrl) (struct file *file, void *fh, - struct v4l2_control *a); - int (*vidioc_g_ext_ctrls) (struct file *file, void *fh, - struct v4l2_ext_controls *a); - int (*vidioc_s_ext_ctrls) (struct file *file, void *fh, - struct v4l2_ext_controls *a); - int (*vidioc_try_ext_ctrls) (struct file *file, void *fh, - struct v4l2_ext_controls *a); - int (*vidioc_querymenu) (struct file *file, void *fh, - struct v4l2_querymenu *a); + int (*vidioc_queryctrl)(struct file *file, void *fh, + struct v4l2_queryctrl *a); + int (*vidioc_query_ext_ctrl)(struct file *file, void *fh, + struct v4l2_query_ext_ctrl *a); + int (*vidioc_g_ctrl)(struct file *file, void *fh, + struct v4l2_control *a); + int (*vidioc_s_ctrl)(struct file *file, void *fh, + struct v4l2_control *a); + int (*vidioc_g_ext_ctrls)(struct file *file, void *fh, + struct v4l2_ext_controls *a); + int (*vidioc_s_ext_ctrls)(struct file *file, void *fh, + struct v4l2_ext_controls *a); + int (*vidioc_try_ext_ctrls)(struct file *file, void *fh, + struct v4l2_ext_controls *a); + int (*vidioc_querymenu)(struct file *file, void *fh, + struct v4l2_querymenu *a); /* Audio ioctls */ - int (*vidioc_enumaudio) (struct file *file, void *fh, - struct v4l2_audio *a); - int (*vidioc_g_audio) (struct file *file, void *fh, - struct v4l2_audio *a); - int (*vidioc_s_audio) (struct file *file, void *fh, - const struct v4l2_audio *a); + int (*vidioc_enumaudio)(struct file *file, void *fh, + struct v4l2_audio *a); + int (*vidioc_g_audio)(struct file *file, void *fh, + struct v4l2_audio *a); + int (*vidioc_s_audio)(struct file *file, void *fh, + const struct v4l2_audio *a); /* Audio out ioctls */ - int (*vidioc_enumaudout) (struct file *file, void *fh, - struct v4l2_audioout *a); - int (*vidioc_g_audout) (struct file *file, void *fh, - struct v4l2_audioout *a); - int (*vidioc_s_audout) (struct file *file, void *fh, - const struct v4l2_audioout *a); - int (*vidioc_g_modulator) (struct file *file, void *fh, - struct v4l2_modulator *a); - int (*vidioc_s_modulator) (struct file *file, void *fh, - const struct v4l2_modulator *a); + int (*vidioc_enumaudout)(struct file *file, void *fh, + struct v4l2_audioout *a); + int (*vidioc_g_audout)(struct file *file, void *fh, + struct v4l2_audioout *a); + int (*vidioc_s_audout)(struct file *file, void *fh, + const struct v4l2_audioout *a); + int (*vidioc_g_modulator)(struct file *file, void *fh, + struct v4l2_modulator *a); + int (*vidioc_s_modulator)(struct file *file, void *fh, + const struct v4l2_modulator *a); /* Crop ioctls */ - int (*vidioc_cropcap) (struct file *file, void *fh, - struct v4l2_cropcap *a); - int (*vidioc_g_crop) (struct file *file, void *fh, - struct v4l2_crop *a); - int (*vidioc_s_crop) (struct file *file, void *fh, - const struct v4l2_crop *a); - int (*vidioc_g_selection) (struct file *file, void *fh, - struct v4l2_selection *s); - int (*vidioc_s_selection) (struct file *file, void *fh, - struct v4l2_selection *s); + int (*vidioc_cropcap)(struct file *file, void *fh, + struct v4l2_cropcap *a); + int (*vidioc_g_crop)(struct file *file, void *fh, + struct v4l2_crop *a); + int (*vidioc_s_crop)(struct file *file, void *fh, + const struct v4l2_crop *a); + int (*vidioc_g_selection)(struct file *file, void *fh, + struct v4l2_selection *s); + int (*vidioc_s_selection)(struct file *file, void *fh, + struct v4l2_selection *s); /* Compression ioctls */ - int (*vidioc_g_jpegcomp) (struct file *file, void *fh, - struct v4l2_jpegcompression *a); - int (*vidioc_s_jpegcomp) (struct file *file, void *fh, - const struct v4l2_jpegcompression *a); - int (*vidioc_g_enc_index) (struct file *file, void *fh, - struct v4l2_enc_idx *a); - int (*vidioc_encoder_cmd) (struct file *file, void *fh, - struct v4l2_encoder_cmd *a); - int (*vidioc_try_encoder_cmd) (struct file *file, void *fh, - struct v4l2_encoder_cmd *a); - int (*vidioc_decoder_cmd) (struct file *file, void *fh, - struct v4l2_decoder_cmd *a); - int (*vidioc_try_decoder_cmd) (struct file *file, void *fh, - struct v4l2_decoder_cmd *a); + int (*vidioc_g_jpegcomp)(struct file *file, void *fh, + struct v4l2_jpegcompression *a); + int (*vidioc_s_jpegcomp)(struct file *file, void *fh, + const struct v4l2_jpegcompression *a); + int (*vidioc_g_enc_index)(struct file *file, void *fh, + struct v4l2_enc_idx *a); + int (*vidioc_encoder_cmd)(struct file *file, void *fh, + struct v4l2_encoder_cmd *a); + int (*vidioc_try_encoder_cmd)(struct file *file, void *fh, + struct v4l2_encoder_cmd *a); + int (*vidioc_decoder_cmd)(struct file *file, void *fh, + struct v4l2_decoder_cmd *a); + int (*vidioc_try_decoder_cmd)(struct file *file, void *fh, + struct v4l2_decoder_cmd *a); /* Stream type-dependent parameter ioctls */ - int (*vidioc_g_parm) (struct file *file, void *fh, - struct v4l2_streamparm *a); - int (*vidioc_s_parm) (struct file *file, void *fh, - struct v4l2_streamparm *a); + int (*vidioc_g_parm)(struct file *file, void *fh, + struct v4l2_streamparm *a); + int (*vidioc_s_parm)(struct file *file, void *fh, + struct v4l2_streamparm *a); /* Tuner ioctls */ - int (*vidioc_g_tuner) (struct file *file, void *fh, - struct v4l2_tuner *a); - int (*vidioc_s_tuner) (struct file *file, void *fh, - const struct v4l2_tuner *a); - int (*vidioc_g_frequency) (struct file *file, void *fh, - struct v4l2_frequency *a); - int (*vidioc_s_frequency) (struct file *file, void *fh, - const struct v4l2_frequency *a); - int (*vidioc_enum_freq_bands) (struct file *file, void *fh, - struct v4l2_frequency_band *band); + int (*vidioc_g_tuner)(struct file *file, void *fh, + struct v4l2_tuner *a); + int (*vidioc_s_tuner)(struct file *file, void *fh, + const struct v4l2_tuner *a); + int (*vidioc_g_frequency)(struct file *file, void *fh, + struct v4l2_frequency *a); + int (*vidioc_s_frequency)(struct file *file, void *fh, + const struct v4l2_frequency *a); + int (*vidioc_enum_freq_bands)(struct file *file, void *fh, + struct v4l2_frequency_band *band); /* Sliced VBI cap */ - int (*vidioc_g_sliced_vbi_cap) (struct file *file, void *fh, - struct v4l2_sliced_vbi_cap *a); + int (*vidioc_g_sliced_vbi_cap)(struct file *file, void *fh, + struct v4l2_sliced_vbi_cap *a); /* Log status ioctl */ - int (*vidioc_log_status) (struct file *file, void *fh); + int (*vidioc_log_status)(struct file *file, void *fh); - int (*vidioc_s_hw_freq_seek) (struct file *file, void *fh, - const struct v4l2_hw_freq_seek *a); + int (*vidioc_s_hw_freq_seek)(struct file *file, void *fh, + const struct v4l2_hw_freq_seek *a); /* Debugging ioctls */ #ifdef CONFIG_VIDEO_ADV_DEBUG - int (*vidioc_g_register) (struct file *file, void *fh, - struct v4l2_dbg_register *reg); - int (*vidioc_s_register) (struct file *file, void *fh, - const struct v4l2_dbg_register *reg); + int (*vidioc_g_register)(struct file *file, void *fh, + struct v4l2_dbg_register *reg); + int (*vidioc_s_register)(struct file *file, void *fh, + const struct v4l2_dbg_register *reg); - int (*vidioc_g_chip_info) (struct file *file, void *fh, - struct v4l2_dbg_chip_info *chip); + int (*vidioc_g_chip_info)(struct file *file, void *fh, + struct v4l2_dbg_chip_info *chip); #endif - int (*vidioc_enum_framesizes) (struct file *file, void *fh, - struct v4l2_frmsizeenum *fsize); + int (*vidioc_enum_framesizes)(struct file *file, void *fh, + struct v4l2_frmsizeenum *fsize); - int (*vidioc_enum_frameintervals) (struct file *file, void *fh, - struct v4l2_frmivalenum *fival); + int (*vidioc_enum_frameintervals)(struct file *file, void *fh, + struct v4l2_frmivalenum *fival); /* DV Timings IOCTLs */ - int (*vidioc_s_dv_timings) (struct file *file, void *fh, - struct v4l2_dv_timings *timings); - int (*vidioc_g_dv_timings) (struct file *file, void *fh, - struct v4l2_dv_timings *timings); - int (*vidioc_query_dv_timings) (struct file *file, void *fh, - struct v4l2_dv_timings *timings); - int (*vidioc_enum_dv_timings) (struct file *file, void *fh, - struct v4l2_enum_dv_timings *timings); - int (*vidioc_dv_timings_cap) (struct file *file, void *fh, - struct v4l2_dv_timings_cap *cap); - int (*vidioc_g_edid) (struct file *file, void *fh, struct v4l2_edid *edid); - int (*vidioc_s_edid) (struct file *file, void *fh, struct v4l2_edid *edid); - - int (*vidioc_subscribe_event) (struct v4l2_fh *fh, - const struct v4l2_event_subscription *sub); + int (*vidioc_s_dv_timings)(struct file *file, void *fh, + struct v4l2_dv_timings *timings); + int (*vidioc_g_dv_timings)(struct file *file, void *fh, + struct v4l2_dv_timings *timings); + int (*vidioc_query_dv_timings)(struct file *file, void *fh, + struct v4l2_dv_timings *timings); + int (*vidioc_enum_dv_timings)(struct file *file, void *fh, + struct v4l2_enum_dv_timings *timings); + int (*vidioc_dv_timings_cap)(struct file *file, void *fh, + struct v4l2_dv_timings_cap *cap); + int (*vidioc_g_edid)(struct file *file, void *fh, + struct v4l2_edid *edid); + int (*vidioc_s_edid)(struct file *file, void *fh, + struct v4l2_edid *edid); + + int (*vidioc_subscribe_event)(struct v4l2_fh *fh, + const struct v4l2_event_subscription *sub); int (*vidioc_unsubscribe_event)(struct v4l2_fh *fh, const struct v4l2_event_subscription *sub); /* For other private ioctls */ - long (*vidioc_default) (struct file *file, void *fh, - bool valid_prio, unsigned int cmd, void *arg); + long (*vidioc_default)(struct file *file, void *fh, + bool valid_prio, unsigned int cmd, void *arg); }; @@ -573,38 +586,123 @@ struct v4l2_ioctl_ops { #define V4L2_DEV_DEBUG_POLL 0x10 /* Video standard functions */ -extern const char *v4l2_norm_to_name(v4l2_std_id id); -extern void v4l2_video_std_frame_period(int id, struct v4l2_fract *frameperiod); -extern int v4l2_video_std_construct(struct v4l2_standard *vs, + +/** + * v4l2_norm_to_name - Ancillary routine to analog TV standard name from its ID. + * + * @id: analog TV standard ID. + * + * Return: returns a string with the name of the analog TV standard. + * If the standard is not found or if @id points to multiple standard, + * it returns "Unknown". + */ +const char *v4l2_norm_to_name(v4l2_std_id id); + +/** + * v4l2_video_std_frame_period - Ancillary routine that fills a + * struct &v4l2_fract pointer with the default framerate fraction. + * + * @id: analog TV sdandard ID. + * @frameperiod: struct &v4l2_fract pointer to be filled + * + */ +void v4l2_video_std_frame_period(int id, struct v4l2_fract *frameperiod); + +/** + * v4l2_video_std_construct - Ancillary routine that fills in the fields of + * a &v4l2_standard structure according to the @id parameter. + * + * @vs: struct &v4l2_standard pointer to be filled + * @id: analog TV sdandard ID. + * @name: name of the standard to be used + * + * .. note:: + * + * This ancillary routine is obsolete. Shouldn't be used on newer drivers. + */ +int v4l2_video_std_construct(struct v4l2_standard *vs, int id, const char *name); -/* Prints the ioctl in a human-readable format. If prefix != NULL, - then do printk(KERN_DEBUG "%s: ", prefix) first. */ -extern void v4l_printk_ioctl(const char *prefix, unsigned int cmd); -/* Internal use only: get the mutex (if any) that we need to lock for the - given command. */ +/** + * v4l_printk_ioctl - Ancillary routine that prints the ioctl in a + * human-readable format. + * + * @prefix: prefix to be added at the ioctl prints. + * @cmd: ioctl name + * + * .. note:: + * + * If prefix != %NULL, then it will issue a + * ``printk(KERN_DEBUG "%s: ", prefix)`` first. + */ +void v4l_printk_ioctl(const char *prefix, unsigned int cmd); + struct video_device; -extern struct mutex *v4l2_ioctl_get_lock(struct video_device *vdev, unsigned cmd); + + +/** + * v4l2_ioctl_get_lock - get the mutex (if any) that it is need to lock for + * a given command. + * + * @vdev: Pointer to struct &video_device. + * @cmd: Ioctl name. + * + * .. note:: Internal use only. Should not be used outside V4L2 core. + */ +struct mutex *v4l2_ioctl_get_lock(struct video_device *vdev, unsigned int cmd); /* names for fancy debug output */ extern const char *v4l2_field_names[]; extern const char *v4l2_type_names[]; #ifdef CONFIG_COMPAT -/* 32 Bits compatibility layer for 64 bits processors */ -extern long v4l2_compat_ioctl32(struct file *file, unsigned int cmd, - unsigned long arg); +/** + * v4l2_compat_ioctl32 -32 Bits compatibility layer for 64 bits processors + * + * @file: Pointer to struct &file. + * @cmd: Ioctl name. + * @arg: Ioctl argument. + */ +long int v4l2_compat_ioctl32(struct file *file, unsigned int cmd, + unsigned long arg); #endif -typedef long (*v4l2_kioctl)(struct file *file, - unsigned int cmd, void *arg); +/** + * typedef v4l2_kioctl - Typedef used to pass an ioctl handler. + * + * @file: Pointer to struct &file. + * @cmd: Ioctl name. + * @arg: Ioctl argument. + */ +typedef long (*v4l2_kioctl)(struct file *file, unsigned int cmd, void *arg); -/* Include support for obsoleted stuff */ -extern long video_usercopy(struct file *file, unsigned int cmd, - unsigned long arg, v4l2_kioctl func); +/** + * video_usercopy - copies data from/to userspace memory when an ioctl is + * issued. + * + * @file: Pointer to struct &file. + * @cmd: Ioctl name. + * @arg: Ioctl argument. + * @func: function that will handle the ioctl + * + * .. note:: + * + * This routine should be used only inside the V4L2 core. + */ +long int video_usercopy(struct file *file, unsigned int cmd, + unsigned long int arg, v4l2_kioctl func); -/* Standard handlers for V4L ioctl's */ -extern long video_ioctl2(struct file *file, - unsigned int cmd, unsigned long arg); +/** + * video_ioctl2 - Handles a V4L2 ioctl. + * + * @file: Pointer to struct &file. + * @cmd: Ioctl name. + * @arg: Ioctl argument. + * + * Method used to hancle an ioctl. Should be used to fill the + * &v4l2_ioctl_ops.unlocked_ioctl on all V4L2 drivers. + */ +long int video_ioctl2(struct file *file, + unsigned int cmd, unsigned long int arg); #endif /* _V4L2_IOCTL_H */ -- cgit v1.2.3 From 65d7aba0d3c32fc686fe19e146b8cd8a0a87952d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 30 Aug 2016 19:16:25 -0300 Subject: [media] v4l2-device.h: fix some doc tags Fix some minor issues at the documentation tags on this file, adding cross-references where needed, and fixing some broken ones. While here, fix a few spaces before tabs to make Checkpatch happier. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-device.h | 68 ++++++++++++++++++++++----------------------- 1 file changed, 34 insertions(+), 34 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-device.h b/include/media/v4l2-device.h index a9d6aa41790e..8ffa94009d1a 100644 --- a/include/media/v4l2-device.h +++ b/include/media/v4l2-device.h @@ -39,7 +39,7 @@ struct v4l2_ctrl_handler; * if this struct is embedded into a larger struct. * @name: unique device name, by default the driver name + bus ID * @notify: notify callback called by some sub-devices. - * @ctrl_handler: The control handler. May be NULL. + * @ctrl_handler: The control handler. May be %NULL. * @prio: Device's priority state * @ref: Keep track of the references to this struct. * @release: Release function that is called when the ref count @@ -53,8 +53,8 @@ struct v4l2_ctrl_handler; * * .. note:: * - * #) dev->driver_data points to this struct. - * #) dev might be NULL if there is no parent device + * #) @dev->driver_data points to this struct. + * #) @dev might be %NULL if there is no parent device */ struct v4l2_device { @@ -76,10 +76,10 @@ struct v4l2_device { /** * v4l2_device_get - gets a V4L2 device reference * - * @v4l2_dev: pointer to struct v4l2_device + * @v4l2_dev: pointer to struct &v4l2_device * * This is an ancillary routine meant to increment the usage for the - * struct v4l2_device pointed by @v4l2_dev. + * struct &v4l2_device pointed by @v4l2_dev. */ static inline void v4l2_device_get(struct v4l2_device *v4l2_dev) { @@ -89,23 +89,23 @@ static inline void v4l2_device_get(struct v4l2_device *v4l2_dev) /** * v4l2_device_put - putss a V4L2 device reference * - * @v4l2_dev: pointer to struct v4l2_device + * @v4l2_dev: pointer to struct &v4l2_device * * This is an ancillary routine meant to decrement the usage for the - * struct v4l2_device pointed by @v4l2_dev. + * struct &v4l2_device pointed by @v4l2_dev. */ int v4l2_device_put(struct v4l2_device *v4l2_dev); /** - * v4l2_device_register -Initialize v4l2_dev and make dev->driver_data - * point to v4l2_dev. + * v4l2_device_register - Initialize v4l2_dev and make @dev->driver_data + * point to @v4l2_dev. * - * @dev: pointer to struct device - * @v4l2_dev: pointer to struct v4l2_device + * @dev: pointer to struct &device + * @v4l2_dev: pointer to struct &v4l2_device * * .. note:: - * dev may be NULL in rare cases (ISA devices). - * In such case the caller must fill in the v4l2_dev->name field + * @dev may be %NULL in rare cases (ISA devices). + * In such case the caller must fill in the @v4l2_dev->name field * before calling this function. */ int __must_check v4l2_device_register(struct device *dev, @@ -113,14 +113,14 @@ int __must_check v4l2_device_register(struct device *dev, /** * v4l2_device_set_name - Optional function to initialize the - * name field of struct v4l2_device + * name field of struct &v4l2_device * - * @v4l2_dev: pointer to struct v4l2_device + * @v4l2_dev: pointer to struct &v4l2_device * @basename: base name for the device name * @instance: pointer to a static atomic_t var with the instance usage for - * the device driver. + * the device driver. * - * v4l2_device_set_name() initializes the name field of struct v4l2_device + * v4l2_device_set_name() initializes the name field of struct &v4l2_device * using the driver name and a driver-global atomic_t instance. * * This function will increment the instance counter and returns the @@ -132,7 +132,7 @@ int __must_check v4l2_device_register(struct device *dev, * * ... * - * instance = v4l2_device_set_name(&v4l2_dev, "foo", &drv_instance); + * instance = v4l2_device_set_name(&\ v4l2_dev, "foo", &\ drv_instance); * * The first time this is called the name field will be set to foo0 and * this function returns 0. If the name ends with a digit (e.g. cx18), @@ -147,16 +147,16 @@ int v4l2_device_set_name(struct v4l2_device *v4l2_dev, const char *basename, * @v4l2_dev: pointer to struct v4l2_device * * Should be called when the USB parent disconnects. - * Since the parent disappears, this ensures that v4l2_dev doesn't have + * Since the parent disappears, this ensures that @v4l2_dev doesn't have * an invalid parent pointer. * - * .. note:: This function sets v4l2_dev->dev to NULL. + * .. note:: This function sets @v4l2_dev->dev to NULL. */ void v4l2_device_disconnect(struct v4l2_device *v4l2_dev); /** * v4l2_device_unregister - Unregister all sub-devices and any other - * resources related to v4l2_dev. + * resources related to @v4l2_dev. * * @v4l2_dev: pointer to struct v4l2_device */ @@ -165,8 +165,8 @@ void v4l2_device_unregister(struct v4l2_device *v4l2_dev); /** * v4l2_device_register_subdev - Registers a subdev with a v4l2 device. * - * @v4l2_dev: pointer to struct v4l2_device - * @sd: pointer to struct v4l2_subdev + * @v4l2_dev: pointer to struct &v4l2_device + * @sd: pointer to struct &v4l2_subdev * * While registered, the subdev module is marked as in-use. * @@ -179,7 +179,7 @@ int __must_check v4l2_device_register_subdev(struct v4l2_device *v4l2_dev, /** * v4l2_device_unregister_subdev - Unregisters a subdev with a v4l2 device. * - * @sd: pointer to struct v4l2_subdev + * @sd: pointer to struct &v4l2_subdev * * .. note :: * @@ -191,7 +191,7 @@ void v4l2_device_unregister_subdev(struct v4l2_subdev *sd); /** * v4l2_device_register_subdev_nodes - Registers device nodes for all subdevs * of the v4l2 device that are marked with - * the V4L2_SUBDEV_FL_HAS_DEVNODE flag. + * the %V4L2_SUBDEV_FL_HAS_DEVNODE flag. * * @v4l2_dev: pointer to struct v4l2_device */ @@ -201,9 +201,9 @@ v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev); /** * v4l2_subdev_notify - Sends a notification to v4l2_device. * - * @sd: pointer to struct v4l2_subdev + * @sd: pointer to struct &v4l2_subdev * @notification: type of notification. Please notice that the notification - * type is driver-specific. + * type is driver-specific. * @arg: arguments for the notification. Those are specific to each * notification type. */ @@ -222,7 +222,7 @@ static inline void v4l2_subdev_notify(struct v4l2_subdev *sd, Ignore any errors. Note that you cannot add or delete a subdev while walking the subdevs list. */ #define __v4l2_device_call_subdevs_p(v4l2_dev, sd, cond, o, f, args...) \ - do { \ + do { \ list_for_each_entry((sd), &(v4l2_dev)->subdevs, list) \ if ((cond) && (sd)->ops->o && (sd)->ops->o->f) \ (sd)->ops->o->f((sd) , ##args); \ @@ -241,15 +241,15 @@ static inline void v4l2_subdev_notify(struct v4l2_subdev *sd, return with that error code. Note that you cannot add or delete a subdev while walking the subdevs list. */ #define __v4l2_device_call_subdevs_until_err_p(v4l2_dev, sd, cond, o, f, args...) \ -({ \ +({ \ long __err = 0; \ \ list_for_each_entry((sd), &(v4l2_dev)->subdevs, list) { \ if ((cond) && (sd)->ops->o && (sd)->ops->o->f) \ __err = (sd)->ops->o->f((sd) , ##args); \ if (__err && __err != -ENOIOCTLCMD) \ - break; \ - } \ + break; \ + } \ (__err == -ENOIOCTLCMD) ? 0 : __err; \ }) @@ -276,7 +276,7 @@ static inline void v4l2_subdev_notify(struct v4l2_subdev *sd, match them all). If the callback returns an error other than 0 or -ENOIOCTLCMD, then return with that error code. Note that you cannot add or delete a subdev while walking the subdevs list. */ -#define v4l2_device_call_until_err(v4l2_dev, grpid, o, f, args...) \ +#define v4l2_device_call_until_err(v4l2_dev, grpid, o, f, args...) \ ({ \ struct v4l2_subdev *__sd; \ __v4l2_device_call_subdevs_until_err_p(v4l2_dev, __sd, \ @@ -300,8 +300,8 @@ static inline void v4l2_subdev_notify(struct v4l2_subdev *sd, /* * Call the specified callback for all subdevs where grp_id & grpmsk != 0 - * (if grpmsk == `0, then match them all). If the callback returns an error - * other than 0 or -ENOIOCTLCMD, then return with that error code. Note that + * (if grpmsk == 0, then match them all). If the callback returns an error + * other than 0 or %-ENOIOCTLCMD, then return with that error code. Note that * you cannot add or delete a subdev while walking the subdevs list. */ #define v4l2_device_mask_call_until_err(v4l2_dev, grpmsk, o, f, args...) \ -- cgit v1.2.3 From f06606e56bc61d65cbc1ad3a8dc6e81ec1b2034e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 30 Aug 2016 20:11:11 -0300 Subject: [media] v4l2-dv-timings.h: let kernel-doc parte the typedef argument Now that scripts/kernel-doc was fixed to parse the typedef argument used here, let it produce documentation. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-dv-timings.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-dv-timings.h b/include/media/v4l2-dv-timings.h index 65caadf13eec..0a7d9e1fc8c8 100644 --- a/include/media/v4l2-dv-timings.h +++ b/include/media/v4l2-dv-timings.h @@ -28,8 +28,8 @@ */ extern const struct v4l2_dv_timings v4l2_dv_timings_presets[]; -/* - * v4l2_check_dv_timings_fnc - timings check callback +/** + * typedef v4l2_check_dv_timings_fnc - timings check callback * * @t: the v4l2_dv_timings struct. * @handle: a handle from the driver. -- cgit v1.2.3 From 59d44bbe46fe876c55d5cc051d552b1debb1c454 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 30 Aug 2016 21:08:17 -0300 Subject: [media] v4l2-subdev.h: fix a doc nitpick warning One markup tag is wrong here. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-subdev.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h index 6e1d044e3ee8..2c1e328ccb1d 100644 --- a/include/media/v4l2-subdev.h +++ b/include/media/v4l2-subdev.h @@ -226,7 +226,7 @@ struct v4l2_subdev_core_ops { * * @g_tuner: callback for %VIDIOC_G_TUNER ioctl handler code. * - * @s_tuner: callback for %VIDIOC_S_TUNER ioctl handler code. &vt->type must be + * @s_tuner: callback for %VIDIOC_S_TUNER ioctl handler code. @vt->type must be * filled in. Normally done by video_ioctl2 or the * bridge driver. * -- cgit v1.2.3 From 848d10314bfe1be79f5ca4deb3d2bf81f6adcf38 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 31 Aug 2016 16:34:07 -0300 Subject: [media] fix broken references on dvb/video*rst Trivially fix those broken references, by copying the structs fron the header, just like other API documentation at the DVB side. This doesn't have the level of quality used at the V4L2 side of the API, but, as this documents a deprecated API, used only by av7110 driver, it doesn't make much sense to invest time making it better. Signed-off-by: Mauro Carvalho Chehab --- include/uapi/linux/dvb/video.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'include') diff --git a/include/uapi/linux/dvb/video.h b/include/uapi/linux/dvb/video.h index 49392564f9d6..260f033a5b54 100644 --- a/include/uapi/linux/dvb/video.h +++ b/include/uapi/linux/dvb/video.h @@ -206,7 +206,8 @@ typedef __u16 video_attributes_t; /* 6 line 21-2 data present in GOP (1=yes, 0=no) */ /* 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */ /* 2 source letterboxed (1=yes, 0=no) */ -/* 0 film/camera mode (0=camera, 1=film (625/50 only)) */ +/* 0 film/camera mode (0= + *camera, 1=film (625/50 only)) */ /* bit definitions for capabilities: */ -- cgit v1.2.3 From c13dce18b8266566e951b1d4b9bbbbbf25a00068 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 08:18:04 -0300 Subject: [media] rc-map.h: fix a Sphinx warning ./include/media/rc-map.h:121: WARNING: Inline emphasis start-string without end-string. Signed-off-by: Mauro Carvalho Chehab --- include/media/rc-map.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/media/rc-map.h b/include/media/rc-map.h index 173ad58fb61b..3c8edb34f84a 100644 --- a/include/media/rc-map.h +++ b/include/media/rc-map.h @@ -117,7 +117,7 @@ struct rc_map_table { * @scan: pointer to struct &rc_map_table * @size: Max number of entries * @len: Number of entries that are in use - * @alloc: size of *scan, in bytes + * @alloc: size of \*scan, in bytes * @rc_type: type of the remote controller protocol, as defined at * enum &rc_type * @name: name of the key map table -- cgit v1.2.3 From 82631b5bb268f670613db110177483ae3e85f913 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 09:57:24 -0300 Subject: [media] mc-core.rst: fix a warning about an internal routine Fix this warning: Documentation/media/kapi/mc-core.rst:97: WARNING: c:func reference target not found: media_devnode_release The media_device_release() is a function internal to media-devnode.c, and not exported elsewhere. So, we can't cross-reference it here. Make it explicit at the documentation. Signed-off-by: Mauro Carvalho Chehab --- include/media/media-devnode.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'include') diff --git a/include/media/media-devnode.h b/include/media/media-devnode.h index 972168e90413..cd23e915764c 100644 --- a/include/media/media-devnode.h +++ b/include/media/media-devnode.h @@ -76,7 +76,8 @@ struct media_file_operations { * @parent: parent device * @minor: device node minor number * @flags: flags, combination of the ``MEDIA_FLAG_*`` constants - * @release: release callback called at the end of media_devnode_release() + * @release: release callback called at the end of ``media_devnode_release()`` + * routine at media-device.c. * * This structure represents a media-related device node. * -- cgit v1.2.3 From 4781646c1e13b23ed31eb12f7e314824d98ce066 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 10:16:27 -0300 Subject: [media] v4l2-mem2mem.h: move descriptions from .c file Several routines are somewhat documented at v4l2-mem2mem.c file. Move what's there to the header file. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-mem2mem.h | 132 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) (limited to 'include') diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h index 5a9597dd1ee0..e5449a2c8475 100644 --- a/include/media/v4l2-mem2mem.h +++ b/include/media/v4l2-mem2mem.h @@ -94,13 +94,52 @@ struct v4l2_m2m_buffer { struct list_head list; }; +/** + * v4l2_m2m_get_curr_priv() - return driver private data for the currently + * running instance or NULL if no instance is running + */ void *v4l2_m2m_get_curr_priv(struct v4l2_m2m_dev *m2m_dev); +/** + * v4l2_m2m_get_vq() - return vb2_queue for the given type + */ struct vb2_queue *v4l2_m2m_get_vq(struct v4l2_m2m_ctx *m2m_ctx, enum v4l2_buf_type type); +/** + * v4l2_m2m_try_schedule() - check whether an instance is ready to be added to + * the pending job queue and add it if so. + * @m2m_ctx: m2m context assigned to the instance to be checked + * + * There are three basic requirements an instance has to meet to be able to run: + * 1) at least one source buffer has to be queued, + * 2) at least one destination buffer has to be queued, + * 3) streaming has to be on. + * + * If a queue is buffered (for example a decoder hardware ringbuffer that has + * to be drained before doing streamoff), allow scheduling without v4l2 buffers + * on that queue. + * + * There may also be additional, custom requirements. In such case the driver + * should supply a custom callback (job_ready in v4l2_m2m_ops) that should + * return 1 if the instance is ready. + * An example of the above could be an instance that requires more than one + * src/dst buffer per transaction. + */ void v4l2_m2m_try_schedule(struct v4l2_m2m_ctx *m2m_ctx); +/** + * v4l2_m2m_job_finish() - inform the framework that a job has been finished + * and have it clean up + * + * Called by a driver to yield back the device after it has finished with it. + * Should be called as soon as possible after reaching a state which allows + * other instances to take control of the device. + * + * This function has to be called only after device_run() callback has been + * called on the driver. To prevent recursion, it should not be called directly + * from the device_run() callback though. + */ void v4l2_m2m_job_finish(struct v4l2_m2m_dev *m2m_dev, struct v4l2_m2m_ctx *m2m_ctx); @@ -110,38 +149,114 @@ v4l2_m2m_buf_done(struct vb2_v4l2_buffer *buf, enum vb2_buffer_state state) vb2_buffer_done(&buf->vb2_buf, state); } +/** + * v4l2_m2m_reqbufs() - multi-queue-aware REQBUFS multiplexer + */ int v4l2_m2m_reqbufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_requestbuffers *reqbufs); +/** + * v4l2_m2m_querybuf() - multi-queue-aware QUERYBUF multiplexer + * + * See v4l2_m2m_mmap() documentation for details. + */ int v4l2_m2m_querybuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_buffer *buf); +/** + * v4l2_m2m_qbuf() - enqueue a source or destination buffer, depending on + * the type + */ int v4l2_m2m_qbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_buffer *buf); + +/** + * v4l2_m2m_dqbuf() - dequeue a source or destination buffer, depending on + * the type + */ int v4l2_m2m_dqbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_buffer *buf); + +/** + * v4l2_m2m_prepare_buf() - prepare a source or destination buffer, depending on + * the type + */ int v4l2_m2m_prepare_buf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_buffer *buf); + +/** + * v4l2_m2m_create_bufs() - create a source or destination buffer, depending + * on the type + */ int v4l2_m2m_create_bufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_create_buffers *create); +/** + * v4l2_m2m_expbuf() - export a source or destination buffer, depending on + * the type + */ int v4l2_m2m_expbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_exportbuffer *eb); +/** + * v4l2_m2m_streamon() - turn on streaming for a video queue + */ int v4l2_m2m_streamon(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, enum v4l2_buf_type type); + +/** + * v4l2_m2m_streamoff() - turn off streaming for a video queue + */ int v4l2_m2m_streamoff(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, enum v4l2_buf_type type); +/** + * v4l2_m2m_poll() - poll replacement, for destination buffers only + * + * Call from the driver's poll() function. Will poll both queues. If a buffer + * is available to dequeue (with dqbuf) from the source queue, this will + * indicate that a non-blocking write can be performed, while read will be + * returned in case of the destination queue. + */ unsigned int v4l2_m2m_poll(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct poll_table_struct *wait); +/** + * v4l2_m2m_mmap() - source and destination queues-aware mmap multiplexer + * + * Call from driver's mmap() function. Will handle mmap() for both queues + * seamlessly for videobuffer, which will receive normal per-queue offsets and + * proper videobuf queue pointers. The differentiation is made outside videobuf + * by adding a predefined offset to buffers from one of the queues and + * subtracting it before passing it back to videobuf. Only drivers (and + * thus applications) receive modified offsets. + */ int v4l2_m2m_mmap(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct vm_area_struct *vma); +/** + * v4l2_m2m_init() - initialize per-driver m2m data + * + * Usually called from driver's probe() function. + */ struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops); + +/** + * v4l2_m2m_release() - cleans up and frees a m2m_dev structure + * + * Usually called from driver's remove() function. + */ void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev); +/** + * v4l2_m2m_ctx_init() - allocate and initialize a m2m context + * @priv - driver's instance private data + * @m2m_dev - a previously initialized m2m_dev struct + * @vq_init - a callback for queue type-specific initialization function to be + * used for initializing videobuf_queues + * + * Usually called from driver's open() function. + */ struct v4l2_m2m_ctx *v4l2_m2m_ctx_init(struct v4l2_m2m_dev *m2m_dev, void *drv_priv, int (*queue_init)(void *priv, struct vb2_queue *src_vq, struct vb2_queue *dst_vq)); @@ -158,8 +273,18 @@ static inline void v4l2_m2m_set_dst_buffered(struct v4l2_m2m_ctx *m2m_ctx, m2m_ctx->cap_q_ctx.buffered = buffered; } +/** + * v4l2_m2m_ctx_release() - release m2m context + * + * Usually called from driver's release() function. + */ void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx); +/** + * v4l2_m2m_buf_queue() - add a buffer to the proper ready buffers list. + * + * Call from buf_queue(), videobuf_queue_ops callback. + */ void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx, struct vb2_v4l2_buffer *vbuf); @@ -187,6 +312,9 @@ unsigned int v4l2_m2m_num_dst_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx) return m2m_ctx->cap_q_ctx.num_rdy; } +/** + * v4l2_m2m_next_buf() - return next buffer from the list of ready buffers + */ void *v4l2_m2m_next_buf(struct v4l2_m2m_queue_ctx *q_ctx); /** @@ -233,6 +361,10 @@ struct vb2_queue *v4l2_m2m_get_dst_vq(struct v4l2_m2m_ctx *m2m_ctx) return &m2m_ctx->cap_q_ctx.q; } +/** + * v4l2_m2m_buf_remove() - take off a buffer from the list of ready buffers and + * return it + */ void *v4l2_m2m_buf_remove(struct v4l2_m2m_queue_ctx *q_ctx); /** -- cgit v1.2.3 From dcbd87358929ed989732a9866e683e33d0018461 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 10:39:58 -0300 Subject: [media] v4l2-mem2mem.h: document function arguments There are lots of troubles with the function arguments on this file. Fix them. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-mem2mem.h | 93 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 80 insertions(+), 13 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h index e5449a2c8475..00410bd14772 100644 --- a/include/media/v4l2-mem2mem.h +++ b/include/media/v4l2-mem2mem.h @@ -97,11 +97,16 @@ struct v4l2_m2m_buffer { /** * v4l2_m2m_get_curr_priv() - return driver private data for the currently * running instance or NULL if no instance is running + * + * @m2m_dev: pointer to struct &v4l2_m2m_dev */ void *v4l2_m2m_get_curr_priv(struct v4l2_m2m_dev *m2m_dev); /** * v4l2_m2m_get_vq() - return vb2_queue for the given type + * + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @type: type of the V4L2 buffer, as defined by enum &v4l2_buf_type */ struct vb2_queue *v4l2_m2m_get_vq(struct v4l2_m2m_ctx *m2m_ctx, enum v4l2_buf_type type); @@ -109,7 +114,8 @@ struct vb2_queue *v4l2_m2m_get_vq(struct v4l2_m2m_ctx *m2m_ctx, /** * v4l2_m2m_try_schedule() - check whether an instance is ready to be added to * the pending job queue and add it if so. - * @m2m_ctx: m2m context assigned to the instance to be checked + * + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx * * There are three basic requirements an instance has to meet to be able to run: * 1) at least one source buffer has to be queued, @@ -132,6 +138,9 @@ void v4l2_m2m_try_schedule(struct v4l2_m2m_ctx *m2m_ctx); * v4l2_m2m_job_finish() - inform the framework that a job has been finished * and have it clean up * + * @m2m_dev: pointer to struct &v4l2_m2m_dev + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * * Called by a driver to yield back the device after it has finished with it. * Should be called as soon as possible after reaching a state which allows * other instances to take control of the device. @@ -151,6 +160,10 @@ v4l2_m2m_buf_done(struct vb2_v4l2_buffer *buf, enum vb2_buffer_state state) /** * v4l2_m2m_reqbufs() - multi-queue-aware REQBUFS multiplexer + * + * @file: pointer to struct &file + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @reqbufs: pointer to struct &v4l2_requestbuffers */ int v4l2_m2m_reqbufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_requestbuffers *reqbufs); @@ -158,6 +171,10 @@ int v4l2_m2m_reqbufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, /** * v4l2_m2m_querybuf() - multi-queue-aware QUERYBUF multiplexer * + * @file: pointer to struct &file + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @buf: pointer to struct &v4l2_buffer + * * See v4l2_m2m_mmap() documentation for details. */ int v4l2_m2m_querybuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, @@ -166,6 +183,10 @@ int v4l2_m2m_querybuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, /** * v4l2_m2m_qbuf() - enqueue a source or destination buffer, depending on * the type + * + * @file: pointer to struct &file + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @buf: pointer to struct &v4l2_buffer */ int v4l2_m2m_qbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_buffer *buf); @@ -173,6 +194,10 @@ int v4l2_m2m_qbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, /** * v4l2_m2m_dqbuf() - dequeue a source or destination buffer, depending on * the type + * + * @file: pointer to struct &file + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @buf: pointer to struct &v4l2_buffer */ int v4l2_m2m_dqbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_buffer *buf); @@ -180,6 +205,10 @@ int v4l2_m2m_dqbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, /** * v4l2_m2m_prepare_buf() - prepare a source or destination buffer, depending on * the type + * + * @file: pointer to struct &file + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @buf: pointer to struct &v4l2_buffer */ int v4l2_m2m_prepare_buf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_buffer *buf); @@ -187,6 +216,10 @@ int v4l2_m2m_prepare_buf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, /** * v4l2_m2m_create_bufs() - create a source or destination buffer, depending * on the type + * + * @file: pointer to struct &file + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @create: pointer to struct &v4l2_create_buffers */ int v4l2_m2m_create_bufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_create_buffers *create); @@ -194,18 +227,30 @@ int v4l2_m2m_create_bufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, /** * v4l2_m2m_expbuf() - export a source or destination buffer, depending on * the type + * + * @file: pointer to struct &file + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @eb: pointer to struct &v4l2_exportbuffer */ int v4l2_m2m_expbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, struct v4l2_exportbuffer *eb); /** * v4l2_m2m_streamon() - turn on streaming for a video queue + * + * @file: pointer to struct &file + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @type: type of the V4L2 buffer, as defined by enum &v4l2_buf_type */ int v4l2_m2m_streamon(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, enum v4l2_buf_type type); /** * v4l2_m2m_streamoff() - turn off streaming for a video queue + * + * @file: pointer to struct &file + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @type: type of the V4L2 buffer, as defined by enum &v4l2_buf_type */ int v4l2_m2m_streamoff(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, enum v4l2_buf_type type); @@ -213,6 +258,10 @@ int v4l2_m2m_streamoff(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, /** * v4l2_m2m_poll() - poll replacement, for destination buffers only * + * @file: pointer to struct &file + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @wait: pointer to struct &poll_table_struct + * * Call from the driver's poll() function. Will poll both queues. If a buffer * is available to dequeue (with dqbuf) from the source queue, this will * indicate that a non-blocking write can be performed, while read will be @@ -224,6 +273,10 @@ unsigned int v4l2_m2m_poll(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, /** * v4l2_m2m_mmap() - source and destination queues-aware mmap multiplexer * + * @file: pointer to struct &file + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @vma: pointer to struct &vm_area_struct + * * Call from driver's mmap() function. Will handle mmap() for both queues * seamlessly for videobuffer, which will receive normal per-queue offsets and * proper videobuf queue pointers. The differentiation is made outside videobuf @@ -237,6 +290,8 @@ int v4l2_m2m_mmap(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, /** * v4l2_m2m_init() - initialize per-driver m2m data * + * @m2m_ops: pointer to struct v4l2_m2m_ops + * * Usually called from driver's probe() function. */ struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops); @@ -244,16 +299,19 @@ struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops); /** * v4l2_m2m_release() - cleans up and frees a m2m_dev structure * + * @m2m_dev: pointer to struct &v4l2_m2m_dev + * * Usually called from driver's remove() function. */ void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev); /** * v4l2_m2m_ctx_init() - allocate and initialize a m2m context - * @priv - driver's instance private data - * @m2m_dev - a previously initialized m2m_dev struct - * @vq_init - a callback for queue type-specific initialization function to be - * used for initializing videobuf_queues + * + * @m2m_dev: a previously initialized m2m_dev struct + * @drv_priv: driver's instance private data + * @queue_init: a callback for queue type-specific initialization function + * to be used for initializing videobuf_queues * * Usually called from driver's open() function. */ @@ -276,6 +334,8 @@ static inline void v4l2_m2m_set_dst_buffered(struct v4l2_m2m_ctx *m2m_ctx, /** * v4l2_m2m_ctx_release() - release m2m context * + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * * Usually called from driver's release() function. */ void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx); @@ -283,6 +343,9 @@ void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx); /** * v4l2_m2m_buf_queue() - add a buffer to the proper ready buffers list. * + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx + * @vbuf: pointer to struct &vb2_v4l2_buffer + * * Call from buf_queue(), videobuf_queue_ops callback. */ void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx, @@ -292,7 +355,7 @@ void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx, * v4l2_m2m_num_src_bufs_ready() - return the number of source buffers ready for * use * - * @m2m_ctx: pointer to struct v4l2_m2m_ctx + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx */ static inline unsigned int v4l2_m2m_num_src_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx) @@ -304,7 +367,7 @@ unsigned int v4l2_m2m_num_src_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx) * v4l2_m2m_num_src_bufs_ready() - return the number of destination buffers * ready for use * - * @m2m_ctx: pointer to struct v4l2_m2m_ctx + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx */ static inline unsigned int v4l2_m2m_num_dst_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx) @@ -314,6 +377,8 @@ unsigned int v4l2_m2m_num_dst_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx) /** * v4l2_m2m_next_buf() - return next buffer from the list of ready buffers + * + * @q_ctx: pointer to struct @v4l2_m2m_queue_ctx */ void *v4l2_m2m_next_buf(struct v4l2_m2m_queue_ctx *q_ctx); @@ -321,7 +386,7 @@ void *v4l2_m2m_next_buf(struct v4l2_m2m_queue_ctx *q_ctx); * v4l2_m2m_next_src_buf() - return next source buffer from the list of ready * buffers * - * @m2m_ctx: pointer to struct v4l2_m2m_ctx + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx */ static inline void *v4l2_m2m_next_src_buf(struct v4l2_m2m_ctx *m2m_ctx) { @@ -332,7 +397,7 @@ static inline void *v4l2_m2m_next_src_buf(struct v4l2_m2m_ctx *m2m_ctx) * v4l2_m2m_next_dst_buf() - return next destination buffer from the list of * ready buffers * - * @m2m_ctx: pointer to struct v4l2_m2m_ctx + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx */ static inline void *v4l2_m2m_next_dst_buf(struct v4l2_m2m_ctx *m2m_ctx) { @@ -342,7 +407,7 @@ static inline void *v4l2_m2m_next_dst_buf(struct v4l2_m2m_ctx *m2m_ctx) /** * v4l2_m2m_get_src_vq() - return vb2_queue for source buffers * - * @m2m_ctx: pointer to struct v4l2_m2m_ctx + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx */ static inline struct vb2_queue *v4l2_m2m_get_src_vq(struct v4l2_m2m_ctx *m2m_ctx) @@ -353,7 +418,7 @@ struct vb2_queue *v4l2_m2m_get_src_vq(struct v4l2_m2m_ctx *m2m_ctx) /** * v4l2_m2m_get_dst_vq() - return vb2_queue for destination buffers * - * @m2m_ctx: pointer to struct v4l2_m2m_ctx + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx */ static inline struct vb2_queue *v4l2_m2m_get_dst_vq(struct v4l2_m2m_ctx *m2m_ctx) @@ -364,6 +429,8 @@ struct vb2_queue *v4l2_m2m_get_dst_vq(struct v4l2_m2m_ctx *m2m_ctx) /** * v4l2_m2m_buf_remove() - take off a buffer from the list of ready buffers and * return it + * + * @q_ctx: pointer to struct @v4l2_m2m_queue_ctx */ void *v4l2_m2m_buf_remove(struct v4l2_m2m_queue_ctx *q_ctx); @@ -371,7 +438,7 @@ void *v4l2_m2m_buf_remove(struct v4l2_m2m_queue_ctx *q_ctx); * v4l2_m2m_src_buf_remove() - take off a source buffer from the list of ready * buffers and return it * - * @m2m_ctx: pointer to struct v4l2_m2m_ctx + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx */ static inline void *v4l2_m2m_src_buf_remove(struct v4l2_m2m_ctx *m2m_ctx) { @@ -382,7 +449,7 @@ static inline void *v4l2_m2m_src_buf_remove(struct v4l2_m2m_ctx *m2m_ctx) * v4l2_m2m_dst_buf_remove() - take off a destination buffer from the list of * ready buffers and return it * - * @m2m_ctx: pointer to struct v4l2_m2m_ctx + * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx */ static inline void *v4l2_m2m_dst_buf_remove(struct v4l2_m2m_ctx *m2m_ctx) { -- cgit v1.2.3 From 5fa5edbe59a7ab8ab649268fcb578662dfb7ca99 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 10:16:36 -0300 Subject: [media] v4l2-mem2mem.h: document the public structures Most structures here are not documented. Add a documentation for them. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-mem2mem.h | 67 +++++++++++++++++++++++++++++++++----------- 1 file changed, 51 insertions(+), 16 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h index 00410bd14772..cfa4f5e521a7 100644 --- a/include/media/v4l2-mem2mem.h +++ b/include/media/v4l2-mem2mem.h @@ -41,9 +41,9 @@ * This function does not have to (and will usually not) wait * until the device enters a state when it can be stopped. * @lock: optional. Define a driver's own lock callback, instead of using - * m2m_ctx->q_lock. + * &v4l2_m2m_ctx->q_lock. * @unlock: optional. Define a driver's own unlock callback, instead of - * using m2m_ctx->q_lock. + * using &v4l2_m2m_ctx->q_lock. */ struct v4l2_m2m_ops { void (*device_run)(void *priv); @@ -53,31 +53,59 @@ struct v4l2_m2m_ops { void (*unlock)(void *priv); }; +/** + * struct v4l2_m2m_dev - opaque struct used to represent a V4L2 M2M device. + * + * This structure is has the per-device context for a memory to memory + * device, and it is used internally at v4l2-mem2mem.c. + */ struct v4l2_m2m_dev; +/** + * struct v4l2_m2m_queue_ctx - represents a queue for buffers ready to be + * processed + * + * @q: pointer to struct &vb2_queue + * @rdy_queue: List of V4L2 mem-to-mem queues + * @rdy_spinlock: spin lock to protect the struct usage + * @num_rdy: number of buffers ready to be processed + * @buffered: is the queue buffered? + * + * Queue for buffers ready to be processed as soon as this + * instance receives access to the device. + */ + struct v4l2_m2m_queue_ctx { -/* private: internal use only */ struct vb2_queue q; - /* Queue for buffers ready to be processed as soon as this - * instance receives access to the device */ struct list_head rdy_queue; spinlock_t rdy_spinlock; u8 num_rdy; bool buffered; }; +/** + * struct v4l2_m2m_ctx - Memory to memory context structure + * + * @q_lock: struct &mutex lock + * @m2m_dev: pointer to struct &v4l2_m2m_dev + * @cap_q_ctx: Capture (output to memory) queue context + * @out_q_ctx: Output (input from memory) queue context + * @queue: List of memory to memory contexts + * @job_flags: Job queue flags, used internally by v4l2-mem2mem.c: + * %TRANS_QUEUED, %TRANS_RUNNING and %TRANS_ABORT. + * @finished: Wait queue used to signalize when a job queue finished. + * @priv: Instance private data + */ struct v4l2_m2m_ctx { /* optional cap/out vb2 queues lock */ struct mutex *q_lock; -/* private: internal use only */ + /* internal use only */ struct v4l2_m2m_dev *m2m_dev; - /* Capture (output to memory) queue context */ struct v4l2_m2m_queue_ctx cap_q_ctx; - /* Output (input from memory) queue context */ struct v4l2_m2m_queue_ctx out_q_ctx; /* For device job queue */ @@ -85,10 +113,15 @@ struct v4l2_m2m_ctx { unsigned long job_flags; wait_queue_head_t finished; - /* Instance private data */ void *priv; }; +/** + * struct v4l2_m2m_buffer - Memory to memory buffer + * + * @vb: pointer to struct &vb2_v4l2_buffer + * @list: list of m2m buffers + */ struct v4l2_m2m_buffer { struct vb2_v4l2_buffer vb; struct list_head list; @@ -145,9 +178,9 @@ void v4l2_m2m_try_schedule(struct v4l2_m2m_ctx *m2m_ctx); * Should be called as soon as possible after reaching a state which allows * other instances to take control of the device. * - * This function has to be called only after device_run() callback has been - * called on the driver. To prevent recursion, it should not be called directly - * from the device_run() callback though. + * This function has to be called only after &v4l2_m2m_ops->device_run + * callback has been called on the driver. To prevent recursion, it should + * not be called directly from the &v4l2_m2m_ops->device_run callback though. */ void v4l2_m2m_job_finish(struct v4l2_m2m_dev *m2m_dev, struct v4l2_m2m_ctx *m2m_ctx); @@ -292,7 +325,9 @@ int v4l2_m2m_mmap(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, * * @m2m_ops: pointer to struct v4l2_m2m_ops * - * Usually called from driver's probe() function. + * Usually called from driver's ``probe()`` function. + * + * Return: returns an opaque pointer to the internal data to handle M2M context */ struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops); @@ -301,7 +336,7 @@ struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops); * * @m2m_dev: pointer to struct &v4l2_m2m_dev * - * Usually called from driver's remove() function. + * Usually called from driver's ``remove()`` function. */ void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev); @@ -313,7 +348,7 @@ void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev); * @queue_init: a callback for queue type-specific initialization function * to be used for initializing videobuf_queues * - * Usually called from driver's open() function. + * Usually called from driver's ``open()`` function. */ struct v4l2_m2m_ctx *v4l2_m2m_ctx_init(struct v4l2_m2m_dev *m2m_dev, void *drv_priv, @@ -346,7 +381,7 @@ void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx); * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx * @vbuf: pointer to struct &vb2_v4l2_buffer * - * Call from buf_queue(), videobuf_queue_ops callback. + * Call from videobuf_queue_ops->ops->buf_queue, videobuf_queue_ops callback. */ void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx, struct vb2_v4l2_buffer *vbuf); -- cgit v1.2.3 From 9f8d3a2ee78110afc2aee85d979b869faac257e7 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 17:20:44 -0300 Subject: [media] v4l2-mem2mem.h: make kernel-doc parse v4l2-mem2mem.h again The kernel-doc C parser doesn't like opaque structures. So, document it on another way. This should get rid of this warning: ./include/media/v4l2-mem2mem.h:62: error: Cannot parse struct or union! Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-mem2mem.h | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h index cfa4f5e521a7..498c99baf8ac 100644 --- a/include/media/v4l2-mem2mem.h +++ b/include/media/v4l2-mem2mem.h @@ -53,12 +53,6 @@ struct v4l2_m2m_ops { void (*unlock)(void *priv); }; -/** - * struct v4l2_m2m_dev - opaque struct used to represent a V4L2 M2M device. - * - * This structure is has the per-device context for a memory to memory - * device, and it is used internally at v4l2-mem2mem.c. - */ struct v4l2_m2m_dev; /** @@ -88,7 +82,7 @@ struct v4l2_m2m_queue_ctx { * struct v4l2_m2m_ctx - Memory to memory context structure * * @q_lock: struct &mutex lock - * @m2m_dev: pointer to struct &v4l2_m2m_dev + * @m2m_dev: opaque pointer to the internal data to handle M2M context * @cap_q_ctx: Capture (output to memory) queue context * @out_q_ctx: Output (input from memory) queue context * @queue: List of memory to memory contexts @@ -131,7 +125,7 @@ struct v4l2_m2m_buffer { * v4l2_m2m_get_curr_priv() - return driver private data for the currently * running instance or NULL if no instance is running * - * @m2m_dev: pointer to struct &v4l2_m2m_dev + * @m2m_dev: opaque pointer to the internal data to handle M2M context */ void *v4l2_m2m_get_curr_priv(struct v4l2_m2m_dev *m2m_dev); @@ -171,7 +165,7 @@ void v4l2_m2m_try_schedule(struct v4l2_m2m_ctx *m2m_ctx); * v4l2_m2m_job_finish() - inform the framework that a job has been finished * and have it clean up * - * @m2m_dev: pointer to struct &v4l2_m2m_dev + * @m2m_dev: opaque pointer to the internal data to handle M2M context * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx * * Called by a driver to yield back the device after it has finished with it. @@ -334,7 +328,7 @@ struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops); /** * v4l2_m2m_release() - cleans up and frees a m2m_dev structure * - * @m2m_dev: pointer to struct &v4l2_m2m_dev + * @m2m_dev: opaque pointer to the internal data to handle M2M context * * Usually called from driver's ``remove()`` function. */ @@ -343,7 +337,7 @@ void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev); /** * v4l2_m2m_ctx_init() - allocate and initialize a m2m context * - * @m2m_dev: a previously initialized m2m_dev struct + * @m2m_dev: opaque pointer to the internal data to handle M2M context * @drv_priv: driver's instance private data * @queue_init: a callback for queue type-specific initialization function * to be used for initializing videobuf_queues -- cgit v1.2.3 From 88b7eb092efb8197d29d5202d77d1fb919419ec5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 13:34:37 -0300 Subject: [media] videobuf2-core.h: move function descriptions from c file There are several functions that were documented at the .c file. As we only include the headers, we need to move them to there, in order to have documentation. Signed-off-by: Mauro Carvalho Chehab --- include/media/videobuf2-core.h | 269 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) (limited to 'include') diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h index b6546db670ca..68f93dacb38f 100644 --- a/include/media/videobuf2-core.h +++ b/include/media/videobuf2-core.h @@ -536,35 +536,274 @@ struct vb2_queue { #endif }; +/** + * vb2_plane_vaddr() - Return a kernel virtual address of a given plane + * @vb: vb2_buffer to which the plane in question belongs to + * @plane_no: plane number for which the address is to be returned + * + * This function returns a kernel virtual address of a given plane if + * such a mapping exist, NULL otherwise. + */ void *vb2_plane_vaddr(struct vb2_buffer *vb, unsigned int plane_no); + +/** + * vb2_plane_cookie() - Return allocator specific cookie for the given plane + * @vb: vb2_buffer to which the plane in question belongs to + * @plane_no: plane number for which the cookie is to be returned + * + * This function returns an allocator specific cookie for a given plane if + * available, NULL otherwise. The allocator should provide some simple static + * inline function, which would convert this cookie to the allocator specific + * type that can be used directly by the driver to access the buffer. This can + * be for example physical address, pointer to scatter list or IOMMU mapping. + */ void *vb2_plane_cookie(struct vb2_buffer *vb, unsigned int plane_no); +/** + * vb2_buffer_done() - inform videobuf that an operation on a buffer is finished + * @vb: vb2_buffer returned from the driver + * @state: either %VB2_BUF_STATE_DONE if the operation finished successfully, + * %VB2_BUF_STATE_ERROR if the operation finished with an error or + * %VB2_BUF_STATE_QUEUED if the driver wants to requeue buffers. + * If start_streaming fails then it should return buffers with state + * %VB2_BUF_STATE_QUEUED to put them back into the queue. + * + * This function should be called by the driver after a hardware operation on + * a buffer is finished and the buffer may be returned to userspace. The driver + * cannot use this buffer anymore until it is queued back to it by videobuf + * by the means of buf_queue callback. Only buffers previously queued to the + * driver by buf_queue can be passed to this function. + * + * While streaming a buffer can only be returned in state DONE or ERROR. + * The start_streaming op can also return them in case the DMA engine cannot + * be started for some reason. In that case the buffers should be returned with + * state QUEUED. + */ void vb2_buffer_done(struct vb2_buffer *vb, enum vb2_buffer_state state); + +/** + * vb2_discard_done() - discard all buffers marked as DONE + * @q: videobuf2 queue + * + * This function is intended to be used with suspend/resume operations. It + * discards all 'done' buffers as they would be too old to be requested after + * resume. + * + * Drivers must stop the hardware and synchronize with interrupt handlers and/or + * delayed works before calling this function to make sure no buffer will be + * touched by the driver and/or hardware. + */ void vb2_discard_done(struct vb2_queue *q); + +/** + * vb2_wait_for_all_buffers() - wait until all buffers are given back to vb2 + * @q: videobuf2 queue + * + * This function will wait until all buffers that have been given to the driver + * by buf_queue() are given back to vb2 with vb2_buffer_done(). It doesn't call + * wait_prepare, wait_finish pair. It is intended to be called with all locks + * taken, for example from stop_streaming() callback. + */ int vb2_wait_for_all_buffers(struct vb2_queue *q); +/** + * vb2_core_querybuf() - query video buffer information + * @q: videobuf queue + * @index: id number of the buffer + * @pb: buffer struct passed from userspace + * + * Should be called from vidioc_querybuf ioctl handler in driver. + * The passed buffer should have been verified. + * This function fills the relevant information for the userspace. + */ void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb); + +/** + * vb2_core_reqbufs() - Initiate streaming + * @q: videobuf2 queue + * @memory: memory type + * @count: requested buffer count + * + * Should be called from vidioc_reqbufs ioctl handler of a driver. + * This function: + * 1) verifies streaming parameters passed from the userspace, + * 2) sets up the queue, + * 3) negotiates number of buffers and planes per buffer with the driver + * to be used during streaming, + * 4) allocates internal buffer structures (struct vb2_buffer), according to + * the agreed parameters, + * 5) for MMAP memory type, allocates actual video memory, using the + * memory handling/allocation routines provided during queue initialization + * + * If req->count is 0, all the memory will be freed instead. + * If the queue has been allocated previously (by a previous vb2_reqbufs) call + * and the queue is not busy, memory will be reallocated. + * + * The return values from this function are intended to be directly returned + * from vidioc_reqbufs handler in driver. + */ int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory, unsigned int *count); + +/** + * vb2_core_create_bufs() - Allocate buffers and any required auxiliary structs + * @q: videobuf2 queue + * @memory: memory type + * @count: requested buffer count + * @parg: parameter passed to device driver + * + * Should be called from vidioc_create_bufs ioctl handler of a driver. + * This function: + * 1) verifies parameter sanity + * 2) calls the .queue_setup() queue operation + * 3) performs any necessary memory allocations + * + * The return values from this function are intended to be directly returned + * from vidioc_create_bufs handler in driver. + */ int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory, unsigned int *count, unsigned requested_planes, const unsigned int requested_sizes[]); + +/** + * vb2_core_prepare_buf() - Pass ownership of a buffer from userspace + * to the kernel + * @q: videobuf2 queue + * @index: id number of the buffer + * @pb: buffer structure passed from userspace to vidioc_prepare_buf + * handler in driver + * + * Should be called from vidioc_prepare_buf ioctl handler of a driver. + * The passed buffer should have been verified. + * This function calls buf_prepare callback in the driver (if provided), + * in which driver-specific buffer initialization can be performed, + * + * The return values from this function are intended to be directly returned + * from vidioc_prepare_buf handler in driver. + */ int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb); + +/** + * vb2_core_qbuf() - Queue a buffer from userspace + * @q: videobuf2 queue + * @index: id number of the buffer + * @pb: buffer structure passed from userspace to vidioc_qbuf handler + * in driver + * + * Should be called from vidioc_qbuf ioctl handler of a driver. + * The passed buffer should have been verified. + * This function: + * 1) if necessary, calls buf_prepare callback in the driver (if provided), in + * which driver-specific buffer initialization can be performed, + * 2) if streaming is on, queues the buffer in driver by the means of buf_queue + * callback for processing. + * + * The return values from this function are intended to be directly returned + * from vidioc_qbuf handler in driver. + */ int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb); + +/** + * vb2_core_dqbuf() - Dequeue a buffer to the userspace + * @q: videobuf2 queue + * @pindex: pointer to the buffer index. May be NULL + * @pb: buffer structure passed from userspace to vidioc_dqbuf handler + * in driver + * @nonblocking: if true, this call will not sleep waiting for a buffer if no + * buffers ready for dequeuing are present. Normally the driver + * would be passing (file->f_flags & O_NONBLOCK) here + * + * Should be called from vidioc_dqbuf ioctl handler of a driver. + * The passed buffer should have been verified. + * This function: + * 1) calls buf_finish callback in the driver (if provided), in which + * driver can perform any additional operations that may be required before + * returning the buffer to userspace, such as cache sync, + * 2) the buffer struct members are filled with relevant information for + * the userspace. + * + * The return values from this function are intended to be directly returned + * from vidioc_dqbuf handler in driver. + */ int vb2_core_dqbuf(struct vb2_queue *q, unsigned int *pindex, void *pb, bool nonblocking); int vb2_core_streamon(struct vb2_queue *q, unsigned int type); int vb2_core_streamoff(struct vb2_queue *q, unsigned int type); +/** + * vb2_core_expbuf() - Export a buffer as a file descriptor + * @q: videobuf2 queue + * @fd: file descriptor associated with DMABUF (set by driver) * + * @type: buffer type + * @index: id number of the buffer + * @plane: index of the plane to be exported, 0 for single plane queues + * @flags: flags for newly created file, currently only O_CLOEXEC is + * supported, refer to manual of open syscall for more details + * + * The return values from this function are intended to be directly returned + * from vidioc_expbuf handler in driver. + */ int vb2_core_expbuf(struct vb2_queue *q, int *fd, unsigned int type, unsigned int index, unsigned int plane, unsigned int flags); +/** + * vb2_core_queue_init() - initialize a videobuf2 queue + * @q: videobuf2 queue; this structure should be allocated in driver + * + * The vb2_queue structure should be allocated by the driver. The driver is + * responsible of clearing it's content and setting initial values for some + * required entries before calling this function. + * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer + * to the struct vb2_queue description in include/media/videobuf2-core.h + * for more information. + */ int vb2_core_queue_init(struct vb2_queue *q); + +/** + * vb2_core_queue_release() - stop streaming, release the queue and free memory + * @q: videobuf2 queue + * + * This function stops streaming and performs necessary clean ups, including + * freeing video buffer memory. The driver is responsible for freeing + * the vb2_queue structure itself. + */ void vb2_core_queue_release(struct vb2_queue *q); +/** + * vb2_queue_error() - signal a fatal error on the queue + * @q: videobuf2 queue + * + * Flag that a fatal unrecoverable error has occurred and wake up all processes + * waiting on the queue. Polling will now set POLLERR and queuing and dequeuing + * buffers will return -EIO. + * + * The error flag will be cleared when cancelling the queue, either from + * vb2_streamoff or vb2_queue_release. Drivers should thus not call this + * function before starting the stream, otherwise the error flag will remain set + * until the queue is released when closing the device node. + */ void vb2_queue_error(struct vb2_queue *q); +/** + * vb2_mmap() - map video buffers into application address space + * @q: videobuf2 queue + * @vma: vma passed to the mmap file operation handler in the driver + * + * Should be called from mmap file operation handler of a driver. + * This function maps one plane of one of the available video buffers to + * userspace. To map whole video memory allocated on reqbufs, this function + * has to be called once per each plane per each buffer previously allocated. + * + * When the userspace application calls mmap, it passes to it an offset returned + * to it earlier by the means of vidioc_querybuf handler. That offset acts as + * a "cookie", which is then used to identify the plane to be mapped. + * This function finds a plane with a matching offset and a mapping is performed + * by the means of a provided memory operation. + * + * The return values from this function are intended to be directly returned + * from the mmap handler in driver. + */ int vb2_mmap(struct vb2_queue *q, struct vm_area_struct *vma); #ifndef CONFIG_MMU unsigned long vb2_get_unmapped_area(struct vb2_queue *q, @@ -573,6 +812,23 @@ unsigned long vb2_get_unmapped_area(struct vb2_queue *q, unsigned long pgoff, unsigned long flags); #endif + +/** + * vb2_core_poll() - implements poll userspace operation + * @q: videobuf2 queue + * @file: file argument passed to the poll file operation handler + * @wait: wait argument passed to the poll file operation handler + * + * This function implements poll file operation handler for a driver. + * For CAPTURE queues, if a buffer is ready to be dequeued, the userspace will + * be informed that the file descriptor of a video device is available for + * reading. + * For OUTPUT queues, if a buffer is ready to be dequeued, the file descriptor + * will be reported as available for writing. + * + * The return values from this function are intended to be directly returned + * from poll handler in driver. + */ unsigned int vb2_core_poll(struct vb2_queue *q, struct file *file, poll_table *wait); size_t vb2_read(struct vb2_queue *q, char __user *data, size_t count, @@ -717,7 +973,20 @@ static inline void vb2_clear_last_buffer_dequeued(struct vb2_queue *q) * The following functions are not part of the vb2 core API, but are useful * functions for videobuf2-*. */ + +/** + * vb2_buffer_in_use() - return true if the buffer is in use and + * the queue cannot be freed (by the means of REQBUFS(0)) call + * + * @vb: buffer for which plane size should be returned + * @q: videobuf queue + */ bool vb2_buffer_in_use(struct vb2_queue *q, struct vb2_buffer *vb); + +/** + * vb2_verify_memory_type() - Check whether the memory type and buffer type + * passed to a buffer operation are compatible with the queue. + */ int vb2_verify_memory_type(struct vb2_queue *q, enum vb2_memory memory, unsigned int type); #endif /* _MEDIA_VIDEOBUF2_CORE_H */ -- cgit v1.2.3 From 52839f66edde1ed709390b55a0d3f82593203308 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 14:08:00 -0300 Subject: [media] videobuf2-core.h: document enum vb2_memory This enum was not documented. Document it. Signed-off-by: Mauro Carvalho Chehab --- include/media/videobuf2-core.h | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'include') diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h index 68f93dacb38f..65eeca83687a 100644 --- a/include/media/videobuf2-core.h +++ b/include/media/videobuf2-core.h @@ -20,6 +20,20 @@ #define VB2_MAX_FRAME (32) #define VB2_MAX_PLANES (8) +/** + * enum vb2_memory - type of memory model used to make the buffers visible + * on userspace. + * + * @VB2_MEMORY_UNKNOWN: Buffer status is unknown or it is not used yet on + * userspace. + * @VB2_MEMORY_MMAP: The buffers are allocated by the Kernel and it is + * memory mapped via mmap() ioctl. This model is + * also used when the user is using the buffers via + * read() or write() system calls. + * @VB2_MEMORY_USERPTR: The buffers was allocated in userspace and it is + * memory mapped via mmap() ioctl. + * @VB2_MEMORY_DMABUF: The buffers are passed to userspace via DMA buffer. + */ enum vb2_memory { VB2_MEMORY_UNKNOWN = 0, VB2_MEMORY_MMAP = 1, -- cgit v1.2.3 From f286f4dfc50a9f4d777534794a773eb4fbbedd72 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 14:08:34 -0300 Subject: [media] videobuf2-core.h: improve documentation There are several small issues with the documentation. Fix them, in order to avoid producing warnings. While here, also make checkpatch.pl happy. Signed-off-by: Mauro Carvalho Chehab --- include/media/videobuf2-core.h | 143 ++++++++++++++++++++++++----------------- 1 file changed, 85 insertions(+), 58 deletions(-) (limited to 'include') diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h index 65eeca83687a..9a144f2d9083 100644 --- a/include/media/videobuf2-core.h +++ b/include/media/videobuf2-core.h @@ -49,13 +49,13 @@ struct vb2_threadio_data; * @alloc: allocate video memory and, optionally, allocator private data, * return ERR_PTR() on failure or a pointer to allocator private, * per-buffer data on success; the returned private structure - * will then be passed as buf_priv argument to other ops in this + * will then be passed as @buf_priv argument to other ops in this * structure. Additional gfp_flags to use when allocating the * are also passed to this operation. These flags are from the * gfp_flags field of vb2_queue. * @put: inform the allocator that the buffer will no longer be used; * usually will result in the allocator freeing the buffer (if - * no other users of this buffer are present); the buf_priv + * no other users of this buffer are present); the @buf_priv * argument is the allocator private per-buffer structure * previously returned from the alloc callback. * @get_dmabuf: acquire userspace memory for a hardware operation; used for @@ -65,7 +65,7 @@ struct vb2_threadio_data; * videobuf layer when queuing a video buffer of USERPTR type; * should return an allocator private per-buffer structure * associated with the buffer on success, ERR_PTR() on failure; - * the returned private structure will then be passed as buf_priv + * the returned private structure will then be passed as @buf_priv * argument to other ops in this structure. * @put_userptr: inform the allocator that a USERPTR buffer will no longer * be used. @@ -75,7 +75,7 @@ struct vb2_threadio_data; * allocator private per-buffer structure on success; * this needs to be used for further accesses to the buffer. * @detach_dmabuf: inform the exporter of the buffer that the current DMABUF - * buffer is no longer used; the buf_priv argument is the + * buffer is no longer used; the @buf_priv argument is the * allocator private per-buffer structure previously returned * from the attach_dmabuf callback. * @map_dmabuf: request for access to the dmabuf from allocator; the allocator @@ -109,11 +109,13 @@ struct vb2_threadio_data; * * #) Required ops for read/write access types: alloc, put, num_users, vaddr. * - * #) Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf, unmap_dmabuf. + * #) Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, + * map_dmabuf, unmap_dmabuf. */ struct vb2_mem_ops { void *(*alloc)(struct device *dev, unsigned long attrs, - unsigned long size, enum dma_data_direction dma_dir, + unsigned long size, + enum dma_data_direction dma_dir, gfp_t gfp_flags); void (*put)(void *buf_priv); struct dma_buf *(*get_dmabuf)(void *buf_priv, unsigned long flags); @@ -126,7 +128,8 @@ struct vb2_mem_ops { void (*prepare)(void *buf_priv); void (*finish)(void *buf_priv); - void *(*attach_dmabuf)(struct device *dev, struct dma_buf *dbuf, + void *(*attach_dmabuf)(struct device *dev, + struct dma_buf *dbuf, unsigned long size, enum dma_data_direction dma_dir); void (*detach_dmabuf)(void *buf_priv); @@ -291,7 +294,7 @@ struct vb2_buffer { /** * struct vb2_ops - driver-specific callbacks * - * @queue_setup: called from %VIDIOC_REQBUFS and %VIDIOC_CREATE_BUFS + * @queue_setup: called from VIDIOC_REQBUFS() and VIDIOC_CREATE_BUFS() * handlers before memory allocation. It can be called * twice: if the original number of requested buffers * could not be allocated, then it will be called a @@ -302,11 +305,11 @@ struct vb2_buffer { * buffer in \*num_planes, the size of each plane should be * set in the sizes\[\] array and optional per-plane * allocator specific device in the alloc_devs\[\] array. - * When called from %VIDIOC_REQBUFS, \*num_planes == 0, the - * driver has to use the currently configured format to + * When called from VIDIOC_REQBUFS,() \*num_planes == 0, + * the driver has to use the currently configured format to * determine the plane sizes and \*num_buffers is the total * number of buffers that are being allocated. When called - * from %VIDIOC_CREATE_BUFS, \*num_planes != 0 and it + * from VIDIOC_CREATE_BUFS,() \*num_planes != 0 and it * describes the requested number of planes and sizes\[\] * contains the requested plane sizes. If either * \*num_planes or the requested sizes are invalid callback @@ -325,11 +328,11 @@ struct vb2_buffer { * initialization failure (return != 0) will prevent * queue setup from completing successfully; optional. * @buf_prepare: called every time the buffer is queued from userspace - * and from the %VIDIOC_PREPARE_BUF ioctl; drivers may + * and from the VIDIOC_PREPARE_BUF() ioctl; drivers may * perform any initialization required before each * hardware operation in this callback; drivers can * access/modify the buffer here as it is still synced for - * the CPU; drivers that support %VIDIOC_CREATE_BUFS must + * the CPU; drivers that support VIDIOC_CREATE_BUFS() must * also validate the buffer size; if an error is returned, * the buffer will not be queued in driver; optional. * @buf_finish: called before every dequeue of the buffer back to @@ -353,24 +356,25 @@ struct vb2_buffer { * driver can return an error if hardware fails, in that * case all buffers that have been already given by * the @buf_queue callback are to be returned by the driver - * by calling @vb2_buffer_done\(%VB2_BUF_STATE_QUEUED\). + * by calling vb2_buffer_done() with %VB2_BUF_STATE_QUEUED. * If you need a minimum number of buffers before you can * start streaming, then set @min_buffers_needed in the * vb2_queue structure. If that is non-zero then - * start_streaming won't be called until at least that + * @start_streaming won't be called until at least that * many buffers have been queued up by userspace. * @stop_streaming: called when 'streaming' state must be disabled; driver * should stop any DMA transactions or wait until they * finish and give back all buffers it got from &buf_queue - * callback by calling @vb2_buffer_done\(\) with either + * callback by calling vb2_buffer_done() with either * %VB2_BUF_STATE_DONE or %VB2_BUF_STATE_ERROR; may use * vb2_wait_for_all_buffers() function * @buf_queue: passes buffer vb to the driver; driver may start * hardware operation on this buffer; driver should give * the buffer back by calling vb2_buffer_done() function; - * it is allways called after calling %VIDIOC_STREAMON ioctl; - * might be called before start_streaming callback if user - * pre-queued buffers before calling %VIDIOC_STREAMON. + * it is allways called after calling VIDIOC_STREAMON() + * ioctl; might be called before @start_streaming callback + * if user pre-queued buffers before calling + * VIDIOC_STREAMON(). */ struct vb2_ops { int (*queue_setup)(struct vb2_queue *q, @@ -418,7 +422,7 @@ struct vb2_buf_ops { * * @type: private buffer type whose content is defined by the vb2-core * caller. For example, for V4L2, it should match - * the V4L2_BUF_TYPE_* in include/uapi/linux/videodev2.h + * the types defined on enum &v4l2_buf_type * @io_modes: supported io methods (see vb2_io_modes enum) * @dev: device to use for the default allocation context if the driver * doesn't fill in the @alloc_devs array. @@ -453,12 +457,12 @@ struct vb2_buf_ops { * Typically this is 0, but it may be e.g. GFP_DMA or __GFP_DMA32 * to force the buffer allocation to a specific memory zone. * @min_buffers_needed: the minimum number of buffers needed before - * start_streaming() can be called. Used when a DMA engine + * @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): + * Private elements (won't appear at the uAPI book): * @mmap_lock: private mutex used when buffers are allocated/freed/mmapped * @memory: current memory type used * @bufs: videobuf buffer structures @@ -471,7 +475,7 @@ struct vb2_buf_ops { * @done_wq: waitqueue for processes waiting for buffers ready to be dequeued * @alloc_devs: memory type/allocator-specific per-plane device * @streaming: current streaming state - * @start_streaming_called: start_streaming() was called successfully and we + * @start_streaming_called: @start_streaming was called successfully and we * started streaming. * @error: a fatal error occurred on the queue * @waiting_for_buffers: used in poll() to check if vb2 is still waiting for @@ -576,17 +580,18 @@ void *vb2_plane_cookie(struct vb2_buffer *vb, unsigned int plane_no); /** * vb2_buffer_done() - inform videobuf that an operation on a buffer is finished * @vb: vb2_buffer returned from the driver - * @state: either %VB2_BUF_STATE_DONE if the operation finished successfully, - * %VB2_BUF_STATE_ERROR if the operation finished with an error or - * %VB2_BUF_STATE_QUEUED if the driver wants to requeue buffers. - * If start_streaming fails then it should return buffers with state - * %VB2_BUF_STATE_QUEUED to put them back into the queue. + * @state: either %VB2_BUF_STATE_DONE if the operation finished + * successfully, %VB2_BUF_STATE_ERROR if the operation finished + * with an error or %VB2_BUF_STATE_QUEUED if the driver wants to + * requeue buffers. If start_streaming fails then it should return + * buffers with state %VB2_BUF_STATE_QUEUED to put them back into + * the queue. * * This function should be called by the driver after a hardware operation on * a buffer is finished and the buffer may be returned to userspace. The driver * cannot use this buffer anymore until it is queued back to it by videobuf - * by the means of buf_queue callback. Only buffers previously queued to the - * driver by buf_queue can be passed to this function. + * by the means of &vb2_ops->buf_queue callback. Only buffers previously queued + * to the driver by &vb2_ops->buf_queue can be passed to this function. * * While streaming a buffer can only be returned in state DONE or ERROR. * The start_streaming op can also return them in case the DMA engine cannot @@ -614,9 +619,9 @@ void vb2_discard_done(struct vb2_queue *q); * @q: videobuf2 queue * * This function will wait until all buffers that have been given to the driver - * by buf_queue() are given back to vb2 with vb2_buffer_done(). It doesn't call - * wait_prepare, wait_finish pair. It is intended to be called with all locks - * taken, for example from stop_streaming() callback. + * by &vb2_ops->buf_queue are given back to vb2 with vb2_buffer_done(). It + * doesn't call wait_prepare()/wait_finish() pair. It is intended to be called + * with all locks taken, for example from &vb2_ops->stop_streaming callback. */ int vb2_wait_for_all_buffers(struct vb2_queue *q); @@ -639,14 +644,16 @@ void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb); * @count: requested buffer count * * Should be called from vidioc_reqbufs ioctl handler of a driver. + * * This function: - * 1) verifies streaming parameters passed from the userspace, - * 2) sets up the queue, - * 3) negotiates number of buffers and planes per buffer with the driver + * + * #) verifies streaming parameters passed from the userspace, + * #) sets up the queue, + * #) negotiates number of buffers and planes per buffer with the driver * to be used during streaming, - * 4) allocates internal buffer structures (struct vb2_buffer), according to + * #) allocates internal buffer structures (struct vb2_buffer), according to * the agreed parameters, - * 5) for MMAP memory type, allocates actual video memory, using the + * #) for MMAP memory type, allocates actual video memory, using the * memory handling/allocation routines provided during queue initialization * * If req->count is 0, all the memory will be freed instead. @@ -664,20 +671,22 @@ int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory, * @q: videobuf2 queue * @memory: memory type * @count: requested buffer count - * @parg: parameter passed to device driver + * @requested_planes: number of planes requested + * @requested_sizes: array with the size of the planes * - * Should be called from vidioc_create_bufs ioctl handler of a driver. + * Should be called from VIDIOC_CREATE_BUFS() ioctl handler of a driver. * This function: - * 1) verifies parameter sanity - * 2) calls the .queue_setup() queue operation - * 3) performs any necessary memory allocations * - * The return values from this function are intended to be directly returned - * from vidioc_create_bufs handler in driver. + * #) verifies parameter sanity + * #) calls the .queue_setup() queue operation + * #) performs any necessary memory allocations + * + * Return: the return values from this function are intended to be directly + * returned from VIDIOC_CREATE_BUFS() handler in driver. */ int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory, - unsigned int *count, unsigned requested_planes, - const unsigned int requested_sizes[]); + unsigned int *count, unsigned int requested_planes, + const unsigned int requested_sizes[]); /** * vb2_core_prepare_buf() - Pass ownership of a buffer from userspace @@ -699,6 +708,7 @@ int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb); /** * vb2_core_qbuf() - Queue a buffer from userspace + * * @q: videobuf2 queue * @index: id number of the buffer * @pb: buffer structure passed from userspace to vidioc_qbuf handler @@ -706,11 +716,13 @@ int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb); * * Should be called from vidioc_qbuf ioctl handler of a driver. * The passed buffer should have been verified. + * * This function: - * 1) if necessary, calls buf_prepare callback in the driver (if provided), in + * + * #) if necessary, calls buf_prepare callback in the driver (if provided), in * which driver-specific buffer initialization can be performed, - * 2) if streaming is on, queues the buffer in driver by the means of buf_queue - * callback for processing. + * #) if streaming is on, queues the buffer in driver by the means of + * &vb2_ops->buf_queue callback for processing. * * The return values from this function are intended to be directly returned * from vidioc_qbuf handler in driver. @@ -729,11 +741,13 @@ int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb); * * Should be called from vidioc_dqbuf ioctl handler of a driver. * The passed buffer should have been verified. + * * This function: - * 1) calls buf_finish callback in the driver (if provided), in which + * + * #) calls buf_finish callback in the driver (if provided), in which * driver can perform any additional operations that may be required before * returning the buffer to userspace, such as cache sync, - * 2) the buffer struct members are filled with relevant information for + * #) the buffer struct members are filled with relevant information for * the userspace. * * The return values from this function are intended to be directly returned @@ -819,6 +833,7 @@ void vb2_queue_error(struct vb2_queue *q); * from the mmap handler in driver. */ int vb2_mmap(struct vb2_queue *q, struct vm_area_struct *vma); + #ifndef CONFIG_MMU unsigned long vb2_get_unmapped_area(struct vb2_queue *q, unsigned long addr, @@ -844,14 +859,18 @@ unsigned long vb2_get_unmapped_area(struct vb2_queue *q, * from poll handler in driver. */ unsigned int vb2_core_poll(struct vb2_queue *q, struct file *file, - poll_table *wait); + poll_table *wait); + 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 +/** + * typedef vb2_thread_fnc - callback function for use with vb2_thread + * + * @vb: pointer to struct &vb2_buffer + * @priv: pointer to a private pointer * * This is called whenever a buffer is dequeued in the thread. */ @@ -867,9 +886,11 @@ typedef int (*vb2_thread_fnc)(struct vb2_buffer *vb, void *priv); * This starts a thread that will queue and dequeue until an error occurs * or @vb2_thread_stop is called. * - * This function should not be used for anything else but the videobuf2-dvb - * support. If you think you have another good use-case for this, then please - * contact the linux-media mailinglist first. + * .. attention:: + * + * This function should not be used for anything else but the videobuf2-dvb + * support. If you think you have another good use-case for this, then please + * contact the linux-media mailing list first. */ int vb2_thread_start(struct vb2_queue *q, vb2_thread_fnc fnc, void *priv, const char *thread_name); @@ -1000,6 +1021,12 @@ bool vb2_buffer_in_use(struct vb2_queue *q, struct vb2_buffer *vb); /** * vb2_verify_memory_type() - Check whether the memory type and buffer type * passed to a buffer operation are compatible with the queue. + * + * @q: videobuf queue + * @memory: memory model, as defined by enum &vb2_memory. + * @type: private buffer type whose content is defined by the vb2-core + * caller. For example, for V4L2, it should match + * the types defined on enum &v4l2_buf_type */ int vb2_verify_memory_type(struct vb2_queue *q, enum vb2_memory memory, unsigned int type); -- cgit v1.2.3 From 24ade5b6de002c51d18722e996dd92e49ad88802 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 14:22:00 -0300 Subject: [media] videobuf2-v4l2.h: get kernel-doc tags from C file There are several functions documented at the C file. Move them to the header, as this is the one used to build the media books. Signed-off-by: Mauro Carvalho Chehab --- include/media/videobuf2-v4l2.h | 151 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 150 insertions(+), 1 deletion(-) (limited to 'include') diff --git a/include/media/videobuf2-v4l2.h b/include/media/videobuf2-v4l2.h index 3cc836f76675..01b1b71fc6fd 100644 --- a/include/media/videobuf2-v4l2.h +++ b/include/media/videobuf2-v4l2.h @@ -49,22 +49,171 @@ struct vb2_v4l2_buffer { container_of(vb, struct vb2_v4l2_buffer, vb2_buf) int vb2_querybuf(struct vb2_queue *q, struct v4l2_buffer *b); + +/** + * vb2_reqbufs() - Wrapper for vb2_core_reqbufs() that also verifies + * the memory and type values. + * @q: videobuf2 queue + * @req: struct passed from userspace to vidioc_reqbufs handler + * in driver + */ int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req); +/** + * vb2_create_bufs() - Wrapper for vb2_core_create_bufs() that also verifies + * the memory and type values. + * @q: videobuf2 queue + * @create: creation parameters, passed from userspace to vidioc_create_bufs + * handler in driver + */ int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create); + +/** + * vb2_prepare_buf() - Pass ownership of a buffer from userspace to the kernel + * @q: videobuf2 queue + * @b: buffer structure passed from userspace to vidioc_prepare_buf + * handler in driver + * + * Should be called from vidioc_prepare_buf ioctl handler of a driver. + * This function: + * 1) verifies the passed buffer, + * 2) calls buf_prepare callback in the driver (if provided), in which + * driver-specific buffer initialization can be performed, + * + * The return values from this function are intended to be directly returned + * from vidioc_prepare_buf handler in driver. + */ int vb2_prepare_buf(struct vb2_queue *q, struct v4l2_buffer *b); +/** + * vb2_qbuf() - Queue a buffer from userspace + * @q: videobuf2 queue + * @b: buffer structure passed from userspace to vidioc_qbuf handler + * in driver + * + * Should be called from vidioc_qbuf ioctl handler of a driver. + * This function: + * 1) verifies the passed buffer, + * 2) if necessary, calls buf_prepare callback in the driver (if provided), in + * which driver-specific buffer initialization can be performed, + * 3) if streaming is on, queues the buffer in driver by the means of buf_queue + * callback for processing. + * + * The return values from this function are intended to be directly returned + * from vidioc_qbuf handler in driver. + */ int vb2_qbuf(struct vb2_queue *q, struct v4l2_buffer *b); + +/** + * vb2_expbuf() - Export a buffer as a file descriptor + * @q: videobuf2 queue + * @eb: export buffer structure passed from userspace to vidioc_expbuf + * handler in driver + * + * The return values from this function are intended to be directly returned + * from vidioc_expbuf handler in driver. + */ int vb2_expbuf(struct vb2_queue *q, struct v4l2_exportbuffer *eb); + +/** + * vb2_dqbuf() - Dequeue a buffer to the userspace + * @q: videobuf2 queue + * @b: buffer structure passed from userspace to vidioc_dqbuf handler + * in driver + * @nonblocking: if true, this call will not sleep waiting for a buffer if no + * buffers ready for dequeuing are present. Normally the driver + * would be passing (file->f_flags & O_NONBLOCK) here + * + * Should be called from vidioc_dqbuf ioctl handler of a driver. + * This function: + * 1) verifies the passed buffer, + * 2) calls buf_finish callback in the driver (if provided), in which + * driver can perform any additional operations that may be required before + * returning the buffer to userspace, such as cache sync, + * 3) the buffer struct members are filled with relevant information for + * the userspace. + * + * The return values from this function are intended to be directly returned + * from vidioc_dqbuf handler in driver. + */ int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking); +/** + * vb2_streamon - start streaming + * @q: videobuf2 queue + * @type: type argument passed from userspace to vidioc_streamon handler + * + * Should be called from vidioc_streamon handler of a driver. + * This function: + * 1) verifies current state + * 2) passes any previously queued buffers to the driver and starts streaming + * + * The return values from this function are intended to be directly returned + * from vidioc_streamon handler in the driver. + */ int vb2_streamon(struct vb2_queue *q, enum v4l2_buf_type type); + +/** + * vb2_streamoff - stop streaming + * @q: videobuf2 queue + * @type: type argument passed from userspace to vidioc_streamoff handler + * + * Should be called from vidioc_streamoff handler of a driver. + * This function: + * 1) verifies current state, + * 2) stop streaming and dequeues any queued buffers, including those previously + * passed to the driver (after waiting for the driver to finish). + * + * This call can be used for pausing playback. + * The return values from this function are intended to be directly returned + * from vidioc_streamoff handler in the driver + */ int vb2_streamoff(struct vb2_queue *q, enum v4l2_buf_type type); +/** + * vb2_queue_init() - initialize a videobuf2 queue + * @q: videobuf2 queue; this structure should be allocated in driver + * + * The vb2_queue structure should be allocated by the driver. The driver is + * responsible of clearing it's content and setting initial values for some + * required entries before calling this function. + * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer + * to the struct vb2_queue description in include/media/videobuf2-core.h + * for more information. + */ int __must_check vb2_queue_init(struct vb2_queue *q); + +/** + * vb2_queue_release() - stop streaming, release the queue and free memory + * @q: videobuf2 queue + * + * This function stops streaming and performs necessary clean ups, including + * freeing video buffer memory. The driver is responsible for freeing + * the vb2_queue structure itself. + */ void vb2_queue_release(struct vb2_queue *q); + +/** + * vb2_poll() - implements poll userspace operation + * @q: videobuf2 queue + * @file: file argument passed to the poll file operation handler + * @wait: wait argument passed to the poll file operation handler + * + * This function implements poll file operation handler for a driver. + * For CAPTURE queues, if a buffer is ready to be dequeued, the userspace will + * be informed that the file descriptor of a video device is available for + * reading. + * For OUTPUT queues, if a buffer is ready to be dequeued, the file descriptor + * will be reported as available for writing. + * + * If the driver uses struct v4l2_fh, then vb2_poll() will also check for any + * pending events. + * + * The return values from this function are intended to be directly returned + * from poll handler in driver. + */ unsigned int vb2_poll(struct vb2_queue *q, struct file *file, - poll_table *wait); + poll_table *wait); /* * The following functions are not part of the vb2 core API, but are simple -- cgit v1.2.3 From bf4404b482f927096ba3001d829a79f788d2265f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 18:01:44 -0300 Subject: [media] videobuf2-v4l2.h: improve documentation There are a few issues at the documentation: fields not documented, bad cross refrences, etc. Fix them. Signed-off-by: Mauro Carvalho Chehab --- include/media/videobuf2-v4l2.h | 52 +++++++++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 19 deletions(-) (limited to 'include') diff --git a/include/media/videobuf2-v4l2.h b/include/media/videobuf2-v4l2.h index 01b1b71fc6fd..611d4f330a4c 100644 --- a/include/media/videobuf2-v4l2.h +++ b/include/media/videobuf2-v4l2.h @@ -25,11 +25,13 @@ /** * struct vb2_v4l2_buffer - video buffer information for v4l2 + * * @vb2_buf: video buffer 2 * @flags: buffer informational flags * @field: enum v4l2_field; field order of the image in the buffer * @timecode: frame timecode * @sequence: sequence count of this frame + * * Should contain enough information to be able to cover all the fields * of struct v4l2_buffer at videodev2.h */ @@ -53,6 +55,7 @@ int vb2_querybuf(struct vb2_queue *q, struct v4l2_buffer *b); /** * vb2_reqbufs() - Wrapper for vb2_core_reqbufs() that also verifies * the memory and type values. + * * @q: videobuf2 queue * @req: struct passed from userspace to vidioc_reqbufs handler * in driver @@ -62,6 +65,7 @@ int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req); /** * vb2_create_bufs() - Wrapper for vb2_core_create_bufs() that also verifies * the memory and type values. + * * @q: videobuf2 queue * @create: creation parameters, passed from userspace to vidioc_create_bufs * handler in driver @@ -70,15 +74,17 @@ int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create); /** * vb2_prepare_buf() - Pass ownership of a buffer from userspace to the kernel + * * @q: videobuf2 queue * @b: buffer structure passed from userspace to vidioc_prepare_buf * handler in driver * * Should be called from vidioc_prepare_buf ioctl handler of a driver. * This function: - * 1) verifies the passed buffer, - * 2) calls buf_prepare callback in the driver (if provided), in which - * driver-specific buffer initialization can be performed, + * + * #) verifies the passed buffer, + * #) calls buf_prepare callback in the driver (if provided), in which + * driver-specific buffer initialization can be performed. * * The return values from this function are intended to be directly returned * from vidioc_prepare_buf handler in driver. @@ -88,53 +94,57 @@ int vb2_prepare_buf(struct vb2_queue *q, struct v4l2_buffer *b); /** * vb2_qbuf() - Queue a buffer from userspace * @q: videobuf2 queue - * @b: buffer structure passed from userspace to vidioc_qbuf handler + * @b: buffer structure passed from userspace to VIDIOC_QBUF() handler * in driver * - * Should be called from vidioc_qbuf ioctl handler of a driver. + * Should be called from VIDIOC_QBUF() ioctl handler of a driver. + * * This function: - * 1) verifies the passed buffer, - * 2) if necessary, calls buf_prepare callback in the driver (if provided), in + * + * #) verifies the passed buffer, + * #) if necessary, calls buf_prepare callback in the driver (if provided), in * which driver-specific buffer initialization can be performed, - * 3) if streaming is on, queues the buffer in driver by the means of buf_queue + * #) if streaming is on, queues the buffer in driver by the means of buf_queue * callback for processing. * * The return values from this function are intended to be directly returned - * from vidioc_qbuf handler in driver. + * from VIDIOC_QBUF() handler in driver. */ int vb2_qbuf(struct vb2_queue *q, struct v4l2_buffer *b); /** * vb2_expbuf() - Export a buffer as a file descriptor * @q: videobuf2 queue - * @eb: export buffer structure passed from userspace to vidioc_expbuf + * @eb: export buffer structure passed from userspace to VIDIOC_EXPBUF() * handler in driver * * The return values from this function are intended to be directly returned - * from vidioc_expbuf handler in driver. + * from VIDIOC_EXPBUF() handler in driver. */ int vb2_expbuf(struct vb2_queue *q, struct v4l2_exportbuffer *eb); /** * vb2_dqbuf() - Dequeue a buffer to the userspace * @q: videobuf2 queue - * @b: buffer structure passed from userspace to vidioc_dqbuf handler + * @b: buffer structure passed from userspace to VIDIOC_DQBUF() handler * in driver * @nonblocking: if true, this call will not sleep waiting for a buffer if no * buffers ready for dequeuing are present. Normally the driver * would be passing (file->f_flags & O_NONBLOCK) here * - * Should be called from vidioc_dqbuf ioctl handler of a driver. + * Should be called from VIDIOC_DQBUF() ioctl handler of a driver. + * * This function: - * 1) verifies the passed buffer, - * 2) calls buf_finish callback in the driver (if provided), in which + * + * #) verifies the passed buffer, + * #) calls buf_finish callback in the driver (if provided), in which * driver can perform any additional operations that may be required before * returning the buffer to userspace, such as cache sync, - * 3) the buffer struct members are filled with relevant information for + * #) the buffer struct members are filled with relevant information for * the userspace. * * The return values from this function are intended to be directly returned - * from vidioc_dqbuf handler in driver. + * from VIDIOC_DQBUF() handler in driver. */ int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking); @@ -144,7 +154,9 @@ int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking); * @type: type argument passed from userspace to vidioc_streamon handler * * Should be called from vidioc_streamon handler of a driver. + * * This function: + * * 1) verifies current state * 2) passes any previously queued buffers to the driver and starts streaming * @@ -159,9 +171,11 @@ int vb2_streamon(struct vb2_queue *q, enum v4l2_buf_type type); * @type: type argument passed from userspace to vidioc_streamoff handler * * Should be called from vidioc_streamoff handler of a driver. + * * This function: - * 1) verifies current state, - * 2) stop streaming and dequeues any queued buffers, including those previously + * + * #) verifies current state, + * #) stop streaming and dequeues any queued buffers, including those previously * passed to the driver (after waiting for the driver to finish). * * This call can be used for pausing playback. -- cgit v1.2.3 From dba2d12ae49217254cfc0452c68f1a4e2d2f1e4b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 18:12:18 -0300 Subject: [media] videobuf2-v4l2: document two helper functions Document vb2_ops_wait_prepare() and vb2_ops_wait_finish(), in order to fix those two warnings: Documentation/media/kapi/v4l2-dev.rst:166: WARNING: c:func reference target not found: vb2_ops_wait_prepare Documentation/media/kapi/v4l2-dev.rst:166: WARNING: c:func reference target not found: vb2_ops_wait_finish Signed-off-by: Mauro Carvalho Chehab --- include/media/videobuf2-v4l2.h | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) (limited to 'include') diff --git a/include/media/videobuf2-v4l2.h b/include/media/videobuf2-v4l2.h index 611d4f330a4c..036127c54bbf 100644 --- a/include/media/videobuf2-v4l2.h +++ b/include/media/videobuf2-v4l2.h @@ -268,9 +268,22 @@ unsigned long vb2_fop_get_unmapped_area(struct file *file, unsigned long addr, unsigned long len, unsigned long pgoff, unsigned long flags); #endif -/* struct vb2_ops helpers, only use if vq->lock is non-NULL. */ - +/** + * vb2_ops_wait_prepare - helper function to lock a struct &vb2_queue + * + * @vq: pointer to struct vb2_queue + * + * ..note:: only use if vq->lock is non-NULL. + */ void vb2_ops_wait_prepare(struct vb2_queue *vq); + +/** + * vb2_ops_wait_finish - helper function to unlock a struct &vb2_queue + * + * @vq: pointer to struct vb2_queue + * + * ..note:: only use if vq->lock is non-NULL. + */ void vb2_ops_wait_finish(struct vb2_queue *vq); #endif /* _MEDIA_VIDEOBUF2_V4L2_H */ -- cgit v1.2.3 From 0d56015d80a2c187c107d7780b89712bda8eee2e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 18:23:35 -0300 Subject: [media] v4l2-flash-led-class.h: document v4l2_flash_ops Fix this warning: ./include/media/v4l2-flash-led-class.h:103: WARNING: c:type reference target not found: v4l2_flash_ops Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-flash-led-class.h | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-flash-led-class.h b/include/media/v4l2-flash-led-class.h index 3d184ab52274..b0fe4d6f4a5f 100644 --- a/include/media/v4l2-flash-led-class.h +++ b/include/media/v4l2-flash-led-class.h @@ -20,7 +20,7 @@ struct led_classdev; struct v4l2_flash; enum led_brightness; -/* +/** * struct v4l2_flash_ctrl_data - flash control initialization data, filled * basing on the features declared by the LED flash * class driver in the v4l2_flash_config @@ -33,14 +33,21 @@ struct v4l2_flash_ctrl_data { u32 cid; }; +/** + * struct v4l2_flash_ops - V4L2 flash operations + * + * @external_strobe_set: Setup strobing the flash by hardware pin state + * assertion. + * @intensity_to_led_brightness: Convert intensity to brightness in a device + * specific manner + * @led_brightness_to_intensity: convert brightness to intensity in a device + * specific manner. + */ struct v4l2_flash_ops { - /* setup strobing the flash by hardware pin state assertion */ int (*external_strobe_set)(struct v4l2_flash *v4l2_flash, bool enable); - /* convert intensity to brightness in a device specific manner */ enum led_brightness (*intensity_to_led_brightness) (struct v4l2_flash *v4l2_flash, s32 intensity); - /* convert brightness to intensity in a device specific manner */ s32 (*led_brightness_to_intensity) (struct v4l2_flash *v4l2_flash, enum led_brightness); }; -- cgit v1.2.3 From cb8d67cf70b4bc7d60c356896823022717b70d1e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 8 Sep 2016 18:31:17 -0300 Subject: [media] v4l2-subdev: fix some references to v4l2_dev There is a warning there, because it was pointing to a different name. Fix it. While here, use struct &foo, instead of &struct foo. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-subdev.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h index 2c1e328ccb1d..e175c2c891a8 100644 --- a/include/media/v4l2-subdev.h +++ b/include/media/v4l2-subdev.h @@ -764,7 +764,7 @@ struct v4l2_subdev_platform_data { * @entity: pointer to &struct media_entity * @list: List of sub-devices * @owner: The owner is the same as the driver's &struct device owner. - * @owner_v4l2_dev: true if the &sd->owner matches the owner of &v4l2_dev->dev + * @owner_v4l2_dev: true if the &sd->owner matches the owner of @v4l2_dev->dev * ownner. Initialized by v4l2_device_register_subdev(). * @flags: subdev flags. Can be: * %V4L2_SUBDEV_FL_IS_I2C - Set this flag if this subdev is a i2c device; @@ -774,9 +774,9 @@ struct v4l2_subdev_platform_data { * %V4L2_SUBDEV_FL_HAS_EVENTS - Set this flag if this subdev generates * events. * - * @v4l2_dev: pointer to &struct v4l2_device - * @ops: pointer to &struct v4l2_subdev_ops - * @internal_ops: pointer to &struct v4l2_subdev_internal_ops. + * @v4l2_dev: pointer to struct &v4l2_device + * @ops: pointer to struct &v4l2_subdev_ops + * @internal_ops: pointer to struct &v4l2_subdev_internal_ops. * Never call these internal ops from within a driver! * @ctrl_handler: The control handler of this subdev. May be NULL. * @name: Name of the sub-device. Please notice that the name must be unique. -- cgit v1.2.3 From 9ef0b3f3f88d2a177e3403dd57e373d97f1c389c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 9 Sep 2016 08:40:15 -0300 Subject: [media] v4l2-subdev.h: fix a typo at a kernel-doc markup One struct at the comment was not written well. Fix it. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-subdev.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h index e175c2c891a8..863f92600607 100644 --- a/include/media/v4l2-subdev.h +++ b/include/media/v4l2-subdev.h @@ -421,7 +421,7 @@ struct v4l2_subdev_video_ops { * in video mode via the vbi device node. * * @decode_vbi_line: video decoders that support sliced VBI need to implement - * this ioctl. Field p of the &struct v4l2_sliced_vbi_line is set to the + * this ioctl. Field p of the &struct v4l2_decode_vbi_line is set to the * start of the VBI data that was generated by the decoder. The driver * then parses the sliced VBI data and sets the other fields in the * struct accordingly. The pointer p is updated to point to the start of -- cgit v1.2.3 From 283e4a82999f48c61495436b9bbd0357a3268f9d Mon Sep 17 00:00:00 2001 From: Robert Jarzmik Date: Tue, 6 Sep 2016 06:04:20 -0300 Subject: [media] media: platform: pxa_camera: make a standalone v4l2 device This patch removes the soc_camera API dependency from pxa_camera. In the current status : - all previously captures are working the same on pxa270 - the s_crop() call was removed, judged not working (see what happens soc_camera_s_crop() when get_crop() == NULL) - if the pixel clock is provided by then sensor, ie. not MCLK, the dual stage change is not handled yet. => there is no in-tree user of this, so I'll let it that way - the MCLK is not yet finished, it's as in the legacy way, ie. activated at video device opening and closed at video device closing. In a subsequence patch pxa_camera_mclk_ops should be used, and platform data MCLK ignored. It will be the sensor's duty to request the clock and enable it, which will end in pxa_camera_mclk_ops. Signed-off-by: Robert Jarzmik Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- include/linux/platform_data/media/camera-pxa.h | 2 ++ 1 file changed, 2 insertions(+) (limited to 'include') diff --git a/include/linux/platform_data/media/camera-pxa.h b/include/linux/platform_data/media/camera-pxa.h index 6709b1cd7c77..ce5d90e1a6e4 100644 --- a/include/linux/platform_data/media/camera-pxa.h +++ b/include/linux/platform_data/media/camera-pxa.h @@ -37,6 +37,8 @@ struct pxacamera_platform_data { unsigned long flags; unsigned long mclk_10khz; + int sensor_i2c_adapter_id; + int sensor_i2c_address; }; extern void pxa_set_camera_info(struct pxacamera_platform_data *); -- cgit v1.2.3 From cfe41359942b933ee0058c73df7dcc00dae64885 Mon Sep 17 00:00:00 2001 From: Jouni Ukkonen Date: Mon, 25 Apr 2016 09:19:10 -0300 Subject: [media] media: Add 1X14 14-bit raw bayer media bus code definitions The codes will be called: MEDIA_BUS_FMT_SBGGR14_1X14 MEDIA_BUS_FMT_SGBRG14_1X14 MEDIA_BUS_FMT_SGRBG14_1X14 MEDIA_BUS_FMT_SRGGB14_1X14 Signed-off-by: Jouni Ukkonen Signed-off-by: Sakari Ailus Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- include/uapi/linux/media-bus-format.h | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'include') diff --git a/include/uapi/linux/media-bus-format.h b/include/uapi/linux/media-bus-format.h index 190d491d5b13..1dff459ab6ff 100644 --- a/include/uapi/linux/media-bus-format.h +++ b/include/uapi/linux/media-bus-format.h @@ -97,7 +97,7 @@ #define MEDIA_BUS_FMT_YUV10_1X30 0x2016 #define MEDIA_BUS_FMT_AYUV8_1X32 0x2017 -/* Bayer - next is 0x3019 */ +/* Bayer - next is 0x301d */ #define MEDIA_BUS_FMT_SBGGR8_1X8 0x3001 #define MEDIA_BUS_FMT_SGBRG8_1X8 0x3013 #define MEDIA_BUS_FMT_SGRBG8_1X8 0x3002 @@ -122,6 +122,10 @@ #define MEDIA_BUS_FMT_SGBRG12_1X12 0x3010 #define MEDIA_BUS_FMT_SGRBG12_1X12 0x3011 #define MEDIA_BUS_FMT_SRGGB12_1X12 0x3012 +#define MEDIA_BUS_FMT_SBGGR14_1X14 0x3019 +#define MEDIA_BUS_FMT_SGBRG14_1X14 0x301a +#define MEDIA_BUS_FMT_SGRBG14_1X14 0x301b +#define MEDIA_BUS_FMT_SRGGB14_1X14 0x301c /* JPEG compressed formats - next is 0x4002 */ #define MEDIA_BUS_FMT_JPEG_1X8 0x4001 -- cgit v1.2.3 From 82dec0a7db16f7691470b58c28e79a2f65e829c4 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Mon, 27 Jun 2016 11:15:57 -0300 Subject: [media] media: Add 1X16 16-bit raw bayer media bus code definitions The codes will be called: MEDIA_BUS_FMT_SBGGR16_1X16 MEDIA_BUS_FMT_SGBRG16_1X16 MEDIA_BUS_FMT_SGRBG16_1X16 MEDIA_BUS_FMT_SRGGB16_1X16 Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- include/uapi/linux/media-bus-format.h | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'include') diff --git a/include/uapi/linux/media-bus-format.h b/include/uapi/linux/media-bus-format.h index 1dff459ab6ff..2168759c1287 100644 --- a/include/uapi/linux/media-bus-format.h +++ b/include/uapi/linux/media-bus-format.h @@ -97,7 +97,7 @@ #define MEDIA_BUS_FMT_YUV10_1X30 0x2016 #define MEDIA_BUS_FMT_AYUV8_1X32 0x2017 -/* Bayer - next is 0x301d */ +/* Bayer - next is 0x3021 */ #define MEDIA_BUS_FMT_SBGGR8_1X8 0x3001 #define MEDIA_BUS_FMT_SGBRG8_1X8 0x3013 #define MEDIA_BUS_FMT_SGRBG8_1X8 0x3002 @@ -126,6 +126,10 @@ #define MEDIA_BUS_FMT_SGBRG14_1X14 0x301a #define MEDIA_BUS_FMT_SGRBG14_1X14 0x301b #define MEDIA_BUS_FMT_SRGGB14_1X14 0x301c +#define MEDIA_BUS_FMT_SBGGR16_1X16 0x301d +#define MEDIA_BUS_FMT_SGBRG16_1X16 0x301e +#define MEDIA_BUS_FMT_SGRBG16_1X16 0x301f +#define MEDIA_BUS_FMT_SRGGB16_1X16 0x3020 /* JPEG compressed formats - next is 0x4002 */ #define MEDIA_BUS_FMT_JPEG_1X8 0x4001 -- cgit v1.2.3 From 68429f50ab60074e58b98010103fcc5bac4afd54 Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Tue, 3 Nov 2015 00:27:51 -0200 Subject: [media] media: Move media_device link_notify operation to an ops structure This will allow adding new operations without increasing the media_device structure size for drivers that don't implement any media device operation. Signed-off-by: Laurent Pinchart Signed-off-by: Sakari Ailus Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- include/media/media-device.h | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) (limited to 'include') diff --git a/include/media/media-device.h b/include/media/media-device.h index 481dd6c672cb..ef93e21335df 100644 --- a/include/media/media-device.h +++ b/include/media/media-device.h @@ -48,6 +48,16 @@ struct media_entity_notify { void (*notify)(struct media_entity *entity, void *notify_data); }; +/** + * struct media_device_ops - Media device operations + * @link_notify: Link state change notification callback. This callback is + * called with the graph_mutex held. + */ +struct media_device_ops { + int (*link_notify)(struct media_link *link, u32 flags, + unsigned int notification); +}; + /** * struct media_device - Media device * @dev: Parent device @@ -80,8 +90,7 @@ struct media_entity_notify { * @enable_source: Enable Source Handler function pointer * @disable_source: Disable Source Handler function pointer * - * @link_notify: Link state change notification callback. This callback is - * called with the graph_mutex held. + * @ops: Operation handler callbacks * * This structure represents an abstract high-level media device. It allows easy * access to entities and provides basic media device-level support. The @@ -150,8 +159,7 @@ struct media_device { struct media_pipeline *pipe); void (*disable_source)(struct media_entity *entity); - int (*link_notify)(struct media_link *link, u32 flags, - unsigned int notification); + const struct media_device_ops *ops; }; /* We don't need to include pci.h or usb.h here */ -- cgit v1.2.3 From fd44aa9a254b18176ec3792a18e7de6977030ca8 Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Wed, 17 Aug 2016 09:57:37 -0300 Subject: [media] v4l: rcar-fcp: Don't force users to check for disabled FCP support The rcar_fcp_enable() function immediately returns successfully when the FCP device pointer is NULL to avoid forcing the users to check the FCP device manually before every call. However, the stub version of the function used when the FCP driver is disabled returns -ENOSYS unconditionally, resulting in a different API contract for the two versions of the function. As a user that requires FCP support will fail at probe time when calling rcar_fcp_get() if the FCP driver is disabled, the stub version of the rcar_fcp_enable() function will only be called with a NULL FCP device. We can thus return 0 unconditionally to align the behaviour with the normal version of the function. Reported-by: Sergei Shtylyov Signed-off-by: Laurent Pinchart Reviewed-by: Geert Uytterhoeven Signed-off-by: Mauro Carvalho Chehab --- include/media/rcar-fcp.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/media/rcar-fcp.h b/include/media/rcar-fcp.h index 4c7fc77eaf29..8723f05c6321 100644 --- a/include/media/rcar-fcp.h +++ b/include/media/rcar-fcp.h @@ -29,7 +29,7 @@ static inline struct rcar_fcp_device *rcar_fcp_get(const struct device_node *np) static inline void rcar_fcp_put(struct rcar_fcp_device *fcp) { } static inline int rcar_fcp_enable(struct rcar_fcp_device *fcp) { - return -ENOSYS; + return 0; } static inline void rcar_fcp_disable(struct rcar_fcp_device *fcp) { } #endif -- cgit v1.2.3 From bffba4737bf39542c4cb4d276f4bf18cfa0ffa21 Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Thu, 18 Aug 2016 10:16:17 -0300 Subject: [media] v4l: vsp1: Fix tri-planar format support through DRM API The vsp1 driver supports tri-planar formats, but the DRM API only passes two memory addresses. Add a third one. Signed-off-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- include/media/vsp1.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/media/vsp1.h b/include/media/vsp1.h index 9322d9775fb7..458b400373d4 100644 --- a/include/media/vsp1.h +++ b/include/media/vsp1.h @@ -26,7 +26,7 @@ int vsp1_du_setup_lif(struct device *dev, unsigned int width, struct vsp1_du_atomic_config { u32 pixelformat; unsigned int pitch; - dma_addr_t mem[2]; + dma_addr_t mem[3]; struct v4l2_rect src; struct v4l2_rect dst; unsigned int alpha; -- cgit v1.2.3 From 7389e6ef347443ac90116c2208bbdfb4f9d135ba Mon Sep 17 00:00:00 2001 From: Charles-Antoine Couret Date: Thu, 15 Sep 2016 12:29:50 -0300 Subject: [media] SDI: add flag for SDI formats and SMPTE 125M definition Adding others generic flags, which could be used by many components like GS1662. Signed-off-by: Charles-Antoine Couret Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- include/uapi/linux/v4l2-dv-timings.h | 12 ++++++++++++ include/uapi/linux/videodev2.h | 8 ++++++++ 2 files changed, 20 insertions(+) (limited to 'include') diff --git a/include/uapi/linux/v4l2-dv-timings.h b/include/uapi/linux/v4l2-dv-timings.h index 086168e18ca8..f31957166337 100644 --- a/include/uapi/linux/v4l2-dv-timings.h +++ b/include/uapi/linux/v4l2-dv-timings.h @@ -934,4 +934,16 @@ V4L2_DV_FL_REDUCED_BLANKING) \ } +/* SDI timings definitions */ + +/* SMPTE-125M */ +#define V4L2_DV_BT_SDI_720X487I60 { \ + .type = V4L2_DV_BT_656_1120, \ + V4L2_INIT_BT_TIMINGS(720, 487, 1, \ + V4L2_DV_HSYNC_POS_POL, \ + 13500000, 16, 121, 0, 0, 19, 0, 0, 19, 0, \ + V4L2_DV_BT_STD_SDI, \ + V4L2_DV_FL_FIRST_FIELD_EXTRA_LINE) \ +} + #endif diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h index 5529741202b5..94f123f3e04e 100644 --- a/include/uapi/linux/videodev2.h +++ b/include/uapi/linux/videodev2.h @@ -1274,6 +1274,7 @@ struct v4l2_bt_timings { #define V4L2_DV_BT_STD_DMT (1 << 1) /* VESA Discrete Monitor Timings */ #define V4L2_DV_BT_STD_CVT (1 << 2) /* VESA Coordinated Video Timings */ #define V4L2_DV_BT_STD_GTF (1 << 3) /* VESA Generalized Timings Formula */ +#define V4L2_DV_BT_STD_SDI (1 << 4) /* SDI Timings */ /* Flags */ @@ -1305,6 +1306,11 @@ struct v4l2_bt_timings { * use the range 16-235) as opposed to 0-255. All formats defined in CEA-861 * except for the 640x480 format are CE formats. */ #define V4L2_DV_FL_IS_CE_VIDEO (1 << 4) +/* Some formats like SMPTE-125M have an interlaced signal with a odd + * total height. For these formats, if this flag is set, the first + * field has the extra line. If not, it is the second field. + */ +#define V4L2_DV_FL_FIRST_FIELD_EXTRA_LINE (1 << 5) /* A few useful defines to calculate the total blanking and frame sizes */ #define V4L2_DV_BT_BLANKING_WIDTH(bt) \ @@ -1429,6 +1435,8 @@ struct v4l2_input { /* field 'status' - analog */ #define V4L2_IN_ST_NO_H_LOCK 0x00000100 /* No horizontal sync lock */ #define V4L2_IN_ST_COLOR_KILL 0x00000200 /* Color killer is active */ +#define V4L2_IN_ST_NO_V_LOCK 0x00000400 /* No vertical sync lock */ +#define V4L2_IN_ST_NO_STD_LOCK 0x00000800 /* No standard format lock */ /* field 'status' - digital */ #define V4L2_IN_ST_NO_SYNC 0x00010000 /* No synchronization lock */ -- cgit v1.2.3 From e383ce0736f5ce74bbc0e989c6d044e29fefb9dc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 22 Sep 2016 07:59:03 -0300 Subject: [media] get rid of a number of problems at the cross references As warned by linuxdoc[1] tool, using: $ for i in $(git grep kernel-doc Documentation/media/kapi/|cut -d: -f4); do kernel-lintdoc --sloppy $i; done include/media/v4l2-dev.h:118 :WARN: function name from comment differs: v4l2_prio_close <--> v4l2_prio_check include/media/v4l2-mc.h:56 [kernel-doc WARN] : enum name from comment differs: if_vid_dec_index <--> if_vid_dec_pad_index include/media/v4l2-mc.h:71 [kernel-doc WARN] : enum name from comment differs: if_aud_dec_index <--> if_aud_dec_pad_index include/media/v4l2-mem2mem.h:396 [kernel-doc WARN] : function name from comment differs: v4l2_m2m_num_src_bufs_ready <--> v4l2_m2m_num_dst_bufs_ready drivers/media/dvb-core/dvb_math.h:28 [kernel-doc WARN] : function name from comment differs: cintlog2 <--> intlog2 include/media/v4l2-subdev.h:215 [kernel-doc WARN] : struct name from comment differs: s_radio <--> v4l2_subdev_tuner_ops include/media/v4l2-subdev.h:890 [kernel-doc WARN] : function name from comment differs: v4l2_set_subdevdata <--> v4l2_set_subdev_hostdata include/media/v4l2-subdev.h:901 [kernel-doc WARN] : function name from comment differs: v4l2_get_subdevdata <--> v4l2_get_subdev_hostdata drivers/media/dvb-core/dvb_ringbuffer.h:196 [kernel-doc WARN] : function name from comment differs: dvb_ringbuffer_writeuser <--> dvb_ringbuffer_write_user include/media/videobuf2-core.h:399 [kernel-doc WARN] : struct name from comment differs: vb2_ops <--> vb2_buf_ops include/media/media-entity.h:132 [kernel-doc ERROR] : duplicate parameter definition 'source' include/media/media-entity.h:477 [kernel-doc WARN] : function name from comment differs: media_entity_enum_test <--> media_entity_enum_test_and_set include/media/media-entity.h:535 [kernel-doc WARN] : function name from comment differs: gobj_to_entity <--> gobj_to_pad include/media/media-entity.h:544 [kernel-doc WARN] : function name from comment differs: gobj_to_entity <--> gobj_to_link include/media/media-entity.h:553 [kernel-doc WARN] : function name from comment differs: gobj_to_entity <--> gobj_to_intf include/media/media-entity.h:562 [kernel-doc WARN] : function name from comment differs: gobj_to_entity <--> intf_to_devnode include/media/rc-core.h:234 [kernel-doc WARN] : function name from comment differs: rc_open <--> rc_close include/media/v4l2-ctrls.h:397 [kernel-doc WARN] : missing initial short description of 'v4l2_ctrl_handler_init' include/media/v4l2-dev.h:118 [kernel-doc WARN] : function name from comment differs: v4l2_prio_close <--> v4l2_prio_check include/media/v4l2-event.h:225 [kernel-doc WARN] : missing initial short description of 'v4l2_src_change_event_subscribe' [1] https://return42.github.io/linuxdoc/linux.html The above are real issues at the documentation. On several cases, caused by cut-and-paste. Fix them. Signed-off-by: Mauro Carvalho Chehab --- include/media/media-entity.h | 13 +++++++------ include/media/rc-core.h | 2 +- include/media/v4l2-ctrls.h | 3 ++- include/media/v4l2-dev.h | 2 +- include/media/v4l2-event.h | 3 ++- include/media/v4l2-mc.h | 4 ++-- include/media/v4l2-mem2mem.h | 2 +- include/media/v4l2-subdev.h | 7 ++++--- include/media/videobuf2-core.h | 2 +- 9 files changed, 21 insertions(+), 17 deletions(-) (limited to 'include') diff --git a/include/media/media-entity.h b/include/media/media-entity.h index e21958c7c5d9..b2203ee7a4c1 100644 --- a/include/media/media-entity.h +++ b/include/media/media-entity.h @@ -129,7 +129,7 @@ struct media_pipeline { * an interface. * @gobj1: Part of a union. Used to get the pointer for the second * graph_object of the link. - * @source: Part of a union. Used only if the second object (gobj1) is + * @sink: Part of a union. Used only if the second object (gobj1) is * a pad. In that case, it represents the sink pad. * @entity: Part of a union. Used only if the second object (gobj1) is * an entity. @@ -474,7 +474,8 @@ static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum, } /** - * media_entity_enum_test - Test whether the entity is marked, and mark it + * media_entity_enum_test_and_set - Test whether the entity is marked, + * and mark it * * @ent_enum: Entity enumeration * @entity: Entity to be tested @@ -532,7 +533,7 @@ static inline bool media_entity_enum_intersects( container_of(gobj, struct media_entity, graph_obj) /** - * gobj_to_entity - returns the struct &media_pad pointer from the + * gobj_to_pad - returns the struct &media_pad pointer from the * @gobj contained on it. * * @gobj: Pointer to the struct &media_gobj graph object @@ -541,7 +542,7 @@ static inline bool media_entity_enum_intersects( container_of(gobj, struct media_pad, graph_obj) /** - * gobj_to_entity - returns the struct &media_link pointer from the + * gobj_to_link - returns the struct &media_link pointer from the * @gobj contained on it. * * @gobj: Pointer to the struct &media_gobj graph object @@ -550,7 +551,7 @@ static inline bool media_entity_enum_intersects( container_of(gobj, struct media_link, graph_obj) /** - * gobj_to_entity - returns the struct &media_interface pointer from the + * gobj_to_intf - returns the struct &media_interface pointer from the * @gobj contained on it. * * @gobj: Pointer to the struct &media_gobj graph object @@ -559,7 +560,7 @@ static inline bool media_entity_enum_intersects( container_of(gobj, struct media_interface, graph_obj) /** - * gobj_to_entity - returns the struct media_intf_devnode pointer from the + * intf_to_devnode - returns the struct media_intf_devnode pointer from the * @intf contained on it. * * @intf: Pointer to struct &media_intf_devnode diff --git a/include/media/rc-core.h b/include/media/rc-core.h index 10908e356b23..40188d362486 100644 --- a/include/media/rc-core.h +++ b/include/media/rc-core.h @@ -231,7 +231,7 @@ void rc_unregister_device(struct rc_dev *dev); int rc_open(struct rc_dev *rdev); /** - * rc_open - Closes a RC device + * rc_close - Closes a RC device * * @rdev: pointer to struct rc_dev. */ diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h index beea0a2c0894..e1006b391cdc 100644 --- a/include/media/v4l2-ctrls.h +++ b/include/media/v4l2-ctrls.h @@ -394,7 +394,8 @@ int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl, #ifdef CONFIG_LOCKDEP /** - * v4l2_ctrl_handler_init - + * v4l2_ctrl_handler_init - helper function to create a static struct + * &lock_class_key and calls v4l2_ctrl_handler_init_class() * * @hdl: The control handler. * @nr_of_controls_hint: A hint of how many controls this handler is diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h index 477e90d89a04..e657614521e3 100644 --- a/include/media/v4l2-dev.h +++ b/include/media/v4l2-dev.h @@ -115,7 +115,7 @@ void v4l2_prio_close(struct v4l2_prio_state *global, enum v4l2_priority local); enum v4l2_priority v4l2_prio_max(struct v4l2_prio_state *global); /** - * v4l2_prio_close - Implements the priority logic for a file handler close + * v4l2_prio_check - Implements the priority logic for a file handler close * * @global: pointer to the &struct v4l2_prio_state of the device node. * @local: desired priority, as defined by enum &v4l2_priority local diff --git a/include/media/v4l2-event.h b/include/media/v4l2-event.h index ca854203b8b9..a700285c64a9 100644 --- a/include/media/v4l2-event.h +++ b/include/media/v4l2-event.h @@ -222,7 +222,8 @@ int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd, struct v4l2_fh *fh, struct v4l2_event_subscription *sub); /** - * v4l2_src_change_event_subscribe - + * v4l2_src_change_event_subscribe - helper function that calls + * v4l2_event_subscribe() if the event is %V4L2_EVENT_SOURCE_CHANGE. * * @fh: pointer to struct v4l2_fh * @sub: pointer to &struct v4l2_event_subscription diff --git a/include/media/v4l2-mc.h b/include/media/v4l2-mc.h index 28c3f9d9c209..2634d9dc9916 100644 --- a/include/media/v4l2-mc.h +++ b/include/media/v4l2-mc.h @@ -53,7 +53,7 @@ enum tuner_pad_index { }; /** - * enum if_vid_dec_index - video IF-PLL pad index for + * enum if_vid_dec_pad_index - video IF-PLL pad index for * MEDIA_ENT_F_IF_VID_DECODER * * @IF_VID_DEC_PAD_IF_INPUT: video Intermediate Frequency (IF) sink pad @@ -68,7 +68,7 @@ enum if_vid_dec_pad_index { }; /** - * enum if_aud_dec_index - audio/sound IF-PLL pad index for + * enum if_aud_dec_pad_index - audio/sound IF-PLL pad index for * MEDIA_ENT_F_IF_AUD_DECODER * * @IF_AUD_DEC_PAD_IF_INPUT: audio Intermediate Frequency (IF) sink pad diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h index 498c99baf8ac..1b355344c804 100644 --- a/include/media/v4l2-mem2mem.h +++ b/include/media/v4l2-mem2mem.h @@ -393,7 +393,7 @@ unsigned int v4l2_m2m_num_src_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx) } /** - * v4l2_m2m_num_src_bufs_ready() - return the number of destination buffers + * v4l2_m2m_num_dst_bufs_ready() - return the number of destination buffers * ready for use * * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h index 863f92600607..cf778c5dca18 100644 --- a/include/media/v4l2-subdev.h +++ b/include/media/v4l2-subdev.h @@ -212,7 +212,8 @@ struct v4l2_subdev_core_ops { }; /** - * struct s_radio - Callbacks used when v4l device was opened in radio mode. + * struct v4l2_subdev_tuner_ops - Callbacks used when v4l device was opened + * in radio mode. * * @s_radio: callback for %VIDIOC_S_RADIO ioctl handler code. * @@ -887,7 +888,7 @@ static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd) } /** - * v4l2_set_subdevdata - Sets V4L2 dev private host data + * v4l2_set_subdev_hostdata - Sets V4L2 dev private host data * * @sd: pointer to &struct v4l2_subdev * @p: pointer to the private data to be stored. @@ -898,7 +899,7 @@ static inline void v4l2_set_subdev_hostdata(struct v4l2_subdev *sd, void *p) } /** - * v4l2_get_subdevdata - Gets V4L2 dev private data + * v4l2_get_subdev_hostdata - Gets V4L2 dev private data * * @sd: pointer to &struct v4l2_subdev * diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h index 9a144f2d9083..ac5898a55fd9 100644 --- a/include/media/videobuf2-core.h +++ b/include/media/videobuf2-core.h @@ -396,7 +396,7 @@ struct vb2_ops { }; /** - * struct vb2_ops - driver-specific callbacks + * struct vb2_buf_ops - driver-specific callbacks * * @verify_planes_array: Verify that a given user space structure contains * enough planes for the buffer. This is called -- cgit v1.2.3 From 2ceeca0499d745213306ecd785af17adb2321b6a Mon Sep 17 00:00:00 2001 From: Sean Young Date: Wed, 21 Sep 2016 06:54:19 -0300 Subject: [media] rc: split nec protocol into its three variants Currently we do not know what variant (bit length) of the nec protocol is used, other than from guessing from the length of the scancode. Now nec will be handled the same way as the sony protocol or the rc6 protocol; one variant per bit length. In the future we might want to expose the rc protocol type to userspace and we don't want to be introducing this world of pain into userspace too. Signed-off-by: Sean Young Signed-off-by: Mauro Carvalho Chehab --- include/media/rc-map.h | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) (limited to 'include') diff --git a/include/media/rc-map.h b/include/media/rc-map.h index 3c8edb34f84a..e1cc14cba391 100644 --- a/include/media/rc-map.h +++ b/include/media/rc-map.h @@ -24,6 +24,8 @@ * @RC_TYPE_SONY15: Sony 15 bit protocol * @RC_TYPE_SONY20: Sony 20 bit protocol * @RC_TYPE_NEC: NEC protocol + * @RC_TYPE_NECX: Extended NEC protocol + * @RC_TYPE_NEC32: NEC 32 bit protocol * @RC_TYPE_SANYO: Sanyo protocol * @RC_TYPE_MCE_KBD: RC6-ish MCE keyboard/mouse * @RC_TYPE_RC6_0: Philips RC6-0-16 protocol @@ -46,16 +48,18 @@ enum rc_type { RC_TYPE_SONY15 = 7, RC_TYPE_SONY20 = 8, RC_TYPE_NEC = 9, - RC_TYPE_SANYO = 10, - RC_TYPE_MCE_KBD = 11, - RC_TYPE_RC6_0 = 12, - RC_TYPE_RC6_6A_20 = 13, - RC_TYPE_RC6_6A_24 = 14, - RC_TYPE_RC6_6A_32 = 15, - RC_TYPE_RC6_MCE = 16, - RC_TYPE_SHARP = 17, - RC_TYPE_XMP = 18, - RC_TYPE_CEC = 19, + RC_TYPE_NECX = 10, + RC_TYPE_NEC32 = 11, + RC_TYPE_SANYO = 12, + RC_TYPE_MCE_KBD = 13, + RC_TYPE_RC6_0 = 14, + RC_TYPE_RC6_6A_20 = 15, + RC_TYPE_RC6_6A_24 = 16, + RC_TYPE_RC6_6A_32 = 17, + RC_TYPE_RC6_MCE = 18, + RC_TYPE_SHARP = 19, + RC_TYPE_XMP = 20, + RC_TYPE_CEC = 21, }; #define RC_BIT_NONE 0ULL @@ -69,6 +73,8 @@ enum rc_type { #define RC_BIT_SONY15 (1ULL << RC_TYPE_SONY15) #define RC_BIT_SONY20 (1ULL << RC_TYPE_SONY20) #define RC_BIT_NEC (1ULL << RC_TYPE_NEC) +#define RC_BIT_NECX (1ULL << RC_TYPE_NECX) +#define RC_BIT_NEC32 (1ULL << RC_TYPE_NEC32) #define RC_BIT_SANYO (1ULL << RC_TYPE_SANYO) #define RC_BIT_MCE_KBD (1ULL << RC_TYPE_MCE_KBD) #define RC_BIT_RC6_0 (1ULL << RC_TYPE_RC6_0) @@ -84,8 +90,9 @@ enum rc_type { RC_BIT_RC5 | RC_BIT_RC5X | RC_BIT_RC5_SZ | \ RC_BIT_JVC | \ RC_BIT_SONY12 | RC_BIT_SONY15 | RC_BIT_SONY20 | \ - RC_BIT_NEC | RC_BIT_SANYO | RC_BIT_MCE_KBD | \ - RC_BIT_RC6_0 | RC_BIT_RC6_6A_20 | RC_BIT_RC6_6A_24 | \ + RC_BIT_NEC | RC_BIT_NECX | RC_BIT_NEC32 | \ + RC_BIT_SANYO | RC_BIT_MCE_KBD | RC_BIT_RC6_0 | \ + RC_BIT_RC6_6A_20 | RC_BIT_RC6_6A_24 | \ RC_BIT_RC6_6A_32 | RC_BIT_RC6_MCE | RC_BIT_SHARP | \ RC_BIT_XMP | RC_BIT_CEC) -- cgit v1.2.3