FILE
legacy_dvb_audio.rst
File preview with syntax highlighting.
linux-6.19.14/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 2 3.. c:namespace:: dtv.legacy.audio 4 5.. _dvb_audio: 6 7================ 8DVB Audio Device 9================ 10 11.. attention:: Do **not** use in new drivers! 12 See: :ref:`legacy_dvb_decoder_notes` 13 14The DVB audio device controls the MPEG2 audio decoder of the DVB 15hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data 16types and ioctl definitions can be accessed by including 17``linux/dvb/audio.h`` in your application. 18 19Please note that most DVB cards don’t have their own MPEG decoder, which 20results in the omission of the audio and video device. 21 22These ioctls were also used by V4L2 to control MPEG decoders implemented 23in V4L2. The use of these ioctls for that purpose has been made obsolete 24and proper V4L2 ioctls or controls have been created to replace that 25functionality. Use :ref:`V4L2 ioctls<audio>` for new drivers! 26 27 28Audio Data Types 29================ 30 31This section describes the structures, data types and defines used when 32talking to the audio device. 33 34 35----- 36 37 38audio_stream_source_t 39--------------------- 40 41Synopsis 42~~~~~~~~ 43 44.. c:enum:: audio_stream_source_t 45 46.. code-block:: c 47 48 typedef enum { 49 AUDIO_SOURCE_DEMUX, 50 AUDIO_SOURCE_MEMORY 51 } audio_stream_source_t; 52 53Constants 54~~~~~~~~~ 55 56.. flat-table:: 57 :header-rows: 0 58 :stub-columns: 0 59 60 - .. 61 62 - ``AUDIO_SOURCE_DEMUX`` 63 64 - :cspan:`1` Selects the demultiplexer (fed either by the frontend 65 or the DVR device) as the source of the video stream. 66 67 - .. 68 69 - ``AUDIO_SOURCE_MEMORY`` 70 71 - Selects the stream from the application that comes through 72 the `write()`_ system call. 73 74Description 75~~~~~~~~~~~ 76 77The audio stream source is set through the `AUDIO_SELECT_SOURCE`_ call 78and can take the following values, depending on whether we are replaying 79from an internal (demux) or external (user write) source. 80 81The data fed to the decoder is also controlled by the PID-filter. 82Output selection: :c:type:`dmx_output` ``DMX_OUT_DECODER``. 83 84 85----- 86 87 88audio_play_state_t 89------------------ 90 91Synopsis 92~~~~~~~~ 93 94.. c:enum:: audio_play_state_t 95 96.. code-block:: c 97 98 typedef enum { 99 AUDIO_STOPPED, 100 AUDIO_PLAYING, 101 AUDIO_PAUSED 102 } audio_play_state_t; 103 104Constants 105~~~~~~~~~ 106 107.. flat-table:: 108 :header-rows: 0 109 :stub-columns: 0 110 111 - .. 112 113 - ``AUDIO_STOPPED`` 114 115 - Audio is stopped. 116 117 - .. 118 119 - ``AUDIO_PLAYING`` 120 121 - Audio is currently playing. 122 123 - .. 124 125 - ``AUDIO_PAUSE`` 126 127 - Audio is frozen. 128 129Description 130~~~~~~~~~~~ 131 132This values can be returned by the `AUDIO_GET_STATUS`_ call 133representing the state of audio playback. 134 135 136----- 137 138 139audio_channel_select_t 140---------------------- 141 142Synopsis 143~~~~~~~~ 144 145.. c:enum:: audio_channel_select_t 146 147.. code-block:: c 148 149 typedef enum { 150 AUDIO_STEREO, 151 AUDIO_MONO_LEFT, 152 AUDIO_MONO_RIGHT, 153 AUDIO_MONO, 154 AUDIO_STEREO_SWAPPED 155 } audio_channel_select_t; 156 157Constants 158~~~~~~~~~ 159 160.. flat-table:: 161 :header-rows: 0 162 :stub-columns: 0 163 164 - .. 165 166 - ``AUDIO_STEREO`` 167 168 - Stereo. 169 170 - .. 171 172 - ``AUDIO_MONO_LEFT`` 173 174 - Mono, select left stereo channel as source. 175 176 - .. 177 178 - ``AUDIO_MONO_RIGHT`` 179 180 - Mono, select right stereo channel as source. 181 182 - .. 183 184 - ``AUDIO_MONO`` 185 186 - Mono source only. 187 188 - .. 189 190 - ``AUDIO_STEREO_SWAPPED`` 191 192 - Stereo, swap L & R. 193 194Description 195~~~~~~~~~~~ 196 197The audio channel selected via `AUDIO_CHANNEL_SELECT`_ is determined by 198this value. 199 200 201----- 202 203 204audio_mixer_t 205------------- 206 207Synopsis 208~~~~~~~~ 209 210.. c:struct:: audio_mixer 211 212.. code-block:: c 213 214 typedef struct audio_mixer { 215 unsigned int volume_left; 216 unsigned int volume_right; 217 } audio_mixer_t; 218 219Variables 220~~~~~~~~~ 221 222.. flat-table:: 223 :header-rows: 0 224 :stub-columns: 0 225 226 - .. 227 228 - ``unsigned int volume_left`` 229 230 - Volume left channel. 231 Valid range: 0 ... 255 232 233 - .. 234 235 - ``unsigned int volume_right`` 236 237 - Volume right channel. 238 Valid range: 0 ... 255 239 240Description 241~~~~~~~~~~~ 242 243This structure is used by the `AUDIO_SET_MIXER`_ call to set the 244audio volume. 245 246 247----- 248 249 250audio_status 251------------ 252 253Synopsis 254~~~~~~~~ 255 256.. c:struct:: audio_status 257 258.. code-block:: c 259 260 typedef struct audio_status { 261 int AV_sync_state; 262 int mute_state; 263 audio_play_state_t play_state; 264 audio_stream_source_t stream_source; 265 audio_channel_select_t channel_select; 266 int bypass_mode; 267 audio_mixer_t mixer_state; 268 } audio_status_t; 269 270Variables 271~~~~~~~~~ 272 273.. flat-table:: 274 :header-rows: 0 275 :stub-columns: 0 276 277 - .. 278 279 - :rspan:`2` ``int AV_sync_state`` 280 281 - :cspan:`1` Shows if A/V synchronization is ON or OFF. 282 283 - .. 284 285 - TRUE ( != 0 ) 286 287 - AV-sync ON. 288 289 - .. 290 291 - FALSE ( == 0 ) 292 293 - AV-sync OFF. 294 295 - .. 296 297 - :rspan:`2` ``int mute_state`` 298 299 - :cspan:`1` Indicates if audio is muted or not. 300 301 - .. 302 303 - TRUE ( != 0 ) 304 305 - mute audio 306 307 - .. 308 309 - FALSE ( == 0 ) 310 311 - unmute audio 312 313 - .. 314 315 - `audio_play_state_t`_ ``play_state`` 316 317 - Current playback state. 318 319 - .. 320 321 - `audio_stream_source_t`_ ``stream_source`` 322 323 - Current source of the data. 324 325 - .. 326 327 - :rspan:`2` ``int bypass_mode`` 328 329 - :cspan:`1` Is the decoding of the current Audio stream in 330 the DVB subsystem enabled or disabled. 331 332 - .. 333 334 - TRUE ( != 0 ) 335 336 - Bypass disabled. 337 338 - .. 339 340 - FALSE ( == 0 ) 341 342 - Bypass enabled. 343 344 - .. 345 346 - `audio_mixer_t`_ ``mixer_state`` 347 348 - Current volume settings. 349 350Description 351~~~~~~~~~~~ 352 353The `AUDIO_GET_STATUS`_ call returns this structure as information 354about various states of the playback operation. 355 356 357----- 358 359 360audio encodings 361--------------- 362 363Synopsis 364~~~~~~~~ 365 366.. code-block:: c 367 368 #define AUDIO_CAP_DTS 1 369 #define AUDIO_CAP_LPCM 2 370 #define AUDIO_CAP_MP1 4 371 #define AUDIO_CAP_MP2 8 372 #define AUDIO_CAP_MP3 16 373 #define AUDIO_CAP_AAC 32 374 #define AUDIO_CAP_OGG 64 375 #define AUDIO_CAP_SDDS 128 376 #define AUDIO_CAP_AC3 256 377 378Constants 379~~~~~~~~~ 380 381.. flat-table:: 382 :header-rows: 0 383 :stub-columns: 0 384 385 - .. 386 387 - ``AUDIO_CAP_DTS`` 388 389 - :cspan:`1` The hardware accepts DTS audio tracks. 390 391 - .. 392 393 - ``AUDIO_CAP_LPCM`` 394 395 - The hardware accepts uncompressed audio with 396 Linear Pulse-Code Modulation (LPCM) 397 398 - .. 399 400 - ``AUDIO_CAP_MP1`` 401 402 - The hardware accepts MPEG-1 Audio Layer 1. 403 404 - .. 405 406 - ``AUDIO_CAP_MP2`` 407 408 - The hardware accepts MPEG-1 Audio Layer 2. 409 Also known as MUSICAM. 410 411 - .. 412 413 - ``AUDIO_CAP_MP3`` 414 415 - The hardware accepts MPEG-1 Audio Layer III. 416 Commonly known as .mp3. 417 418 - .. 419 420 - ``AUDIO_CAP_AAC`` 421 422 - The hardware accepts AAC (Advanced Audio Coding). 423 424 - .. 425 426 - ``AUDIO_CAP_OGG`` 427 428 - The hardware accepts Vorbis audio tracks. 429 430 - .. 431 432 - ``AUDIO_CAP_SDDS`` 433 434 - The hardware accepts Sony Dynamic Digital Sound (SDDS). 435 436 - .. 437 438 - ``AUDIO_CAP_AC3`` 439 440 - The hardware accepts Dolby Digital ATSC A/52 audio. 441 Also known as AC-3. 442 443Description 444~~~~~~~~~~~ 445 446A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the 447following bits set according to the hardwares capabilities. 448 449 450----- 451 452 453Audio Function Calls 454==================== 455 456 457AUDIO_STOP 458---------- 459 460Synopsis 461~~~~~~~~ 462 463.. c:macro:: AUDIO_STOP 464 465.. code-block:: c 466 467 int ioctl(int fd, int request = AUDIO_STOP) 468 469Arguments 470~~~~~~~~~ 471 472.. flat-table:: 473 :header-rows: 0 474 :stub-columns: 0 475 476 - .. 477 478 - ``int fd`` 479 480 - File descriptor returned by a previous call to `open()`_. 481 482 - .. 483 484 - ``int request`` 485 486 - :cspan:`1` Equals ``AUDIO_STOP`` for this command. 487 488Description 489~~~~~~~~~~~ 490 491.. attention:: Do **not** use in new drivers! 492 See: :ref:`legacy_dvb_decoder_notes` 493 494This ioctl call asks the Audio Device to stop playing the current 495stream. 496 497Return Value 498~~~~~~~~~~~~ 499 500On success 0 is returned, on error -1 and the ``errno`` variable is set 501appropriately. The generic error codes are described at the 502:ref:`Generic Error Codes <gen-errors>` chapter. 503 504 505----- 506 507 508AUDIO_PLAY 509---------- 510 511Synopsis 512~~~~~~~~ 513 514.. c:macro:: AUDIO_PLAY 515 516.. code-block:: c 517 518 int ioctl(int fd, int request = AUDIO_PLAY) 519 520Arguments 521~~~~~~~~~ 522 523.. flat-table:: 524 :header-rows: 0 525 :stub-columns: 0 526 527 - .. 528 529 - ``int fd`` 530 531 - File descriptor returned by a previous call to `open()`_. 532 533 - .. 534 535 - ``int request`` 536 537 - :cspan:`1` Equals ``AUDIO_PLAY`` for this command. 538 539Description 540~~~~~~~~~~~ 541 542.. attention:: Do **not** use in new drivers! 543 See: :ref:`legacy_dvb_decoder_notes` 544 545This ioctl call asks the Audio Device to start playing an audio stream 546from the selected source. 547 548Return Value 549~~~~~~~~~~~~ 550 551On success 0 is returned, on error -1 and the ``errno`` variable is set 552appropriately. The generic error codes are described at the 553:ref:`Generic Error Codes <gen-errors>` chapter. 554 555 556----- 557 558 559AUDIO_PAUSE 560----------- 561 562Synopsis 563~~~~~~~~ 564 565.. c:macro:: AUDIO_PAUSE 566 567.. code-block:: c 568 569 int ioctl(int fd, int request = AUDIO_PAUSE) 570 571Arguments 572~~~~~~~~~ 573 574.. flat-table:: 575 :header-rows: 0 576 :stub-columns: 0 577 578 - .. 579 580 - ``int fd`` 581 582 - :cspan:`1` File descriptor returned by a previous call 583 to `open()`_. 584 585 - .. 586 587 - ``int request`` 588 589 - Equals ``AUDIO_PAUSE`` for this command. 590 591Description 592~~~~~~~~~~~ 593 594.. attention:: Do **not** use in new drivers! 595 See: :ref:`legacy_dvb_decoder_notes` 596 597This ioctl call suspends the audio stream being played. Decoding and 598playing are paused. It is then possible to restart again decoding and 599playing process of the audio stream using `AUDIO_CONTINUE`_ command. 600 601Return Value 602~~~~~~~~~~~~ 603 604On success 0 is returned, on error -1 and the ``errno`` variable is set 605appropriately. The generic error codes are described at the 606:ref:`Generic Error Codes <gen-errors>` chapter. 607 608 609----- 610 611 612AUDIO_CONTINUE 613-------------- 614 615Synopsis 616~~~~~~~~ 617 618.. c:macro:: AUDIO_CONTINUE 619 620.. code-block:: c 621 622 int ioctl(int fd, int request = AUDIO_CONTINUE) 623 624Arguments 625~~~~~~~~~ 626 627.. flat-table:: 628 :header-rows: 0 629 :stub-columns: 0 630 631 - .. 632 633 - ``int fd`` 634 635 - :cspan:`1` File descriptor returned by a previous call 636 to `open()`_. 637 638 - .. 639 640 - ``int request`` 641 642 - Equals ``AUDIO_CONTINUE`` for this command. 643 644Description 645~~~~~~~~~~~ 646 647.. attention:: Do **not** use in new drivers! 648 See: :ref:`legacy_dvb_decoder_notes` 649 650This ioctl restarts the decoding and playing process previously paused 651with `AUDIO_PAUSE`_ command. 652 653Return Value 654~~~~~~~~~~~~ 655 656On success 0 is returned, on error -1 and the ``errno`` variable is set 657appropriately. The generic error codes are described at the 658:ref:`Generic Error Codes <gen-errors>` chapter. 659 660 661----- 662 663 664AUDIO_SELECT_SOURCE 665------------------- 666 667Synopsis 668~~~~~~~~ 669 670.. c:macro:: AUDIO_SELECT_SOURCE 671 672.. code-block:: c 673 674 int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, 675 audio_stream_source_t source) 676 677Arguments 678~~~~~~~~~ 679 680.. flat-table:: 681 :header-rows: 0 682 :stub-columns: 0 683 684 - .. 685 686 - ``int fd`` 687 688 - :cspan:`1` File descriptor returned by a previous call 689 to `open()`_. 690 691 - .. 692 693 - ``int request`` 694 695 - Equals ``AUDIO_SELECT_SOURCE`` for this command. 696 697 - .. 698 699 - `audio_stream_source_t`_ ``source`` 700 701 - Indicates the source that shall be used for the Audio stream. 702 703Description 704~~~~~~~~~~~ 705 706.. attention:: Do **not** use in new drivers! 707 See: :ref:`legacy_dvb_decoder_notes` 708 709This ioctl call informs the audio device which source shall be used for 710the input data. The possible sources are demux or memory. If 711``AUDIO_SOURCE_MEMORY`` is selected, the data is fed to the Audio Device 712through the write command. If ``AUDIO_SOURCE_DEMUX`` is selected, the data 713is directly transferred from the onboard demux-device to the decoder. 714Note: This only supports DVB-devices with one demux and one decoder so far. 715 716Return Value 717~~~~~~~~~~~~ 718 719On success 0 is returned, on error -1 and the ``errno`` variable is set 720appropriately. The generic error codes are described at the 721:ref:`Generic Error Codes <gen-errors>` chapter. 722 723 724----- 725 726 727AUDIO_SET_MUTE 728-------------- 729 730Synopsis 731~~~~~~~~ 732 733.. c:macro:: AUDIO_SET_MUTE 734 735.. code-block:: c 736 737 int ioctl(int fd, int request = AUDIO_SET_MUTE, int state) 738 739Arguments 740~~~~~~~~~ 741 742.. flat-table:: 743 :header-rows: 0 744 :stub-columns: 0 745 746 - .. 747 748 - ``int fd`` 749 750 - :cspan:`1` File descriptor returned by a previous call 751 to `open()`_. 752 753 - .. 754 755 - ``int request`` 756 757 - :cspan:`1` Equals ``AUDIO_SET_MUTE`` for this command. 758 759 - .. 760 761 - :rspan:`2` ``int state`` 762 763 - :cspan:`1` Indicates if audio device shall mute or not. 764 765 - .. 766 767 - TRUE ( != 0 ) 768 769 - mute audio 770 771 - .. 772 773 - FALSE ( == 0 ) 774 775 - unmute audio 776 777Description 778~~~~~~~~~~~ 779 780.. attention:: Do **not** use in new drivers! 781 See: :ref:`legacy_dvb_decoder_notes` 782 783This ioctl is for DVB devices only. To control a V4L2 decoder use the 784V4L2 :ref:`VIDIOC_DECODER_CMD` with the 785``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead. 786 787This ioctl call asks the audio device to mute the stream that is 788currently being played. 789 790Return Value 791~~~~~~~~~~~~ 792 793On success 0 is returned, on error -1 and the ``errno`` variable is set 794appropriately. The generic error codes are described at the 795:ref:`Generic Error Codes <gen-errors>` chapter. 796 797 798----- 799 800 801AUDIO_SET_AV_SYNC 802----------------- 803 804Synopsis 805~~~~~~~~ 806 807.. c:macro:: AUDIO_SET_AV_SYNC 808 809.. code-block:: c 810 811 int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, int state) 812 813Arguments 814~~~~~~~~~ 815 816.. flat-table:: 817 :header-rows: 0 818 :stub-columns: 0 819 820 - .. 821 822 - ``int fd`` 823 824 - :cspan:`1` File descriptor returned by a previous call 825 to `open()`_. 826 827 - .. 828 829 - ``int request`` 830 831 - :cspan:`1` Equals ``AUDIO_AV_SYNC`` for this command. 832 833 - .. 834 835 - :rspan:`2` ``int state`` 836 837 - :cspan:`1` Tells the DVB subsystem if A/V synchronization 838 shall be ON or OFF. 839 840 - .. 841 842 - TRUE ( != 0 ) 843 844 - AV-sync ON. 845 846 - .. 847 848 - FALSE ( == 0 ) 849 850 - AV-sync OFF. 851 852Description 853~~~~~~~~~~~ 854 855.. attention:: Do **not** use in new drivers! 856 See: :ref:`legacy_dvb_decoder_notes` 857 858This ioctl call asks the Audio Device to turn ON or OFF A/V 859synchronization. 860 861Return Value 862~~~~~~~~~~~~ 863 864On success 0 is returned, on error -1 and the ``errno`` variable is set 865appropriately. The generic error codes are described at the 866:ref:`Generic Error Codes <gen-errors>` chapter. 867 868 869----- 870 871 872AUDIO_SET_BYPASS_MODE 873--------------------- 874 875Synopsis 876~~~~~~~~ 877 878.. c:macro:: AUDIO_SET_BYPASS_MODE 879 880.. code-block:: c 881 882 int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, int mode) 883 884Arguments 885~~~~~~~~~ 886 887.. flat-table:: 888 :header-rows: 0 889 :stub-columns: 0 890 891 - .. 892 893 - ``int fd`` 894 895 - :cspan:`1` File descriptor returned by a previous call 896 to `open()`_. 897 898 - .. 899 900 - ``int request`` 901 902 - :cspan:`1` Equals ``AUDIO_SET_BYPASS_MODE`` for this command. 903 904 - .. 905 906 - :rspan:`2` ``int mode`` 907 908 - :cspan:`1` Enables or disables the decoding of the current 909 Audio stream in the DVB subsystem. 910 - .. 911 912 - TRUE ( != 0 ) 913 914 - Disable bypass 915 916 - .. 917 918 - FALSE ( == 0 ) 919 920 - Enable bypass 921 922Description 923~~~~~~~~~~~ 924 925.. attention:: Do **not** use in new drivers! 926 See: :ref:`legacy_dvb_decoder_notes` 927 928This ioctl call asks the Audio Device to bypass the Audio decoder and 929forward the stream without decoding. This mode shall be used if streams 930that can’t be handled by the DVB system shall be decoded. Dolby 931DigitalTM streams are automatically forwarded by the DVB subsystem if 932the hardware can handle it. 933 934Return Value 935~~~~~~~~~~~~ 936 937On success 0 is returned, on error -1 and the ``errno`` variable is set 938appropriately. The generic error codes are described at the 939:ref:`Generic Error Codes <gen-errors>` chapter. 940 941 942----- 943 944 945AUDIO_CHANNEL_SELECT 946-------------------- 947 948Synopsis 949~~~~~~~~ 950 951.. c:macro:: AUDIO_CHANNEL_SELECT 952 953.. code-block:: c 954 955 int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, 956 audio_channel_select_t) 957 958Arguments 959~~~~~~~~~ 960 961.. flat-table:: 962 :header-rows: 0 963 :stub-columns: 0 964 965 - .. 966 967 - ``int fd`` 968 969 - :cspan:`1` File descriptor returned by a previous call 970 to `open()`_. 971 972 - .. 973 974 - ``int request`` 975 976 - Equals ``AUDIO_CHANNEL_SELECT`` for this command. 977 978 - .. 979 980 - `audio_channel_select_t`_ ``ch`` 981 982 - Select the output format of the audio (mono left/right, stereo). 983 984Description 985~~~~~~~~~~~ 986 987.. attention:: Do **not** use in new drivers! 988 See: :ref:`legacy_dvb_decoder_notes` 989 990This ioctl is for DVB devices only. To control a V4L2 decoder use the 991V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead. 992 993This ioctl call asks the Audio Device to select the requested channel if 994possible. 995 996Return Value 997~~~~~~~~~~~~ 998 999On success 0 is returned, on error -1 and the ``errno`` variable is set 1000appropriately. The generic error codes are described at the 1001:ref:`Generic Error Codes <gen-errors>` chapter. 1002 1003 1004----- 1005 1006 1007AUDIO_GET_STATUS 1008---------------- 1009 1010Synopsis 1011~~~~~~~~ 1012 1013.. c:macro:: AUDIO_GET_STATUS 1014 1015.. code-block:: c 1016 1017 int ioctl(int fd, int request = AUDIO_GET_STATUS, 1018 struct audio_status *status) 1019 1020Arguments 1021~~~~~~~~~ 1022 1023.. flat-table:: 1024 :header-rows: 0 1025 :stub-columns: 0 1026 1027 - .. 1028 1029 - ``int fd`` 1030 1031 - :cspan:`1` File descriptor returned by a previous call 1032 to `open()`_. 1033 1034 - .. 1035 1036 - ``int request`` 1037 1038 - Equals AUDIO_GET_STATUS for this command. 1039 1040 - .. 1041 1042 - ``struct`` `audio_status`_ ``*status`` 1043 1044 - Returns the current state of Audio Device. 1045 1046Description 1047~~~~~~~~~~~ 1048 1049.. attention:: Do **not** use in new drivers! 1050 See: :ref:`legacy_dvb_decoder_notes` 1051 1052This ioctl call asks the Audio Device to return the current state of the 1053Audio Device. 1054 1055Return Value 1056~~~~~~~~~~~~ 1057 1058On success 0 is returned, on error -1 and the ``errno`` variable is set 1059appropriately. The generic error codes are described at the 1060:ref:`Generic Error Codes <gen-errors>` chapter. 1061 1062 1063----- 1064 1065 1066AUDIO_GET_CAPABILITIES 1067---------------------- 1068 1069Synopsis 1070~~~~~~~~ 1071 1072.. c:macro:: AUDIO_GET_CAPABILITIES 1073 1074.. code-block:: c 1075 1076 int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES, 1077 unsigned int *cap) 1078 1079Arguments 1080~~~~~~~~~ 1081 1082.. flat-table:: 1083 :header-rows: 0 1084 :stub-columns: 0 1085 1086 - .. 1087 1088 - ``int fd`` 1089 1090 - :cspan:`1` File descriptor returned by a previous call 1091 to `open()`_. 1092 1093 - .. 1094 1095 - ``int request`` 1096 1097 - Equals ``AUDIO_GET_CAPABILITIES`` for this command. 1098 1099 - .. 1100 1101 - ``unsigned int *cap`` 1102 1103 - Returns a bit array of supported sound formats. 1104 Bits are defined in `audio encodings`_. 1105 1106Description 1107~~~~~~~~~~~ 1108 1109.. attention:: Do **not** use in new drivers! 1110 See: :ref:`legacy_dvb_decoder_notes` 1111 1112This ioctl call asks the Audio Device to tell us about the decoding 1113capabilities of the audio hardware. 1114 1115Return Value 1116~~~~~~~~~~~~ 1117 1118On success 0 is returned, on error -1 and the ``errno`` variable is set 1119appropriately. The generic error codes are described at the 1120:ref:`Generic Error Codes <gen-errors>` chapter. 1121 1122 1123----- 1124 1125 1126AUDIO_CLEAR_BUFFER 1127------------------ 1128 1129Synopsis 1130~~~~~~~~ 1131 1132.. c:macro:: AUDIO_CLEAR_BUFFER 1133 1134.. code-block:: c 1135 1136 int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER) 1137 1138Arguments 1139~~~~~~~~~ 1140 1141.. flat-table:: 1142 :header-rows: 0 1143 :stub-columns: 0 1144 1145 - .. 1146 1147 - ``int fd`` 1148 1149 - :cspan:`1` File descriptor returned by a previous call 1150 to `open()`_. 1151 1152 - .. 1153 1154 - ``int request`` 1155 1156 - Equals ``AUDIO_CLEAR_BUFFER`` for this command. 1157 1158Description 1159~~~~~~~~~~~ 1160 1161.. attention:: Do **not** use in new drivers! 1162 See: :ref:`legacy_dvb_decoder_notes` 1163 1164This ioctl call asks the Audio Device to clear all software and hardware 1165buffers of the audio decoder device. 1166 1167Return Value 1168~~~~~~~~~~~~ 1169 1170On success 0 is returned, on error -1 and the ``errno`` variable is set 1171appropriately. The generic error codes are described at the 1172:ref:`Generic Error Codes <gen-errors>` chapter. 1173 1174 1175----- 1176 1177 1178AUDIO_SET_ID 1179------------ 1180 1181Synopsis 1182~~~~~~~~ 1183 1184.. c:macro:: AUDIO_SET_ID 1185 1186.. code-block:: c 1187 1188 int ioctl(int fd, int request = AUDIO_SET_ID, int id) 1189 1190Arguments 1191~~~~~~~~~ 1192 1193.. flat-table:: 1194 :header-rows: 0 1195 :stub-columns: 0 1196 1197 - .. 1198 1199 - ``int fd`` 1200 1201 - :cspan:`1` File descriptor returned by a previous call 1202 to `open()`_. 1203 1204 - .. 1205 1206 - ``int request`` 1207 1208 - Equals ``AUDIO_SET_ID`` for this command. 1209 1210 - .. 1211 1212 - ``int id`` 1213 1214 - Audio sub-stream id. 1215 1216Description 1217~~~~~~~~~~~ 1218 1219.. attention:: Do **not** use in new drivers! 1220 See: :ref:`legacy_dvb_decoder_notes` 1221 1222This ioctl selects which sub-stream is to be decoded if a program or 1223system stream is sent to the video device. 1224 1225If no audio stream type is set the id has to be in range [0xC0,0xDF] 1226for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] for LPCM. 1227See ITU-T H.222.0 | ISO/IEC 13818-1 for further description. 1228 1229If the stream type is set with `AUDIO_SET_STREAMTYPE`_, specifies the 1230id just the sub-stream id of the audio stream and only the first 5 bits 1231(& 0x1F) are recognized. 1232 1233Return Value 1234~~~~~~~~~~~~ 1235 1236On success 0 is returned, on error -1 and the ``errno`` variable is set 1237appropriately. The generic error codes are described at the 1238:ref:`Generic Error Codes <gen-errors>` chapter. 1239 1240 1241----- 1242 1243 1244AUDIO_SET_MIXER 1245--------------- 1246 1247Synopsis 1248~~~~~~~~ 1249 1250.. c:macro:: AUDIO_SET_MIXER 1251 1252.. code-block:: c 1253 1254 int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix) 1255 1256Arguments 1257~~~~~~~~~ 1258 1259.. flat-table:: 1260 :header-rows: 0 1261 :stub-columns: 0 1262 1263 - .. 1264 1265 - ``int fd`` 1266 1267 - :cspan:`1` File descriptor returned by a previous call 1268 to `open()`_. 1269 1270 - .. 1271 1272 - ``int request`` 1273 1274 - Equals ``AUDIO_SET_MIXER`` for this command. 1275 1276 - .. 1277 1278 - ``audio_mixer_t *mix`` 1279 1280 - Mixer settings. 1281 1282Description 1283~~~~~~~~~~~ 1284 1285.. attention:: Do **not** use in new drivers! 1286 See: :ref:`legacy_dvb_decoder_notes` 1287 1288This ioctl lets you adjust the mixer settings of the audio decoder. 1289 1290Return Value 1291~~~~~~~~~~~~ 1292 1293On success 0 is returned, on error -1 and the ``errno`` variable is set 1294appropriately. The generic error codes are described at the 1295:ref:`Generic Error Codes <gen-errors>` chapter. 1296 1297 1298----- 1299 1300 1301AUDIO_SET_STREAMTYPE 1302-------------------- 1303 1304Synopsis 1305~~~~~~~~ 1306 1307.. c:macro:: AUDIO_SET_STREAMTYPE 1308 1309.. code-block:: c 1310 1311 int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type) 1312 1313Arguments 1314~~~~~~~~~ 1315 1316.. flat-table:: 1317 :header-rows: 0 1318 :stub-columns: 0 1319 1320 - .. 1321 1322 - ``int fd`` 1323 1324 - :cspan:`1` File descriptor returned by a previous call 1325 to `open()`_. 1326 1327 - .. 1328 1329 - ``int request`` 1330 1331 - Equals ``AUDIO_SET_STREAMTYPE`` for this command. 1332 1333 - .. 1334 1335 - ``int type`` 1336 1337 - Stream type. 1338 1339Description 1340~~~~~~~~~~~ 1341 1342.. attention:: Do **not** use in new drivers! 1343 See: :ref:`legacy_dvb_decoder_notes` 1344 1345This ioctl tells the driver which kind of audio stream to expect. This 1346is useful if the stream offers several audio sub-streams like LPCM and 1347AC3. 1348 1349Stream types defined in ITU-T H.222.0 | ISO/IEC 13818-1 are used. 1350 1351 1352Return Value 1353~~~~~~~~~~~~ 1354 1355On success 0 is returned, on error -1 and the ``errno`` variable is set 1356appropriately. The generic error codes are described at the 1357:ref:`Generic Error Codes <gen-errors>` chapter. 1358 1359.. flat-table:: 1360 :header-rows: 0 1361 :stub-columns: 0 1362 1363 - .. 1364 1365 - ``EINVAL`` 1366 1367 - Type is not a valid or supported stream type. 1368 1369 1370----- 1371 1372 1373AUDIO_BILINGUAL_CHANNEL_SELECT 1374------------------------------ 1375 1376Synopsis 1377~~~~~~~~ 1378 1379.. c:macro:: AUDIO_BILINGUAL_CHANNEL_SELECT 1380 1381.. code-block:: c 1382 1383 int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT, 1384 audio_channel_select_t) 1385 1386Arguments 1387~~~~~~~~~ 1388 1389.. flat-table:: 1390 :header-rows: 0 1391 :stub-columns: 0 1392 1393 - .. 1394 1395 - ``int fd`` 1396 1397 - :cspan:`1` File descriptor returned by a previous call 1398 to `open()`_. 1399 1400 - .. 1401 1402 - ``int request`` 1403 1404 - Equals ``AUDIO_BILINGUAL_CHANNEL_SELECT`` for this command. 1405 1406 - .. 1407 1408 - ``audio_channel_select_t ch`` 1409 1410 - Select the output format of the audio (mono left/right, stereo). 1411 1412Description 1413~~~~~~~~~~~ 1414 1415.. attention:: Do **not** use in new drivers! 1416 See: :ref:`legacy_dvb_decoder_notes` 1417 1418This ioctl has been replaced by the V4L2 1419``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control 1420for MPEG decoders controlled through V4L2. 1421 1422This ioctl call asks the Audio Device to select the requested channel 1423for bilingual streams if possible. 1424 1425Return Value 1426~~~~~~~~~~~~ 1427 1428On success 0 is returned, on error -1 and the ``errno`` variable is set 1429appropriately. The generic error codes are described at the 1430:ref:`Generic Error Codes <gen-errors>` chapter. 1431 1432 1433----- 1434 1435 1436open() 1437------ 1438 1439Synopsis 1440~~~~~~~~ 1441 1442.. code-block:: c 1443 1444 #include <fcntl.h> 1445 1446.. c:function:: int open(const char *deviceName, int flags) 1447 1448Arguments 1449~~~~~~~~~ 1450 1451.. flat-table:: 1452 :header-rows: 0 1453 :stub-columns: 0 1454 1455 - .. 1456 1457 - ``const char *deviceName`` 1458 1459 - Name of specific audio device. 1460 1461 - .. 1462 1463 - :rspan:`3` ``int flags`` 1464 1465 - :cspan:`1` A bit-wise OR of the following flags: 1466 1467 - .. 1468 1469 - ``O_RDONLY`` 1470 1471 - read-only access 1472 1473 - .. 1474 1475 - ``O_RDWR`` 1476 1477 - read/write access 1478 1479 - .. 1480 1481 - ``O_NONBLOCK`` 1482 - | Open in non-blocking mode 1483 | (blocking mode is the default) 1484 1485Description 1486~~~~~~~~~~~ 1487 1488This system call opens a named audio device (e.g. 1489``/dev/dvb/adapter0/audio0``) for subsequent use. When an open() call has 1490succeeded, the device will be ready for use. The significance of 1491blocking or non-blocking mode is described in the documentation for 1492functions where there is a difference. It does not affect the semantics 1493of the open() call itself. A device opened in blocking mode can later be 1494put into non-blocking mode (and vice versa) using the F_SETFL command 1495of the fcntl system call. This is a standard system call, documented in 1496the Linux manual page for fcntl. Only one user can open the Audio Device 1497in O_RDWR mode. All other attempts to open the device in this mode will 1498fail, and an error code will be returned. If the Audio Device is opened 1499in O_RDONLY mode, the only ioctl call that can be used is 1500`AUDIO_GET_STATUS`_. All other call will return with an error code. 1501 1502Return Value 1503~~~~~~~~~~~~ 1504 1505.. flat-table:: 1506 :header-rows: 0 1507 :stub-columns: 0 1508 1509 - .. 1510 1511 - ``ENODEV`` 1512 1513 - Device driver not loaded/available. 1514 1515 - .. 1516 1517 - ``EBUSY`` 1518 1519 - Device or resource busy. 1520 1521 - .. 1522 1523 - ``EINVAL`` 1524 1525 - Invalid argument. 1526 1527 1528----- 1529 1530 1531close() 1532------- 1533 1534Synopsis 1535~~~~~~~~ 1536 1537.. c:function:: int close(int fd) 1538 1539Arguments 1540~~~~~~~~~ 1541 1542.. flat-table:: 1543 :header-rows: 0 1544 :stub-columns: 0 1545 1546 - .. 1547 1548 - ``int fd`` 1549 1550 - :cspan:`1` File descriptor returned by a previous call 1551 to `open()`_. 1552 1553Description 1554~~~~~~~~~~~ 1555 1556This system call closes a previously opened audio device. 1557 1558Return Value 1559~~~~~~~~~~~~ 1560 1561.. flat-table:: 1562 :header-rows: 0 1563 :stub-columns: 0 1564 1565 - .. 1566 1567 - ``EBADF`` 1568 1569 - Fd is not a valid open file descriptor. 1570 1571----- 1572 1573 1574write() 1575------- 1576 1577Synopsis 1578~~~~~~~~ 1579 1580.. code-block:: c 1581 1582 size_t write(int fd, const void *buf, size_t count) 1583 1584Arguments 1585~~~~~~~~~ 1586 1587.. flat-table:: 1588 :header-rows: 0 1589 :stub-columns: 0 1590 1591 - .. 1592 1593 - ``int fd`` 1594 1595 - :cspan:`1` File descriptor returned by a previous call 1596 to `open()`_. 1597 1598 - .. 1599 1600 - ``void *buf`` 1601 1602 - Pointer to the buffer containing the PES data. 1603 1604 - .. 1605 1606 - ``size_t count`` 1607 1608 - Size of buf. 1609 1610Description 1611~~~~~~~~~~~ 1612 1613This system call can only be used if ``AUDIO_SOURCE_MEMORY`` is selected 1614in the ioctl call `AUDIO_SELECT_SOURCE`_. The data provided shall be in 1615PES format. If ``O_NONBLOCK`` is not specified the function will block 1616until buffer space is available. The amount of data to be transferred is 1617implied by count. 1618 1619Return Value 1620~~~~~~~~~~~~ 1621 1622.. flat-table:: 1623 :header-rows: 0 1624 :stub-columns: 0 1625 1626 - .. 1627 1628 - ``EPERM`` 1629 1630 - :cspan:`1` Mode ``AUDIO_SOURCE_MEMORY`` not selected. 1631 1632 - .. 1633 1634 - ``ENOMEM`` 1635 1636 - Attempted to write more data than the internal buffer can hold. 1637 1638 - .. 1639 1640 - ``EBADF`` 1641 1642 - Fd is not a valid open file descriptor.
~/
Read-only file preview.