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 ==============
8 DVB OSD Device
9 ==============
10
11 .. attention:: Do **not** use in new drivers!
12 See: :ref:`legacy_dvb_decoder_notes`
13
14 The DVB OSD device controls the OnScreen-Display of the AV7110 based
15 DVB-cards with hardware MPEG2 decoder. It can be accessed through
16 ``/dev/dvb/adapter?/osd0``.
17 Data types and ioctl definitions can be accessed by including
18 ``linux/dvb/osd.h`` in your application.
19
20 The OSD is not a frame-buffer like on many other cards.
21 It is a kind of canvas one can draw on.
22 The color-depth is limited depending on the memory size installed.
23 An appropriate palette of colors has to be set up.
24 The installed memory size can be identified with the `OSD_GET_CAPABILITY`_
25 ioctl.
26
27 OSD Data Types
28 ==============
29
30 OSD_Command
31 -----------
32
33 Synopsis
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
64 Commands
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
303 Description
304 ~~~~~~~~~~~
305
306 The ``OSD_Command`` data type is used with the `OSD_SEND_CMD`_ ioctl to
307 tell the driver which OSD_Command to execute.
308
309
310 -----
311
312 osd_cmd_t
313 ---------
314
315 Synopsis
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
330 Variables
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
379 Description
380 ~~~~~~~~~~~
381
382 The ``osd_cmd_t`` data type is used with the `OSD_SEND_CMD`_ ioctl.
383 It contains the data for the OSD_Command and the `OSD_Command`_ itself.
384 The structure has to be passed to the driver and the components may be
385 modified by it.
386
387
388 -----
389
390
391 osd_raw_window_t
392 ----------------
393
394 Synopsis
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
422 Constants
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
549 Description
550 ~~~~~~~~~~~
551
552 The ``osd_raw_window_t`` data type is used with the `OSD_Command`_
553 OSD_OpenRaw to tell the driver which type of OSD to open.
554
555
556 -----
557
558
559 osd_cap_t
560 ---------
561
562 Synopsis
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
573 Variables
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
592 Supported 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
605 Description
606 ~~~~~~~~~~~
607
608 This structure of data used with the `OSD_GET_CAPABILITY`_ call.
609
610
611 -----
612
613
614 OSD Function Calls
615 ==================
616
617 OSD_SEND_CMD
618 ------------
619
620 Synopsis
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
630 Arguments
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
651 Description
652 ~~~~~~~~~~~
653
654 .. attention:: Do **not** use in new drivers!
655 See: :ref:`legacy_dvb_decoder_notes`
656
657 This ioctl sends the `OSD_Command`_ to the card.
658
659 Return Value
660 ~~~~~~~~~~~~
661
662 On success 0 is returned, on error -1 and the ``errno`` variable is set
663 appropriately. 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
680 OSD_GET_CAPABILITY
681 ------------------
682
683 Synopsis
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
693 Arguments
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
720 Description
721 ~~~~~~~~~~~
722
723 .. attention:: Do **not** use in new drivers!
724 See: :ref:`legacy_dvb_decoder_notes`
725
726 This ioctl is used to get the capabilities of the OSD of the AV7110 based
727 DVB-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
733 Return Value
734 ~~~~~~~~~~~~
735
736 On success 0 is returned, on error -1 and the ``errno`` variable is set
737 appropriately. 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
755 open()
756 ------
757
758 Synopsis
759 ~~~~~~~~
760
761 .. code-block:: c
762
763 #include <fcntl.h>
764
765 .. c:function:: int open(const char *deviceName, int flags)
766
767 Arguments
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
804 Description
805 ~~~~~~~~~~~
806
807 This system call opens a named OSD device (e.g.
808 ``/dev/dvb/adapter?/osd0``) for subsequent use.
809
810 Return 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
845 close()
846 -------
847
848 Synopsis
849 ~~~~~~~~
850
851 .. c:function:: int close(int fd)
852
853 Arguments
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
867 Description
868 ~~~~~~~~~~~
869
870 This system call closes a previously opened OSD device.
871
872 Return 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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.