Commit 89cb3ddb authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

[media] doc-rst: Fix conversion for v4l2 core functions 



The conversion from DocBook lead into some conversion issues,
basically due to the lack of proper support at kernel-doc.

So, address them:

- Now, the C files with the exported symbols also need to be
  added. So, all headers need to be included twice: one to
  get the structs/enums/.. and another one for the functions;

- Notes should use the ReST tag, as kernel-doc doesn't
  recognizes it anymore;

- Identation needs to be fixed, as ReST uses it to identify
  when a format "tag" ends.

- kernel-doc doesn't escape things like *pointer, so we
  need to manually add a escape char before it.

- On some cases, kernel-doc conversion requires violating
  the 80-cols, as otherwise it won't properly parse the
  source code.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent 5b6137dc

Documentation/media/kapi/v4l2-core.rst

+21 −0
Original line number Diff line number Diff line
@@ -34,3 +34,24 @@ Video2Linux devices 
.. kernel-doc:: include/media/videobuf2-v4l2.h



.. kernel-doc:: include/media/videobuf2-memops.h









.. kernel-doc:: include/media/tveeprom.h

   :export: drivers/media/common/tveeprom.c



.. kernel-doc:: include/media/v4l2-ctrls.h

   :export: drivers/media/v4l2-core/v4l2-ctrls.c



.. kernel-doc:: include/media/v4l2-dv-timings.h

   :export: drivers/media/v4l2-core/v4l2-dv-timings.c



.. kernel-doc:: include/media/v4l2-flash-led-class.h

   :export: drivers/media/v4l2-core/v4l2-flash-led-class.c



.. kernel-doc:: include/media/v4l2-mc.h

   :export: drivers/media/v4l2-core/v4l2-mc.c



.. kernel-doc:: include/media/videobuf2-core.h

   :export: drivers/media/v4l2-core/videobuf2-core.c

include/media/tuner-types.h

+6 −2
Original line number Diff line number Diff line
@@ -35,8 +35,12 @@ enum param_type { 
 * those ranges, as they're defined inside the driver. This is used by

 * analog tuners that are compatible with the "Philips way" to setup the

 * tuners. On those devices, the tuner set is done via 4 bytes:

 *	divider byte1 (DB1), divider byte 2 (DB2), Control byte (CB) and

 *	band switch byte (BB).

 *

 *	#) divider byte1 (DB1)

 *	#) divider byte 2 (DB2)

 *	#) Control byte (CB)

 *	#) band switch byte (BB)

 *

 * Some tuners also have an additional optional Auxiliary byte (AB).

 */

struct tuner_range {

include/media/tveeprom.h

+15 −3
Original line number Diff line number Diff line
@@ -27,31 +27,43 @@ enum tveeprom_audio_processor { 
 * struct tveeprom - Contains the fields parsed from Hauppauge eeproms

 *

 * @has_radio:			1 if the device has radio; 0 otherwise.

 *

 * @has_ir:			If has_ir == 0, then it is unknown what the IR

 *				capabilities are. Otherwise:

 *				bit 0) 1 (= IR capabilities are known);

 *				bit 1) IR receiver present;

 *				bit 2) IR transmitter (blaster) present.

 *

 * @has_MAC_address:		0: no MAC, 1: MAC present, 2: unknown.

 * @tuner_type:			type of the tuner (TUNER_*, as defined at

 *				include/media/tuner.h).

 *

 * @tuner_formats:		Supported analog TV standards (V4L2_STD_*).

 * @tuner_hauppauge_model:	Hauppauge's code for the device model number.

 * @tuner2_type:		type of the second tuner (TUNER_*, as defined

 *				at include/media/tuner.h).

 *

 * @tuner2_formats:		Tuner 2 supported analog TV standards

 *				(V4L2_STD_*).

 *

 * @tuner2_hauppauge_model:	tuner 2 Hauppauge's code for the device model

 *				number.

 *

 * @audio_processor:		analog audio decoder, as defined by enum

 *				tveeprom_audio_processor.

 *

 * @decoder_processor:		Hauppauge's code for the decoder chipset.

 *				Unused by the drivers, as they probe the

 *				decoder based on the PCI or USB ID.

 *

 * @model:			Hauppauge's model number

 *

 * @revision:			Card revision number

 *

 * @serial_number:		Card's serial number

 *

 * @rev_str:			Card revision converted to number

 *

 * @MAC_address:		MAC address for the network interface

 */

struct tveeprom {

include/media/v4l2-mc.h

+8 −5
Original line number Diff line number Diff line
@@ -114,7 +114,10 @@ struct usb_device; 
 * Add links between the entities commonly found on PC customer's hardware at

 * the V4L2 side: camera sensors, audio and video PLL-IF decoders, tuners,

 * analog TV decoder and I/O entities (video, VBI and Software Defined Radio).

 * NOTE: webcams are modelled on a very simple way: the sensor is

 *

 * .. note::

 *

 *    Webcams are modelled on a very simple way: the sensor is

 *    connected directly to the I/O entity. All dirty details, like

 *    scaler and crop HW are hidden. While such mapping is enough for v4l2

 *    interface centric PC-consumer's hardware, V4L2 subdev centric camera

include/media/videobuf2-core.h

+18 −12
Original line number Diff line number Diff line
@@ -86,11 +86,17 @@ struct vb2_threadio_data; 
 * @mmap:	setup a userspace mapping for a given memory buffer under

 *		the provided virtual memory region.

 *

 * Required ops for USERPTR types: get_userptr, put_userptr.

 * Required ops for MMAP types: alloc, put, num_users, mmap.

 * 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.

 * Those operations are used by the videobuf2 core to implement the memory

 * handling/memory allocators for each type of supported streaming I/O method.

 *

 * .. note::

 *    #) Required ops for USERPTR types: get_userptr, put_userptr.

 *

 *    #) Required ops for MMAP types: alloc, put, num_users, mmap.

 *

 *    #) 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.

 */

struct vb2_mem_ops {

	void		*(*alloc)(void *alloc_ctx, unsigned long size,
@@ -279,19 +285,19 @@ struct vb2_buffer { 
 *			second time with the actually allocated number of

 *			buffers to verify if that is OK.

 *			The driver should return the required number of buffers

 *			in *num_buffers, the required number of planes per

 *			buffer in *num_planes, the size of each plane should be

 *			in \*num_buffers, the required number of planes per

 *			buffer in \*num_planes, the size of each plane should be

 *			set in the sizes[] array and optional per-plane

 *			allocator specific context in the alloc_ctxs[] array.

 *			When called from VIDIOC_REQBUFS, *num_planes == 0, the

 *			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

 *			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

 *			must return -EINVAL. In this case *num_buffers are

 *			\*num_planes or the requested sizes are invalid callback

 *			must return -EINVAL. In this case \*num_buffers are

 *			being allocated additionally to q->num_buffers.

 * @wait_prepare:	release any locks taken while calling vb2 functions;

 *			it is called before an ioctl needs to wait for a new

include/media/v4l2-subdev.h

+2 −2

File changed.

Contains only whitespace changes.

CRA Git | Maintained and supported by SUSTech CRA and CCSE