--- axfer-transfer.1 2024-12-04 01:07:17.640624893 +0000 +++ axfer-transfer.1.new 2024-12-04 02:13:27.201543086 +0000 @@ -71,8 +71,7 @@ Filepath is handled as a path relative t if it\(aqs not full path from root directory. The standard input or output is used if filepath is not specified or given as -.I \(aq\-\(aq -\&. +.IR \(aq\-\(aq . For playback transmission, container format of given .I filepath @@ -90,11 +89,11 @@ are allowed with option. In this case, standard input and output is not available. The same .I filepath is not allowed except for paths listed below: - \- /dev/null - \- /dev/zero - \- /dev/full - \- /dev/random - \- /dev/urandom + \(en /dev/null + \(en /dev/zero + \(en /dev/full + \(en /dev/random + \(en /dev/urandom .SS Common options @@ -137,26 +136,26 @@ Indicate format of audio sample. This is playback transmission with files including raw audio data. Available sample format is listed below: - - [S8|U8|S16|U16|S32|U32][_LE|_BE] - - [S24|U24][_LE|_BE] - - FLOAT[_LE|_BE] - - FLOAT64[_LE|_BE] - - IEC958_SUBFRAME[_LE|_BE] - - MU_LAW - - A_LAW - - [S20|U20][_LE|_BE] - - [S24|U24][_3LE|_3BE] - - [S20|U20][_3LE|_3BE] - - [S18|U18][_3LE|_3BE] - - DSD_U8 - - DSD_[U16|U32][_LE|_BE] + \(en [S8|U8|S16|U16|S32|U32][_LE|_BE] + \(en [S24|U24][_LE|_BE] + \(en FLOAT[_LE|_BE] + \(en FLOAT64[_LE|_BE] + \(en IEC958_SUBFRAME[_LE|_BE] + \(en MU_LAW + \(en A_LAW + \(en [S20|U20][_LE|_BE] + \(en [S24|U24][_3LE|_3BE] + \(en [S20|U20][_3LE|_3BE] + \(en [S18|U18][_3LE|_3BE] + \(en DSD_U8 + \(en DSD_[U16|U32][_LE|_BE] If endian\-ness is omitted, host endian\-ness is used. Some special formats are available: - - cd (16 bit little endian, 44100, stereo) [= \-f S16_LE \-c 2 \-r 44100] - - cdr (16 bit big endian, 44100, stereo) [= \-f S16_BE \-c 2 \-f 44100] - - dat (16 bit little endian, 48000, stereo) [= \-f S16_LE \-c 2 \-r 48000] + \(en cd (16 bit little endian, 44100, stereo) [= \-f S16_LE \-c 2 \-r 44100] + \(en cdr (16 bit big endian, 44100, stereo) [= \-f S16_BE \-c 2 \-f 44100] + \(en dat (16 bit little endian, 48000, stereo) [= \-f S16_LE \-c 2 \-r 48000] If omitted, .I U8 @@ -166,14 +165,14 @@ transmission backend. Unavailable sample format is listed below. These format has size of data frame unaligned to byte unit. - - IMA_ADPCM - - MPEG - - GSM - - SPECIAL - - G723_24 - - G723_24_1B - - G723_40 - - G723_40_1B + \(en IMA_ADPCM + \(en MPEG + \(en GSM + \(en SPECIAL + \(en G723_24 + \(en G723_24_1B + \(en G723_40 + \(en G723_40_1B .TP .B \-c, \-\-channels=# @@ -181,8 +180,8 @@ Indicate the number of audio data sample capture transmission, or playback transmission with files including raw audio data. The value should be between .I 1 to -.I 256 -\&. If omitted, +.IR 256 . +If omitted, .I 1 is used as a default. @@ -197,8 +196,8 @@ data. If the value is less than unit. The value should be between .I 2000 and -.I 192000 -\&. If omitted, +.IR 192000 . +If omitted, .I 8000 is used as a default. @@ -206,10 +205,10 @@ is used as a default. .B \-t, \-\-file\-type=TYPE Indicate the type of file. This is required for capture transmission. Available types are listed below: - - wav: Microsoft/IBM RIFF/Wave format - - au, sparc: Sparc AU format - - voc: Creative Tech. voice format - - raw: raw data + \(en wav: Microsoft/IBM RIFF/Wave format + \(en au, sparc: Sparc AU format + \(en voc: Creative Tech. voice format + \(en raw: raw data When nothing is indicated, for capture transmission, the type is decided according to suffix of @@ -235,9 +234,8 @@ Dump hardware parameters and finish run .TP .B \-\-xfer\-backend=BACKEND Select backend of transmission from a list below. The default is libasound. -.br - - libasound - - libffado (optional if compiled) + \(en libasound + \(en libffado (optional if compiled) .SS Backend options for libasound @@ -324,14 +322,12 @@ option, however its unit is micro\-secon This option indicates the type of waiter for event notification. At present, four types are available; -.I default -, -.I select -, +.IR default , +.IR select , .I poll and -.I epoll -\&. With +.IR epoll . +With .I default type, \(aqsnd_pcm_wait()\(aq is used. With .I select @@ -375,7 +371,8 @@ This option configures given value to software parameter of PCM substream. In blocking mode, the value is used as threshold of the number of available audio data frames in buffer of PCM substream to wake up process blocked by I/O operation. In non\-blocking mode, -any I/O operation returns \-EAGAIN until the available number of audio data frame reaches the threshold. +any I/O operation returns \-EAGAIN +until the available number of audio data frame reaches the threshold. This option has an effect in cases neither .I \-\-mmap @@ -509,8 +506,10 @@ or .I 1 are available. Neither this option nor .I \-g -is available at the same time. If nothing specified, libffado performs to -communicate to units on IEEE 1394 bus managed by all of 1394 OHCI controller available in Linux system. +is available at the same time. +If nothing specified, +libffado performs to communicate to units on IEEE 1394 bus +managed by all of 1394 OHCI controller available in Linux system. .TP .B \-n, \-\-node=# @@ -526,7 +525,7 @@ specified unit. This option uses given value to decide a target unit to communicate. The value should be prefixed with '0x' and consists of hexadecimal literal letters -(0\-9, a\-f, A\-F). Neither this option nor +(0\(en9, a\(enf, A\(enF). Neither this option nor .I \-p is available at the same time. If nothing specified, libffado performs to communicate to units on IEEE 1394 bus managed by all of 1394 OHCI controller @@ -577,7 +576,7 @@ isochronous communication. The given value should be within .I RLIMIT_RTPRIO parameter of process. Please read -.I getrlimit(2) +.BR getrlimit (2) for details. .SH POSIX SIGNALS @@ -597,20 +596,18 @@ The other signals perform default behavi .SH EXAMPLES -.PP .in +4n .EX .B $ axfer transfer playback \-d 1 something .EE .in .PP - The above will transfer audio data frame in \(aqsomething\(aq file for playback -during 1 second. The sample format is detected automatically as a result to +during 1 second. +The sample format is detected automatically as a result to parse \(aqsomething\(aq as long as it\(aqs compliant to one of Microsoft/IBM RIFF/Wave, Sparc AU, Creative Tech. voice formats. If nothing detected, -.I \-r -, +.IR \-r , .I \-c and .I \-f @@ -626,7 +623,6 @@ should be given with special format. .EE .in .PP - The above will transfer audio data frame in \(aqsomething\(aq file including no information of sample format, as sample format of 22050 Hz, monaural, signed 16 bit little endian PCM for playback. The transmission continues till catching @@ -634,8 +630,7 @@ bit little endian PCM for playback. The from keyboard or .I SIGTERM by -.I kill(1) -\&. +.BR kill (1). .PP .in +4n @@ -644,36 +639,32 @@ by .EE .in .PP - The above will transfer audio data frame to \(aqsomething.wav\(aq file as sample format of 44.1 kHz, 2 channels, signed 16 bit little endian PCM, during 10 seconds. The file format is Microsoft/IBM RIFF/Wave according to suffix of the given -.I filepath -\&. +.IR filepath . .PP .in +4n .EX -.B $ axfer transfer capture \-s 1024 \-r 48000 \-c 2 \-f S32_BE \-I \-t au channels +.B $ axfer transfer capture \-s 1024 \-r 48000 \-c 2 \-f S32_BE \-I \-t au \ +channels .EE .in .PP - The above will transfer audio data frame as sample format of 48.0 kHz, 2 channels, signed 32 bit big endian PCM for 1,024 number of data frames to files named \(aqchannels\-1.au\(aq and \(aqchannels\-2.au\(aq. .SH SCHEDULING MODEL - In a design of ALSA PCM core, runtime of PCM substream supports two modes; .I period\-wakeup and -.I no\-period\-wakeup. +.IR no\-period\-wakeup . These two modes are for different scheduling models. .SS IRQ\-based scheduling model - As a default, .I period\-wakeup mode is used. In this mode, in\-kernel drivers should operate hardware to @@ -693,7 +684,7 @@ to the IRQ, direct media access (DMA) tr dedicated host memory and device memory. If target hardware doesn't support this kind of mechanism, the periodical -notification should be emulated by any timer; e.g. hrtimer, kernel timer. +notification should be emulated by any timer; e.g., hrtimer, kernel timer. External PCM plugins generated by PCM plugin SDK in alsa\-lib should also emulate the above behaviour. @@ -701,8 +692,8 @@ In this mode, PCM applications are progr operations. They execute blocking system calls to read/write audio data frame in buffer of PCM substream, or blocking system calls to wait until any audio data frame is available. In -.I axfer -, this is called +.IR axfer , +this is called .I IRQ\-based scheduling model and a default behaviour. Users can explicitly configure this mode by usage of @@ -712,7 +703,6 @@ option with value. .SS Timer\-based scheduling model - The .I no\-period\-wakeup mode is an optional mode of runtime of PCM substream. The mode assumes a @@ -720,7 +710,7 @@ specific feature of hardware and assist applications. In this mode, in\-kernel drivers don't operate hardware to generate periodical notification for transmission of audio data frame. The hardware should automatically continue transmission of audio data frame -without periodical operation of the drivers; e.g. according to auto\-triggered +without periodical operation of the drivers; e.g., according to auto\-triggered DMA transmission, a chain of registered descriptors. In this mode, nothing wakes up blocked processes, therefore PCM applications @@ -735,8 +725,8 @@ PCM core to update a position to head of XRUN. In -.I axfer -, this is called +.IR axfer , +this is called .I timer\-based scheduling model and available as long as hardware/driver assists .I no\-period\-wakeup @@ -757,7 +747,6 @@ transmission position and handling posit PCM buffers. .SS Advantages and issues - Ideally, timer\-based scheduling model has some advantages than IRQ\-based scheduling model. At first, no interrupt context runs for PCM substream. The PCM substream is handled in any process context only. No need to care of race @@ -779,7 +768,6 @@ each I/O operation. As of Linux kernel v kernel/userspace has no feature to report it. .SH COMPATIBILITY TO APLAY - The .B transfer subcommand of @@ -902,22 +890,22 @@ option, this option should increase comp .SS Modular structure This program consists of three modules; -.I xfer -, +.IR xfer , .I mapper and -.I container -\&. +.IR container . Each module has an abstraction layer to enable actual implementation. .nf +.ft CR -------- ---------- ------------- -device <-> | xfer | <-> | mapper | <-> | container | <-> file +device <\-> | xfer | <\-> | mapper | <\-> | container | <\-> file -------- ---------- ------------- libasound single wav libffado multiple au voc raw +.ft .fi The @@ -950,8 +938,7 @@ module handles buffer layout and alignme The module has two implementations; .I single and -.I multiple -\&. +.IR multiple . The .I single backend uses one container to construct the buffer. The @@ -978,8 +965,8 @@ In passing audio data frame between the copying between a buffer to another buffer as much as possible. For example, in some scenarios below, no copying occurs between modules. - - xfer(mmap/interleaved), mapper(single), container(any) - - xfer(mmap/non\-interleaved), mapper(multiple), containers(any) + \(en xfer(mmap/interleaved), mapper(single), container(any) + \(en xfer(mmap/non\-interleaved), mapper(multiple), containers(any) .SS Unit test @@ -998,12 +985,11 @@ takes long time to finish. Please take c any CI environment. .SH SEE ALSO -\fB -axfer(1), -axfer\-list(1), -alsamixer(1), -amixer(1) -\fP +.BR \ +axfer "(1), " \ +axfer\-list "(1), " \ +alsamixer "(1), " \ +amixer (1) .SH AUTHOR Takashi Sakamoto