axfer/axfer-transfer.1

   1 .TH AXFER\-TRANSFER 1 "28 November 2018" "alsa\-utils"
   2
   3 .SH NAME
   4 axfer\-transfer \- transferrer of audio data frame for sound devices and nodes.
   5
   6 .SH SYNOPSIS
   7
   8 .B axfer transfer
   9 .I direction
  10 [
  11 .I common\-options
  12 ] [
  13 .I backend\-options
  14 ] [
  15 .I filepath
  16 ]
  17
  18 .B axfer transfer
  19 .I direction
  20 [
  21 .I common\-options
  22 ] [
  23 .I backend\-options
  24 ]
  25 .I \-I
  26 |
  27 .I \-\-separate\-channels filepath ...
  28
  29 direction =
  30 .B capture
  31 |
  32 .B playback
  33
  34 common\-options = ( read
  35 .I OPTIONS
  36 section )
  37
  38 backend\-options = ( read
  39 .I OPTIONS
  40 section )
  41
  42 filepaths = ( read
  43 .I OPTIONS
  44 section )
  45
  46 .SH DESCRIPTION
  47 The
  48 .B transfer
  49 subcommand of
  50 .B axfer
  51 performs transmission of audio data frames for devices available in supported
  52 backends. This program is essentially designed to use alsa\-lib APIs
  53 (libasound backend) to handle sound devices supported by Linux sound subsystem
  54 (ALSA).
  55
  56 .SH OPTIONS
  57
  58 .SS Direction
  59
  60 .TP
  61 .B capture
  62 Operates for capture transmission.
  63
  64 .TP
  65 .B playback
  66 Operates for playback transmission.
  67
  68 .SS Filepath
  69
  70 Filepath is handled as a path relative to current working directory of run time
  71 if it\(aqs not full path from root directory.
  72
  73 The standard input or output is used if filepath is not specified or given as
  74 .I \(aq\-\(aq
  75 \&.
  76
  77 For playback transmission, container format of given
  78 \I filepath
  79 is detected automatically and metadata is used for parameters of sample format,
  80 channels, rate, duration. If nothing detected, content of given file path is
  81 handled as raw data. In this case, the parameters should be indicated as
  82 options.
  83
  84 Multiple
  85 .I filepaths
  86 are allowed with
  87 .I \-I
  88 |
  89 .I \-\-separate\-channels
  90 option. In this case, standard input and output is not available. The same
  91 .I filepath
  92 is not allowed except for paths listed below:
  93  \- /dev/null
  94  \- /dev/zero
  95  \- /dev/full
  96  \- /dev/random
  97  \- /dev/urandom
  98
  99 .SS Common options
 100
 101 .TP
 102 .B \-h, \-\-help
 103 Print help messages and finish run time.
 104
 105 .TP
 106 .B \-q, \-\-quiet
 107 Quiet mode. Suppress messages (not sound :))
 108
 109 .TP
 110 .B \-v, \-\-verbose
 111 Verbose mode. Runtime dumps supplemental information according to the number of
 112 this option given in command line.
 113
 114 .TP
 115 .B \-d, \-\-duration=#
 116 Interrupt after # seconds. A value of zero means infinity. The default is zero,
 117 so if this option is omitted then the transmission process will run until it is
 118 killed. Either
 119 .I \-d
 120 or
 121 .I \-s
 122 option is available exclusively.
 123
 124 .TP
 125 .B \-s, \-\-samples=#
 126 Interrupt after transmission of # number of data frames. A value of zero means
 127 infinity. The default is zero, so if this options is omitted then the
 128 transmission process will run until it is killed. Either
 129 .I \-d
 130 or
 131 .I \-s
 132 option is available exclusively.
 133
 134 .TP
 135 .B \-f, \-\-format=FORMAT
 136 Indicate format of audio sample. This is required for capture transmission, or
 137 playback transmission with files including raw audio data.
 138
 139 Available sample format is listed below:
 140  - [S8|U8|S16|U16|S32|U32][_LE|_BE]
 141  - [S24|U24][_LE|_BE]
 142  - FLOAT[_LE|_BE]
 143  - FLOAT64[_LE|_BE]
 144  - IEC958_SUBFRAME[_LE|_BE]
 145  - MU_LAW
 146  - A_LAW
 147  - [S20|U20][_LE|_BE]
 148  - [S24|U24][_3LE|_3BE]
 149  - [S20|U20][_3LE|_3BE]
 150  - [S18|U18][_3LE|_3BE]
 151  - DSD_U8
 152  - DSD_[U16|U32][_LE|_BE]
 153
 154 If endian\-ness is omitted, host endian\-ness is used.
 155
 156 Some special formats are available:
 157  - cd (16 bit little endian, 44100, stereo) [= \-f S16_LE \-c 2 \-r 44100]
 158  - cdr (16 bit big endian, 44100, stereo) [= \-f S16_BE \-c 2 \-f 44100]
 159  - dat (16 bit little endian, 48000, stereo) [= \-f S16_LE \-c 2 \-r 48000]
 160
 161 If omitted,
 162 .I U8
 163 is used as a default. Actual available formats are restricted by each
 164 transmission backend.
 165
 166 Unavailable sample format is listed below. These format has size of data frame
 167 unaligned to byte unit.
 168
 169  - IMA_ADPCM
 170  - MPEG
 171  - GSM
 172  - SPECIAL
 173  - G723_24
 174  - G723_24_1B
 175  - G723_40
 176  - G723_40_1B
 177
 178 .TP
 179 .B \-c, \-\-channels=#
 180 Indicate the number of audio data samples per frame. This is required for
 181 capture transmission, or playback transmission with files including raw audio
 182 data. The value should be between
 183 .I 1 to
 184 .I 256
 185 \&. If omitted,
 186 .I 1
 187 is used as a default.
 188
 189 .TP
 190 .B \-r, \-\-rate=#
 191 Indicate the number of audio data frame per second. This is required for
 192 capture transmission, or playback transmission with files including raw audio
 193 data. If the value is less than
 194 .I 1000
 195 , it\(aqs interpreted by
 196 .I kHz
 197 unit. The value should be between
 198 .I 2000
 199 and
 200 .I 192000
 201 \&. If omitted,
 202 .I 8000
 203 is used as a default.
 204
 205 .TP
 206 .B \-t, \-\-file\-type=TYPES
 207 Indicate the type of file. This is required for capture transmission. Available
 208 types are listed below:
 209  - wav: Microsoft/IBM RIFF/Wave format
 210  - au, sparc: Sparc AU format
 211  - voc: Creative Tech. voice format
 212  - raw: raw data
 213
 214 When nothing is indicated, for capture transmission, the type is decided
 215 according to suffix of
 216 .I filepath
 217 , and
 218 .I raw
 219 type is used for fallback.
 220
 221 .TP
 222 .B \-I, \-\-separate\-channels
 223 Indicate this option when several files are going to be handled. For capture
 224 transmission, if one filepath is given as
 225 .I filepath
 226 , a list of
 227 .I filepaths
 228 is generated in a formula \(aq<filepath>\-<sequential number>[.suffix]\(aq.
 229 The suffix is omitted when raw format of container is used.
 230
 231 .TP
 232 .B \-\-dump\-hw\-params
 233 Dump hardware parameters and finish run time if backend supports it.
 234
 235 .TP
 236 .B \-\-xfer\-backend=BACKEND
 237 Select backend of transmission from a list below. The default is libasound.
 238 .br
 239  - libasound
 240  - libffado (optional if compiled)
 241
 242 .SS Backend options for libasound
 243
 244 .TP
 245 .B \-D, \-\-device
 246
 247 This option is used to select PCM node in libasound configuration space.
 248 Available nodes are listed by
 249 .I pcm
 250 operation of
 251 .I list
 252 subcommand.
 253
 254 .TP
 255 .B \-N, \-\-nonblock
 256
 257 With this option, PCM substream is opened in non\-blocking mode. When audio
 258 data frame is not available in buffer of the PCM substream, I/O operation
 259 immediately returns without blocking process. This option implicitly uses
 260 .I \-\-waiter\-type
 261 option as well to prevent heavy consumption of CPU time.
 262
 263 .TP
 264 .B \-M, \-\-mmap
 265
 266 With this option, audio data frame is processed directly in buffer of PCM
 267 substream if selected node supports this operation. Without the option,
 268 temporary buffers are used to copy audio data frame for buffer of PCM substream.
 269 This option implicitly uses
 270 .I \-\-waiter\-type
 271 option as well to prevent heavy consumption of CPU time.
 272
 273 .TP
 274 .B \-F, \-\-period\-size
 275
 276 This option configures given value to
 277 .I period_size
 278 hardware parameter of PCM substream. The parameter indicates the number of audio
 279 data frame per period in buffer of the PCM substream. Actual number is decided
 280 as a result of interaction between each implementation of PCM plugin chained
 281 from the selected PCM node, and in\-kernel driver or PCM I/O plugins.
 282
 283 Ideally, the same amount of audio data frame as the value should be handled in
 284 one I/O operation. Actually, it is not, depending on implementation of the PCM
 285 plugins, in\-kernel driver, PCM I/O plugins and scheduling model. For \(aqhw\(aq
 286 PCM plugin in \(aqirq\(aq scheduling model, the value is used to decide
 287 intervals of hardware interrupt, thus the same amount of audio data frame as
 288 the value is expected to be available for one I/O operation.
 289
 290 .TP
 291 .B \-\-period\-time
 292
 293 This option configures given value to
 294 .I period_time
 295 hardware parameter of PCM substream. This option is similar to
 296 .I \-\-period\-size
 297 option, however its unit is micro\-second.
 298
 299 .TP
 300 .B \-B, \-\-buffer\-size
 301
 302 This option configures given value to
 303 .I buffer_size
 304 hardware parameter of PCM substream. The parameter indicates the number of audio
 305 data frame in buffer of PCM substream. Actual number is decided as a result of
 306 interaction between each implementation of PCM plugin chained from the selected
 307 PCM node, and in\-kernel driver or PCM I/O plugins.
 308
 309 Ideally, this is multiples of the number of audio data frame per period, thus
 310 the size of period. Actually, it is not, depending on implementation of the PCM
 311 plugins, in\-kernel driver and PCM I/O plugins.
 312
 313 .TP
 314 .B \-\-buffer\-time
 315
 316 This option configures given value to
 317 .I buffer_time
 318 hardware parameter of PCM substream. This option is similar to
 319 .I \-\-buffer\-size
 320 option, however its unit is micro\-second.
 321
 322 .TP
 323 .B \-\-waiter\-type
 324
 325 This option indicates the type of waiter for event notification. At present,
 326 four types are available;
 327 .I default
 328 ,
 329 .I select
 330 ,
 331 .I poll
 332 and
 333 .I epoll
 334 \&. With
 335 .I default
 336 type, \(aqsnd_pcm_wait()\(aq is used. With
 337 .I select
 338 type, \(aqselect(2)\(aq system call is used. With
 339 .I poll
 340 type, \(aqpoll(2)\(aq system call is used. With
 341 .I epoll
 342 type, Linux\-specific \(aqepoll(7)\(aq system call is used.
 343
 344 This option should correspond to one of
 345 .I \-\-nonblock
 346 or
 347 .I \-\-mmap
 348 options, or
 349 .I timer
 350 value of
 351 .I \-\-sched\-model
 352 option.
 353 Neither this option nor
 354 .I \-\-test\-nowait
 355 is available at the same time.
 356
 357 .TP
 358 .B \-\-sched\-model
 359
 360 This option selects scheduling model for process of this program. One of
 361 .I irq
 362 or
 363 .I timer
 364 is available. In detail, please read \(aqSCHEDULING MODEL\(aq section.
 365
 366 When nothing specified,
 367 .I irq
 368 model is used.
 369
 370 .TP
 371 .B \-A, \-\-avail\-min
 372
 373 This option configures given value to
 374 .I avail\-min
 375 software parameter of PCM substream. In blocking mode, the value is used as
 376 threshold of the number of available audio data frames in buffer of PCM
 377 substream to wake up process blocked by I/O operation. In non\-blocking mode,
 378 any I/O operation returns \-EAGAIN untill the available number of audio data frame reaches the threshold.
 379
 380 This option has an effect in cases neither
 381 .I \-\-mmap
 382 nor
 383 .I timer
 384 value of
 385 .I \-\-sched\-model
 386 option is used.
 387
 388 .TP
 389 .B \-R, \-\-start\-delay
 390
 391 This option configures given value to
 392 .I start_threshold
 393 software parameter of PCM substream. The value is used as threshold to start
 394 PCM substream automatically. At present, this option has an effect in cases
 395 neither
 396 .I \-\-mmap
 397 nor
 398 .I timer
 399 value of
 400 .I \-\-sched\-model
 401 option is used.
 402
 403 For playback transmission, when the number of accumulated audio data frame
 404 in buffer of PCM substream to which this program writes out reaches the
 405 threshold, the PCM substream starts automatically without an explicit call of
 406 .I snd_pcm_start()
 407 to the PCM substream.
 408
 409 For capture transmission, this option is useless. The number of
 410 accumulated audio data frame is not increased without an explicit call of
 411 .I snd_pcm_start()
 412 to the PCM substream.
 413
 414 This option has an effect in cases neither
 415 .I \-\-mmap
 416 nor
 417 .I timer
 418 value of
 419 .I \-\-sched\-model
 420 option is used.
 421
 422 .TP
 423 .B \-T, \-\-stop\-delay
 424
 425 This option configures given value to
 426 .I stop_threshold
 427 software parameter of PCM substream. The value is used as threshold to stop PCM
 428 substream automatically. At present, this option has an effect in cases neither
 429 .I \-\-mmap
 430 nor
 431 .I timer
 432 value of
 433 .I \-\-sched\-model
 434 option is used.
 435
 436 For capture transmission, when the number of accumulated audio data frame
 437 in buffer of PCM substream to which a driver or alsa\-lib PCM plugins write
 438 reaches the threshold, the PCM substream stops automatically without an explicit
 439 call of
 440 .I snd_pcm_stop()
 441 to the PCM substream. This is a case that this program leaves the audio data
 442 frames without reading for a while.
 443
 444 For playback transmission, when the number available audio data frame in buffer
 445 of PCM substream from which a driver or alsa\-lib PCM plugins read reaches the
 446 threshold, the PCM substream stops automatically without an explicit call of
 447 .I snd_pcm_stop()
 448 to the PCM substream. This is a case that this program leaves the audio data
 449 frames without writing for a while.
 450
 451 This option has an effect in cases neither
 452 .I \-\-mmap
 453 nor
 454 .I timer
 455 value of
 456 .I \-\-sched\-model
 457 option is used.
 458
 459 .TP
 460 .B \-\-disable\-resample
 461
 462 This option has an effect for \(aqplug\(aq plugin in alsa\-lib to suppress
 463 conversion of sampling rate for audio data frame.
 464
 465 .TP
 466 .B \-\-disable\-channels
 467
 468 This option has an effect for \(aqplug\(aq plugin in alsa\-lib to suppress
 469 conversion of channels for audio data frame.
 470
 471 .TP
 472 .B \-\-disable\-format
 473
 474 This option has an effect for \(aqplug\(aq plugin in alsa\-lib to suppress
 475 conversion of sample format for audio data frame.
 476
 477 .TP
 478 .B \-\-disable\-softvol
 479
 480 This option has an effect for \(aqsoftvol\(aq plugin in alsa\-lib to suppress
 481 conversion of samples for audio data frame via additional control element.
 482
 483 .TP
 484 .B \-\-fatal\-errors
 485
 486 This option suppresses recovery operation from XRUN state of running PCM
 487 substream, then process of this program is going to finish as usual.
 488
 489 .TP
 490 .B \-\-test\-nowait
 491
 492 This option disables any waiter for I/O event notification. I/O operations are
 493 iterated till any of audio data frame is available. The option brings heavy
 494 load in consumption of CPU time.
 495
 496 .SS Backend options for libffado
 497
 498 This backend is automatically available when configure script detects
 499 .I ffado_streaming_init()
 500 symbol in libffado shared object.
 501
 502 .TP
 503 .B \-p, \-\-port
 504
 505 This option uses given value to decide which 1394 OHCI controller is used to
 506 communicate. When Linux system has two 1394 OHCI controllers,
 507 .I 0
 508 or
 509 .I 1
 510 are available. Neither this option nor
 511 .I \-g
 512 is available at the same time. If nothing specified, libffado performs to
 513 communicate to units on IEEE 1394 bus managed by all of 1394 OHCI controller available in Linux system.
 514
 515 .TP
 516 .B \-n, \-\-node
 517
 518 This option uses given value to decide which unit is used to communicate. This
 519 option requires
 520 .I \-p
 521 option to indicate which 1394 OHCI controller is used to communicate to the
 522 specified unit.
 523
 524 .TP
 525 .B \-g, \-\-guid
 526
 527 This option uses given value to decide a target unit to communicate. The value
 528 should be prefixed with '0x' and consists of hexadecimal literal letters
 529 (0\-9, a\-f, A\-F). Neither this option nor
 530 .I \-p
 531 is available at the same time. If nothing specified, libffado performs to
 532 communicate to units on IEEE 1394 bus managed by all of 1394 OHCI controller
 533 available in Linux system.
 534
 535 .TP
 536 .B \-\-frames\-per\-period
 537
 538 This option uses given value to decide the number of audio data frame in one
 539 read/write operation. The operation is blocked till the number of available
 540 audio data frame exceeds the given value. As a default, 512 audio data frames
 541 is used.
 542
 543 .TP
 544 .B \-\-periods\-per\-buffer
 545
 546 This option uses given value to decide the size of intermediate buffer between
 547 this program and libffado. As a default, 2 periods per buffer is used.
 548
 549 .TP
 550 .B \-\-slave
 551
 552 This option allows this program to run slave mode. In this mode, libffado
 553 adds unit directory into configuration ROM of 1394 OHCI controller where Linux
 554 system runs. The unit directory can be found by the other node on the same bus.
 555 Linux system running on the node can transfer isochronous packet with audio
 556 data frame to the unit. This program can receive the packet and demultiplex the
 557 audio data frame.
 558
 559 .TP
 560 .B \-\-snoop
 561
 562 This option allows this program to run snoop mode. In this mode, libffado
 563 listens isochronous channels to which device transfers isochronous packet. When
 564 isochronous communication starts by any unit on the same bus, the packets can
 565 be handled by this program.
 566
 567 .TP
 568 .B \-\-sched\-priority
 569
 570 This option executes
 571 .I pthread_setschedparam()
 572 in a call of
 573 .I ffado_streaming_init()
 574 to configure
 575 scheduling policy and given value as its priority for threads related to
 576 isochronous communication.
 577 The given value should be within
 578 .I RLIMIT_RTPRIO
 579 parameter of process. Please read
 580 .I getrlimit(2)
 581 for details.
 582
 583 .SH POSIX SIGNALS
 584 During transmission,
 585 .I SIGINT
 586 and
 587 .I SIGTERM
 588 will close handled files and PCM substream to be going to finish run time.
 589
 590 .I SIGTSTP
 591 will suspend PCM substream and
 592 .I SIGCONT
 593 will resume it. No XRUNs are expected. With libffado backend, the suspend/resume
 594 is not supported and runtime is aboeted immediately.
 595
 596 The other signals perform default behaviours.
 597
 598 .SH EXAMPLES
 599
 600 .PP
 601 .in +4n
 602 .EX
 603 .B $ axfer transfer playback \-d 1 something
 604 .EE
 605 .in
 606 .PP
 607
 608 The above will transfer audio data frame in \(aqsomething\(aq file for playback
 609 during 1 second.  The sample format is detected automatically as a result to
 610 parse \(aqsomething\(aq as long as it\(aqs compliant to one of Microsoft/IBM
 611 RIFF/Wave, Sparc AU, Creative Tech. voice formats. If nothing detected,
 612 .I \-r
 613 ,
 614 .I \-c
 615 and
 616 .I \-f
 617 should be given,
 618 or
 619 .I \-f
 620 should be given with special format.
 621
 622 .PP
 623 .in +4n
 624 .EX
 625 .B $ axfer transfer playback \-r 22050 \-c 1 \-f S16_LE \-t raw something
 626 .EE
 627 .in
 628 .PP
 629
 630 The above will transfer audio data frame in \(aqsomething\(aq file including no
 631 information of sample format, as sample format of 22050 Hz, monaural, signed 16
 632 bit little endian PCM for playback. The transmission continues till catching
 633 .I SIGINT
 634 from keyboard or
 635 .I SIGTERM
 636 by
 637 .I kill(1)
 638 \&.
 639
 640 .PP
 641 .in +4n
 642 .EX
 643 .B $ axfer transfer capture \-d 10 \-f cd something.wav
 644 .EE
 645 .in
 646 .PP
 647
 648 The above will transfer audio data frame to \(aqsomething.wav\(aq file as
 649 sample format of 44.1 kHz, 2 channels, signed 16 bit little endian PCM, during
 650 10 seconds. The file format is Microsoft/IBM RIFF/Wave according to suffix of
 651 the given
 652 .I filepath
 653 \&.
 654
 655 .PP
 656 .in +4n
 657 .EX
 658 .B $ axfer transfer capture \-s 1024 \-r 48000 \-c 2 \-f S32_BE \-I \-t au channels
 659 .EE
 660 .in
 661 .PP
 662
 663 The above will transfer audio data frame as sample format of 48.0 kHz, 2
 664 channels, signed 32 bit big endian PCM for 1,024 number of data frames to files
 665 named \(aqchannels\-1.au\(aq and \(aqchannels\-2.au\(aq.
 666
 667 .SH SCHEDULING MODEL
 668
 669 In a design of ALSA PCM core, runtime of PCM substream supports two modes;
 670 .I period\-wakeup
 671 and
 672 .I no\-period\-wakeup.
 673 These two modes are for different scheduling models.
 674
 675 .SS IRQ\-based scheduling model
 676
 677 As a default,
 678 .I period\-wakeup
 679 mode is used. In this mode, in\-kernel drivers should operate hardware to
 680 generate periodical notification for transmission of audio data frame. The
 681 interval of notification is equivalent to the same amount of audio data frame
 682 as one period of buffer, against actual time.
 683
 684 In a handler assigned to the notification, a helper function of ALSA PCM core
 685 is called to update a position to head of hardware transmission, then compare
 686 it with a position to head of application operation to judge overrun/underrun
 687 (XRUN) and to wake up blocked processes.
 688
 689 For this purpose, hardware IRQ of controller for serial audio bus such as
 690 Inter\-IC sound is typically used. In this case, the controller generates the
 691 IRQ according to transmission on the serial audio bus. In the handler assigned
 692 to the IRQ, direct media access (DMA) transmission is requested between
 693 dedicated host memory and device memory.
 694
 695 If target hardware doesn't support this kind of mechanism, the periodical
 696 notification should be emulated by any timer; e.g. hrtimer, kernel timer.
 697 External PCM plugins generated by PCM plugin SDK in alsa\-lib should also
 698 emulate the above behaviour.
 699
 700 In this mode, PCM applications are programmed according to typical way of I/O
 701 operations. They execute blocking system calls to read/write audio data frame
 702 in buffer of PCM substream, or blocking system calls to wait until any audio
 703 data frame is available. In
 704 .I axfer
 705 , this is called
 706 .I IRQ\-based
 707 scheduling model and a default behaviour. Users can explicitly configure this
 708 mode by usage of
 709 .I \-\-sched\-model
 710 option with
 711 .I irq
 712 value.
 713
 714 .SS Timer\-based scheduling model
 715
 716 The
 717 .I no\-period\-wakeup
 718 mode is an optional mode of runtime of PCM substream. The mode assumes a
 719 specific feature of hardware and assist of in\-kernel driver and PCM
 720 applications. In this mode, in\-kernel drivers don't operate hardware to
 721 generate periodical notification for transmission of audio data frame.
 722 The hardware should automatically continue transmission of audio data frame
 723 without periodical operation of the drivers; e.g. according to auto\-triggered
 724 DMA transmission, a chain of registered descriptors.
 725
 726 In this mode, nothing wakes up blocked processes, therefore PCM applications
 727 should be programmed without any blocking operation. For this reason, this mode
 728 is enabled when the PCM applications explicitly configure hardware parameter to
 729 runtime of PCM substream, to prevent disorder of existing applications.
 730 Additionally, nothing maintains timing for transmission of audio data frame,
 731 therefore the PCM applications should voluntarily handle any timer to queue
 732 audio data frame in buffer of the PCM substream for lapse of time. Furthermore,
 733 instead of driver, the PCM application should call a helper function of ALSA
 734 PCM core to update a position to head of hardware transmission and to check
 735 XRUN.
 736
 737 In
 738 .I axfer
 739 , this is called
 740 .I timer\-based
 741 scheduling model and available as long as hardware/driver assists
 742 .I no\-period\-wakeup
 743 runtime. Users should explicitly set this mode by usage of
 744 .I \-\-sched\-model
 745 option with
 746 .I timer
 747 value.
 748
 749 In the scheduling model, PCM applications need to care of available space on
 750 PCM buffer by lapse of time, typically by yielding CPU and wait for
 751 rescheduling. For the yielding, timeout is calculated for preferable amount of
 752 PCM frames to process. This is convenient to a kind of applications, like sound
 753 servers. when an I/O thread of the server wait for the timeout, the other
 754 threads can process audio data frames for server clients. Furthermore, with
 755 usage of rewinding/forwarding, applications can achieve low latency between
 756 transmission position and handling position even if they uses large size of
 757 PCM buffers.
 758
 759 .SS Advantages and issues
 760
 761 Ideally, timer\-based scheduling model has some advantages than IRQ\-based
 762 scheduling model. At first, no interrupt context runs for PCM substream. The
 763 PCM substream is handled in any process context only. No need to care of race
 764 conditions between IRQ and process contexts. This reduces some concerns for
 765 some developers of drivers and applications. Secondary, CPU time is not used
 766 for handlers on the interrupt context. The CPU time can be dedicated for the
 767 other tasks. This is good in a point of Time Sharing System. Thirdly, hardware
 768 is not configured to generate interrupts. This is good in a point of reduction
 769 of overall power consumption possibly.
 770
 771 In either scheduling model, the hardware should allow drivers to read the
 772 number of audio data frame transferred between the dedicated memory and the
 773 device memory for audio serial bus. However, in timer\-based scheduling model,
 774 fine granularity and accuracy of the value is important. Actually hardware
 775 performs transmission between dedicated memory and device memory for a small
 776 batch of audio data frames or bytes. In a view of PCM applications, the
 777 granularity in current transmission is required to decide correct timeout for
 778 each I/O operation. As of Linux kernel v4.21, ALSA PCM interface between
 779 kernel/userspace has no feature to report it.
 780
 781 .SH COMPATIBILITY TO APLAY
 782
 783 The
 784 .B transfer
 785 subcommand of
 786 .B axfer
 787 is designed to keep compatibility to aplay(1). However some options below are
 788 not compatible due to several technical reasons.
 789
 790 .TP
 791 .I \-I, \-\-separate\-channels
 792 This option is supported just for files to store audio data frames corresponding
 793 to each channel. In aplay(1) implementation, this option has an additional
 794 effect to use PCM buffer aligned to non\-interleaved order if a target device
 795 supports. As of 2018, PCM buffer of non\-interleaved order is hardly used by
 796 sound devices.
 797
 798 .TP
 799 .I \-A, \-\-avail\-min
 800 This option indicates threshold to wake up blocked process in a unit of
 801 audio data frame. Against aplay(1) implementation, this option has no effect
 802 with
 803 .I \-\-mmap
 804 option as well as
 805 .I timer
 806 of
 807 .I \-\-sched\-model
 808 option.
 809
 810 .TP
 811 .I \-R, \-\-start\-delay
 812 This option indicates threshold to start prepared PCM substream in a unit of
 813 audio data frame. Against aplay(1) implementation, this option has no effect
 814 with
 815 .I \-\-mmap
 816 option as well as
 817 .I timer
 818 of
 819 .I \-\-sched\-model
 820 option.
 821
 822 .TP
 823 .I \-T, \-\-stop\-delay
 824 This option indicates threshold to stop running PCM substream in a unit of
 825 audio data frame. Against aplay(1) implementation, this option has no effect
 826 with
 827 .I \-\-mmap
 828 option as well as
 829 .I timer
 830 of
 831 .I \-\-sched\-model
 832 option.
 833
 834 .TP
 835 .I \-\-max\-file\-time=#
 836 This option is unsupported. In aplay(1) implementation, the option has an
 837 effect for capture transmission to save files up to the same number of data
 838 frames as the given value by second unit, or the maximum number of data frames
 839 supported by used file format. When reaching to the limitation, used file is
 840 closed, then new file is opened and audio data frames are written. However, this
 841 option requires extra handling of files and shall increase complexity of main
 842 loop of axfer.
 843
 844 .TP
 845 .I \-\-use\-strftime=FORMAT
 846 This option is unsupported. In aplay(1) implementation, the option has an effect
 847 for capture transmission to generate file paths according to given format in
 848 which some extra formats are available as well as formats supported by
 849 strftime(3). However, this option requires extra string processing for file
 850 paths and it\(aqs bothersome if written in C language.
 851
 852 .TP
 853 .I \-\-process\-id\-file=FILEPATH
 854 This option is unsupported. In aplay(1) implementation, the option has an effect
 855 to create a file for given value and write out process ID to it. This file
 856 allows users to get process ID and send any POSIX signal to aplay process.
 857 However, this idea has some troubles for file locking when multiple aplay
 858 processes run with the same file.
 859
 860 .TP
 861 .I \-V, \-\-vumeter=TYPE
 862 This option is not supported at present. In aplay(1) implementation, this option
 863 has an effect to occupy stdout with some terminal control characters and display
 864 vumeter for monaural and stereo channels. However, some problems lay; this
 865 feature is just for audio data frames with PCM format, this feature brings
 866 disorder of terminal after aborting, stdout is not available for pipeline.
 867
 868 .TP
 869 .I \-i, \-\-interactive
 870 This option is not supported at present. In aplay(1) implementation, this option
 871 has an effect to occupy stdin for key input and suspend/resume PCM substream
 872 according to pushed enter key. However, this feature requires an additional
 873 input handling in main loop and leave bothersome operation to maintain PCM
 874 substream.
 875
 876 .TP
 877 .I \-m, \-\-chmap=CH1,CH2,...
 878 ALSA PCM core and control core doesn't support this feature, therefore
 879 remapping should be done in userspace. This brings overhead to align audio
 880 data frames, especially for mmap operation. Furthermore, as of alsa-lib v1.1.8,
 881 some plugins don't support this feature expectedly, thus this option is a lack
 882 of transparent operation. At present, this option is not supported yet not to
 883 confuse users.
 884
 885 .TP
 886 .I SIGTSTP, SIGCONT
 887 This performs suspend/resume of PCM substream. In aplay(1) implementation,
 888 these operations bring XRUN state to the substream, and suspend/resume is done
 889 in interactive mode in the above. Some developers use the signal for recovery
 890 test from XRUN. At present, no alternative is supported for the test.
 891
 892 .TP
 893 .I SIGUSR1
 894 This is not supported. In aplay(1) implementation, this signal is assigned to a
 895 handler to close a current file to store audio data frame and open a new file
 896 to continue processing. However, as well as
 897 .I \-\-max\-file\-time
 898 option, this option should increase complexity of main loop of axfer.
 899
 900 .SH DESIGN
 901
 902 .SS Modular structure
 903
 904 This program consists of three modules;
 905 .I xfer
 906 ,
 907 .I mapper
 908 and
 909 .I container
 910 \&.
 911 Each module has an abstraction layer to enable actual implementation.
 912
 913 .nf
 914            --------     ----------     -------------
 915 device <-> | xfer | <-> | mapper | <-> | container | <-> file
 916            --------     ----------     -------------
 917             libasound    single         wav
 918             libffado     multiple       au
 919                                         voc
 920                                         raw
 921 .fi
 922
 923 The
 924 .I xfer
 925 module performs actual transmission to devices and nodes. The module can have
 926 several transmission backends. As a default backend,
 927 .I libasound
 928 backend is used to perform transmission via alsa\-lib APIs. The module allows
 929 each backend to parse own command line options.
 930
 931 The
 932 .I container
 933 module performs to read/write audio data frame via descriptor for file/stream
 934 of multimedia container or raw data. The module automatically detect type of
 935 multimedia container and parse parameters in its metadata of data header. At
 936 present, three types of multimedia containers are supported; Microsoft/IBM
 937 RIFF/Wave (
 938 .I wav
 939 ), Sparc AU (
 940 .I au
 941 ) and Creative Technology voice (
 942 .I voc
 943 ). Additionally, a special container is prepared for raw audio data (
 944 .I raw
 945 ).
 946
 947 The
 948 .I mapper
 949 module handles buffer layout and alignment for transmission of audio data frame.
 950 The module has two implementations;
 951 .I single
 952 and
 953 .I multiple
 954 \&.
 955 The
 956 .I single
 957 backend uses one container to construct the buffer. The
 958 .I multiple
 959 backend uses several containers to construct it.
 960
 961 .SS Care of copying audio data frame
 962
 963 Between the
 964 .I xfer
 965 module and
 966 .I mapper
 967 module, a pointer to buffer including audio data frames is passed. This buffer
 968 has two shapes for interleaved and non\-interleaved order. For the former, the
 969 pointer points to one buffer. For the latter, the pointer points to an array in
 970 which each element points to one buffer. Between the
 971 .I mapper
 972 module and
 973 .I container
 974 module, a pointer to one buffer is passed because supported media containers
 975 including raw type store audio data frames in interleaved order.
 976
 977 In passing audio data frame between the modules, axfer is programmed to avoid
 978 copying between a buffer to another buffer as much as possible. For example, in
 979 some scenarios below, no copying occurs between modules.
 980
 981  - xfer(mmap/interleaved), mapper(single), container(any)
 982  - xfer(mmap/non\-interleaved), mapper(multiple), containers(any)
 983
 984 .SS Unit test
 985
 986 For each of the
 987 .I mapper
 988 and
 989 .I container
 990 module, unit test is available. To run the tests, execute below command:
 991
 992 .nf
 993 $ make test
 994 .fi
 995
 996 Each test iterates writing to file and reading to the file for many times and it
 997 takes long time to finish. Please take care of the execution time if running on
 998 any CI environment.
 999
1000 .SH SEE ALSO
1001 \fB
1002 axfer(1),
1003 axfer\-list(1),
1004 alsamixer(1),
1005 amixer(1)
1006 \fP
1007
1008 .SH AUTHOR
1009 Takashi Sakamoto <o\-takashi@sakamocchi.jp>