On Wed, 21 Oct 2015 08:53:27 +0200, han.lu@intel.com wrote:
From: "Lu, Han" han.lu@intel.com
Add more information about BAT utility, including design intent, principles, use mode, hardware connection, options, example and return value.
Signed-off-by: Lu, Han han.lu@intel.com
Applied, thanks.
Takashi
diff --git a/bat/Makefile.am b/bat/Makefile.am index 0849d0d..3a76d7f 100644 --- a/bat/Makefile.am +++ b/bat/Makefile.am @@ -1,4 +1,7 @@ bin_PROGRAMS = bat +man_MANS = bat.1
+EXTRA_DIST = bat.1
bat_SOURCES = \ bat.c \ diff --git a/bat/bat.1 b/bat/bat.1 new file mode 100644 index 0000000..e00fc27 --- /dev/null +++ b/bat/bat.1 @@ -0,0 +1,158 @@ +.TH BAT 1 "20th October 2015" +.SH NAME +bat - command-line sound tester for ALSA sound card driver
+.SH SYNOPSIS +\fBbat\fP [\fIflags\fP]
+.SH DESCRIPTION +\fBBAT(Basic Audio Tester)\fP is a simple command-line utility intended +to help automate audio driver and sound server testing with little human +interaction. BAT can be used to test audio quality, stress test features +and test audio before and after PM state changes.
+BAT's design is relatively simple. BAT plays an audio stream and captures +the same stream in either a digital or analog loop back. It then compares +the captured stream using a FFT to the original to determine if the test +case passes or fails.
+BAT can either run wholly on the target machine being tested (standalone +mode) or can run as a client/server mode where by bat client runs on the +target and runs as a server on a separate tester machine. The client/server +mode still requires some manual interaction for synchronization, but this +is actively being developed for future releases.
+The hardware testing configuration may require the use of an analog cable +connecting target to tester machines or a cable to create an analog +loopback if no loopback mode is not available on the sound hardware that +is being tested. +An analog loopback cable can be used to connect the "line in" to "line out" +jacks to create a loopback. If only headphone and mic jacks (or combo jack) +are available then the following simple circuit can be used to create an +analog loopback :-
+https://source.android.com/devices/audio/loopback.html
+.SH OPTIONS +.TP +\fI-h, --help\fP +Help: show syntax. +.TP +\fI-D\fP +Select sound card to be tested by name. +.TP +\fI-P\fP +Select the playback PCM device. +.TP +\fI-C\fP +Select the capture PCM device. +.TP +\fI-f\fP +Sample format +.br +Recognized sample formats are: U8 S16_LE S24_3LE S32_LE +.br +Some of these may not be available on selected hardware +.br +The available format shortcuts are: +.nf +-f cd (16 bit little endian, 44100, stereo) [-f S16_LE -c2 -r44100] +-f dat (16 bit little endian, 48000, stereo) [-f S16_LE -c2 -r48000] +.fi +If no format is given S16_LE is used. +.TP +\fI-c\fP +The number of channels. The default is one channel. +Valid values at the moment are 1 or 2. +.TP +\fI-r\fP +Sampling rate in Hertz. The default rate is 44100 Hertz. +Valid values depends on hardware support. +.TP +\fI-n\fP +Duration of generated signal. +The value could be either of the two forms: +.br +1. Decimal integer, means number of frames; +.br +2. Floating point with suffix 's', means number of seconds. +.br +The default is 2 seconds. +.TP +\fI-k\fP +Sigma k value for analysis. +.br +The analysis function reads data from WAV file, run FFT against the data +to get magnitude of frequency vectors, and then calculates the average +value and standard deviation of frequency vectors. After that, we define +a threshold: +.br +threshold = k * standard_deviation + mean_value +.br +Frequencies with amplitude larger than threshold will be recognized as a +peak, and the frequency with largest peak value will be recognized as a +detected frequency. +.br +BAT then compares the detected frequency to target frequency, to decide +if the detecting passes or fails. +.br +The default value is 3.0. +.TP +\fI-F\fP +Target frequency for signal generation and analysis, in Hertz. +The default is 997.0 Hertz. +Valid range is (DC_THRESHOLD, 40% * Sampling rate). +.TP +\fI-p\fP +Total number of periods to play or capture. +.TP +\fI--log=#\fP +Write stderr and stdout output to this log file. +.TP +\fI--file=#\fP +Input WAV file for playback. +.TP +\fI--saveplay=#\fP +Target WAV file to save capture test content. +.TP +\fI--local\fP +Internal loopback mode. +Playback, capture and analysis internal to BAT only. This is intended for +developers to test new BAT features as no audio is routed outside of BAT.
+.SH EXAMPLES
+.TP +\fBbat -P plughw:0,0 -C plughw:0,0 -c 2 -f S32_LE -F 250\fR +Generate and play a sine wave of 250 Hertz with 2 channel and S32_LE format, +and then capture and analyze.
+.TP +\fBbat -P plughw:0,0 -C plughw:0,0 --file 500Hz.wav\fR +Play the RIFF WAV file "500Hz.wav" which contains 500 Hertz waveform LPCM +data, and then capture and analyze.
+.SH RETURN VALUE +.br +On success, returns 0. +.br +If no peak be detected, returns -1001; +.br +If only DC be detected, returns -1002; +.br +If peak frequency does not match with the target frequency, returns -1003.
+.SH SEE ALSO +\fB +aplay(1) +\fP
+.SH BUGS +Currently only support RIFF WAV format with PCM data. Please report any bugs to +the alsa-devel mailing list.
+.SH AUTHOR +\fBbat\fP is by Liam Girdwood liam.r.girdwood@linux.intel.com, Bernard Gautier +bernard.gautier@intel.com and Han Lu han.lu@intel.com. +This document is by Liam Girdwood liam.r.girdwood@linux.intel.com and Han Lu
+han.lu@intel.com.
1.9.1