[alsa-devel] [PATCH 1/1] BAT: Add man page

[han.lu at intel.com]

From: "Lu, Han" <han.lu at 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 at intel.com>

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 at linux.intel.com>, Bernard Gautier
+<bernard.gautier at intel.com> and Han Lu <han.lu at intel.com>.
+This document is by Liam Girdwood <liam.r.girdwood at linux.intel.com> and Han Lu
+<han.lu at intel.com>.
-- 
1.9.1