diff options
| -rw-r--r-- | dvb-spec/dvbapi/LICENSE | 355 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/Makefile | 8 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/audio.tex | 80 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/ca.tex | 4 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/demux.tex | 101 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/devices.tex | 6 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/dvbapi.tex | 8 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/examples.tex | 26 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/fdl.tex | 367 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/frontend.tex | 689 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/intro.tex | 117 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/kdapi.tex | 9 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/net.tex | 19 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/sec.tex | 282 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/title.tex | 24 | ||||
| -rw-r--r-- | dvb-spec/dvbapi/video.tex | 101 |
16 files changed, 1350 insertions, 846 deletions
diff --git a/dvb-spec/dvbapi/LICENSE b/dvb-spec/dvbapi/LICENSE new file mode 100644 index 000000000..b42936beb --- /dev/null +++ b/dvb-spec/dvbapi/LICENSE @@ -0,0 +1,355 @@ + GNU Free Documentation License + Version 1.1, March 2000 + + Copyright (C) 2000 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +written document "free" in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The "Document", below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as "you". + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than five). +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section entitled "History", and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section as "Endorsements" + or to conflict in title with any Invariant Section. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled "History" +in the various original documents, forming one section entitled +"History"; likewise combine any sections entitled "Acknowledgements", +and any sections entitled "Dedications". You must delete all sections +entitled "Endorsements." + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an "aggregate", and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +If you have no Invariant Sections, write "with no Invariant Sections" +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write "no Front-Cover Texts" instead of +"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. diff --git a/dvb-spec/dvbapi/Makefile b/dvb-spec/dvbapi/Makefile index fe9827cff..83a5e5f7a 100644 --- a/dvb-spec/dvbapi/Makefile +++ b/dvb-spec/dvbapi/Makefile @@ -1,13 +1,13 @@ all: dvbapi.ps dvbapi.pdf -TEXS= dvbapi.tex devices.tex video.tex audio.tex ca.tex sec.tex frontend.tex \ - intro.tex title.tex dvbstb.ps +TEXS= dvbapi.tex devices.tex video.tex audio.tex ca.tex net.tex frontend.tex \ + demux.tex kdapi.tex examples.tex intro.tex title.tex dvbstb.ps dvbapi.pdf: dvbapi.dvi - dvipdf $< $@ + dvipdf $< dvbapi.ps: dvbapi.dvi - dvips -o $@ $< + dvips $< dvbapi.dvi: dvbapi.bbl $(TEXS) -latex dvbapi diff --git a/dvb-spec/dvbapi/audio.tex b/dvb-spec/dvbapi/audio.tex index 540248463..05c23e56f 100644 --- a/dvb-spec/dvbapi/audio.tex +++ b/dvb-spec/dvbapi/audio.tex @@ -1,7 +1,13 @@ \devsec{DVB Audio Device} The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. -It can be accessed through \texttt{/dev/ost/audio}. +It can be accessed through \texttt{/dev/dvb/adapter0/audio0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/video.h} in your application. + +Please note that some DVB cards don't have their own +MPEG decoder, which results in the omission of the audio and video +device. \devsubsec{Audio Data Types} @@ -9,16 +15,16 @@ It can be accessed through \texttt{/dev/ost/audio}. This section describes the structures, data types and defines used when talking to the audio device. -\devsubsubsec{audioStreamSource\_t} +\devsubsubsec{audio\_stream\_source\_t} \label{audiostreamsource} The audio stream source is set through the AUDIO\_SELECT\_SOURCE call and can take the following values, depending on whether we are -replaying from an internal (demuxer) or external (user write) source. +replaying from an internal (demux) or external (user write) source. \begin{verbatim} typedef enum { AUDIO_SOURCE_DEMUX, AUDIO_SOURCE_MEMORY -} audio\_stream_source_t; +} audio_stream_source_t; \end{verbatim} AUDIO\_SOURCE\_DEMUX selects the demultiplexer (fed either by the frontend or the DVR device) as the source of @@ -27,7 +33,7 @@ If AUDIO\_SOURCE\_MEMORY is selected the stream comes from the application through the \texttt{write()} system call. -\devsubsubsec{audioPlayState\_t} +\devsubsubsec{audio\_play\_state\_t} The following values can be returned by the AUDIO\_GET\_STATUS call representing the state of audio playback. \label{audioplaystate} @@ -36,45 +42,45 @@ typedef enum { AUDIO_STOPPED, AUDIO_PLAYING, AUDIO_PAUSED -} audio\_play_state_t; +} audio_play_state_t; \end{verbatim} -\devsubsubsec{audioChannelSelect\_t} +\devsubsubsec{audio\_channel\_select\_t} \label{audiochannelselect} The audio channel selected via AUDIO\_CHANNEL\_SELECT is determined by -the following values. +the following values. \begin{verbatim} typedef enum { AUDIO_STEREO, AUDIO_MONO_LEFT, AUDIO_MONO_RIGHT, -} audio\_channel_select_t; +} audio_channel_select_t; \end{verbatim} -\devsubsubsec{audio\_status\_t} +\devsubsubsec{struct audio\_status} \label{audiostatus} The AUDIO\_GET\_STATUS call returns the following structure informing about various states of the playback operation. \begin{verbatim} -typedef struct audio\_status { +typedef struct audio_status { boolean AV_sync_state; boolean mute_state; - audio\_play_state_t play_state; - audio\_stream_source_t stream_source; - audio\_channel_select_t channel_select; + audio_play_state_t play_state; + audio_stream_source_t stream_source; + audio_channel_select_t channel_select; boolean bypass_mode; -} audio\_status_t; +} audio_status_t; \end{verbatim} -\devsubsubsec{audio\_mixer\_t} +\devsubsubsec{struct audio\_mixer} \label{audiomixer} The following structure is used by the AUDIO\_SET\_MIXER call to set the audio volume. \begin{verbatim} -typedef struct audio\_mixer { +typedef struct audio_mixer { unsigned int volume_left; unsigned int volume_right; -} audio\_mixer_t; +} audio_mixer_t; \end{verbatim} \devsubsubsec{audio encodings} @@ -94,25 +100,31 @@ the following bits set according to the hardwares capabilities. \end{verbatim} -\devsubsubsec{audio karaoke} +\devsubsubsec{struct audio\_karaoke} \label{audiokaraoke} The ioctl AUDIO\_SET\_KARAOKE uses the following format: \begin{verbatim} typedef -struct audio\_karaoke{ /* if Vocal1 or Vocal2 are non-zero, they get mixed */ - int vocal1; /* into left and right t at 70% each */ - int vocal2; /* if both, Vocal1 and Vocal2 are non-zero, Vocal1 gets */ - int melody; /* mixed into the left channel and */ - /* Vocal2 into the right channel at 100% each. */ - /* if Melody is non-zero, the melody channel gets mixed */ /* into left and right */ -} audio\_karaoke_t; +struct audio_karaoke{ + int vocal1; + int vocal2; + int melody; +} audio_karaoke_t; \end{verbatim} +If Vocal1 or Vocal2 are non-zero, they get mixed +into left and right t at 70\% each. +If both, Vocal1 and Vocal2 are non-zero, Vocal1 gets +mixed into the left channel and +Vocal2 into the right channel at 100\% each. +Ff Melody is non-zero, the melody channel gets mixed +into left and right. + \devsubsubsec{audio attributes} \label{aattrib} The following attributes can be set by a call to AUDIO\_SET\_ATTRIBUTES: \begin{verbatim} -typedef uint16_t audio\_attributes_t; +typedef uint16_t audio_attributes_t; /* bits: descr. */ /* 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */ /* 12 multichannel extension */ @@ -130,7 +142,7 @@ typedef uint16_t audio\_attributes_t; \function{open()}{ int open(const char *deviceName, int flags);}{ - This system call opens a named audio device (e.g. /dev/ost/audio) for subsequent + This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0) for subsequent use. When an open() call has succeeded, the device will be ready for use. The significance of blocking or non-blocking mode is described in the documentation for functions where there is a difference. It does not affect @@ -225,7 +237,7 @@ typedef uint16_t audio\_attributes_t; \ifunction{AUDIO\_SELECT\_SOURCE}{ int ioctl(int fd, int request = AUDIO\_SELECT\_SOURCE, - audioStreamSource\_t source);}{ + audio\_stream\_source\_t source);}{ This ioctl call informs the audio device which source shall be used for the input data. The possible sources are demux or memory. If AUDIO\_SOURCE\_MEMORY @@ -233,7 +245,7 @@ typedef uint16_t audio\_attributes_t; }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_SELECT\_SOURCE for this command.\\ - audioStreamSource\_t source& Indicates the source that shall be used for the + audio\_stream\_source\_t source& Indicates the source that shall be used for the Audio stream. }{ EBADF& fd is not a valid open file descriptor.\\ @@ -295,13 +307,13 @@ typedef uint16_t audio\_attributes_t; \ifunction{AUDIO\_CHANNEL\_SELECT}{ int ioctl(int fd, int request = AUDIO\_CHANNEL\_SELECT, - audioChannelSelect\_t);}{ + audio\_channel\_select\_t);}{ This ioctl call asks the Audio Device to select the requested channel if possible. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_CHANNEL\_SELECT for this command.\\ - audioChannelSelect\_t ch & + audio\_channel\_select\_t ch & Select the output format of the audio (mono left/right, stereo). }{ EBADF& fd is not a valid open file descriptor.\\ @@ -412,13 +424,13 @@ typedef uint16_t audio\_attributes_t; } \ifunction{AUDIO\_SET\_ATTRIBUTES}{ - int ioctl(fd, int request = AUDIO\_SET\_ATTRIBUTES, audioAttributes\_t attr );}{ + int ioctl(fd, int request = AUDIO\_SET\_ATTRIBUTES, audio\_attributes\_t attr );}{ This ioctl is intended for DVD playback and allows you to set certain information about the audio stream. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_SET\_ATTRIBUTES for this command.\\ - iaudioAttributes\_t attr & audio attributes according to section \ref{aattrib}\\ + audio\_attributes\_t attr & audio attributes according to section \ref{aattrib}\\ }{ EBADF& fd is not a valid open file descriptor \\ EINVAL& attr is not a valid or supported attribute setting.\\ diff --git a/dvb-spec/dvbapi/ca.tex b/dvb-spec/dvbapi/ca.tex index eba512b1b..fe76da454 100644 --- a/dvb-spec/dvbapi/ca.tex +++ b/dvb-spec/dvbapi/ca.tex @@ -1,7 +1,9 @@ \devsec{DVB CA Device} The DVB CA device controls the conditional access hardware. -It can be accessed through \texttt{/dev/ost/ca}. +It can be accessed through \texttt{/dev/dvb/adapter0/ca0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/ca.h} in your application. \devsubsec{CA Data Types} diff --git a/dvb-spec/dvbapi/demux.tex b/dvb-spec/dvbapi/demux.tex index c74b133ec..dd032f58d 100644 --- a/dvb-spec/dvbapi/demux.tex +++ b/dvb-spec/dvbapi/demux.tex @@ -1,16 +1,14 @@ \devsec{DVB Demux Device} The DVB demux device controls the filters of the DVB hardware/software. -It can be accessed through \texttt{/dev/ost/demux}. +It can be accessed through \texttt{/dev/adapter0/demux0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/dmx.h} in your application. \devsubsec{Demux Data Types} -\begin{verbatim} -typedef uint16_t uint16_t; -\end{verbatim} - -\devsubsubsec{dmxOutput\_t} +\devsubsubsec{dmx\_output\_t} \label{dmxoutput} \begin{verbatim} @@ -19,26 +17,30 @@ typedef enum DMX_OUT_DECODER, DMX_OUT_TAP, DMX_OUT_TS_TAP -} dmx\_output_t; +} dmx_output_t; \end{verbatim} -/* Output multiplexed into a new TS */ -/* (to be retrieved by reading from the */ -/* logical DVR device). */ + +\noindent\texttt{DMX\_OUT\_TAP} delivers the stream output to the demux device +on which the ioctl is called. + +\noindent\texttt{DMX\_OUT\_TS\_TAP} routes output to the logical DVR device +\texttt{/dev/dvb/adapter0/dvr0}, which delivers a TS multiplexed from +all filters for which \texttt{DMX\_OUT\_TS\_TAP} was specified. -\devsubsubsec{dmxInput\_t} +\devsubsubsec{dmx\_input\_t} \label{dmxinput} \begin{verbatim} typedef enum { - DMX_IN_FRONTEND, /* Input from a front-end device. */ - DMX_IN_DVR /* Input from the logical DVR device. */ -} dmx\_input_t; + DMX_IN_FRONTEND, + DMX_IN_DVR +} dmx_input_t; \end{verbatim} -\devsubsubsec{dmxPesType\_t} +\devsubsubsec{dmx\_pes\_type\_t} \label{dmxpestype} \begin{verbatim} @@ -50,7 +52,7 @@ typedef enum DMX_PES_SUBTITLE, DMX_PES_PCR, DMX_PES_OTHER -} dmx\_pes\_type_t; +} dmx_pes_type_t; \end{verbatim} @@ -62,11 +64,11 @@ typedef enum { DMX_SCRAMBLING_EV, DMX_FRONTEND_EV -} dmx\_event_t; +} dmx_event_t; \end{verbatim} -\devsubsubsec{dmxScramblingStatus\_t} +\devsubsubsec{dmx\_scrambling\_status\_t} \label{dmxscramblingstatus} \begin{verbatim} @@ -74,32 +76,32 @@ typedef enum { DMX_SCRAMBLING_OFF, DMX_SCRAMBLING_ON -} dmx\_scrambling_status_t; +} dmx_scrambling_status_t; \end{verbatim} -\devsubsubsec{dmx\_filter\_t} +\devsubsubsec{struct dmx\_filter} \label{dmxfilter} \begin{verbatim} -typedef struct dmx\_filter +typedef struct dmx_filter { uint8_t filter[DMX_FILTER_SIZE]; uint8_t mask[DMX_FILTER_SIZE]; -} dmx\_filter\_t; +} dmx_filter_t; \end{verbatim} -\devsubsubsec{dmx\_sct\_filter\_params} +\devsubsubsec{struct dmx\_sct\_filter\_params} \label{dmxsctfilterparams} \begin{verbatim} -struct dmx\_sct\_filter\_params +struct dmx_sct_filter_params { - uint16_t pid; - dmx\_filter\_t filter; - uint32_t timeout; - uint32_t flags; + uint16_t pid; + dmx_filter_t filter; + uint32_t timeout; + uint32_t flags; #define DMX_CHECK_CRC 1 #define DMX_ONESHOT 2 #define DMX_IMMEDIATE_START 4 @@ -107,32 +109,32 @@ struct dmx\_sct\_filter\_params \end{verbatim} -\devsubsubsec{dmx\_pes\_filter\_params} +\devsubsubsec{struct dmx\_pes\_filter\_params} \label{dmxpesfilterparams} \begin{verbatim} -struct dmx\_pes\_filter\_params +struct dmx_pes_filter_params { - uint16_t pid; - dmx\_input_t input; - dmx\_output_t output; - dmx\_pes\_type_t pes\_type; - uint32_t flags; + uint16_t pid; + dmx_input_t input; + dmx_output_t output; + dmx_pes_type_t pes_type; + uint32_t flags; }; \end{verbatim} -\devsubsubsec{dmx\_event} +\devsubsubsec{struct dmx\_event} \label{dmxevent} \begin{verbatim} -struct dmx\_event +struct dmx_event { - dmx\_event_t event; - time_t timeStamp; + dmx_event_t event; + time_t timeStamp; union { - dmx\_scrambling_status_t scrambling; + dmx_scrambling_status_t scrambling; } u; }; \end{verbatim} @@ -142,16 +144,15 @@ struct dmx\_event \devsubsec{Demux Function Calls} \function{open()}{ int open(const char *deviceName, int flags);}{ - This system call, used with a device name of /dev/ost/demuxn, where n - denotes the specific demux device to be opened, allocates a new filter + This system call, used with a device name of /dev/dvb/adapter0/demux0, + allocates a new filter and returns a handle which can be used for subsequent control of that filter. This call has to be made for each filter to be used, i.e. every returned file descriptor is a reference to a single filter. - /dev/ost/dvrn is a logical device to be used for retrieving Transport - Streams for digital video recording. n identifies the physical demux - device that provides the actual DVR functionality. When reading from + /dev/dvb/adapter0/dvr0 is a logical device to be used for retrieving Transport + Streams for digital video recording. When reading from this device a transport stream containing the packets from all PES - filters set in the corresponding demux device (/dev/ost/demuxn) + filters set in the corresponding demux device (/dev/dvb/adapter0/demux0) having the output set to DMX\_OUT\_TS\_TAP. A recorded Transport Stream is replayed by writing to this device. % This device can only be opened in read-write mode. @@ -211,7 +212,7 @@ struct dmx\_event ioctl function or by setting the DMX\_IMMEDIATE\_START flag. If the reading is done from a logical DVR demux device, the data will constitute a Transport Stream including the packets from all PES filters - in the corresponding demux device /dev/ost/demuxn having the output set + in the corresponding demux device /dev/dvb/adapter0/demux0 having the output set to DMX\_OUT\_TS\_TAP. }{ int fd & File descriptor returned by a previous call to open().\\ @@ -236,11 +237,11 @@ struct dmx\_event \function{write()}{ ssize\_t write(int fd, const void *buf, size\_t count); }{ - This system call is only provided by the logical device /dev/ost/dvrn, - where n identifies the physical demux device that provides the actual + This system call is only provided by the logical device /dev/dvb/adapter0/dvr0, + associated with the physical demux device that provides the actual DVR functionality. It is used for replay of a digitally recorded Transport Stream. Matching filters have to be defined in the - corresponding physical demux device, /dev/ost/demuxn. + corresponding physical demux device, /dev/dvb/adapter0/demux0. The amount of data to be transferred is implied by count. }{ int fd & File descriptor returned by a previous call to open().\\ diff --git a/dvb-spec/dvbapi/devices.tex b/dvb-spec/dvbapi/devices.tex index 9c561e853..11eccd897 100644 --- a/dvb-spec/dvbapi/devices.tex +++ b/dvb-spec/dvbapi/devices.tex @@ -1,9 +1,9 @@ -\input{video.tex} -\input{audio.tex} \input{frontend.tex} -\input{sec.tex} \input{demux.tex} +\input{video.tex} +\input{audio.tex} \input{ca.tex} +\input{net.tex} \input{kdapi.tex} %%% Local Variables: diff --git a/dvb-spec/dvbapi/dvbapi.tex b/dvb-spec/dvbapi/dvbapi.tex index ad0251c01..d75c2417f 100644 --- a/dvb-spec/dvbapi/dvbapi.tex +++ b/dvb-spec/dvbapi/dvbapi.tex @@ -1,4 +1,4 @@ -\documentclass[10pt]{book} +\documentclass[a4paper,10pt]{book} \usepackage[dvips,colorlinks=true]{hyperref} \usepackage{times} @@ -131,7 +131,7 @@ \renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}{}} \lhead[\fancyplain{}{\bfseries \thepage}]{\bfseries \rightmark} \rhead[\fancyplain{}{\bfseries \leftmark}]{\bfseries \thepage} -\cfoot{\copyright 2002 convergence GmbH} +%\cfoot{\copyright\ 2002, 2003 Convergence GmbH} \input{intro.tex} @@ -145,6 +145,10 @@ \cleardoublepage +\input{fdl.tex} + +\cleardoublepage + \thispagestyle{plain}\chaptermark{Bibliography} \addcontentsline{toc}{chapter}{Bibliography} \bibliographystyle{bibsec} diff --git a/dvb-spec/dvbapi/examples.tex b/dvb-spec/dvbapi/examples.tex index 126268c5d..c9a19ba29 100644 --- a/dvb-spec/dvbapi/examples.tex +++ b/dvb-spec/dvbapi/examples.tex @@ -1,6 +1,10 @@ \chapter{Examples} In this section we would like to present some examples for using the DVB API. +Maintainer note: This section is out of date. Please refer to the sample +programs packaged with the driver distribution from +\texttt{http://linuxtv.org/}. + \section{Tuning} We will start with a generic tuning subroutine that uses the frontend and SEC, as well as the demux devices. The example is given for QPSK @@ -17,14 +21,14 @@ tuners, but can easily be adjusted for QAM. #include <time.h> #include <unistd.h> -#include <ost/dmx.h> -#include <ost/frontend.h> -#include <ost/sec.h> +#include <linux/dvb/dmx.h> +#include <linux/dvb/frontend.h> +#include <linux/dvb/sec.h> #include <sys/poll.h> -#define DMX "/dev/ost/demux" -#define FRONT "/dev/ost/frontend" -#define SEC "/dev/ost/sec" +#define DMX "/dev/dvb/adapter0/demux1" +#define FRONT "/dev/dvb/adapter0/frontend1" +#define SEC "/dev/dvb/adapter0/sec1" /* routine for checking if we have a signal and other status information*/ int FEReadStatus(int fd, fe_status_t *stat) @@ -234,12 +238,12 @@ recording. #include <time.h> #include <unistd.h> -#include <ost/dmx.h> -#include <ost/video.h> +#include <linux/dvb/dmx.h> +#include <linux/dvb/video.h> #include <sys/poll.h> -#define DVR "/dev/ost/dvr" -#define AUDIO "/dev/ost/audio" -#define VIDEO "/dev/ost/video" +#define DVR "/dev/dvb/adapter0/dvr1" +#define AUDIO "/dev/dvb/adapter0/audio1" +#define VIDEO "/dev/dvb/adapter0/video1" #define BUFFY (188*20) #define MAX_LENGTH (1024*1024*5) /* record 5MB */ diff --git a/dvb-spec/dvbapi/fdl.tex b/dvb-spec/dvbapi/fdl.tex new file mode 100644 index 000000000..c0fcbe3f3 --- /dev/null +++ b/dvb-spec/dvbapi/fdl.tex @@ -0,0 +1,367 @@ +% fdl.tex +% This file is a chapter. It must be included in a larger document to work +% properly. + +\chapter{GNU Free Documentation License} + +Version 1.1, March 2000\\ + + Copyright \copyright\ 2000 Free Software Foundation, Inc.\\ + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA\\ + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +\section*{Preamble} + +The purpose of this License is to make a manual, textbook, or other +written document ``free'' in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +\section{Applicability and Definitions} + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The ``Document'', below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as ``you''. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, \LaTeX~input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + +\section{Verbatim Copying} + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +\section{Copying in Quantity} + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +\section{Modifications} + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +\begin{itemize} + +\item Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +\item List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than five). +\item State on the Title page the name of the publisher of the + Modified Version, as the publisher. +\item Preserve all the copyright notices of the Document. +\item Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +\item Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +\item Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +\item Include an unaltered copy of this License. +\item Preserve the section entitled ``History'', and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled ``History'' in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +\item Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the ``History'' section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +\item In any section entitled ``Acknowledgements'' or ``Dedications'', + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +\item Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +\item Delete any section entitled ``Endorsements''. Such a section + may not be included in the Modified Version. +\item Do not retitle any existing section as ``Endorsements'' + or to conflict in title with any Invariant Section. + +\end{itemize} + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties -- for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +\section{Combining Documents} + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled ``History'' +in the various original documents, forming one section entitled +``History''; likewise combine any sections entitled ``Acknowledgements'', +and any sections entitled ``Dedications''. You must delete all sections +entitled ``Endorsements.'' + + +\section{Collections of Documents} + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + + +\section{Aggregation With Independent Works} + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an ``aggregate'', and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + + +\section{Translation} + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + + +\section{Termination} + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +\section{Future Revisions of This License} + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + +\section*{ADDENDUM: How to use this License for your documents} + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +\begin{quote} + + Copyright \copyright\ YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + +\end{quote} + +If you have no Invariant Sections, write ``with no Invariant Sections'' +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write ``no Front-Cover Texts'' instead of +``Front-Cover Texts being LIST''; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex index e41ef3d54..bb177df1b 100644 --- a/dvb-spec/dvbapi/frontend.tex +++ b/dvb-spec/dvbapi/frontend.tex @@ -1,52 +1,176 @@ \devsec{DVB Frontend API} The DVB frontend device controls the tuner and DVB demodulator hardware. -It can be accessed through \texttt{/dev/ost/frontend}. -If you are using \texttt{devfs} you can use \texttt{/dev/dvb/card0/frontend}. -The frontend device will only be made visible through \texttt{devfs} -if the corresponding card actually has a frontend. Cards which support -the DVB API but, e.g., only can play back recordings, will not offer the -frontend device. +It can be accessed through \texttt{/dev/dvb/adapter0/frontend0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/frontend.h} in your application. + +DVB frontends come in three varieties: DVB-S (satellite), DVB-C (cable) +and DVB-T (terrestrial). Transmission via the internet (DVB-IP) is +not handled by this API. +For DVB-S the frontend device also supports satellite equipment control +(SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) specification +is available from Eutelsat \texttt{http://www.eutelsat.org/}. + +Note that the DVB API may also be used for MPEG decoder-only PCI cards, +in which case there exists no frontend device. \devsubsec{Frontend Data Types} -\devsubsubsec{frontend status} -\label{frontendstatus} +\devsubsubsec{frontend type} +\label{frontendtype} + +For historic reasons frontend types are named after the +type of modulation used in transmission. -Several functions of the frontend device use the feStatus data -type defined by \begin{verbatim} -typedef uint32_t feStatus; +typedef enum fe_type { + FE_QPSK, /* DVB-S */ + FE_QAM, /* DVB-C */ + FE_OFDM /* DVB-T */ +} fe_type_t; \end{verbatim} -to indicate the current state and/or state changes of -the frontend hardware. -\noindent -It can take on the values +\devsubsubsec{frontend capabilities} +\label{frontendcaps} + +Capabilities describe what a frontend can do. Some capabilities +can only be supported for a specific frontend type. + +\begin{verbatim} +typedef enum fe_caps { + FE_IS_STUPID = 0, + FE_CAN_INVERSION_AUTO = 0x1, + FE_CAN_FEC_1_2 = 0x2, + FE_CAN_FEC_2_3 = 0x4, + FE_CAN_FEC_3_4 = 0x8, + FE_CAN_FEC_4_5 = 0x10, + FE_CAN_FEC_5_6 = 0x20, + FE_CAN_FEC_6_7 = 0x40, + FE_CAN_FEC_7_8 = 0x80, + FE_CAN_FEC_8_9 = 0x100, + FE_CAN_FEC_AUTO = 0x200, + FE_CAN_QPSK = 0x400, + FE_CAN_QAM_16 = 0x800, + FE_CAN_QAM_32 = 0x1000, + FE_CAN_QAM_64 = 0x2000, + FE_CAN_QAM_128 = 0x4000, + FE_CAN_QAM_256 = 0x8000, + FE_CAN_QAM_AUTO = 0x10000, + FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000, + FE_CAN_BANDWIDTH_AUTO = 0x40000, + FE_CAN_GUARD_INTERVAL_AUTO = 0x80000, + FE_CAN_HIERARCHY_AUTO = 0x100000, + FE_CAN_MUTE_TS = 0x80000000, + FE_CAN_CLEAN_SETUP = 0x40000000 +} fe_caps_t; +\end{verbatim} + +\devsubsubsec{frontend information} +\label{frontendinfo} + +Information about the frontend ca be queried with +FE\_GET\_INFO (\ref{fegetinfo}). + +\begin{verbatim} +struct dvb_frontend_info { + char name[128]; + fe_type_t type; + uint32_t frequency_min; + uint32_t frequency_max; + uint32_t frequency_stepsize; + uint32_t frequency_tolerance; + uint32_t symbol_rate_min; + uint32_t symbol_rate_max; + uint32_t symbol_rate_tolerance; /* ppm */ + uint32_t notifier_delay; /* ms */ + fe_caps_t caps; +}; +\end{verbatim} + +\devsubsubsec{diseqc master command} +\label{diseqcmastercmd} + +A message sent from the frontend to DiSEqC capable equipment. + +\begin{verbatim} +struct dvb_diseqc_master_cmd { + uint8_t msg [6]; /* { framing, address, command, data[3] } */ + uint8_t msg_len; /* valid values are 3...6 */ +}; +\end{verbatim} + +\devsubsubsec{diseqc slave reply} +\label{diseqcslavereply} + +A reply to the frontend from DiSEqC 2.0 capable equipment. + +\begin{verbatim} +struct dvb_diseqc_slave_reply { + uint8_t msg [4]; /* { framing, data [3] } */ + uint8_t msg_len; /* valid values are 0...4, 0 means no msg */ + int timeout; /* return from ioctl after timeout ms with */ +}; /* errorcode when no message was received */ +\end{verbatim} + +\devsubsubsec{SEC voltage} +\label{secvoltage} + +The voltage is usually used with non-DiSEqC capable LNBs to +switch the polarzation (horizontal/vertical). + +\begin{verbatim} +typedef enum fe_sec_voltage { + SEC_VOLTAGE_13, + SEC_VOLTAGE_18 +} fe_sec_voltage_t; +\end{verbatim} + +\devsubsubsec{SEC continuous tone} +\label{sectone} + +The continous 22KHz tone is usually used with non-DiSEqC capable LNBs to +switch the high/low band of a dual-band LNB. + +\begin{verbatim} +typedef enum fe_sec_tone_mode { + SEC_TONE_ON, + SEC_TONE_OFF +} fe_sec_tone_mode_t; +\end{verbatim} + +\devsubsubsec{SEC tone burst} +\label{sectoneburst} + +The 22KHz tone burst is usually used with non-DiSEqC capable +switches to select between two connected LNBs/satellites. + \begin{verbatim} -#define FE_HAS_POWER 1 -#define FE_HAS_SIGNAL 2 -#define FE_SPECTRUM_INV 4 -#define FE_HAS_LOCK 8 -#define FE_HAS_CARRIER 16 -#define FE_HAS_VITERBI 32 -#define FE_HAS_SYNC 64 -#define TUNER_HAS_LOCK 128 +typedef enum fe_sec_mini_cmd { + SEC_MINI_A, + SEC_MINI_B +} fe_sec_mini_cmd_t; \end{verbatim} -which can be ORed together and have the following meaning: -\medskip -\begin{tabular}{lp{11cm}} -FE\_HAS\_POWER & the frontend is powered up and is ready to be used\\ -FE\_HAS\_SIGNAL & the frontend detects a signal above the normal noise level\\ -FE\_SPECTRUM\_INV & spectrum inversion is enabled/was necessary for lock\\ -FE\_HAS\_LOCK & frontend successfully locked to a DVB signal \\ -FE\_HAS\_CARRIER & carrier detected in signal\\ -FE\_HAS\_VITERBI & lock at viterbi decoder stage\\ -FE\_HAS\_SYNC & TS sync bytes detected \\ -TUNER\_HAS\_LOCK & the tuner has a frequency lock -\end{tabular} +\devsubsubsec{frontend status} +\label{frontendstatus} + +Several functions of the frontend device use the fe\_status data +type defined by +\begin{verbatim} +typedef enum fe_status { + FE_HAS_SIGNAL = 0x01, /* found something above the noise level */ + FE_HAS_CARRIER = 0x02, /* found a DVB signal */ + FE_HAS_VITERBI = 0x04, /* FEC is stable */ + FE_HAS_SYNC = 0x08, /* found sync bytes */ + FE_HAS_LOCK = 0x10, /* everything's working... */ + FE_TIMEDOUT = 0x20, /* no lock within the last ~2 seconds */ + FE_REINIT = 0x40 /* frontend was reinitialized, */ +} fe_status_t; /* application is recommned to reset */ +\end{verbatim} +to indicate the current state and/or state changes of +the frontend hardware. \devsubsubsec{frontend parameters} @@ -57,45 +181,44 @@ depend on the kind of hardware you are using. All kinds of parameters are combined as a union in the FrontendParameters structure: \begin{verbatim} -typedef struct { - __u32 Frequency; /* (absolute) frequency in Hz for QAM/OFDM */ - /* intermediate frequency in kHz for QPSK */ - fe_spectral_inversion_t Inversion; /* spectral inversion */ +struct dvb_frontend_parameters { + uint32_t frequency; /* (absolute) frequency in Hz for QAM/OFDM */ + /* intermediate frequency in kHz for QPSK */ + fe_spectral_inversion_t inversion; union { - QPSKParameters qpsk; - QAMParameters qam; - OFDMParameters ofdm; + struct dvb_qpsk_parameters qpsk; + struct dvb_qam_parameters qam; + struct dvb_ofdm_parameters ofdm; } u; -} FrontendParameters; +}; \end{verbatim} For satellite QPSK frontends you have to use QPSKParameters defined by \begin{verbatim} -typedef struct { - __u32 SymbolRate; /* symbol rate in Symbols per second */ - fe_code_rate_t FEC_inner; /* forward error correction (see above) */ -} QPSKParameters; +struct dvb_qpsk_parameters { + uint32_t symbol_rate; /* symbol rate in Symbols per second */ + fe_code_rate_t fec_inner; /* forward error correction (see above) */ +}; \end{verbatim} for cable QAM frontend you use the QAMParameters structure \begin{verbatim} -typedef struct { - __u32 SymbolRate; /* symbol rate in Symbols per second */ - fe_code_rate_t FEC_outer; /* forward error correction (see above) */ - fe_code_rate_t FEC_inner; /* forward error correction (see above) */ - fe_modulation_t QAM; /* modulation type (see above) */ -} QAMParameters; +struct dvb_qam_parameters { + uint32_t symbol_rate; /* symbol rate in Symbols per second */ + fe_code_rate_t fec_inner; /* forward error correction (see above) */ + fe_modulation_t modulation; /* modulation type (see above) */ +}; \end{verbatim} DVB-T frontends are supported by the OFDMParamters structure \begin{verbatim} -typedef struct { - fe_bandwidth_t bandWidth; - fe_code_rate_t HP_fe_code_rate_t; /* high priority stream code rate */ - fe_code_rate_t LP_fe_code_rate_t; /* low priority stream code rate */ - fe_modulation_t Constellation; /* modulation type (see above) */ - fe_transmit_mode_t TransmissionMode; - fe_guard_interval_t guardInterval; - fe_hierarchy_t fe_hierarchy_tInformation; -} OFDMParameters; +struct dvb_ofdm_parameters { + fe_bandwidth_t bandwidth; + fe_code_rate_t code_rate_HP; /* high priority stream code rate */ + fe_code_rate_t code_rate_LP; /* low priority stream code rate */ + fe_modulation_t constellation; /* modulation type (see above) */ + fe_transmit_mode_t transmission_mode; + fe_guard_interval_t guard_interval; + fe_hierarchy_t hierarchy_information; +}; \end{verbatim} In the case of QPSK frontends the Frequency field specifies the intermediate @@ -107,7 +230,7 @@ and is given in Hz. The Inversion field can take one of these values: \begin{verbatim} -typedef enum { +typedef enum fe_spectral_inversion { INVERSION_OFF, INVERSION_ON, INVERSION_AUTO @@ -120,15 +243,18 @@ try to figure out the correct setting by itself. \noindent The possible values for the FEC\_inner field are \begin{verbatim} -enum { - FEC_AUTO, +typedef enum fe_code_rate { + FEC_NONE = 0, FEC_1_2, FEC_2_3, FEC_3_4, + FEC_4_5, FEC_5_6, + FEC_6_7, FEC_7_8, - FEC_NONE -}; + FEC_8_9, + FEC_AUTO +} fe_code_rate_t; \end{verbatim} which correspond to error correction rates of $1\over 2$, $2\over 3$, etc., no error correction or auto detection. @@ -137,47 +263,52 @@ no error correction or auto detection. For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature modulation mode which can be one of the following: \begin{verbatim} -typedef enum -{ QPSK, +typedef enum fe_modulation { + QPSK, QAM_16, QAM_32, QAM_64, QAM_128, - QAM_256 -} QAM_TYPE; + QAM_256, + QAM_AUTO +} fe_modulation_t; \end{verbatim} Finally, there are several more parameters for OFDM: \begin{verbatim} -typedef enum { +typedef enum fe_transmit_mode { TRANSMISSION_MODE_2K, - TRANSMISSION_MODE_8K + TRANSMISSION_MODE_8K, + TRANSMISSION_MODE_AUTO } fe_transmit_mode_t; \end{verbatim} \begin{verbatim} -typedef enum { +typedef enum fe_bandwidth { BANDWIDTH_8_MHZ, BANDWIDTH_7_MHZ, - BANDWIDTH_6_MHZ + BANDWIDTH_6_MHZ, + BANDWIDTH_AUTO } fe_bandwidth_t; \end{verbatim} \begin{verbatim} -typedef enum { +typedef enum fe_guard_interval { GUARD_INTERVAL_1_32, GUARD_INTERVAL_1_16, GUARD_INTERVAL_1_8, - GUARD_INTERVAL_1_4 + GUARD_INTERVAL_1_4, + GUARD_INTERVAL_AUTO } fe_guard_interval_t; \end{verbatim} \begin{verbatim} -typedef enum { +typedef enum fe_hierarchy { HIERARCHY_NONE, HIERARCHY_1, HIERARCHY_2, - HIERARCHY_4 + HIERARCHY_4, + HIERARCHY_AUTO } fe_hierarchy_t; \end{verbatim} @@ -186,78 +317,12 @@ typedef enum { \label{frontendevents} \begin{verbatim} -enum { - FE_UNEXPECTED_EV, - FE_COMPLETION_EV, - FE_FAILURE_EV +struct dvb_frontend_event { + fe_status_t status; + struct dvb_frontend_parameters parameters; }; \end{verbatim} -\begin{verbatim} -typedef struct { - EventType type; /* type of event, FE_UNEXPECTED_EV, ... */ - long timestamp; /* time in seconds since 1970-01-01 */ - - union { - struct { - fe_status_t previousStatus; /* status before event */ - fe_status_t currentStatus; /* status during event */ - } unexpectedEvent; - FrontendParameters completionEvent; /* parameters for which the - tuning succeeded */ - fe_status_t failureEvent; /* status at failure (e.g. no lock) */ - } u; -} FrontendEvent; -\end{verbatim} - -\begin{verbatim} -struct qpskRegister { - uint8_t chipId; - uint8_t address; - uint8_t value; -}; -\end{verbatim} - -\begin{verbatim} -struct qamRegister { - uint8_t chipId; - uint8_t address; - uint8_t value; -}; -\end{verbatim} - -\begin{verbatim} -struct qpskFrontendInfo { - uint32_t minFrequency; - uint32_t maxFrequency; - uint32_t maxSymbolRate; - uint32_t minSymbolRate; - uint32_t hwType; - uint32_t hwVersion; -}; -\end{verbatim} - -\begin{verbatim} -struct qamFrontendInfo { - uint32_t minFrequency; - uint32_t maxFrequency; - uint32_t maxSymbolRate; - uint32_t minSymbolRate; - uint32_t hwType; - uint32_t hwVersion; -}; -\end{verbatim} - -\begin{verbatim} -typedef enum { - FE_POWER_ON, - FE_POWER_STANDBY, - FE_POWER_SUSPEND, - FE_POWER_OFF -} powerState_t; -\end{verbatim} - - \clearpage @@ -265,9 +330,9 @@ typedef enum { \function{open()}{ int open(const char *deviceName, int flags);}{ - This system call opens a named frontend device (e.g. /dev/ost/qpskfe - for a satellite frontend or /dev/ost/qamfe for a cable frontend) - for subsequent use. + This system call opens a named frontend device (/dev/dvb/adapter0/frontend0) + for subsequent use. Usually the first thing to do after a successful open + is to find out the frontend type with FE\_GET\_INFO. The device can be opened in read-only mode, which only allows monitoring of device status and statistics, or read/write mode, which allows @@ -303,119 +368,21 @@ typedef enum { int close(int fd);}{ This system call closes a previously opened front-end device. After closing a front-end device, its corresponding hardware might be - powered down automatically, but only when this is needed to open - another front-end device. - To affect an unconditional power down, it should be done explicitly using - the OST\_SET\_POWER\_STATE ioctl. + powered down automatically. }{ int fd & File descriptor returned by a previous call to open().\\ }{ EBADF & fd is not a valid open file descriptor.\\ } -\ifunction{OST\_SELFTEST}{ - int ioctl(int fd, int request = OST\_SELFTEST);}{ - This ioctl call initiates an automatic self-test of the front-end hardware. - This call requires read/write access to the device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals OST\_SELFTEST for this command.\\ - }{ - -1& Self test failure.\\ -} - -\ifunction{OST\_SET\_POWER\_STATE}{ - int ioctl(int fd, int request = OST\_SET\_POWER\_STATE, uint32\_t state);}{ - This ioctl call, implemented in many OST device drivers, enables direct - control over the power state of the hardware device, which may be on, off, - standby, or suspend. The latter two are low-power modes, which disable all - functionality of the device until turned on again. In contrast to the off - state, however, the standby and suspend states resume operation in the same - state as when the device was active. The only difference between the standby - and suspend states is a different tradeoff between resume time and power - consumption. Power consumption may be lower in the suspend state at the - cost of a longer resume time.\\ - A device that implements this call does not necessarily support two low-power - modes. If it only supports one low-power state, or none at all, the - OST\_SET\_POWER\_STATE operation for the missing states will - still succeed, but - it will be mapped to an existing state as per this table: \\ - \begin{center} - \begin{tabular}[h]{cll} - number of low-power & requested state & resulting state\\ - states supported &&\\ - \\ - 1 & standby & suspend \\ - 1 & suspend & suspend \\ - 0 & standby & on \\ - 0 & suspend & on - \end{tabular} - \end{center}\\ - For other cases where a required state is missing, an error code will be - returned. This can happen if a device does not support the power-off state, - but nevertheless implements this ioctl operation for control of low-power - states. - When opening a device in read/write mode, the driver ensures that the - corresponding hardware device is turned on initially. If the device is - later turned off or put in suspend mode, it has to be explicitly turned on - again.\\ - This call requires read/write access to the device. (Note that the power - management driver can affect the power state of devices without using this - ioctl operation, so having exclusive read/write access to a device does not - imply total control over the power state.) - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals OST\_SET\_POWER\_STATE for this command.\\ - uint32\_t state & Requested power state. One of: \\ - & - \begin{tabular}[h]{ll} - OST\_POWER\_ON& turn power on\\ - OST\_POWER\_STANDBY& set device in standby mode\\ - OST\_POWER\_SUSPEND& set device in suspend mode\\ - OST\_POWER\_OFF& turn power off\\ - \end{tabular} - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINVAL& Illegal state, or not available on this device.\\ - EPERM & Permission denied (needs read/write access).\\ - ENOSYS& Function not available for this device. -} - -\ifunction{FE\_GET\_POWER\_STATE}{ - int ioctl(int fd, int request = OST\_GET\_POWER\_STATE, uint32\_t *state);}{ - This ioctl call, implemented in many OST device drivers, obtains the power - state of the hardware device, which may be on, off, standby, or suspend. - A device that implements this call does not necessarily support all four states. - If there is only one low-power state, the suspend state will be returned for - that state. If there is no low-power state, the on state will be reported - standby and suspend states will be equivalent to the on state. - For this command, read-only access to the device is sufficient. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals OST\_GET\_POWER\_STATE for this command.\\ - uint32\_t *state & Requested power state. One of: \\ - & - \begin{tabular}[h]{ll} - OST\_POWER\_ON& power is on\\ - OST\_POWER\_STANDBY& device in standby mode\\ - OST\_POWER\_SUSPEND& device in suspend mode\\ - OST\_POWER\_OFF& power is off\\ - \end{tabular} - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINVAL& Illegal state, or not available on this device.\\ - EFAULT& state points to invalid address.\\ - ENOSYS& Function not available for this device. -} - \ifunction{FE\_READ\_STATUS}{ - int ioctl(int fd, int request = FE\_READ\_STATUS, feStatus *status);}{ + int ioctl(int fd, int request = FE\_READ\_STATUS, fe\_status\_t *status);}{ This ioctl call returns status information about the front-end. This call only requires read-only access to the device. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_READ\_STATUS for this command.\\ - struct feStatus *status&Points to the location where the front-end + struct fe\_status\_t *status & Points to the location where the front-end status word is to be stored. }{ EBADF& fd is not a valid open file descriptor.\\ @@ -430,10 +397,7 @@ typedef enum { }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_READ\_BER for this command.\\ - uint32\_t *ber & The bit error rate, as a multiple of $10^{-9}$, - is stored into *ber.\\ - & Example: a value of 2500 corresponds to a bit error - rate of $2.5\cdot 10^{-6}$, or 1 error in 400000 bits. + uint32\_t *ber & The bit error rate is stored into *ber.\\ }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& ber points to invalid address.\\ @@ -443,17 +407,14 @@ typedef enum { } \ifunction{FE\_READ\_SNR}{ - int ioctl(int fd, int request = FE\_READ\_SNR, int32\_t *snr);}{ + int ioctl(int fd, int request = FE\_READ\_SNR, int16\_t *snr);}{ This ioctl call returns the signal-to-noise ratio for the signal currently received by the front-end. For this command, read-only access to the device is sufficient. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_READ\_SNR for this command.\\ - int32\_t *snr& The signal-to-noise ratio, as a multiple of - $10^{-6}$ dB, is stored into *snr.\\ - & Example: a value of 12,300,000 corresponds - to a signal-to-noise ratio of 12.3 dB. + int16\_t *snr& The signal-to-noise ratio is stored into *snr.\\ }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& snr points to invalid address.\\ @@ -463,7 +424,7 @@ typedef enum { } \ifunction{FE\_READ\_SIGNAL\_STRENGTH}{ - int ioctl( int fd, int request = FE\_READ\_SIGNAL\_STRENGTH, int32\_t *strength); + int ioctl( int fd, int request = FE\_READ\_SIGNAL\_STRENGTH, int16\_t *strength); }{ This ioctl call returns the signal strength value for the signal currently received by the front-end. For this command, read-only access to the device @@ -471,11 +432,7 @@ is sufficient. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_READ\_SIGNAL\_STRENGTH for this command.\\ -int32\_t *strength & The signal strength value, as a multiple of - $10^{-6 }$ dBm, - is stored into *strength. \\ - &Example: a value of -12,500,000 corresponds to a signal - strength value of -12.5 dBm. +int16\_t *strength & The signal strength value is stored into *strength.\\ }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& status points to invalid address.\\ @@ -505,59 +462,8 @@ by the driver so far. } -\ifunction{FE\_GET\_NEXT\_FREQUENCY}{ - int ioctl( int fd, int request = FE\_GET\_NEXT\_FREQUENCY, uint32\_t *freq);}{ - When scanning a frequency range, it is desirable to use a scanning step size - that is as large as possible, yet small enough to be able to lock to any signal - within the range. - This ioctl operation does just that - it increments a given frequency by a - step size suitable for efficient scanning. - The step size used by this function may be a quite complex function of the given - frequency, hardware capabilities, and parameter settings of the device. Thus, a - returned result is only valid for the current state of the device. - For this command, read-only access to the device is sufficient.\\ - Note that scanning may still be excruciatingly slow on some hardware, for - other reasons than a non-optimal scanning step size. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_GET\_NEXT\_FREQUENCY for this command.\\ - uint32\_t *freq& Input: a given frequency \\ - & Output: the frequency corresponding to - the next higher frequency setting.\\ - }{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& freq points to invalid address.\\ - EINVAL& Maximum supported frequency reached.\\ - ENOSYS& Function not available for this device. -} - -\ifunction{FE\_GET\_NEXT\_SYMBOL\_RATE}{ - int ioctl( int fd, int request = FE\_GET\_NEXT\_SYMBOL\_RATE, uint32\_t *symbolRate); - }{ - When scanning a range of symbol rates (e.g. for "blind acquisition") it is - desirable to use a scanning step size that is as large as possible, yet - small enough to detect any valid signal within the range. This ioctl - operation does just that - it increments a given symbol rate by a step size - suitable for efficient scanning. - The step size used by this function may be a quite complex function of the given - symbol rate, hardware capabilities, and parameter settings of the device. - Thus, a returned result is only valid for the current state of the device. - For this command, read-only access to the device is sufficient. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_GET\_NEXT\_SYMBOL\_RATE for this command.\\ - uint32\_t *symbolRate& Input: a given symbol rate \\ - & Output: the symbol rate corresponding to - the next higher symbol rate.\\ - }{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& symbolRate points to invalid address.\\ - EINVAL& Maximum supported symbol rate reached.\\ - ENOSYS& Function not available for this device. -} - \ifunction{FE\_SET\_FRONTEND}{ - int ioctl(int fd, int request = FE\_SET\_FRONTEND, struct FrontendParameters *p);}{ + int ioctl(int fd, int request = FE\_SET\_FRONTEND, struct dvb\_frontend\_parameters *p);}{ This ioctl call starts a tuning operation using specified parameters. The result of this call will be successful if the parameters were valid and the tuning could be initiated. @@ -571,7 +477,21 @@ by the driver so far. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_SET\_FRONTEND for this command.\\ - struct FrontendParameters *p& Points to parameters for tuning operation.\\ + struct dvb\_frontend\_parameters *p& Points to parameters for tuning operation.\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& p points to invalid address.\\ + EINVAL& Maximum supported symbol rate reached.\\ +} + +\ifunction{FE\_GET\_FRONTEND}{ + int ioctl(int fd, int request = FE\_GET\_FRONTEND, struct dvb\_frontend\_parameters *p);}{ + This ioctl call queries the currently effective frontend parameters. + For this command, read-only access to the device is sufficient. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_SET\_FRONTEND for this command.\\ + struct dvb\_frontend\_parameters *p& Points to parameters for tuning operation.\\ }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& p points to invalid address.\\ @@ -579,8 +499,8 @@ by the driver so far. } \ifunction{FE\_GET\_EVENT}{ - int ioctl(int fd, int request = QPSK\_GET\_EVENT, struct qpskEvent *ev);}{ - This ioctl call returns an event of type qpskEvent if available. If an event + int ioctl(int fd, int request = QPSK\_GET\_EVENT, struct dvb\_frontend\_event *ev);}{ + This ioctl call returns a frontend event if available. If an event is not available, the behavior depends on whether the device is in blocking or non-blocking mode. In the latter case, the call fails immediately with errno set to EWOULDBLOCK. In the former case, the call blocks until an event @@ -593,14 +513,15 @@ by the driver so far. must be serviced regularly to avoid overflow. If an overflow happens, the oldest event is discarded from the queue, and an error (EOVERFLOW) occurs the next time the queue is read. After reporting the error condition in this - fashion, subsequent QPSK\_GET\_EVENT calls will return events from the queue as + fashion, subsequent FE\_GET\_EVENT calls will return events from the queue as usual.\\ For the sake of implementation simplicity, this command requires read/write access to the device. }{ int fd & File descriptor returned by a previous call to open().\\ - int request & Equals QPSK\_GET\_EVENT for this command.\\ - struct qpskEvent *ev&Points to the location where the event, if any, is to be stored. + int request & Equals FE\_GET\_EVENT for this command.\\ + struct dvb\_frontend\_event *ev & Points to the location where the event,\\ + & if any, is to be stored. }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& ev points to invalid address.\\ @@ -611,19 +532,133 @@ by the driver so far. } \ifunction{FE\_GET\_INFO}{ - int ioctl(int fd, int request = FE\_GET\_INFO, struct FrontendInfo *info);}{ +\label{fegetinfo} + int ioctl(int fd, int request = FE\_GET\_INFO, struct dvb\_frontend\_info *info);}{ This ioctl call returns information about the front-end. This call only requires read-only access to the device. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_GET\_INFO for this command.\\ - struct qpskFrontendInfo *info & Points to the location where the front-end + struct dvb\_frontend\_info *info & Points to the location where the front-end information is to be stored. }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& info points to invalid address.\\ } +\ifunction{FE\_DISEC\_RESET\_OVERLOAD}{ + int ioctl(int fd, int request = FE\_DISEC\_RESET\_OVERLOAD);}{ + If the bus has been automatically powered off due to power overload, this + ioctl call restores the power to the bus. The call requires read/write + access to the device. + This call has no effect if the device is manually powered off. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_DISEC\_RESET\_OVERLOAD for this command.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EPERM & Permission denied (needs read/write access).\\ + EINTERNAL & Internal error in the device driver.\\ +} + + +\ifunction{FE\_DISEC\_SEND\_MASTER\_CMD}{ +int ioctl(int fd, int request = FE\_DISEC\_SEND\_MASTER\_CMD, struct dvb\_diseqc\_master\_cmd *cmd);}{ + This ioctl call is used to send a a DiSEqC command.\\ + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_DISEC\_SEND\_MASTER\_CMD for this command.\\ + struct dvb\_diseqc\_master\_cmd *cmd & Pointer to the command to be transmitted.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EFAULT & Seq points to an invalid address.\\ + EINVAL & The data structure referred to by seq is invalid in some way.\\ + EPERM & Permission denied (needs read/write access).\\ + EINTERNAL & Internal error in the device driver.\\ +} + +\ifunction{FE\_DISEC\_RECV\_SLAVE\_REPLY}{ +int ioctl(int fd, int request = FE\_DISEC\_RECV\_SLAVE\_REPLY, struct dvb\_diseqc\_slave\_reply *reply);}{ +This ioctl call is used to receive reply to a DiSEqC 2.0 command.\\ + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_DISEC\_RECV\_SLAVE\_REPLY for this command.\\ + struct dvb\_diseqc\_slave\_reply *reply & Pointer to the command to be received.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EFAULT & Seq points to an invalid address.\\ + EINVAL & The data structure referred to by seq is invalid in some way.\\ + EPERM & Permission denied (needs read/write access).\\ + EINTERNAL & Internal error in the device driver.\\ +} + +\ifunction{FE\_DISEC\_SEND\_BURST}{ +int ioctl(int fd, int request = FE\_DISEC\_SEND\_BURST, fe\_sec\_mini\_cmd\_t burst);}{ +This ioctl call is used to send a 22KHz tone burst.\\ + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_DISEC\_SEND\_BURST for this command.\\ + fe\_sec\_mini\_cmd\_t burst & burst A or B.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EFAULT & Seq points to an invalid address.\\ + EINVAL & The data structure referred to by seq is invalid in some way.\\ + EPERM & Permission denied (needs read/write access).\\ + EINTERNAL & Internal error in the device driver.\\ +} + + +\ifunction{FE\_SET\_TONE}{ +int ioctl(int fd, int request = FE\_SET\_TONE, fe\_sec\_tone\_mode\_t tone);}{ +This call is used to set the generation of the continuous 22kHz tone. +This call requires read/write permissions. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals FE\_SET\_TONE for this command.\\ +fe\_sec\_tone\_mode\_t tone & The requested tone generation mode (on/off).\\ +}{ +ENODEV & Device driver not loaded/available.\\ +EBUSY & Device or resource busy.\\ +EINVAL & Invalid argument.\\ +EPERM & File not opened with read permissions.\\ +EINTERNAL & Internal error in the device driver.\\ +} + + +\ifunction{FE\_SET\_VOLTAGE}{ +int ioctl(int fd, int request = FE\_SET\_VOLTAGE, fe\_sec\_voltage\_t voltage);}{ +This call is used to set the bus voltage. +This call requires read/write permissions. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals FE\_SET\_VOLTAGE for this command.\\ +fe\_sec\_voltage\_t voltage & The requested bus voltage.\\ +}{ +ENODEV & Device driver not loaded/available.\\ +EBUSY & Device or resource busy.\\ +EINVAL & Invalid argument.\\ +EPERM & File not opened with read permissions.\\ +EINTERNAL & Internal error in the device driver.\\ +} + +\ifunction{FE\_ENABLE\_HIGH\_LNB\_VOLTAGE}{ +int ioctl(int fd, int request = FE\_ENABLE\_HIGH\_LNB\_VOLTAGE, int high);}{ +If high != 0 enables slightly higher voltages instead of 13/18V +(to compensate for long cables). +This call requires read/write permissions. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals FE\_SET\_VOLTAGE for this command.\\ +int high & The requested bus voltage.\\ +}{ +ENODEV & Device driver not loaded/available.\\ +EBUSY & Device or resource busy.\\ +EINVAL & Invalid argument.\\ +EPERM & File not opened with read permissions.\\ +EINTERNAL & Internal error in the device driver.\\ +} + + %%% Local Variables: %%% mode: latex %%% TeX-master: "dvbapi" diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex index 1d859fadb..613bcd6c8 100644 --- a/dvb-spec/dvbapi/intro.tex +++ b/dvb-spec/dvbapi/intro.tex @@ -1,15 +1,21 @@ \chapter{Introduction} %\addcontentsline{toc}{part}{Introduction} %\chaptermark{Introduction} + \section{What you need to know} + The reader of this document is required to have some knowledge in the area of digital video broadcasting (DVB) and should be familiar with -part I of ISO/IEC 13818, i.e you should know what a -program/transport stream (PS/TS) is and what is meant by a packetized elementary -stream (PES) or an I-frame. +part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), +i.e you should know what a program/transport stream (PS/TS) is and what is +meant by a packetized elementary stream (PES) or an I-frame. + +Various DVB standards documents are available from +\texttt{http://www.dvb.org/} and/or \texttt{http://www.etsi.org/}. It is also necessary to know how to access unix/linux devices and how to use ioctl calls. This also includes the knowledge of C or C++. + \section{History} The first API for DVB cards we used at Convergence in late 1999 @@ -26,11 +32,12 @@ Nokia and Convergence made it available to all Linux developers and published it on \texttt{http://www.linuxtv.org/} in September 2000. Convergence is the maintainer of the Linux DVB API. Together with the LinuxTV community (i.e. you, the reader of this document), -the Linux DVB API will be constantly reviewed and improved upon. +the Linux DVB API will be constantly reviewed and improved. With the Linux driver for the Siemens/Hauppauge DVB PCI card Convergence provides a first implementation of the Linux DVB API. +\newpage \section{Overview} \begin{figure}[htbp] @@ -49,14 +56,10 @@ main hardware components: Here the raw signal reaches the DVB hardware from a satellite dish or antenna or directly from cable. The frontend down-converts and demodulates -this signal into an MPEG transport stream (TS). - -\item SEC for controlling external hardware like LNBs and antennas - -This part of the hardware can send signals back through the satellite -cable to control the polarization of the LNB, to switch between -different LNBs or even to control the movements of a dish rotor. - +this signal into an MPEG transport stream (TS). In case of a satellite +frontend, this includes a facility for satellite equipment control (SEC), +which allows control of LNB polarization, multi feed switches or +dish rotors. \item Conditional Access (CA) hardware like CI adapters and smartcard slots @@ -74,10 +77,11 @@ or other streams of the same provider. \item MPEG2 audio and video decoder The main targets of the demultiplexer are the MPEG2 audio and video -decoders. After decoding the pass on the uncompressed audio +decoders. After decoding they pass on the uncompressed audio and video to the computer screen or (through a PAL/NTSC encoder) to a TV set. \end{itemize} + Figure \ref{fig:dvbstb} shows a crude schematic of the control and data flow between those components. @@ -91,11 +95,9 @@ Also not every card or STB provides conditional access hardware. The Linux DVB API lets you control these hardware components through currently six Unix-style character devices for -video, audio, frontend, SEC, demux and CA. +video, audio, frontend, demux, CA and IP-over-DVB networking. The video and audio devices control the MPEG2 decoder hardware, the frontend device the tuner and the DVB demodulator. -External hardware like DiSEqC switches and rotors can be controlled -through the SEC device. The demux device gives you control over the PES and section filters of the hardware. If the hardware does not support filtering these filters can be implemented in software. @@ -104,78 +106,41 @@ of the hardware. It can depend on the individual security requirements of the platform, if and how many of the CA functions are made available to the application through this device. +\smallskip All devices can be found in the \texttt{/dev} tree under -\texttt{/dev/ost}, where OST stands for Open Standards Terminal. -The individual devices are called +\texttt{/dev/dvb}. The individual devices are called \begin{itemize} -\item \texttt{/dev/ost/audio}, -\item \texttt{/dev/ost/video}, -\item \texttt{/dev/ost/frontend}, -\item \texttt{/dev/ost/sec}, -\item \texttt{/dev/ost/demux}, -\item \texttt{/dev/ost/ca}, +\item \texttt{/dev/dvb/adapterN/audioM}, +\item \texttt{/dev/dvb/adapterN/videoM}, +\item \texttt{/dev/dvb/adapterN/frontendM}, +\item \texttt{/dev/dvb/adapterN/netM}, +\item \texttt{/dev/dvb/adapterN/demuxM}, +\item \texttt{/dev/dvb/adapterN/caM}, \end{itemize} -but we will omit the ``\texttt{/dev/ost/}'' in the further dicussion of -these devices. - -If more than one card is present in the system the other cards -can be accessed through the corresponding devices with the -card's number appended. \texttt{/dev/ost/demux0} (which -is identical to \texttt{/dev/ost/demux}) would, e.g., control the -demultiplexer of the first card, while \texttt{/dev/ost/demux1} -would control the demultiplexer of the second card, and so on. +where N enumerates the DVB PCI cards in a system starting from~0, +and M enumerates the devices of each type within each adapter, starting +from~0, too. +We will omit the ``\texttt{/dev/dvb/adapterN/}'' in the further dicussion of +these devices. The naming scheme for the devices is the same wheter devfs +is used or not. More details about the data structures and function calls of all the devices are described in the following chapters. +\section{API include files} -\section{DVB Devices with Devfs} - -Recent Linux kernel versions support a special file system called -\textsl{devfs} which is a replacement for the traditional -device directory. -With devfs a Linux DVB driver will only create those device file entries -which actually exist. -It also makes dealing with more complex DVB hardware much easier. -The device structure described above is not well suited to deal -with multiple DVB cards with more than one frontend or demultiplexer. -Consider, e.g., two DVB cards, one with two frontends and -one demultiplexer, the other with one frontend and two demultiplexers. -If we just assign them consecutive numbers, there would be a demultiplexer -and a frontend which do not belong to the same card but have -the same number. - -With \textsl{devfs} we propose a different scheme for the device names. -The root directory for all DVB cards will be \texttt{/dev/dvb}. -Each card gets assigned a sub-directory with the name \texttt{/dev/card0}, -\texttt{/dev/card1}, etc. -The files created in these sub-directories will correspond directly to the -hardware actually present on the card. -Thus, if the first card has one QAM frontend, one demultiplexer -and otherwise no other hardware, -only \texttt{/dev/dvb/card0/qamfe0} and \texttt{/dev/dvb/card0/demux0} -will be created. -When a second DVB-S card with one frontend (including SEC) device, -two demultiplexers and an MPEG2 audio/video decoder is added, the -complete \texttt{/dev/dvb} tree will look like this: +For each of the DVB devices a corresponding include file +exists. The DVB API include files should be included +in application sources with a partial path like: \begin{verbatim} -/dev/dvb/card0/frontend0 - demux0 - -/dev/dvb/card1/video0 - audio0 - demux0 - demux1 - frontend0 - sec0 +#include <linux/dvb/frontend.h> \end{verbatim} - -\section{Using the Devices} - -\dots - +To enable applications to support different API version, an additional +include file \texttt{linux/dvb/version.h} exists, which defines the +constant \texttt{DVB\_API\_VERSION}. This document describes +\texttt{DVB\_API\_VERSION~3}. %%% Local Variables: %%% mode: latex diff --git a/dvb-spec/dvbapi/kdapi.tex b/dvb-spec/dvbapi/kdapi.tex index 59490299b..f7fc69353 100644 --- a/dvb-spec/dvbapi/kdapi.tex +++ b/dvb-spec/dvbapi/kdapi.tex @@ -1,6 +1,13 @@ \devsec{Kernel Demux API} -The kernel 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 DVB device driver writers. The header file for this +API is named \texttt{demux.h} and located in +\texttt{drivers/media/dvb/dvb-core}. + +Maintainer note: This section must be reviewed. It is probably out of date. \devsubsec{Kernel Demux Data Types} diff --git a/dvb-spec/dvbapi/net.tex b/dvb-spec/dvbapi/net.tex new file mode 100644 index 000000000..dc6566633 --- /dev/null +++ b/dvb-spec/dvbapi/net.tex @@ -0,0 +1,19 @@ +\devsec{DVB Network API} + +The DVB net device enables feeding of MPE (multi protocol +encapsulation) packets received via DVB into the Linux network +protocol stack, e.g. for internet via satellite applications. +It can be accessed through \texttt{/dev/dvb/adapter0/net0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/net.h} in your application. + + +\devsubsec{DVB Net Data Types} + +To be written\dots + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/sec.tex b/dvb-spec/dvbapi/sec.tex deleted file mode 100644 index 88342c3a6..000000000 --- a/dvb-spec/dvbapi/sec.tex +++ /dev/null @@ -1,282 +0,0 @@ -\devsec{DVB SEC API} - -The DVB SEC device controls the Satellite Equipment Control of -the DVB hardware, i.e. DiSEqC and V-SEC. -It is accessed through \texttt{/dev/ost/sec}. - -\devsubsec{SEC Data Types} - -\devsubsubsec{secDiseqcCmd} -\label{secdiseqccmd} - -\begin{verbatim} -struct secDiseqcCmd { - uint8_t addr; - uint8_t cmd; - uint8_t numParams; - uint8_t params[SEC_MAX_DISEQC_PARAMS]; -}; -\end{verbatim} - - -\devsubsubsec{secVoltage} -\label{secvoltage} - -\begin{verbatim} -typedef uint32_t secVoltage; -\end{verbatim} -\begin{verbatim} -enum { - SEC_VOLTAGE_OFF, - SEC_VOLTAGE_LT, - SEC_VOLTAGE_13, - SEC_VOLTAGE_13_5, - SEC_VOLTAGE_18, - SEC_VOLTAGE_18_5 -}; -\end{verbatim} - - -\devsubsubsec{secToneMode} -\label{sectonemode} - -\begin{verbatim} -typedef uint32_t secToneMode; -\end{verbatim} -\begin{verbatim} -typedef enum { - SEC_TONE_ON, - SEC_TONE_OFF -} secToneMode_t; -\end{verbatim} - - -\devsubsubsec{secMiniCmd} -\label{secminicmd} - -\begin{verbatim} -typedef uint32_t secMiniCmd; -\end{verbatim} -\begin{verbatim} -typedef enum { - SEC_MINI_NONE, - SEC_MINI_A, - SEC_MINI_B -} secMiniCmd_t; -\end{verbatim} -\begin{verbatim} -struct secStatus { - int32_t busMode; - secVoltage selVolt; - secToneMode contTone; -}; -\end{verbatim} - -\begin{verbatim} -enum { - SEC_BUS_IDLE, - SEC_BUS_BUSY, - SEC_BUS_OFF, - SEC_BUS_OVERLOAD -}; -\end{verbatim} - - -\devsubsubsec{secCommand} -\label{seccommand} - -\begin{verbatim} -struct secCommand { - int32_t type; - union { - struct secDiseqcCmd diseqc; - uint8_t vsec; - uint32_t pause; - } u; -}; -\end{verbatim} - - -\devsubsubsec{secCmdSequence} -\label{seccmdsequence} - -\begin{verbatim} -struct secCmdSequence { - secVoltage voltage; - secMiniCmd miniCommand; - secToneMode continuousTone; - - uint32_t numCommands; - struct secCommand* commands; -}; -\end{verbatim} - -\begin{verbatim} -enum { - SEC_CMDTYPE_DISEQC, - SEC_CMDTYPE_VSEC, - SEC_CMDTYPE_PAUSE -}; -\end{verbatim} - -\begin{verbatim} -typedef enum { - SEC_DISEQC_SENT, - SEC_VSEC_SENT, - SEC_PAUSE_COMPLETE, - SEC_CALLBACK_ERROR -} secCallback_t; -\end{verbatim} - -\clearpage - -\devsubsec{SEC Function Calls} - -\function{open()}{ - int open(const char *deviceName, int flags);}{ - This system call opens a named SEC device for subsequent use. - If the device is opened in read-only mode, only status and statistics - monitoring is allowed. If the device is opened in read/write mode, all - types of operations can be performed. - Any number of applications can have simultaneous access to the device. - }{ - const char *deviceName & Name of specific SEC device.\\ - int flags & A bit-wise OR of the following flags:\\ - & \hspace{1em} O\_RDONLY read-only access\\ - & \hspace{1em} O\_RDWR read/write access\\ - & The optional flag O\_NONBLOCK is not supported. If O\_NONBLOCK is set, - open() and most other subsequent calls to the device will return -1 and - set errno to EWOULDBLOCK. - The communication with the peripheral devices is sequential by nature, - so it is probably preferable to use the device in synchronous mode. - This is the motivation for not going through the extra effort of - implementing asynchronous operation of the device. - }{ - ENODEV & Device driver not loaded/available.\\ - EFAULT & deviceName does not refer to a valid memory area.\\ - EBUSY & Device or resource busy.\\ - EINVAL & Invalid argument.\\ -} - -\function{close()}{ - int close(int fd);}{ - This system call closes a previously opened SEC device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - }{ - EBADF & fd is not a valid open file descriptor.\\ -} - -\ifunction{SEC\_GET\_STATUS}{ - int ioctl(int fd, int request = SEC\_GET\_STATUS, struct secStatus* status);}{ - This call gets the status of the device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals SEC\_GET\_STATUS for this command.\\ - struct secStatus* status & The status of the device.\\ - }{ - ENODEV & Device driver not loaded/available.\\ - EFAULT & status is an invalid pointer.\\ - EBUSY & Device or resource busy.\\ - EINVAL & Invalid argument.\\ - EPERM & File not opened with read permissions.\\ - EINTERNAL & Internal error in the device driver.\\ -} - -\ifunction{SEC\_RESET\_OVERLOAD}{ - int ioctl(int fd, int request = SEC\_RESET\_OVERLOAD);}{ - If the bus has been automatically powered off due to power overload, this - ioctl call restores the power to the bus. The call requires read/write - access to the device. - This call has no effect if the device is manually powered off. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals SEC\_RESET\_OVERLOAD for this command.\\ - }{ - EBADF & fd is not a valid file descriptor.\\ - EPERM & Permission denied (needs read/write access).\\ - EINTERNAL & Internal error in the device driver.\\ -} - -\ifunction{SEC\_SEND\_SEQUENCE}{ -int ioctl(int fd, int request = SEC\_SEND\_SEQUENCE, struct secCmdSequence *seq); -}{ -This ioctl call is used to send a sequence of DiSEqCTM and/or V-SEC -commands. The first version of the SEC device does not support V-SEC -signaling and it aborts the operation with an error code if a V-SEC -command is detected in the input data.\\ -\begin{itemize} -\item[$\bullet$] The call will fail with errno set to EBUSOVERLOAD if the bus is -overloaded. If the bus is overloaded, SEC\_RESET\_OVERLOAD can be -called and the operation can be retried. -\item[$\bullet$] If seq.numCommands equals 0 and seq.miniCommand equals SEC\_MINI\_NONE, -the bus voltage will be switched and the continuous 22kHz tone -generation enabled/disabled immediately. -\end{itemize}\\ -This operation is atomic. If several processes calls this ioctl -simultaneously, the operations will be serialized so a complete sequence -is sent at a time. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals SEC\_SEND\_SEQUENCE for this command.\\ - struct secCmdSequence *seq & Pointer to the command sequence to be transmitted.\\ - }{ - EBADF & fd is not a valid file descriptor.\\ - EFAULT & Seq points to an invalid address.\\ - EINVAL & The data structure referred to by seq is invalid in some way.\\ - EPERM & Permission denied (needs read/write access).\\ - EINTERNAL & Internal error in the device driver.\\ - EBUSMODE & The device is not prepared for transmission - (e.g. it might be manually powered off).\\ - EBUSOVERLOAD & Bus overload has occurred.\\ -} - - -\ifunction{SEC\_SET\_TONE}{ -int ioctl(int fd, int request = SEC\_SET\_TONE, secToneMode tone); -}{ -This call is used to set the generation of the continuous 22kHz tone. -The possibility to just change the tone mode is already provided by -ioctl SEC\_SEND\_SEQUENCE, but SEC\_SET\_TONE is an easier to use interface. -To keep the transmission of a command sequence as -an atomic operation, SEC\_SET\_TONE will block if a transmission is in -progress. This call requires read/write permissions. -}{ -int fd & File descriptor returned by a previous call to open().\\ -int request & Equals SEC\_SET\_TONE for this command.\\ -secToneMode tone & The requested tone generation mode (on/off).\\ -}{ -ENODEV & Device driver not loaded/available.\\ -EBUSY & Device or resource busy.\\ -EINVAL & Invalid argument.\\ -EPERM & File not opened with read permissions.\\ -EINTERNAL & Internal error in the device driver.\\ -} - - -\ifunction{SEC\_SET\_VOLTAGE}{ -int ioctl(int fd, int request = SEC\_SET\_VOLTAGE, secVoltage voltage); -}{ -This call is used to set the bus voltage. The possibility to just change -the bus voltage is already provided by ioctl SEC\_SEND\_SEQUENCE, but -SEC\_SET\_VOLTAGE is an easier to use interface. -To keep the transmission of a command sequence as -an atomic operation, SEC\_SET\_VOLTAGE will block if a transmission is in -progress. -This call requires read/write permissions. -}{ -int fd & File descriptor returned by a previous call to open().\\ -int request & Equals SEC\_SET\_VOLTAGE for this command.\\ -secVoltage voltage & The requested bus voltage.\\ -}{ -ENODEV & Device driver not loaded/available.\\ -EBUSY & Device or resource busy.\\ -EINVAL & Invalid argument.\\ -EPERM & File not opened with read permissions.\\ -EINTERNAL & Internal error in the device driver.\\ -} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% End: diff --git a/dvb-spec/dvbapi/title.tex b/dvb-spec/dvbapi/title.tex index 574464d23..29aca30d6 100644 --- a/dvb-spec/dvbapi/title.tex +++ b/dvb-spec/dvbapi/title.tex @@ -1,23 +1,27 @@ \pagenumbering{arabic} \pagestyle{empty} -\title{\huge\textbf{LINUX DVB API}} +\title{\huge\textbf{LINUX DVB API Version 3}} \author{ \includegraphics{cimlogo.psi}\\ - Convergence integrated media GmbH\\\\ - Dr. Ralph J.K. Metzler\\ - \texttt{<rjkm@convergence.de>}\\\\ - Dr. Marcus O.C. Metzler\\ - \texttt{<mocm@convergence.de>} -% Rosenthalerstr. 51\\ -% 10178 Berlin\\Germany + Copyright 2002, 2003 Convergence GmbH\\\\ + Written by Dr. Ralph J.K. Metzler\\ + \texttt{<rjkm@metzlerbros.de>}\\\\ + and Dr. Marcus O.C. Metzler\\ + \texttt{<mocm@metzlerbros.de>}\\ } -\date{02/14/2002\\V 0.9.4} +\date{02/10/2003\\V 1.0.0-pre1} + \maketitle +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation. +A copy of the license is included in the chapter entitled "GNU +Free Documentation License". + \newpage -%\end{titlepage} % Local Variables: % mode: latex % TeX-master: "dvbapi" diff --git a/dvb-spec/dvbapi/video.tex b/dvb-spec/dvbapi/video.tex index 7300c95c0..3fa066b87 100644 --- a/dvb-spec/dvbapi/video.tex +++ b/dvb-spec/dvbapi/video.tex @@ -1,11 +1,22 @@ \devsec{DVB Video Device} The DVB video device controls the MPEG2 video decoder of the DVB hardware. -It can be accessed through \texttt{/dev/ost/video}. -The include file \texttt{ost/video.h} defines the data types and lists -all I/O calls. Please note that some DVB cards don't have their own -MPEG decoder, which results in the omission of the audio and video -device as well as the video4linux device. +It can be accessed through \texttt{/dev/dvb/adapter0/video0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/video.h} in your application. + + +Note that the DVB video device only controls decoding of the MPEG +video stream, not its presentation on the TV or computer screen. +On PCs this is typically handled by an associated video4linux device, e.g. +\texttt{/dev/video}, which allows scaling and defining output windows. + +Some DVB cards don't have their own MPEG decoder, which results in the omission +of the audio and video device as well as the video4linux device. + +The ioctls that deal with SPUs (sub picture units) and navigation +packets are only supported on some MPEG decoders made for DVD playback. + \devsubsec{Video Data Types} @@ -17,7 +28,7 @@ The \texttt{video\_format\_t} data type defined by typedef enum { VIDEO_FORMAT_4_3, VIDEO_FORMAT_16_9 -} video\_format_t; +} video_format_t; \end{verbatim} is used in the VIDEO\_SET\_FORMAT function (\ref{videosetformat}) to tell the driver which aspect ratio the output hardware (e.g. TV) has. @@ -26,7 +37,7 @@ returned by VIDEO\_GET\_STATUS (\ref{videogetstatus}) and video\_event (\ref{videoevent}) returned by VIDEO\_GET\_EVENT (\ref{videogetevent}) which report about the display format of the current video stream. -\devsubsubsec{videoDisplayFormat\_t} +\devsubsubsec{video\_display\_format\_t} \label{videodispformat} In case the display format of the video stream and of the @@ -39,7 +50,7 @@ typedef enum { VIDEO_PAN_SCAN, VIDEO_LETTER_BOX, VIDEO_CENTER_CUT_OUT -} video\_displayformat_t; +} video_display_format_t; \end{verbatim} as argument. @@ -53,7 +64,7 @@ replaying from an internal (demuxer) or external (user write) source. typedef enum { VIDEO_SOURCE_DEMUX, VIDEO_SOURCE_MEMORY -} video\_stream\_source_t; +} video_stream_source_t; \end{verbatim} VIDEO\_SOURCE\_DEMUX selects the demultiplexer (fed either by the frontend or the DVR device) as the source of @@ -71,35 +82,35 @@ typedef enum { VIDEO_STOPPED, VIDEO_PLAYING, VIDEO_FREEZED -} video\_play\_state_t; +} video_play_state_t; \end{verbatim} -\devsubsubsec{video event} +\devsubsubsec{struct video\_event} \label{videoevent} The following is the structure of a video event as it is returned by the VIDEO\_GET\_EVENT call. \begin{verbatim} -struct video\_event { +struct video_event { int32_t type; time_t timestamp; union { - video\_format_t video\_format; + video_format_t video_format; } u; }; \end{verbatim} -\devsubsubsec{video status} +\devsubsubsec{struct video\_status} \label{videostatus} The VIDEO\_GET\_STATUS call returns the following structure informing about various states of the playback operation. \begin{verbatim} -struct video\_status { - boolean video\_blank; - video\_play\_state_t play\_state; - video\_stream\_source_t stream\_source; - video\_format_t video\_format; - video\_displayformat_t display\_format; +struct video_status { + boolean video_blank; + video_play_state_t play_state; + video_stream_source_t stream_source; + video_format_t video_format; + video_displayformat_t display_format; }; \end{verbatim} If video\_blank is set video will be blanked out if the channel is changed or @@ -113,13 +124,13 @@ Finally, display\_format corresponds to the selected cropping mode in case the source video format is not the same as the format of the output device. -\devsubsubsec{video display still picture} +\devsubsubsec{struct video\_still\_picture} \label{videostill} An I-frame displayed via the VIDEO\_STILLPICTURE call is passed on within the following structure. \begin{verbatim} /* pointer to and size of a single iframe in memory */ -struct video\_still\_picture { +struct video_still_picture { char *iFrame; int32_t size; }; @@ -162,19 +173,19 @@ typedef enum { VIDEO_SYSTEM_NTSC60, VIDEO_SYSTEM_PAL60, VIDEO_SYSTEM_PALM60 -} video\_system_t; +} video_system_t; \end{verbatim} -\devsubsubsec{video highlights} +\devsubsubsec{struct video\_highlight} \label{vhilite} Calling the ioctl VIDEO\_SET\_HIGHLIGHTS posts the SPU highlight information. The call expects the following format for that information: - + \begin{verbatim} typedef -struct video\_highlight { +struct video_highlight { boolean active; /* 1=show highlight, 0=hide highlight */ uint8_t contrast1; /* 7- 4 Pattern pixel contrast */ /* 3- 0 Background pixel contrast */ @@ -190,7 +201,7 @@ struct video\_highlight { uint32_t xpos; /* 23-22 button color number */ /* 21-12 start x */ /* 9- 0 end x */ -} video\_highlight_t; +} video_highlight_t; \end{verbatim} @@ -200,10 +211,10 @@ Calling VIDEO\_SET\_SPU deactivates or activates SPU decoding, according to the following format: \begin{verbatim} typedef -struct video\_spu { +struct video_spu { boolean active; - int stream\_id; -} video\_spu\_t; + int stream_id; +} video_spu_t; \end{verbatim} @@ -212,10 +223,10 @@ struct video\_spu { The following structure is used to set the SPU palette by calling VIDEO\_SPU\_PALETTE: \begin{verbatim} typedef -struct video\_spu\_palette{ /* SPU Palette information */ +struct video_spu_palette{ int length; uint8_t *palette; -} video\_spu\_palette_t; +} video_spu_palette_t; \end{verbatim} \devsubsubsec{video NAVI pack} @@ -224,10 +235,10 @@ In order to get the navigational data the following structure has to be passed to the ioctl VIDEO\_GET\_NAVI: \begin{verbatim} typedef -struct video\_navi\_pack{ - int length; /* 0 ... 1024 */ +struct video_navi_pack{ + int length; /* 0 ... 1024 */ uint8_t data[1024]; -} video\_navi\_pack_t; +} video_navi_pack_t; \end{verbatim} @@ -235,7 +246,7 @@ struct video\_navi\_pack{ \label{vattrib} The following attributes can be set by a call to VIDEO\_SET\_ATTRIBUTES: \begin{verbatim} -typedef uint16_t video\_attributes_t; +typedef uint16_t video_attributes_t; /* bits: descr. */ /* 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */ /* 13-12 TV system (0=525/60, 1=625/50) */ @@ -255,7 +266,7 @@ typedef uint16_t video\_attributes_t; \function{open()}{ int open(const char *deviceName, int flags);}{ - This system call opens a named video device (e.g. /dev/ost/video) + This system call opens a named video device (e.g. /dev/dvb/adapter0/video0) for subsequent use. When an open() call has succeeded, the device will be ready for use. @@ -376,7 +387,7 @@ EINTERNAL & Internal error, possibly in the communication with \ifunction{VIDEO\_SELECT\_SOURCE}{ - int ioctl(fd, int request = VIDEO\_SELECT\_SOURCE, videoStreamSource\_t source);}{ + int ioctl(fd, int request = VIDEO\_SELECT\_SOURCE, video\_stream\_source\_t source);}{ This ioctl call informs the video device which source shall be used for the input data. The possible sources are demux or memory. If memory is selected, the data is fed to the video device through @@ -384,7 +395,7 @@ EINTERNAL & Internal error, possibly in the communication with }{ int fd & File descriptor returned by a previous call to open().\\ int request& Equals VIDEO\_SELECT\_SOURCE for this command. \\ - videoStreamSource\_t source&Indicates which source shall be used for the Video stream.\\ + video\_stream\_source\_t source&Indicates which source shall be used for the Video stream.\\ }{ EBADF& fd is not a valid open file descriptor \\ EINTERNAL & Internal error, possibly in the communication with the DVB subsystem.\\ @@ -446,13 +457,13 @@ EOVERFLOW & \\ \ifunction{VIDEO\_SET\_DISPLAY\_FORMAT}{ \label{videosetdisplayformat} - int ioctl(fd, int request = VIDEO\_SET\_DISPLAY\_FORMAT, videoDisplayFormat\_t format);}{ + int ioctl(fd, int request = VIDEO\_SET\_DISPLAY\_FORMAT, video\_display\_format\_t format);}{ This ioctl call asks the Video Device to select the video format to be applied by the MPEG chip on the video. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals VIDEO\_SET\_DISPLAY\_FORMAT for this command.\\ - videoDisplayFormat\_t format & Selects the video format to be used.\\ + video\_display\_format\_t format & Selects the video format to be used.\\ }{ EBADF& fd is not a valid open file descriptor \\ EINTERNAL & Internal error.\\ @@ -578,7 +589,7 @@ EOVERFLOW & \\ \ifunction{VIDEO\_SET\_SYSTEM}{ \label{videosetsystem} - int ioctl(fd, int request = VIDEO\_SET\_SYSTEM , videoSystem\_t system); + int ioctl(fd, int request = VIDEO\_SET\_SYSTEM , video\_system\_t system); }{ This ioctl sets the television output format. The format (see section \ref{videosys}) may vary from the color format of the displayed MPEG @@ -587,7 +598,7 @@ EOVERFLOW & \\ }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals VIDEO\_SET\_FORMAT for this command.\\ - videoSystem\_t system& video system of TV output.\\ + video\_system\_t system& video system of TV output.\\ }{ EBADF& fd is not a valid open file descriptor \\ EINVAL& system is not a valid or supported video system.\\ @@ -663,7 +674,7 @@ EOVERFLOW & \\ \ifunction{VIDEO\_SET\_ATTRIBUTES}{ \label{videosetattributes} - int ioctl(fd, int request = VIDEO\_SET\_ATTRIBUTE ,videoAttributes\_t + int ioctl(fd, int request = VIDEO\_SET\_ATTRIBUTE ,video\_attributes\_t vattr) }{ This ioctl is intended for DVD playback and allows you to set @@ -673,7 +684,7 @@ EOVERFLOW & \\ }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals VIDEO\_SET\_ATTRIBUTE for this command.\\ - videoAttributes\_t vattr& video attributes according to section \ref{vattrib}.\\ + video\_attributes\_t vattr& video attributes according to section \ref{vattrib}.\\ }{ EBADF& fd is not a valid open file descriptor \\ EINVAL& input is not a valid attribute setting.\\ |