Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit d2f01985 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

[media] doc-rst: Fix conversion for dvb-core.rst 



The conversion from DocBook required some fixes:

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

- Fix the cross-references at the media controller description.

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

Documentation/media/kapi/dtv-core.rst

+27 −13
Original line number Diff line number Diff line
@@ -11,6 +11,15 @@ Digital TV Common functions 
.. kernel-doc:: drivers/media/dvb-core/dvbdev.h







.. kernel-doc:: drivers/media/dvb-core/dvb_math.h

   :export: drivers/media/dvb-core/dvb_math.c



.. kernel-doc:: drivers/media/dvb-core/dvbdev.h

   :export: drivers/media/dvb-core/dvbdev.c







Digital TV Frontend kABI

------------------------
@@ -24,17 +33,20 @@ The header file for this API is named dvb_frontend.h and located in 
drivers/media/dvb-core.



Before using the Digital TV frontend core, the bridge driver should attach

the frontend demod, tuner and SEC devices and call dvb_register_frontend(),

the frontend demod, tuner and SEC devices and call

:cpp:func:`dvb_register_frontend()`,

in order to register the new frontend at the subsystem. At device

detach/removal, the bridge driver should call dvb_unregister_frontend() to

remove the frontend from the core and then dvb_frontend_detach() to free the

memory allocated by the frontend drivers.

detach/removal, the bridge driver should call

:cpp:func:`dvb_unregister_frontend()` to

remove the frontend from the core and then :cpp:func:`dvb_frontend_detach()`

to free the memory allocated by the frontend drivers.



The drivers should also call dvb_frontend_suspend() as part of their

handler for the &device_driver.suspend(), and dvb_frontend_resume() as

part of their handler for &device_driver.resume().

The drivers should also call :cpp:func:`dvb_frontend_suspend()` as part of

their handler for the :c:type:`device_driver`.\ ``suspend()``, and

:cpp:func:`dvb_frontend_resume()` as

part of their handler for :c:type:`device_driver`.\ ``resume()``.



few other optional functions are provided to handle some special cases.

A few other optional functions are provided to handle some special cases.



.. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h
@@ -70,7 +82,7 @@ static or module private and registered to the Demux core for external 
access. It is not necessary to implement every function in the struct

&dmx_demux. For example, a demux interface might support Section filtering,

but not PES filtering. The kABI client is expected to check the value of any

function pointer before calling the function: the value of NULL means

function pointer before calling the function: the value of ``NULL`` means

that the function is not available.



Whenever the functions of the demux API modify shared data, the
@@ -78,7 +90,7 @@ possibilities of lost update and race condition problems should be 
addressed, e.g. by protecting parts of code with mutexes.



Note that functions called from a bottom half context must not sleep.

Even a simple memory allocation without using %GFP_ATOMIC can result in a

Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a

kernel thread being put to sleep if swapping is needed. For example, the

Linux Kernel calls the functions of a network device interface from a

bottom half context. Thus, if a demux kABI function is called from network
@@ -109,14 +121,16 @@ triggered by a hardware interrupt, it is recommended to use the Linux 
bottom half mechanism or start a tasklet instead of making the callback

function call directly from a hardware interrupt.



This mechanism is implemented by dmx_ts_cb() and dmx_section_cb()

This mechanism is implemented by :cpp:func:`dmx_ts_cb()` and :cpp:func:`dmx_section_cb()`

callbacks.





.. kernel-doc:: drivers/media/dvb-core/demux.h





Digital TV Conditional Access kABI

----------------------------------



.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h





.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h

   :export: drivers/media/dvb-core/dvb_ca_en50221.c

drivers/media/dvb-core/demux.h

+45 −45
Original line number Diff line number Diff line
@@ -379,7 +379,7 @@ enum dmx_demux_caps { 
 *	@open is called and decrement it when @close is called.

 *	The @demux function parameter contains a pointer to the demux API and

 *	instance data.

 *	It returns

 *	It returns:

 *	0 on success;

 *	-EUSERS, if maximum usage count was reached;

 *	-EINVAL, on bad parameter.
@@ -392,7 +392,7 @@ enum dmx_demux_caps { 
 *	@open is called and decrement it when @close is called.

 *	The @demux function parameter contains a pointer to the demux API and

 *	instance data.

 *	It returns

 *	It returns:

 *	0 on success;

 *	-ENODEV, if demux was not in use (e. g. no users);

 *	-EINVAL, on bad parameter.
@@ -410,7 +410,7 @@ enum dmx_demux_caps { 
 *	The @buf function parameter contains a pointer to the TS data in

 *	kernel-space memory.

 *	The @count function parameter contains the length of the TS data.

 *	It returns

 *	It returns:

 *	0 on success;

 *	-ERESTARTSYS, if mutex lock was interrupted;

 *	-EINTR, if a signal handling is pending;
@@ -426,7 +426,7 @@ enum dmx_demux_caps { 
 *	instance data.

 *	The @callback function parameter contains a pointer to the callback

 *	function for passing received TS packet.

 *	It returns

 *	It returns:

 *	0 on success;

 *	-ERESTARTSYS, if mutex lock was interrupted;

 *	-EBUSY, if no more TS feeds is available;
@@ -439,7 +439,7 @@ enum dmx_demux_caps { 
 *	instance data.

 *	The @feed function parameter contains a pointer to the TS feed API and

 *	instance data.

 *	It returns

 *	It returns:

 *	0 on success;

 *	-EINVAL on bad parameter.

 *
@@ -457,7 +457,7 @@ enum dmx_demux_caps { 
 *	instance data.

 *	The @callback function parameter contains a pointer to the callback

 *	function for passing received TS packet.

 *	It returns

 *	It returns:

 *	0 on success;

 *	-EBUSY, if no more TS feeds is available;

 *	-EINVAL, on bad parameter.
@@ -470,7 +470,7 @@ enum dmx_demux_caps { 
 *	instance data.

 *	The @feed function parameter contains a pointer to the TS feed API and

 *	instance data.

 *	It returns

 *	It returns:

 *	0 on success;

 *	-EINVAL, on bad parameter.

 *
@@ -486,7 +486,7 @@ enum dmx_demux_caps { 
 *	instance data.

 *	The @frontend function parameter contains a pointer to the front-end

 *	instance data.

 *	It returns

 *	It returns:

 *	0 on success;

 *	-EINVAL, on bad parameter.

 *
@@ -502,7 +502,7 @@ enum dmx_demux_caps { 
 *	instance data.

 *	The @frontend function parameter contains a pointer to the front-end

 *	instance data.

 *	It returns

 *	It returns:

 *	0 on success;

 *	-ENODEV, if the front-end was not found,

 *	-EINVAL, on bad parameter.
@@ -529,7 +529,7 @@ enum dmx_demux_caps { 
 *	instance data.

 *	The @frontend function parameter contains a pointer to the front-end

 *	instance data.

 *	It returns

 *	It returns:

 *	0 on success;

 *	-EINVAL, on bad parameter.

 *
@@ -537,7 +537,7 @@ enum dmx_demux_caps { 
 *	connected by a @connect_frontend call.

 *	The @demux function parameter contains a pointer to the demux API and

 *	instance data.

 *	It returns

 *	It returns:

 *	0 on success;

 *	-EINVAL on bad parameter.

 *
@@ -547,7 +547,7 @@ enum dmx_demux_caps { 
 *	instance data.

 *	The @pids function parameter contains an array with five u16 elements

 *	where the PIDs will be stored.

 *	It returns

 *	It returns:

 *	0 on success;

 *	-EINVAL on bad parameter.

 */