Skip to content

L
linux
Commit d26a5d43 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files
Options

[media] doc-rst: Convert media API to rst 

Move the contents of the media section at
DocBooks/DocBook/device-drivers.tmpl to a new ReST book.

For now, the contents is kept as-is. Next patches will fix
the warnings and add cross-references that were removed due to
the conversion.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent 520a2477
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 423 additions and 379 deletions
Documentation/DocBook/device-drivers.tmpl
View file @ d26a5d43
......@@ -219,64 +219,6 @@ X!Isound/sound_firmware.c
-->
</chapter>
<chapter id="mediadev">
<title>Media Devices</title>
<sect1><title>Video2Linux devices</title>
!Iinclude/media/tuner.h
!Iinclude/media/tuner-types.h
!Iinclude/media/tveeprom.h
!Iinclude/media/v4l2-async.h
!Iinclude/media/v4l2-ctrls.h
!Iinclude/media/v4l2-dv-timings.h
!Iinclude/media/v4l2-event.h
!Iinclude/media/v4l2-flash-led-class.h
!Iinclude/media/v4l2-mc.h
!Iinclude/media/v4l2-mediabus.h
!Iinclude/media/v4l2-mem2mem.h
!Iinclude/media/v4l2-of.h
!Iinclude/media/v4l2-rect.h
!Iinclude/media/v4l2-subdev.h
!Iinclude/media/videobuf2-core.h
!Iinclude/media/videobuf2-v4l2.h
!Iinclude/media/videobuf2-memops.h
</sect1>
<sect1><title>Digital TV (DVB) devices</title>
<sect1><title>Digital TV Common functions</title>
!Idrivers/media/dvb-core/dvb_math.h
!Idrivers/media/dvb-core/dvb_ringbuffer.h
!Idrivers/media/dvb-core/dvbdev.h
</sect1>
<sect1><title>Digital TV Frontend kABI</title>
!Pdrivers/media/dvb-core/dvb_frontend.h Digital TV Frontend
!Idrivers/media/dvb-core/dvb_frontend.h
</sect1>
<sect1><title>Digital TV Demux kABI</title>
!Pdrivers/media/dvb-core/demux.h Digital TV Demux
<sect1><title>Demux Callback API</title>
!Pdrivers/media/dvb-core/demux.h Demux Callback
</sect1>
!Idrivers/media/dvb-core/demux.h
</sect1>
<sect1><title>Digital TV Conditional Access kABI</title>
!Idrivers/media/dvb-core/dvb_ca_en50221.h
</sect1>
</sect1>
<sect1><title>Remote Controller devices</title>
!Iinclude/media/rc-core.h
!Iinclude/media/lirc_dev.h
</sect1>
<sect1><title>Media Controller devices</title>
!Pinclude/media/media-device.h Media Controller
!Iinclude/media/media-device.h
!Iinclude/media/media-devnode.h
!Iinclude/media/media-entity.h
</sect1>
<sect1><title>Consumer Electronics Control devices</title>
!Iinclude/media/cec-edid.h
</sect1>
</chapter>
<chapter id="uart16x50">
<title>16x50 UART Driver</title>
......
Documentation/index.rst
View file @ d26a5d43
......@@ -15,6 +15,7 @@ Contents:
kernel-documentation
media/media_uapi
media/media_drivers
Indices and tables
==================
......
Documentation/media/media_drivers.rst 0 → 100644
View file @ d26a5d43
This diff is collapsed.
drivers/media/dvb-core/demux.h
View file @ d26a5d43
/*
* demux.h
*
* The Kernel Digital TV Demux kABI defines a driver-internal interface for
* registering low-level, hardware specific driver to a hardware independent
* demux layer.
*
* Copyright (c) 2002 Convergence GmbH
*
* based on code:
......@@ -32,49 +36,6 @@
#include <linux/time.h>
#include <linux/dvb/dmx.h>
/**
* DOC: Digital TV Demux
*
* The Kernel Digital TV Demux kABI defines a driver-internal interface for
* registering low-level, hardware specific driver to a hardware independent
* demux layer. It is only of interest for Digital TV device driver writers.
* The header file for this kABI is named demux.h and located in
* drivers/media/dvb-core.
*
* The demux kABI should be implemented for each demux in the system. It is
* used to select the TS source of a demux and to manage the demux resources.
* When the demux client allocates a resource via the demux kABI, it receives
* a pointer to the kABI of that resource.
*
* Each demux receives its TS input from a DVB front-end or from memory, as
* set via this demux kABI. In a system with more than one front-end, the kABI
* can be used to select one of the DVB front-ends as a TS source for a demux,
* unless this is fixed in the HW platform.
*
* The demux kABI only controls front-ends regarding to their connections with
* demuxes; the kABI used to set the other front-end parameters, such as
* tuning, are devined via the Digital TV Frontend kABI.
*
* The functions that implement the abstract interface demux should be defined
* static or module private and registered to the Demux core for external
* access. It is not necessary to implement every function in the struct
* &dmx_demux. For example, a demux interface might support Section filtering,
* but not PES filtering. The kABI client is expected to check the value of any
* function pointer before calling the function: the value of NULL means
* that the function is not available.
*
* Whenever the functions of the demux API modify shared data, the
* possibilities of lost update and race condition problems should be
* addressed, e.g. by protecting parts of code with mutexes.
*
* Note that functions called from a bottom half context must not sleep.
* Even a simple memory allocation without using %GFP_ATOMIC can result in a
* kernel thread being put to sleep if swapping is needed. For example, the
* Linux Kernel calls the functions of a network device interface from a
* bottom half context. Thus, if a demux kABI function is called from network
* device code, the function must not sleep.
*/
/*
* Common definitions
*/
......@@ -230,30 +191,6 @@ struct dmx_section_feed {
int (*stop_filtering)(struct dmx_section_feed *feed);
};
/**
* DOC: Demux Callback
*
* This kernel-space API comprises the callback functions that deliver filtered
* data to the demux client. Unlike the other DVB kABIs, these functions are
* provided by the client and called from the demux code.
*
* The function pointers of this abstract interface are not packed into a
* structure as in the other demux APIs, because the callback functions are
* registered and used independent of each other. As an example, it is possible
* for the API client to provide several callback functions for receiving TS
* packets and no callbacks for PES packets or sections.
*
* The functions that implement the callback API need not be re-entrant: when
* a demux driver calls one of these functions, the driver is not allowed to
* call the function again before the original call returns. If a callback is
* triggered by a hardware interrupt, it is recommended to use the Linux
* bottom half mechanism or start a tasklet instead of making the callback
* function call directly from a hardware interrupt.
*
* This mechanism is implemented by dmx_ts_cb() and dmx_section_cb()
* callbacks.
*/
/**
* typedef dmx_ts_cb - DVB demux TS filter callback function prototype
*
......
drivers/media/dvb-core/dvb_frontend.h
View file @ d26a5d43
/*
* dvb_frontend.h
*
* The Digital TV Frontend kABI defines a driver-internal interface for
* registering low-level, hardware specific driver to a hardware independent
* frontend layer.
*
* Copyright (C) 2001 convergence integrated media GmbH
* Copyright (C) 2004 convergence GmbH
*
......@@ -42,29 +46,6 @@
#include "dvbdev.h"
/**
* DOC: Digital TV Frontend
*
* The Digital TV Frontend kABI defines a driver-internal interface for
* registering low-level, hardware specific driver to a hardware independent
* frontend layer. It is only of interest for Digital TV device driver writers.
* 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(),
* 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.
*
* 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().
*
* A few other optional functions are provided to handle some special cases.
*/
/*
* Maximum number of Delivery systems per frontend. It
* should be smaller or equal to 32
......
include/media/media-device.h
View file @ d26a5d43
......@@ -29,237 +29,6 @@
#include <media/media-devnode.h>
#include <media/media-entity.h>
/**
* DOC: Media Controller
*
* The media controller userspace API is documented in DocBook format in
* Documentation/DocBook/media/v4l/media-controller.xml. This document focus
* on the kernel-side implementation of the media framework.
*
* * Abstract media device model:
*
* Discovering a device internal topology, and configuring it at runtime, is one
* of the goals of the media framework. To achieve this, hardware devices are
* modelled as an oriented graph of building blocks called entities connected
* through pads.
*
* An entity is a basic media hardware building block. It can correspond to
* a large variety of logical blocks such as physical hardware devices
* (CMOS sensor for instance), logical hardware devices (a building block
* in a System-on-Chip image processing pipeline), DMA channels or physical
* connectors.
*
* A pad is a connection endpoint through which an entity can interact with
* other entities. Data (not restricted to video) produced by an entity
* flows from the entity's output to one or more entity inputs. Pads should
* not be confused with physical pins at chip boundaries.
*
* A link is a point-to-point oriented connection between two pads, either
* on the same entity or on different entities. Data flows from a source
* pad to a sink pad.
*
*
* * Media device:
*
* A media device is represented by a struct &media_device instance, defined in
* include/media/media-device.h. Allocation of the structure is handled by the
* media device driver, usually by embedding the &media_device instance in a
* larger driver-specific structure.
*
* Drivers register media device instances by calling
* __media_device_register() via the macro media_device_register()
* and unregistered by calling
* media_device_unregister().
*
* * Entities, pads and links:
*
* - Entities
*
* Entities are represented by a struct &media_entity instance, defined in
* include/media/media-entity.h. The structure is usually embedded into a
* higher-level structure, such as a v4l2_subdev or video_device instance,
* although drivers can allocate entities directly.
*
* Drivers initialize entity pads by calling
* media_entity_pads_init().
*
* Drivers register entities with a media device by calling
* media_device_register_entity()
* and unregistred by calling
* media_device_unregister_entity().
*
* - Interfaces
*
* Interfaces are represented by a struct &media_interface instance, defined in
* include/media/media-entity.h. Currently, only one type of interface is
* defined: a device node. Such interfaces are represented by a struct
* &media_intf_devnode.
*
* Drivers initialize and create device node interfaces by calling
* media_devnode_create()
* and remove them by calling:
* media_devnode_remove().
*
* - Pads
*
* Pads are represented by a struct &media_pad instance, defined in
* include/media/media-entity.h. Each entity stores its pads in a pads array
* managed by the entity driver. Drivers usually embed the array in a
* driver-specific structure.
*
* Pads are identified by their entity and their 0-based index in the pads
* array.
* Both information are stored in the &media_pad structure, making the
* &media_pad pointer the canonical way to store and pass link references.
*
* Pads have flags that describe the pad capabilities and state.
*
* %MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
* %MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
*
* NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must
* be set for each pad.
*
* - Links
*
* Links are represented by a struct &media_link instance, defined in
* include/media/media-entity.h. There are two types of links:
*
* 1. pad to pad links:
*
* Associate two entities via their PADs. Each entity has a list that points
* to all links originating at or targeting any of its pads.
* A given link is thus stored twice, once in the source entity and once in
* the target entity.
*
* Drivers create pad to pad links by calling:
* media_create_pad_link() and remove with media_entity_remove_links().
*
* 2. interface to entity links:
*
* Associate one interface to a Link.
*
* Drivers create interface to entity links by calling:
* media_create_intf_link() and remove with media_remove_intf_links().
*
* NOTE:
*
* Links can only be created after having both ends already created.
*
* Links have flags that describe the link capabilities and state. The
* valid values are described at media_create_pad_link() and
* media_create_intf_link().
*
* Graph traversal:
*
* The media framework provides APIs to iterate over entities in a graph.
*
* To iterate over all entities belonging to a media device, drivers can use
* the media_device_for_each_entity macro, defined in
* include/media/media-device.h.
*
* struct media_entity *entity;
*
* media_device_for_each_entity(entity, mdev) {
* // entity will point to each entity in turn
* ...
* }
*
* Drivers might also need to iterate over all entities in a graph that can be
* reached only through enabled links starting at a given entity. The media
* framework provides a depth-first graph traversal API for that purpose.
*
* Note that graphs with cycles (whether directed or undirected) are *NOT*
* supported by the graph traversal API. To prevent infinite loops, the graph
* traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
* currently defined as 16.
*
* Drivers initiate a graph traversal by calling
* media_entity_graph_walk_start()
*
* The graph structure, provided by the caller, is initialized to start graph
* traversal at the given entity.
*
* Drivers can then retrieve the next entity by calling
* media_entity_graph_walk_next()
*
* When the graph traversal is complete the function will return NULL.
*
* Graph traversal can be interrupted at any moment. No cleanup function call
* is required and the graph structure can be freed normally.
*
* Helper functions can be used to find a link between two given pads, or a pad
* connected to another pad through an enabled link
* media_entity_find_link() and media_entity_remote_pad()
*
* Use count and power handling:
*
* Due to the wide differences between drivers regarding power management
* needs, the media controller does not implement power management. However,
* the &media_entity structure includes a use_count field that media drivers
* can use to track the number of users of every entity for power management
* needs.
*
* The &media_entity.@use_count field is owned by media drivers and must not be
* touched by entity drivers. Access to the field must be protected by the
* &media_device.@graph_mutex lock.
*
* Links setup:
*
* Link properties can be modified at runtime by calling
* media_entity_setup_link()
*
* Pipelines and media streams:
*
* When starting streaming, drivers must notify all entities in the pipeline to
* prevent link states from being modified during streaming by calling
* media_entity_pipeline_start().
*
* The function will mark all entities connected to the given entity through
* enabled links, either directly or indirectly, as streaming.
*
* The &media_pipeline instance pointed to by the pipe argument will be stored
* in every entity in the pipeline. Drivers should embed the &media_pipeline
* structure in higher-level pipeline structures and can then access the
* pipeline through the &media_entity pipe field.
*
* Calls to media_entity_pipeline_start() can be nested. The pipeline pointer
* must be identical for all nested calls to the function.
*
* media_entity_pipeline_start() may return an error. In that case, it will
* clean up any of the changes it did by itself.
*
* When stopping the stream, drivers must notify the entities with
* media_entity_pipeline_stop().
*
* If multiple calls to media_entity_pipeline_start() have been made the same
* number of media_entity_pipeline_stop() calls are required to stop streaming.
* The &media_entity pipe field is reset to NULL on the last nested stop call.
*
* Link configuration will fail with -%EBUSY by default if either end of the
* link is a streaming entity. Links that can be modified while streaming must
* be marked with the %MEDIA_LNK_FL_DYNAMIC flag.
*
* If other operations need to be disallowed on streaming entities (such as
* changing entities configuration parameters) drivers can explicitly check the
* media_entity stream_count field to find out if an entity is streaming. This
* operation must be done with the media_device graph_mutex held.
*
* Link validation:
*
* Link validation is performed by media_entity_pipeline_start() for any
* entity which has sink pads in the pipeline. The
* &media_entity.@link_validate() callback is used for that purpose. In
* @link_validate() callback, entity driver should check that the properties of
* the source pad of the connected entity and its own sink pad match. It is up
* to the type of the entity (and in the end, the properties of the hardware)
* what matching actually means.
*
* Subsystems should facilitate link validation by providing subsystem specific
* helper functions to provide easy access for commonly needed information, and
* in the end provide a way to use driver-specific callbacks.
*/
struct ida;
struct device;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7