tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0
2
3.. c:namespace:: dtv.legacy.osd
4
5.. _dvb_osd:
6
7==============
8DVB OSD Device
9==============
10
11.. attention:: Do **not** use in new drivers!
12 See: :ref:`legacy_dvb_decoder_notes`
13
14The DVB OSD device controls the OnScreen-Display of the AV7110 based
15DVB-cards with hardware MPEG2 decoder. It can be accessed through
16``/dev/dvb/adapter?/osd0``.
17Data types and ioctl definitions can be accessed by including
18``linux/dvb/osd.h`` in your application.
19
20The OSD is not a frame-buffer like on many other cards.
21It is a kind of canvas one can draw on.
22The color-depth is limited depending on the memory size installed.
23An appropriate palette of colors has to be set up.
24The installed memory size can be identified with the `OSD_GET_CAPABILITY`_
25ioctl.
26
27OSD Data Types
28==============
29
30OSD_Command
31-----------
32
33Synopsis
34~~~~~~~~
35
36.. code-block:: c
37
38 typedef enum {
39 /* All functions return -2 on "not open" */
40 OSD_Close = 1,
41 OSD_Open,
42 OSD_Show,
43 OSD_Hide,
44 OSD_Clear,
45 OSD_Fill,
46 OSD_SetColor,
47 OSD_SetPalette,
48 OSD_SetTrans,
49 OSD_SetPixel,
50 OSD_GetPixel,
51 OSD_SetRow,
52 OSD_SetBlock,
53 OSD_FillRow,
54 OSD_FillBlock,
55 OSD_Line,
56 OSD_Query,
57 OSD_Test,
58 OSD_Text,
59 OSD_SetWindow,
60 OSD_MoveWindow,
61 OSD_OpenRaw,
62 } OSD_Command;
63
64Commands
65~~~~~~~~
66
67.. note:: All functions return -2 on "not open"
68
69.. flat-table::
70 :header-rows: 1
71 :stub-columns: 0
72
73 - ..
74
75 - Command
76
77 - | Used variables of ``struct`` `osd_cmd_t`_.
78 | Usage{variable} if alternative use.
79
80 - :cspan:`2` Description
81
82
83
84 - ..
85
86 - ``OSD_Close``
87
88 - -
89
90 - | Disables OSD and releases the buffers.
91 | Returns 0 on success.
92
93 - ..
94
95 - ``OSD_Open``
96
97 - | x0,y0,x1,y1,
98 | BitPerPixel[2/4/8]{color&0x0F},
99 | mix[0..15]{color&0xF0}
100
101 - | Opens OSD with this size and bit depth
102 | Returns 0 on success,
103 | -1 on DRAM allocation error,
104 | -2 on "already open".
105
106 - ..
107
108 - ``OSD_Show``
109
110 - -
111
112 - | Enables OSD mode.
113 | Returns 0 on success.
114
115 - ..
116
117 - ``OSD_Hide``
118
119 - -
120
121 - | Disables OSD mode.
122 | Returns 0 on success.
123
124 - ..
125
126 - ``OSD_Clear``
127
128 - -
129
130 - | Sets all pixel to color 0.
131 | Returns 0 on success.
132
133 - ..
134
135 - ``OSD_Fill``
136
137 - color
138
139 - | Sets all pixel to color <color>.
140 | Returns 0 on success.
141
142 - ..
143
144 - ``OSD_SetColor``
145
146 - | color,
147 | R{x0},G{y0},B{x1},
148 | opacity{y1}
149
150 - | Set palette entry <num> to <r,g,b>, <mix> and <trans> apply
151 | R,G,B: 0..255
152 | R=Red, G=Green, B=Blue
153 | opacity=0: pixel opacity 0% (only video pixel shows)
154 | opacity=1..254: pixel opacity as specified in header
155 | opacity=255: pixel opacity 100% (only OSD pixel shows)
156 | Returns 0 on success, -1 on error.
157
158 - ..
159
160 - ``OSD_SetPalette``
161
162 - | firstcolor{color},
163 | lastcolor{x0},data
164
165 - | Set a number of entries in the palette.
166 | Sets the entries "firstcolor" through "lastcolor" from the
167 array "data".
168 | Data has 4 byte for each color:
169 | R,G,B, and a opacity value: 0->transparent, 1..254->mix,
170 255->pixel
171
172 - ..
173
174 - ``OSD_SetTrans``
175
176 - transparency{color}
177
178 - | Sets transparency of mixed pixel (0..15).
179 | Returns 0 on success.
180
181 - ..
182
183 - ``OSD_SetPixel``
184
185 - x0,y0,color
186
187 - | Sets pixel <x>,<y> to color number <color>.
188 | Returns 0 on success, -1 on error.
189
190 - ..
191
192 - ``OSD_GetPixel``
193
194 - x0,y0
195
196 - | Returns color number of pixel <x>,<y>, or -1.
197 | Command currently not supported by the AV7110!
198
199 - ..
200
201 - ``OSD_SetRow``
202
203 - x0,y0,x1,data
204
205 - | Fills pixels x0,y through x1,y with the content of data[].
206 | Returns 0 on success, -1 on clipping all pixel (no pixel
207 drawn).
208
209 - ..
210
211 - ``OSD_SetBlock``
212
213 - | x0,y0,x1,y1,
214 | increment{color},
215 | data
216
217 - | Fills pixels x0,y0 through x1,y1 with the content of data[].
218 | Inc contains the width of one line in the data block,
219 | inc<=0 uses block width as line width.
220 | Returns 0 on success, -1 on clipping all pixel.
221
222 - ..
223
224 - ``OSD_FillRow``
225
226 - x0,y0,x1,color
227
228 - | Fills pixels x0,y through x1,y with the color <color>.
229 | Returns 0 on success, -1 on clipping all pixel.
230
231 - ..
232
233 - ``OSD_FillBlock``
234
235 - x0,y0,x1,y1,color
236
237 - | Fills pixels x0,y0 through x1,y1 with the color <color>.
238 | Returns 0 on success, -1 on clipping all pixel.
239
240 - ..
241
242 - ``OSD_Line``
243
244 - x0,y0,x1,y1,color
245
246 - | Draw a line from x0,y0 to x1,y1 with the color <color>.
247 | Returns 0 on success.
248
249 - ..
250
251 - ``OSD_Query``
252
253 - | x0,y0,x1,y1,
254 | xasp{color}; yasp=11
255
256 - | Fills parameters with the picture dimensions and the pixel
257 aspect ratio.
258 | Returns 0 on success.
259 | Command currently not supported by the AV7110!
260
261 - ..
262
263 - ``OSD_Test``
264
265 - -
266
267 - | Draws a test picture.
268 | For debugging purposes only.
269 | Returns 0 on success.
270 - ..
271
272 - ``OSD_Text``
273
274 - x0,y0,size,color,text
275
276 - Draws a text at position x0,y0 with the color <color>.
277
278 - ..
279
280 - ``OSD_SetWindow``
281
282 - x0
283
284 - Set window with number 0<x0<8 as current.
285
286 - ..
287
288 - ``OSD_MoveWindow``
289
290 - x0,y0
291
292 - Move current window to (x0, y0).
293
294 - ..
295
296 - ``OSD_OpenRaw``
297
298 - | x0,y0,x1,y1,
299 | `osd_raw_window_t`_ {color}
300
301 - Open other types of OSD windows.
302
303Description
304~~~~~~~~~~~
305
306The ``OSD_Command`` data type is used with the `OSD_SEND_CMD`_ ioctl to
307tell the driver which OSD_Command to execute.
308
309
310-----
311
312osd_cmd_t
313---------
314
315Synopsis
316~~~~~~~~
317
318.. code-block:: c
319
320 typedef struct osd_cmd_s {
321 OSD_Command cmd;
322 int x0;
323 int y0;
324 int x1;
325 int y1;
326 int color;
327 void __user *data;
328 } osd_cmd_t;
329
330Variables
331~~~~~~~~~
332
333.. flat-table::
334 :header-rows: 0
335 :stub-columns: 0
336
337 - ..
338
339 - ``OSD_Command cmd``
340
341 - `OSD_Command`_ to be executed.
342
343 - ..
344
345 - ``int x0``
346
347 - First horizontal position.
348
349 - ..
350
351 - ``int y0``
352
353 - First vertical position.
354
355 - ..
356
357 - ``int x1``
358
359 - Second horizontal position.
360
361 - ..
362
363 - ``int y1``
364
365 - Second vertical position.
366
367 - ..
368
369 - ``int color``
370
371 - Number of the color in the palette.
372
373 - ..
374
375 - ``void __user *data``
376
377 - Command specific Data.
378
379Description
380~~~~~~~~~~~
381
382The ``osd_cmd_t`` data type is used with the `OSD_SEND_CMD`_ ioctl.
383It contains the data for the OSD_Command and the `OSD_Command`_ itself.
384The structure has to be passed to the driver and the components may be
385modified by it.
386
387
388-----
389
390
391osd_raw_window_t
392----------------
393
394Synopsis
395~~~~~~~~
396
397.. code-block:: c
398
399 typedef enum {
400 OSD_BITMAP1,
401 OSD_BITMAP2,
402 OSD_BITMAP4,
403 OSD_BITMAP8,
404 OSD_BITMAP1HR,
405 OSD_BITMAP2HR,
406 OSD_BITMAP4HR,
407 OSD_BITMAP8HR,
408 OSD_YCRCB422,
409 OSD_YCRCB444,
410 OSD_YCRCB444HR,
411 OSD_VIDEOTSIZE,
412 OSD_VIDEOHSIZE,
413 OSD_VIDEOQSIZE,
414 OSD_VIDEODSIZE,
415 OSD_VIDEOTHSIZE,
416 OSD_VIDEOTQSIZE,
417 OSD_VIDEOTDSIZE,
418 OSD_VIDEONSIZE,
419 OSD_CURSOR
420 } osd_raw_window_t;
421
422Constants
423~~~~~~~~~
424
425.. flat-table::
426 :header-rows: 0
427 :stub-columns: 0
428
429 - ..
430
431 - ``OSD_BITMAP1``
432
433 - :cspan:`1` 1 bit bitmap
434
435 - ..
436
437 - ``OSD_BITMAP2``
438
439 - 2 bit bitmap
440
441 - ..
442
443 - ``OSD_BITMAP4``
444
445 - 4 bit bitmap
446
447 - ..
448
449 - ``OSD_BITMAP8``
450
451 - 8 bit bitmap
452
453 - ..
454
455 - ``OSD_BITMAP1HR``
456
457 - 1 Bit bitmap half resolution
458
459 - ..
460
461 - ``OSD_BITMAP2HR``
462
463 - 2 Bit bitmap half resolution
464
465 - ..
466
467 - ``OSD_BITMAP4HR``
468
469 - 4 Bit bitmap half resolution
470
471 - ..
472
473 - ``OSD_BITMAP8HR``
474
475 - 8 Bit bitmap half resolution
476
477 - ..
478
479 - ``OSD_YCRCB422``
480
481 - 4:2:2 YCRCB Graphic Display
482
483 - ..
484
485 - ``OSD_YCRCB444``
486
487 - 4:4:4 YCRCB Graphic Display
488
489 - ..
490
491 - ``OSD_YCRCB444HR``
492
493 - 4:4:4 YCRCB graphic half resolution
494
495 - ..
496
497 - ``OSD_VIDEOTSIZE``
498
499 - True Size Normal MPEG Video Display
500
501 - ..
502
503 - ``OSD_VIDEOHSIZE``
504
505 - MPEG Video Display Half Resolution
506
507 - ..
508
509 - ``OSD_VIDEOQSIZE``
510
511 - MPEG Video Display Quarter Resolution
512
513 - ..
514
515 - ``OSD_VIDEODSIZE``
516
517 - MPEG Video Display Double Resolution
518
519 - ..
520
521 - ``OSD_VIDEOTHSIZE``
522
523 - True Size MPEG Video Display Half Resolution
524
525 - ..
526
527 - ``OSD_VIDEOTQSIZE``
528
529 - True Size MPEG Video Display Quarter Resolution
530
531 - ..
532
533 - ``OSD_VIDEOTDSIZE``
534
535 - True Size MPEG Video Display Double Resolution
536
537 - ..
538
539 - ``OSD_VIDEONSIZE``
540
541 - Full Size MPEG Video Display
542
543 - ..
544
545 - ``OSD_CURSOR``
546
547 - Cursor
548
549Description
550~~~~~~~~~~~
551
552The ``osd_raw_window_t`` data type is used with the `OSD_Command`_
553OSD_OpenRaw to tell the driver which type of OSD to open.
554
555
556-----
557
558
559osd_cap_t
560---------
561
562Synopsis
563~~~~~~~~
564
565.. code-block:: c
566
567 typedef struct osd_cap_s {
568 int cmd;
569 #define OSD_CAP_MEMSIZE 1
570 long val;
571 } osd_cap_t;
572
573Variables
574~~~~~~~~~
575
576.. flat-table::
577 :header-rows: 0
578 :stub-columns: 0
579
580 - ..
581
582 - ``int cmd``
583
584 - Capability to query.
585
586 - ..
587
588 - ``long val``
589
590 - Used to store the Data.
591
592Supported capabilities
593~~~~~~~~~~~~~~~~~~~~~~
594
595.. flat-table::
596 :header-rows: 0
597 :stub-columns: 0
598
599 - ..
600
601 - ``OSD_CAP_MEMSIZE``
602
603 - Memory size installed on the card.
604
605Description
606~~~~~~~~~~~
607
608This structure of data used with the `OSD_GET_CAPABILITY`_ call.
609
610
611-----
612
613
614OSD Function Calls
615==================
616
617OSD_SEND_CMD
618------------
619
620Synopsis
621~~~~~~~~
622
623.. c:macro:: OSD_SEND_CMD
624
625.. code-block:: c
626
627 int ioctl(int fd, int request = OSD_SEND_CMD, enum osd_cmd_t *cmd)
628
629
630Arguments
631~~~~~~~~~
632
633.. flat-table::
634 :header-rows: 0
635 :stub-columns: 0
636
637 - ..
638
639 - ``int fd``
640
641 - :cspan:`1` File descriptor returned by a previous call
642 to `open()`_.
643
644 - ..
645
646 - ``int request``
647
648 - Pointer to the location of the structure `osd_cmd_t`_ for this
649 command.
650
651Description
652~~~~~~~~~~~
653
654.. attention:: Do **not** use in new drivers!
655 See: :ref:`legacy_dvb_decoder_notes`
656
657This ioctl sends the `OSD_Command`_ to the card.
658
659Return Value
660~~~~~~~~~~~~
661
662On success 0 is returned, on error -1 and the ``errno`` variable is set
663appropriately. The generic error codes are described at the
664:ref:`Generic Error Codes <gen-errors>` chapter.
665
666.. flat-table::
667 :header-rows: 0
668 :stub-columns: 0
669
670 - ..
671
672 - ``EINVAL``
673
674 - Command is out of range.
675
676
677-----
678
679
680OSD_GET_CAPABILITY
681------------------
682
683Synopsis
684~~~~~~~~
685
686.. c:macro:: OSD_GET_CAPABILITY
687
688.. code-block:: c
689
690 int ioctl(int fd, int request = OSD_GET_CAPABILITY,
691 struct osd_cap_t *cap)
692
693Arguments
694~~~~~~~~~
695
696.. flat-table::
697 :header-rows: 0
698 :stub-columns: 0
699
700 - ..
701
702 - ``int fd``
703
704 - :cspan:`1` File descriptor returned by a previous call
705 to `open()`_.
706
707 - ..
708
709 - ``int request``
710
711 - Equals ``OSD_GET_CAPABILITY`` for this command.
712
713 - ..
714
715 - ``unsigned int *cap``
716
717 - Pointer to the location of the structure `osd_cap_t`_ for this
718 command.
719
720Description
721~~~~~~~~~~~
722
723.. attention:: Do **not** use in new drivers!
724 See: :ref:`legacy_dvb_decoder_notes`
725
726This ioctl is used to get the capabilities of the OSD of the AV7110 based
727DVB-decoder-card in use.
728
729.. note::
730 The structure osd_cap_t has to be setup by the user and passed to the
731 driver.
732
733Return Value
734~~~~~~~~~~~~
735
736On success 0 is returned, on error -1 and the ``errno`` variable is set
737appropriately. The generic error codes are described at the
738:ref:`Generic Error Codes <gen-errors>` chapter.
739
740.. flat-table::
741 :header-rows: 0
742 :stub-columns: 0
743
744
745 - ..
746
747 - ``EINVAL``
748
749 - Unsupported capability.
750
751
752-----
753
754
755open()
756------
757
758Synopsis
759~~~~~~~~
760
761.. code-block:: c
762
763 #include <fcntl.h>
764
765.. c:function:: int open(const char *deviceName, int flags)
766
767Arguments
768~~~~~~~~~
769
770.. flat-table::
771 :header-rows: 0
772 :stub-columns: 0
773
774 - ..
775
776 - ``const char *deviceName``
777
778 - Name of specific OSD device.
779
780 - ..
781
782 - :rspan:`3` ``int flags``
783
784 - :cspan:`1` A bit-wise OR of the following flags:
785
786 - ..
787
788 - ``O_RDONLY``
789
790 - read-only access
791
792 - ..
793
794 - ``O_RDWR``
795
796 - read/write access
797
798 - ..
799
800 - ``O_NONBLOCK``
801 - | Open in non-blocking mode
802 | (blocking mode is the default)
803
804Description
805~~~~~~~~~~~
806
807This system call opens a named OSD device (e.g.
808``/dev/dvb/adapter?/osd0``) for subsequent use.
809
810Return Value
811~~~~~~~~~~~~
812
813.. flat-table::
814 :header-rows: 0
815 :stub-columns: 0
816
817 - ..
818
819 - ``ENODEV``
820
821 - Device driver not loaded/available.
822
823 - ..
824
825 - ``EINTERNAL``
826
827 - Internal error.
828
829 - ..
830
831 - ``EBUSY``
832
833 - Device or resource busy.
834
835 - ..
836
837 - ``EINVAL``
838
839 - Invalid argument.
840
841
842-----
843
844
845close()
846-------
847
848Synopsis
849~~~~~~~~
850
851.. c:function:: int close(int fd)
852
853Arguments
854~~~~~~~~~
855
856.. flat-table::
857 :header-rows: 0
858 :stub-columns: 0
859
860 - ..
861
862 - ``int fd``
863
864 - :cspan:`1` File descriptor returned by a previous call
865 to `open()`_ .
866
867Description
868~~~~~~~~~~~
869
870This system call closes a previously opened OSD device.
871
872Return Value
873~~~~~~~~~~~~
874
875.. flat-table::
876 :header-rows: 0
877 :stub-columns: 0
878
879 - ..
880
881 - ``EBADF``
882
883 - fd is not a valid open file descriptor.