From patchwork Sat Oct 10 13:36:08 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 7366621 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id CAF5EBEEA4 for ; Sat, 10 Oct 2015 13:37:56 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id C28E8206BA for ; Sat, 10 Oct 2015 13:37:55 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 9AEFA206C3 for ; Sat, 10 Oct 2015 13:37:54 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752087AbbJJNgs (ORCPT ); Sat, 10 Oct 2015 09:36:48 -0400 Received: from bombadil.infradead.org ([198.137.202.9]:39207 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751397AbbJJNgS (ORCPT ); Sat, 10 Oct 2015 09:36:18 -0400 Received: from [179.183.104.18] (helo=smtp.w2.samsung.com) by bombadil.infradead.org with esmtpsa (Exim 4.80.1 #2 (Red Hat Linux)) id 1ZkuJt-0003Bt-UB; Sat, 10 Oct 2015 13:36:18 +0000 Received: from mchehab by smtp.w2.samsung.com with local (Exim 4.85) (envelope-from ) id 1ZkuJm-0003lv-Qh; Sat, 10 Oct 2015 10:36:10 -0300 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Jonathan Corbet , Thierry Reding , linux-doc@vger.kernel.org Subject: [PATCH 25/26] [media] DocBook: Add documentation about the demux API Date: Sat, 10 Oct 2015 10:36:08 -0300 Message-Id: X-Mailer: git-send-email 2.4.3 In-Reply-To: References: In-Reply-To: References: Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP There are several stuff at media's kdapi.xml that don't belong there, as it documents the Kernel internal ABI, and not the userspace API. Add the documentation here. The hole kdapi.xml will be removed on a latter patch, after we finish documenting what's there at the proper places. Signed-off-by: Mauro Carvalho Chehab diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 8d5620aeaf36..42a2d8593e39 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -239,21 +239,86 @@ X!Isound/sound_firmware.c Digital TV (DVB) devices !Idrivers/media/dvb-core/dvb_ca_en50221.h -!Idrivers/media/dvb-core/demux.h !Idrivers/media/dvb-core/dvb_frontend.h !Idrivers/media/dvb-core/dvb_math.h !Idrivers/media/dvb-core/dvb_ringbuffer.h !Idrivers/media/dvb-core/dvbdev.h - - Remote Controller devices + Digital TV Demux API + The kernel demux API 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 API is named + demux.h and located in + drivers/media/dvb-core. + + The demux API 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 API, it receives a pointer to the API of that + resource. + Each demux receives its TS input from a DVB front-end or from + memory, as set via this demux API. In a system with more than one + front-end, the API 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 API only controls front-ends regarding to their connections + with demuxes; the APIs used to set the other front-end parameters, + such as tuning, are not defined in this document. + 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 API 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 API function + is called from network device code, the function must not sleep. + + + +
+ Demux Callback API + 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(). +
+ +!Idrivers/media/dvb-core/demux.h + + Remote Controller devices !Iinclude/media/rc-core.h !Iinclude/media/lirc_dev.h - - Media Controller devices + + Media Controller devices !Iinclude/media/media-device.h !Iinclude/media/media-devnode.h !Iinclude/media/media-entity.h - +