new file mode 100644
@@ -0,0 +1,883 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0
+
+.. c:namespace:: dtv.legacy.osd
+
+.. _dvb_osd:
+
+==============
+DVB OSD Device
+==============
+
+.. attention:: Do **not** use in new drivers!
+ See: :ref:`legacy_dvb_decoder_notes`
+
+The DVB OSD device controls the OnScreen-Display of the AV7110 based
+DVB-cards with hardware MPEG2 decoder. It can be accessed through
+``/dev/dvb/adapter?/osd0``.
+Data types and ioctl definitions can be accessed by including
+``linux/dvb/osd.h`` in your application.
+
+The OSD is not a frame-buffer like on many other cards.
+It is a kind of canvas one can draw on.
+The color-depth is limited depending on the memory size installed.
+An appropriate palette of colors has to be set up.
+The installed memory size can be identified with the `OSD_GET_CAPABILITY`_
+ioctl.
+
+OSD Data Types
+==============
+
+OSD_Command
+-----------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+ typedef enum {
+ /* All functions return -2 on "not open" */
+ OSD_Close = 1,
+ OSD_Open,
+ OSD_Show,
+ OSD_Hide,
+ OSD_Clear,
+ OSD_Fill,
+ OSD_SetColor,
+ OSD_SetPalette,
+ OSD_SetTrans,
+ OSD_SetPixel,
+ OSD_GetPixel,
+ OSD_SetRow,
+ OSD_SetBlock,
+ OSD_FillRow,
+ OSD_FillBlock,
+ OSD_Line,
+ OSD_Query,
+ OSD_Test,
+ OSD_Text,
+ OSD_SetWindow,
+ OSD_MoveWindow,
+ OSD_OpenRaw,
+ } OSD_Command;
+
+Commands
+~~~~~~~~
+
+.. note:: All functions return -2 on "not open"
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+ - ..
+
+ - Command
+
+ - | Used variables of ``struct`` `osd_cmd_t`_.
+ | Usage{variable} if alternative use.
+
+ - :cspan:`2` Description
+
+
+
+ - ..
+
+ - ``OSD_Close``
+
+ - -
+
+ - | Disables OSD and releases the buffers.
+ | Returns 0 on success.
+
+ - ..
+
+ - ``OSD_Open``
+
+ - | x0,y0,x1,y1,
+ | BitPerPixel[2/4/8]{color&0x0F},
+ | mix[0..15]{color&0xF0}
+
+ - | Opens OSD with this size and bit depth
+ | Returns 0 on success,
+ | -1 on DRAM allocation error,
+ | -2 on "already open".
+
+ - ..
+
+ - ``OSD_Show``
+
+ - -
+
+ - | Enables OSD mode.
+ | Returns 0 on success.
+
+ - ..
+
+ - ``OSD_Hide``
+
+ - -
+
+ - | Disables OSD mode.
+ | Returns 0 on success.
+
+ - ..
+
+ - ``OSD_Clear``
+
+ - -
+
+ - | Sets all pixel to color 0.
+ | Returns 0 on success.
+
+ - ..
+
+ - ``OSD_Fill``
+
+ - color
+
+ - | Sets all pixel to color <color>.
+ | Returns 0 on success.
+
+ - ..
+
+ - ``OSD_SetColor``
+
+ - | color,
+ | R{x0},G{y0},B{x1},
+ | opacity{y1}
+
+ - | Set palette entry <num> to <r,g,b>, <mix> and <trans> apply
+ | R,G,B: 0..255
+ | R=Red, G=Green, B=Blue
+ | opacity=0: pixel opacity 0% (only video pixel shows)
+ | opacity=1..254: pixel opacity as specified in header
+ | opacity=255: pixel opacity 100% (only OSD pixel shows)
+ | Returns 0 on success, -1 on error.
+
+ - ..
+
+ - ``OSD_SetPalette``
+
+ - | firstcolor{color},
+ | lastcolor{x0},data
+
+ - | Set a number of entries in the palette.
+ | Sets the entries "firstcolor" through "lastcolor" from the
+ array "data".
+ | Data has 4 byte for each color:
+ | R,G,B, and a opacity value: 0->transparent, 1..254->mix,
+ 255->pixel
+
+ - ..
+
+ - ``OSD_SetTrans``
+
+ - transparency{color}
+
+ - | Sets transparency of mixed pixel (0..15).
+ | Returns 0 on success.
+
+ - ..
+
+ - ``OSD_SetPixel``
+
+ - x0,y0,color
+
+ - | Sets pixel <x>,<y> to color number <color>.
+ | Returns 0 on success, -1 on error.
+
+ - ..
+
+ - ``OSD_GetPixel``
+
+ - x0,y0
+
+ - | Returns color number of pixel <x>,<y>, or -1.
+ | Command currently not supported by the AV7110!
+
+ - ..
+
+ - ``OSD_SetRow``
+
+ - x0,y0,x1,data
+
+ - | Fills pixels x0,y through x1,y with the content of data[].
+ | Returns 0 on success, -1 on clipping all pixel (no pixel
+ drawn).
+
+ - ..
+
+ - ``OSD_SetBlock``
+
+ - | x0,y0,x1,y1,
+ | increment{color},
+ | data
+
+ - | Fills pixels x0,y0 through x1,y1 with the content of data[].
+ | Inc contains the width of one line in the data block,
+ | inc<=0 uses block width as line width.
+ | Returns 0 on success, -1 on clipping all pixel.
+
+ - ..
+
+ - ``OSD_FillRow``
+
+ - x0,y0,x1,color
+
+ - | Fills pixels x0,y through x1,y with the color <color>.
+ | Returns 0 on success, -1 on clipping all pixel.
+
+ - ..
+
+ - ``OSD_FillBlock``
+
+ - x0,y0,x1,y1,color
+
+ - | Fills pixels x0,y0 through x1,y1 with the color <color>.
+ | Returns 0 on success, -1 on clipping all pixel.
+
+ - ..
+
+ - ``OSD_Line``
+
+ - x0,y0,x1,y1,color
+
+ - | Draw a line from x0,y0 to x1,y1 with the color <color>.
+ | Returns 0 on success.
+
+ - ..
+
+ - ``OSD_Query``
+
+ - | x0,y0,x1,y1,
+ | xasp{color}; yasp=11
+
+ - | Fills parameters with the picture dimensions and the pixel
+ aspect ratio.
+ | Returns 0 on success.
+ | Command currently not supported by the AV7110!
+
+ - ..
+
+ - ``OSD_Test``
+
+ - -
+
+ - | Draws a test picture.
+ | For debugging purposes only.
+ | Returns 0 on success.
+ - ..
+
+ - ``OSD_Text``
+
+ - x0,y0,size,color,text
+
+ - Draws a text at position x0,y0 with the color <color>.
+
+ - ..
+
+ - ``OSD_SetWindow``
+
+ - x0
+
+ - Set window with number 0<x0<8 as current.
+
+ - ..
+
+ - ``OSD_MoveWindow``
+
+ - x0,y0
+
+ - Move current window to (x0, y0).
+
+ - ..
+
+ - ``OSD_OpenRaw``
+
+ - | x0,y0,x1,y1,
+ | `osd_raw_window_t`_ {color}
+
+ - Open other types of OSD windows.
+
+Description
+~~~~~~~~~~~
+
+The ``OSD_Command`` data type is used with the `OSD_SEND_CMD`_ ioctl to
+tell the driver which OSD_Command to execute.
+
+
+-----
+
+osd_cmd_t
+---------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+ typedef struct osd_cmd_s {
+ OSD_Command cmd;
+ int x0;
+ int y0;
+ int x1;
+ int y1;
+ int color;
+ void __user *data;
+ } osd_cmd_t;
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ - ..
+
+ - ``OSD_Command cmd``
+
+ - `OSD_Command`_ to be executed.
+
+ - ..
+
+ - ``int x0``
+
+ - First horizontal position.
+
+ - ..
+
+ - ``int y0``
+
+ - First vertical position.
+
+ - ..
+
+ - ``int x1``
+
+ - Second horizontal position.
+
+ - ..
+
+ - ``int y1``
+
+ - Second vertical position.
+
+ - ..
+
+ - ``int color``
+
+ - Number of the color in the palette.
+
+ - ..
+
+ - ``void __user *data``
+
+ - Command specific Data.
+
+Description
+~~~~~~~~~~~
+
+The ``osd_cmd_t`` data type is used with the `OSD_SEND_CMD`_ ioctl.
+It contains the data for the OSD_Command and the `OSD_Command`_ itself.
+The structure has to be passed to the driver and the components may be
+modified by it.
+
+
+-----
+
+
+osd_raw_window_t
+----------------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+ typedef enum {
+ OSD_BITMAP1,
+ OSD_BITMAP2,
+ OSD_BITMAP4,
+ OSD_BITMAP8,
+ OSD_BITMAP1HR,
+ OSD_BITMAP2HR,
+ OSD_BITMAP4HR,
+ OSD_BITMAP8HR,
+ OSD_YCRCB422,
+ OSD_YCRCB444,
+ OSD_YCRCB444HR,
+ OSD_VIDEOTSIZE,
+ OSD_VIDEOHSIZE,
+ OSD_VIDEOQSIZE,
+ OSD_VIDEODSIZE,
+ OSD_VIDEOTHSIZE,
+ OSD_VIDEOTQSIZE,
+ OSD_VIDEOTDSIZE,
+ OSD_VIDEONSIZE,
+ OSD_CURSOR
+ } osd_raw_window_t;
+
+Constants
+~~~~~~~~~
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ - ..
+
+ - ``OSD_BITMAP1``
+
+ - :cspan:`1` 1 bit bitmap
+
+ - ..
+
+ - ``OSD_BITMAP2``
+
+ - 2 bit bitmap
+
+ - ..
+
+ - ``OSD_BITMAP4``
+
+ - 4 bit bitmap
+
+ - ..
+
+ - ``OSD_BITMAP8``
+
+ - 8 bit bitmap
+
+ - ..
+
+ - ``OSD_BITMAP1HR``
+
+ - 1 Bit bitmap half resolution
+
+ - ..
+
+ - ``OSD_BITMAP2HR``
+
+ - 2 Bit bitmap half resolution
+
+ - ..
+
+ - ``OSD_BITMAP4HR``
+
+ - 4 Bit bitmap half resolution
+
+ - ..
+
+ - ``OSD_BITMAP8HR``
+
+ - 8 Bit bitmap half resolution
+
+ - ..
+
+ - ``OSD_YCRCB422``
+
+ - 4:2:2 YCRCB Graphic Display
+
+ - ..
+
+ - ``OSD_YCRCB444``
+
+ - 4:4:4 YCRCB Graphic Display
+
+ - ..
+
+ - ``OSD_YCRCB444HR``
+
+ - 4:4:4 YCRCB graphic half resolution
+
+ - ..
+
+ - ``OSD_VIDEOTSIZE``
+
+ - True Size Normal MPEG Video Display
+
+ - ..
+
+ - ``OSD_VIDEOHSIZE``
+
+ - MPEG Video Display Half Resolution
+
+ - ..
+
+ - ``OSD_VIDEOQSIZE``
+
+ - MPEG Video Display Quarter Resolution
+
+ - ..
+
+ - ``OSD_VIDEODSIZE``
+
+ - MPEG Video Display Double Resolution
+
+ - ..
+
+ - ``OSD_VIDEOTHSIZE``
+
+ - True Size MPEG Video Display Half Resolution
+
+ - ..
+
+ - ``OSD_VIDEOTQSIZE``
+
+ - True Size MPEG Video Display Quarter Resolution
+
+ - ..
+
+ - ``OSD_VIDEOTDSIZE``
+
+ - True Size MPEG Video Display Double Resolution
+
+ - ..
+
+ - ``OSD_VIDEONSIZE``
+
+ - Full Size MPEG Video Display
+
+ - ..
+
+ - ``OSD_CURSOR``
+
+ - Cursor
+
+Description
+~~~~~~~~~~~
+
+The ``osd_raw_window_t`` data type is used with the `OSD_Command`_
+OSD_OpenRaw to tell the driver which type of OSD to open.
+
+
+-----
+
+
+osd_cap_t
+---------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+ typedef struct osd_cap_s {
+ int cmd;
+ #define OSD_CAP_MEMSIZE 1
+ long val;
+ } osd_cap_t;
+
+Variables
+~~~~~~~~~
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ - ..
+
+ - ``int cmd``
+
+ - Capability to query.
+
+ - ..
+
+ - ``long val``
+
+ - Used to store the Data.
+
+Supported capabilities
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ - ..
+
+ - ``OSD_CAP_MEMSIZE``
+
+ - Memory size installed on the card.
+
+Description
+~~~~~~~~~~~
+
+This structure of data used with the `OSD_GET_CAPABILITY`_ call.
+
+
+-----
+
+
+OSD Function Calls
+==================
+
+OSD_SEND_CMD
+------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: OSD_SEND_CMD
+
+.. code-block:: c
+
+ int ioctl(int fd, int request = OSD_SEND_CMD, enum osd_cmd_t *cmd)
+
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ - ..
+
+ - ``int fd``
+
+ - :cspan:`1` File descriptor returned by a previous call
+ to `open()`_.
+
+ - ..
+
+ - ``int request``
+
+ - Pointer to the location of the structure `osd_cmd_t`_ for this
+ command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+ See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl sends the `OSD_Command`_ to the card.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ - ..
+
+ - ``EINVAL``
+
+ - Command is out of range.
+
+
+-----
+
+
+OSD_GET_CAPABILITY
+------------------
+
+Synopsis
+~~~~~~~~
+
+.. c:macro:: OSD_GET_CAPABILITY
+
+.. code-block:: c
+
+ int ioctl(int fd, int request = OSD_GET_CAPABILITY,
+ struct osd_cap_t *cap)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ - ..
+
+ - ``int fd``
+
+ - :cspan:`1` File descriptor returned by a previous call
+ to `open()`_.
+
+ - ..
+
+ - ``int request``
+
+ - Equals ``OSD_GET_CAPABILITY`` for this command.
+
+ - ..
+
+ - ``unsigned int *cap``
+
+ - Pointer to the location of the structure `osd_cap_t`_ for this
+ command.
+
+Description
+~~~~~~~~~~~
+
+.. attention:: Do **not** use in new drivers!
+ See: :ref:`legacy_dvb_decoder_notes`
+
+This ioctl is used to get the capabilities of the OSD of the AV7110 based
+DVB-decoder-card in use.
+
+.. note::
+ The structure osd_cap_t has to be setup by the user and passed to the
+ driver.
+
+Return Value
+~~~~~~~~~~~~
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - ..
+
+ - ``EINVAL``
+
+ - Unsupported capability.
+
+
+-----
+
+
+open()
+------
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: c
+
+ #include <fcntl.h>
+
+.. c:function:: int open(const char *deviceName, int flags)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ - ..
+
+ - ``const char *deviceName``
+
+ - Name of specific OSD device.
+
+ - ..
+
+ - :rspan:`3` ``int flags``
+
+ - :cspan:`1` A bit-wise OR of the following flags:
+
+ - ..
+
+ - ``O_RDONLY``
+
+ - read-only access
+
+ - ..
+
+ - ``O_RDWR``
+
+ - read/write access
+
+ - ..
+
+ - ``O_NONBLOCK``
+ - | Open in non-blocking mode
+ | (blocking mode is the default)
+
+Description
+~~~~~~~~~~~
+
+This system call opens a named OSD device (e.g.
+``/dev/dvb/adapter?/osd0``) for subsequent use.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ - ..
+
+ - ``ENODEV``
+
+ - Device driver not loaded/available.
+
+ - ..
+
+ - ``EINTERNAL``
+
+ - Internal error.
+
+ - ..
+
+ - ``EBUSY``
+
+ - Device or resource busy.
+
+ - ..
+
+ - ``EINVAL``
+
+ - Invalid argument.
+
+
+-----
+
+
+close()
+-------
+
+Synopsis
+~~~~~~~~
+
+.. c:function:: int close(int fd)
+
+Arguments
+~~~~~~~~~
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ - ..
+
+ - ``int fd``
+
+ - :cspan:`1` File descriptor returned by a previous call
+ to `open()`_ .
+
+Description
+~~~~~~~~~~~
+
+This system call closes a previously opened OSD device.
+
+Return Value
+~~~~~~~~~~~~
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ - ..
+
+ - ``EBADF``
+
+ - fd is not a valid open file descriptor.
Add new documentation file for osd.h Signed-off-by: Stefan Herdler <herdler@nurfuerspam.de> --- Everything is used by the AV7110 driver, except 3 OSD_Commands. Remarks has been placed there. That's probably the best solution. Removing would create a gap in the enumeration. Omitting in the documentation would make header and documentation inconsistent again. .../media/dvb/legacy_dvb_osd.rst | 883 ++++++++++++++++++ 1 file changed, 883 insertions(+) create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst -- 2.34.0