| Message ID | 20210428062214.335567-1-hj.tedd.an@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [BlueZ,v2] monitor: Update manpage | expand |
This is automated email and please do not reply to this email!
Dear submitter,
Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=474313
---Test result---
Test Summary:
CheckPatch FAIL 0.38 seconds
GitLint PASS 0.12 seconds
Prep - Setup ELL PASS 46.61 seconds
Build - Prep PASS 0.11 seconds
Build - Configure PASS 8.24 seconds
Build - Make FAIL 197.06 seconds
Make Check FAIL 0.65 seconds
Make Dist PASS 12.74 seconds
Make Dist - Configure PASS 5.11 seconds
Make Dist - Make PASS 79.62 seconds
Build w/ext ELL - Configure PASS 8.24 seconds
Build w/ext ELL - Make FAIL 185.73 seconds
Details
##############################
Test: CheckPatch - FAIL
Desc: Run checkpatch.pl script with rule in .checkpatch.conf
Output:
monitor: Update manpage
WARNING:SPDX_LICENSE_TAG: Missing or malformed SPDX-License-Identifier tag in line 1
#140: FILE: monitor/btmon.rst:1:
+=====
- total: 0 errors, 1 warnings, 240 lines checked
NOTE: For some of the reported defects, checkpatch may be able to
mechanically convert to the typical style using --fix or --fix-inplace.
"[PATCH] monitor: Update manpage" has style problems, please review.
NOTE: Ignored message types: COMMIT_MESSAGE COMPLEX_MACRO CONST_STRUCT FILE_PATH_CHANGES MISSING_SIGN_OFF PREFER_PACKED SPLIT_STRING SSCANF_TO_KSTRTO
NOTE: If any of the errors are false positives, please report
them to the maintainer, see CHECKPATCH in MAINTAINERS.
##############################
Test: GitLint - PASS
Desc: Run gitlint with rule in .gitlint
##############################
Test: Prep - Setup ELL - PASS
Desc: Clone, build, and install ELL
##############################
Test: Build - Prep - PASS
Desc: Prepare environment for build
##############################
Test: Build - Configure - PASS
Desc: Configure the BlueZ source tree
##############################
Test: Build - Make - FAIL
Desc: Build the BlueZ source tree
Output:
monitor/btmon.rst:151: (WARNING/2) Cannot analyze code. Pygments package not found.
Exiting due to level-2 (WARNING) system message.
make[1]: *** [Makefile:11668: monitor/btmon.1] Error 1
make: *** [Makefile:4069: all] Error 2
##############################
Test: Make Check - FAIL
Desc: Run 'make check'
Output:
monitor/btmon.rst:151: (WARNING/2) Cannot analyze code. Pygments package not found.
Exiting due to level-2 (WARNING) system message.
make[1]: *** [Makefile:11668: monitor/btmon.1] Error 1
make: *** [Makefile:10324: check] Error 2
##############################
Test: Make Dist - PASS
Desc: Run 'make dist' and build the distribution tarball
##############################
Test: Make Dist - Configure - PASS
Desc: Configure the source from distribution tarball
##############################
Test: Make Dist - Make - PASS
Desc: Build the source from distribution tarball
##############################
Test: Build w/ext ELL - Configure - PASS
Desc: Configure BlueZ source with '--enable-external-ell' configuration
##############################
Test: Build w/ext ELL - Make - FAIL
Desc: Build BlueZ source with '--enable-external-ell' configuration
Output:
monitor/btmon.rst:151: (WARNING/2) Cannot analyze code. Pygments package not found.
Exiting due to level-2 (WARNING) system message.
make[1]: *** [Makefile:11668: monitor/btmon.1] Error 1
make: *** [Makefile:4069: all] Error 2
---
Regards,
Linux Bluetooth
Hi Tedd, On Tue, Apr 27, 2021 at 11:24 PM Tedd Ho-Jeong An <hj.tedd.an@gmail.com> wrote: > > From: Tedd Ho-Jeong An <tedd.an@intel.com> > > This patch updates the manpage for btmon written in rst format. > --- > Makefile.am | 26 ++++--- > Makefile.tools | 4 ++ > configure.ac | 4 ++ > doc/btmon.txt | 35 ---------- > monitor/btmon.rst | 172 ++++++++++++++++++++++++++++++++++++++++++++++ I do wonder why you change the location from doc to monitor, I think we actually should keep all the documentation under doc and perhaps even have a dedicated make target for those since we would likely want to generate all the manpages from rst which may be time consuming so people not interested on it can just skip it. > 5 files changed, 197 insertions(+), 44 deletions(-) > delete mode 100644 doc/btmon.txt > create mode 100644 monitor/btmon.rst > > diff --git a/Makefile.am b/Makefile.am > index f98243f72..759110cbd 100644 > --- a/Makefile.am > +++ b/Makefile.am > @@ -60,6 +60,11 @@ else > build_plugindir = $(plugindir) > endif > > +if MANPAGES > +man_MANS = > +endif > + > +manual_pages = monitor/btmon.1 > > plugin_LTLIBRARIES = > > @@ -579,13 +584,7 @@ if LIBRARY > pkgconfig_DATA = lib/bluez.pc > endif > > -manual_pages = doc/btmon.1 > - > -if MANPAGES > -dist_noinst_MANS += $(manual_pages) > -endif > - > -EXTRA_DIST += $(manual_pages:.1=.txt) > +EXTRA_DIST += $(manual_pages:.1=.rst) > > DISTCHECK_CONFIGURE_FLAGS = --disable-datafiles --enable-library \ > --enable-health \ > @@ -607,11 +606,20 @@ SED_PROCESS = $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \ > $(SED) -e 's,@pkglibexecdir\@,$(pkglibexecdir),g' \ > < $< > $@ > > +if RUN_RST2MAN > +RST2MAN_PROCESS = $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \ > + $(RST2MAN) --strict --no-raw \ > + --no-generator --no-datestamp $< $@ > +else > +RST2MAN_PROCESS = $(AM_V_GEN)test -f $@ || \ > + { echo "Generated manual page $@ does not exist"; false; } > +endif > + > %.service: %.service.in Makefile > $(SED_PROCESS) > > -%.1: %.txt > - $(AM_V_GEN)a2x --doctype manpage --format manpage $(srcdir)/$< > +%.1: %.rst Makefile > + $(RST2MAN_PROCESS) > > src/builtin.h: src/genbuiltin $(builtin_sources) > $(AM_V_GEN)$(srcdir)/src/genbuiltin $(builtin_modules) > $@ > diff --git a/Makefile.tools b/Makefile.tools > index 57e858290..9b452aa74 100644 > --- a/Makefile.tools > +++ b/Makefile.tools > @@ -49,6 +49,10 @@ monitor_btmon_SOURCES = monitor/main.c monitor/bt.h \ > monitor/tty.h > monitor_btmon_LDADD = lib/libbluetooth-internal.la \ > src/libshared-mainloop.la $(UDEV_LIBS) -ldl > + > +if MANPAGES > +man_MANS += monitor/btmon.1 > +endif > endif > > if LOGGER > diff --git a/configure.ac b/configure.ac > index dbd98c9ad..d7e4766e4 100644 > --- a/configure.ac > +++ b/configure.ac > @@ -326,7 +326,11 @@ AM_CONDITIONAL(DATAFILES, test "${enable_datafiles}" != "no") > AC_ARG_ENABLE(manpages, AC_HELP_STRING([--enable-manpages], > [enable building of manual pages]), > [enable_manpages=${enableval}]) > +if (test "${enable_manpages}" != "no"); then > + AC_CHECK_PROGS(RST2MAN, [rst2man rst2man.py], "no") > +fi > AM_CONDITIONAL(MANPAGES, test "${enable_manpages}" = "yes") > +AM_CONDITIONAL(RUN_RST2MAN, test "${enable_manpages}" = "yes" && test "${RST2MAN}" != "no") > > AC_ARG_ENABLE(testing, AC_HELP_STRING([--enable-testing], > [enable testing tools]), > diff --git a/doc/btmon.txt b/doc/btmon.txt > deleted file mode 100644 > index 7a7fc537b..000000000 > --- a/doc/btmon.txt > +++ /dev/null > @@ -1,35 +0,0 @@ > -BTMON(1) > -======== > -:doctype: manpage > - > - > -NAME > ----- > -btmon - Bluetooth monitor > - > - > -SYNOPSIS > --------- > -*btmon* ['OPTIONS'] > - > - > -DESCRIPTION > ------------ > -The btmon(1) command provides access to the Bluetooth subsystem monitor > -infrastructure for reading HCI traces. > - > - > -AUTHOR > ------- > -btmon was originally written by Marcel Holtmann. > - > - > -RESOURCES > ---------- > -See <http://www.bluez.org/> > - > - > -COPYING > -------- > -Free use of this software is granted under ther terms of the GNU Lesser > -General Public Licenses (LGPL). > diff --git a/monitor/btmon.rst b/monitor/btmon.rst > new file mode 100644 > index 000000000..29d275eb3 > --- /dev/null > +++ b/monitor/btmon.rst > @@ -0,0 +1,172 @@ > +===== > +btmon > +===== > + > +----------------- > +Bluetooth monitor > +----------------- > + > +:Authors: - Marcel Holtmann <marcel@holtmann.org> > + - Tedd Ho-Jeong An <tedd.an@intel.com> > +:Copyright: Free use of this software is granted under ther terms of the GNU > + Lesser General Public Licenses (LGPL). > +:Version: BlueZ > +:Date: April 2021 > +:Manual section: 1 > +:Manual group: Linux System Administration > + > +SYNOPSYS > +======== > + > +**btmon** [*OPTIONS* ...] > + > +DESCRIPTION > +=========== > + > +The btmon(1) command provides access to the Bluetooth subsystem monitor > +infrastructure for reading HCI traces. > + > +OPTIONS > +======= > + > +-r FILE, --read FILE Read traces in btsnoop format from *FILE*. > +-w FILE, --write FILE Save traces in btsnoop format to *FILE*. > +-a FILE, --analyze FILE Analyze traces in btsnoop format from *FILE*. > + It displays the devices found in the *FILE* with > + its packets by type. > +-s SOCKET, --server SOCKET Start monitor server socket. > +-p PRIORITY, --priority PRIORITY Show only priority or lower for user log. > + > +.. list-table:: > + :header-rows: 1 > + :widths: auto > + :stub-columns: 1 > + > + * - *PRIORITY* > + - NAME > + > + * - **3** > + - Error > + > + * - **4** > + - Warning > + > + * - **6** > + - Information (Default) > + > + * - **7** > + - Debug. **debug** can be used. > + > +-i NUM, --index NUM Show only specified controller. *hciNUM* is also > + acceptable. This is useful to capture the traces > + from the specific controller when the multiple > + controllers are presented. > + > +-d TTY, --tty TTY Read data from *TTY*. > + > +-B SPEED, --rate SPEED Set TTY speed. The default *SPEED* is 115300 > + > +-V COMPID, --vendor COMPID Set the default company identifier. The *COMPID* is > + a unique number assigned by the Bluetooth SIG to > + a member company and can be found/searched from the > + Bluetooth SIG webpage. > + > + For example, Intel is 2 and Realtek is 93. > + > +-M, --mgmt Open channel for mgmt events. > + > +-t, --time Show a time instead of time offset. > + > +-T, --date Show a time and date information instead of > + time offset. > + > +-S, --sco Dump SCO traffic in raw hex format. > + > +-A, --a2dp Dump A2DP stream traffic in a raw hex format. > + > +-E IP, --ellisys IP Send Ellisys HCI Injection. > + > +-P, --no-pager Disable pager usage while reading the log file. > + > +-J OPTIONS, --jlink OPTIONS Read data from RTT. Each options are comma(,) > + seprated without spaces. > + > +.. list-table:: > + :header-rows: 1 > + :widths: auto > + :stub-columns: 1 > + > + * - *OPTIONS* > + - Description > + > + * - **DEVICE** > + - Required. Set the target device. > + > + * - **SERIALNO** > + - (Optional) Set the USB serial number. Default is **0**. > + > + * - **INTERFACE** > + - (Optional) Target interface. Default is **swd**. > + > + * - **SPEED** > + - (Optional) Set target interface speed in kHz. Default is **1000**. > + > +-R OPTIONS, --rtt OPTIONS RTT control block parameters. Each options are > + comma(,) seprated without spaces. > + > +.. list-table:: > + :header-rows: 1 > + :widths: auto > + :stub-columns: 1 > + > + * - *OPTIONS* > + - Description > + > + * - **ADDRESS** > + - (Optional) Address of RTT buffer. Default is **0x00** > + > + * - **AREA** > + - (Optional) Size of range to search in RTT buffer. Default is **0** > + > + * - **NAME** > + - (Optional) Buffer name. Default is **btmonitor** > + > +-C WIDTH, --columns WIDTH Output width if not a terminal > + > +-c MODE, --color MODE Set output color. The possible *MODE* values are: > + **auto|always|never**. > + > + Default value is **auto** > + > +-v, --version Show version > + > +-h, --help Show help options > + > +EXAMPLES > +======== > + > +Capture the traces from hci0 to hcidump.log file > +------------------------------------------------ > + > +.. code-block:: bash > + > + $ btmon -i hci0 -w hcidump.log > + > +Open the trace file > +------------------- > + > +.. code-block:: bash > + > + $ btmon -r hcidump.log > + > + > +RESOURCES > +========= > + > +http://www.bluez.org > + > +REPORTING BUGS > +============== > + > +linux-bluetooth@vger.kernel.org > + > -- > 2.25.1 >
Hi Luiz, >> This patch updates the manpage for btmon written in rst format. >> --- >> Makefile.am | 26 ++++--- >> Makefile.tools | 4 ++ >> configure.ac | 4 ++ >> doc/btmon.txt | 35 ---------- >> monitor/btmon.rst | 172 ++++++++++++++++++++++++++++++++++++++++++++++ > > I do wonder why you change the location from doc to monitor, I think > we actually should keep all the documentation under doc and perhaps > even have a dedicated make target for those since we would likely want > to generate all the manpages from rst which may be time consuming so > people not interested on it can just skip it. in iwd, we moved all the manual pages next to the source of the daemon/tools. So yes, I would put this into monitor directory as well. Regards Marcel
Hi Luiz, On Thu, 2021-04-29 at 20:51 -0700, Luiz Augusto von Dentz wrote: > Hi Tedd, > > On Tue, Apr 27, 2021 at 11:24 PM Tedd Ho-Jeong An <hj.tedd.an@gmail.com> wrote: > > From: Tedd Ho-Jeong An <tedd.an@intel.com> > > > > This patch updates the manpage for btmon written in rst format. > > --- > > Makefile.am | 26 ++++--- > > Makefile.tools | 4 ++ > > configure.ac | 4 ++ > > doc/btmon.txt | 35 ---------- > > monitor/btmon.rst | 172 ++++++++++++++++++++++++++++++++++++++++++++++ > > I do wonder why you change the location from doc to monitor, I think > we actually should keep all the documentation under doc and perhaps > even have a dedicated make target for those since we would likely want > to generate all the manpages from rst which may be time consuming so > people not interested on it can just skip it. I converted all manpages in the tree to .rst and ready to submit. Can I combine all in this series or wait for this to merge first? > > 5 files changed, 197 insertions(+), 44 deletions(-) > > delete mode 100644 doc/btmon.txt > > create mode 100644 monitor/btmon.rst > > > > diff --git a/Makefile.am b/Makefile.am > > index f98243f72..759110cbd 100644 > > --- a/Makefile.am > > +++ b/Makefile.am > > @@ -60,6 +60,11 @@ else > > build_plugindir = $(plugindir) > > endif > > > > +if MANPAGES > > +man_MANS = > > +endif > > + > > +manual_pages = monitor/btmon.1 > > > > plugin_LTLIBRARIES = > > > > @@ -579,13 +584,7 @@ if LIBRARY > > pkgconfig_DATA = lib/bluez.pc > > endif > > > > -manual_pages = doc/btmon.1 > > - > > -if MANPAGES > > -dist_noinst_MANS += $(manual_pages) > > -endif > > - > > -EXTRA_DIST += $(manual_pages:.1=.txt) > > +EXTRA_DIST += $(manual_pages:.1=.rst) > > > > DISTCHECK_CONFIGURE_FLAGS = --disable-datafiles --enable-library \ > > --enable-health \ > > @@ -607,11 +606,20 @@ SED_PROCESS = $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \ > > $(SED) -e 's,@pkglibexecdir\@,$(pkglibexecdir),g' \ > > < $< > $@ > > > > +if RUN_RST2MAN > > +RST2MAN_PROCESS = $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \ > > + $(RST2MAN) --strict --no-raw \ > > + --no-generator --no-datestamp $< $@ > > +else > > +RST2MAN_PROCESS = $(AM_V_GEN)test -f $@ || \ > > + { echo "Generated manual page $@ does not exist"; false; } > > +endif > > + > > %.service: %.service.in Makefile > > $(SED_PROCESS) > > > > -%.1: %.txt > > - $(AM_V_GEN)a2x --doctype manpage --format manpage $(srcdir)/$< > > +%.1: %.rst Makefile > > + $(RST2MAN_PROCESS) > > > > src/builtin.h: src/genbuiltin $(builtin_sources) > > $(AM_V_GEN)$(srcdir)/src/genbuiltin $(builtin_modules) > $@ > > diff --git a/Makefile.tools b/Makefile.tools > > index 57e858290..9b452aa74 100644 > > --- a/Makefile.tools > > +++ b/Makefile.tools > > @@ -49,6 +49,10 @@ monitor_btmon_SOURCES = monitor/main.c monitor/bt.h \ > > monitor/tty.h > > monitor_btmon_LDADD = lib/libbluetooth-internal.la \ > > src/libshared-mainloop.la $(UDEV_LIBS) -ldl > > + > > +if MANPAGES > > +man_MANS += monitor/btmon.1 > > +endif > > endif > > > > if LOGGER > > diff --git a/configure.ac b/configure.ac > > index dbd98c9ad..d7e4766e4 100644 > > --- a/configure.ac > > +++ b/configure.ac > > @@ -326,7 +326,11 @@ AM_CONDITIONAL(DATAFILES, test "${enable_datafiles}" != "no") > > AC_ARG_ENABLE(manpages, AC_HELP_STRING([--enable-manpages], > > [enable building of manual pages]), > > [enable_manpages=${enableval}]) > > +if (test "${enable_manpages}" != "no"); then > > + AC_CHECK_PROGS(RST2MAN, [rst2man rst2man.py], "no") > > +fi > > AM_CONDITIONAL(MANPAGES, test "${enable_manpages}" = "yes") > > +AM_CONDITIONAL(RUN_RST2MAN, test "${enable_manpages}" = "yes" && test "${RST2MAN}" != "no") > > > > AC_ARG_ENABLE(testing, AC_HELP_STRING([--enable-testing], > > [enable testing tools]), > > diff --git a/doc/btmon.txt b/doc/btmon.txt > > deleted file mode 100644 > > index 7a7fc537b..000000000 > > --- a/doc/btmon.txt > > +++ /dev/null > > @@ -1,35 +0,0 @@ > > -BTMON(1) > > -======== > > -:doctype: manpage > > - > > - > > -NAME > > ----- > > -btmon - Bluetooth monitor > > - > > - > > -SYNOPSIS > > --------- > > -*btmon* ['OPTIONS'] > > - > > - > > -DESCRIPTION > > ------------ > > -The btmon(1) command provides access to the Bluetooth subsystem monitor > > -infrastructure for reading HCI traces. > > - > > - > > -AUTHOR > > ------- > > -btmon was originally written by Marcel Holtmann. > > - > > - > > -RESOURCES > > ---------- > > -See <http://www.bluez.org/> > > - > > - > > -COPYING > > -------- > > -Free use of this software is granted under ther terms of the GNU Lesser > > -General Public Licenses (LGPL). > > diff --git a/monitor/btmon.rst b/monitor/btmon.rst > > new file mode 100644 > > index 000000000..29d275eb3 > > --- /dev/null > > +++ b/monitor/btmon.rst > > @@ -0,0 +1,172 @@ > > +===== > > +btmon > > +===== > > + > > +----------------- > > +Bluetooth monitor > > +----------------- > > + > > +:Authors: - Marcel Holtmann <marcel@holtmann.org> > > + - Tedd Ho-Jeong An <tedd.an@intel.com> > > +:Copyright: Free use of this software is granted under ther terms of the GNU > > + Lesser General Public Licenses (LGPL). > > +:Version: BlueZ > > +:Date: April 2021 > > +:Manual section: 1 > > +:Manual group: Linux System Administration > > + > > +SYNOPSYS > > +======== > > + > > +**btmon** [*OPTIONS* ...] > > + > > +DESCRIPTION > > +=========== > > + > > +The btmon(1) command provides access to the Bluetooth subsystem monitor > > +infrastructure for reading HCI traces. > > + > > +OPTIONS > > +======= > > + > > +-r FILE, --read FILE Read traces in btsnoop format from *FILE*. > > +-w FILE, --write FILE Save traces in btsnoop format to *FILE*. > > +-a FILE, --analyze FILE Analyze traces in btsnoop format from *FILE*. > > + It displays the devices found in the *FILE* with > > + its packets by type. > > +-s SOCKET, --server SOCKET Start monitor server socket. > > +-p PRIORITY, --priority PRIORITY Show only priority or lower for user log. > > + > > +.. list-table:: > > + :header-rows: 1 > > + :widths: auto > > + :stub-columns: 1 > > + > > + * - *PRIORITY* > > + - NAME > > + > > + * - **3** > > + - Error > > + > > + * - **4** > > + - Warning > > + > > + * - **6** > > + - Information (Default) > > + > > + * - **7** > > + - Debug. **debug** can be used. > > + > > +-i NUM, --index NUM Show only specified controller. *hciNUM* is also > > + acceptable. This is useful to capture the traces > > + from the specific controller when the multiple > > + controllers are presented. > > + > > +-d TTY, --tty TTY Read data from *TTY*. > > + > > +-B SPEED, --rate SPEED Set TTY speed. The default *SPEED* is 115300 > > + > > +-V COMPID, --vendor COMPID Set the default company identifier. The *COMPID* is > > + a unique number assigned by the Bluetooth SIG to > > + a member company and can be found/searched from the > > + Bluetooth SIG webpage. > > + > > + For example, Intel is 2 and Realtek is 93. > > + > > +-M, --mgmt Open channel for mgmt events. > > + > > +-t, --time Show a time instead of time offset. > > + > > +-T, --date Show a time and date information instead of > > + time offset. > > + > > +-S, --sco Dump SCO traffic in raw hex format. > > + > > +-A, --a2dp Dump A2DP stream traffic in a raw hex format. > > + > > +-E IP, --ellisys IP Send Ellisys HCI Injection. > > + > > +-P, --no-pager Disable pager usage while reading the log file. > > + > > +-J OPTIONS, --jlink OPTIONS Read data from RTT. Each options are comma(,) > > + seprated without spaces. > > + > > +.. list-table:: > > + :header-rows: 1 > > + :widths: auto > > + :stub-columns: 1 > > + > > + * - *OPTIONS* > > + - Description > > + > > + * - **DEVICE** > > + - Required. Set the target device. > > + > > + * - **SERIALNO** > > + - (Optional) Set the USB serial number. Default is **0**. > > + > > + * - **INTERFACE** > > + - (Optional) Target interface. Default is **swd**. > > + > > + * - **SPEED** > > + - (Optional) Set target interface speed in kHz. Default is **1000**. > > + > > +-R OPTIONS, --rtt OPTIONS RTT control block parameters. Each options are > > + comma(,) seprated without spaces. > > + > > +.. list-table:: > > + :header-rows: 1 > > + :widths: auto > > + :stub-columns: 1 > > + > > + * - *OPTIONS* > > + - Description > > + > > + * - **ADDRESS** > > + - (Optional) Address of RTT buffer. Default is **0x00** > > + > > + * - **AREA** > > + - (Optional) Size of range to search in RTT buffer. Default is **0** > > + > > + * - **NAME** > > + - (Optional) Buffer name. Default is **btmonitor** > > + > > +-C WIDTH, --columns WIDTH Output width if not a terminal > > + > > +-c MODE, --color MODE Set output color. The possible *MODE* values are: > > + **auto|always|never**. > > + > > + Default value is **auto** > > + > > +-v, --version Show version > > + > > +-h, --help Show help options > > + > > +EXAMPLES > > +======== > > + > > +Capture the traces from hci0 to hcidump.log file > > +------------------------------------------------ > > + > > +.. code-block:: bash > > + > > + $ btmon -i hci0 -w hcidump.log > > + > > +Open the trace file > > +------------------- > > + > > +.. code-block:: bash > > + > > + $ btmon -r hcidump.log > > + > > + > > +RESOURCES > > +========= > > + > > +http://www.bluez.org > > + > > +REPORTING BUGS > > +============== > > + > > +linux-bluetooth@vger.kernel.org > > + > > -- > > 2.25.1 > > > >
Hi Tedd, On Fri, Apr 30, 2021 at 2:43 PM Tedd Ho-Jeong An <hj.tedd.an@gmail.com> wrote: > > Hi Luiz, > > On Thu, 2021-04-29 at 20:51 -0700, Luiz Augusto von Dentz wrote: > > Hi Tedd, > > > > On Tue, Apr 27, 2021 at 11:24 PM Tedd Ho-Jeong An <hj.tedd.an@gmail.com> wrote: > > > From: Tedd Ho-Jeong An <tedd.an@intel.com> > > > > > > This patch updates the manpage for btmon written in rst format. > > > --- > > > Makefile.am | 26 ++++--- > > > Makefile.tools | 4 ++ > > > configure.ac | 4 ++ > > > doc/btmon.txt | 35 ---------- > > > monitor/btmon.rst | 172 ++++++++++++++++++++++++++++++++++++++++++++++ > > > > I do wonder why you change the location from doc to monitor, I think > > we actually should keep all the documentation under doc and perhaps > > even have a dedicated make target for those since we would likely want > > to generate all the manpages from rst which may be time consuming so > > people not interested on it can just skip it. > > I converted all manpages in the tree to .rst and ready to submit. > Can I combine all in this series or wait for this to merge first? Have you added a make target for those? I really don't mind having the manpages generated within the same location of the binary, although I think it would be more organized to have it in one place, but a make target would probably be a good practice. > > > 5 files changed, 197 insertions(+), 44 deletions(-) > > > delete mode 100644 doc/btmon.txt > > > create mode 100644 monitor/btmon.rst > > > > > > diff --git a/Makefile.am b/Makefile.am > > > index f98243f72..759110cbd 100644 > > > --- a/Makefile.am > > > +++ b/Makefile.am > > > @@ -60,6 +60,11 @@ else > > > build_plugindir = $(plugindir) > > > endif > > > > > > +if MANPAGES > > > +man_MANS = > > > +endif > > > + > > > +manual_pages = monitor/btmon.1 > > > > > > plugin_LTLIBRARIES = > > > > > > @@ -579,13 +584,7 @@ if LIBRARY > > > pkgconfig_DATA = lib/bluez.pc > > > endif > > > > > > -manual_pages = doc/btmon.1 > > > - > > > -if MANPAGES > > > -dist_noinst_MANS += $(manual_pages) > > > -endif > > > - > > > -EXTRA_DIST += $(manual_pages:.1=.txt) > > > +EXTRA_DIST += $(manual_pages:.1=.rst) > > > > > > DISTCHECK_CONFIGURE_FLAGS = --disable-datafiles --enable-library \ > > > --enable-health \ > > > @@ -607,11 +606,20 @@ SED_PROCESS = $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \ > > > $(SED) -e 's,@pkglibexecdir\@,$(pkglibexecdir),g' \ > > > < $< > $@ > > > > > > +if RUN_RST2MAN > > > +RST2MAN_PROCESS = $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \ > > > + $(RST2MAN) --strict --no-raw \ > > > + --no-generator --no-datestamp $< $@ > > > +else > > > +RST2MAN_PROCESS = $(AM_V_GEN)test -f $@ || \ > > > + { echo "Generated manual page $@ does not exist"; false; } > > > +endif > > > + > > > %.service: %.service.in Makefile > > > $(SED_PROCESS) > > > > > > -%.1: %.txt > > > - $(AM_V_GEN)a2x --doctype manpage --format manpage $(srcdir)/$< > > > +%.1: %.rst Makefile > > > + $(RST2MAN_PROCESS) > > > > > > src/builtin.h: src/genbuiltin $(builtin_sources) > > > $(AM_V_GEN)$(srcdir)/src/genbuiltin $(builtin_modules) > $@ > > > diff --git a/Makefile.tools b/Makefile.tools > > > index 57e858290..9b452aa74 100644 > > > --- a/Makefile.tools > > > +++ b/Makefile.tools > > > @@ -49,6 +49,10 @@ monitor_btmon_SOURCES = monitor/main.c monitor/bt.h \ > > > monitor/tty.h > > > monitor_btmon_LDADD = lib/libbluetooth-internal.la \ > > > src/libshared-mainloop.la $(UDEV_LIBS) -ldl > > > + > > > +if MANPAGES > > > +man_MANS += monitor/btmon.1 > > > +endif > > > endif > > > > > > if LOGGER > > > diff --git a/configure.ac b/configure.ac > > > index dbd98c9ad..d7e4766e4 100644 > > > --- a/configure.ac > > > +++ b/configure.ac > > > @@ -326,7 +326,11 @@ AM_CONDITIONAL(DATAFILES, test "${enable_datafiles}" != "no") > > > AC_ARG_ENABLE(manpages, AC_HELP_STRING([--enable-manpages], > > > [enable building of manual pages]), > > > [enable_manpages=${enableval}]) > > > +if (test "${enable_manpages}" != "no"); then > > > + AC_CHECK_PROGS(RST2MAN, [rst2man rst2man.py], "no") > > > +fi > > > AM_CONDITIONAL(MANPAGES, test "${enable_manpages}" = "yes") > > > +AM_CONDITIONAL(RUN_RST2MAN, test "${enable_manpages}" = "yes" && test "${RST2MAN}" != "no") > > > > > > AC_ARG_ENABLE(testing, AC_HELP_STRING([--enable-testing], > > > [enable testing tools]), > > > diff --git a/doc/btmon.txt b/doc/btmon.txt > > > deleted file mode 100644 > > > index 7a7fc537b..000000000 > > > --- a/doc/btmon.txt > > > +++ /dev/null > > > @@ -1,35 +0,0 @@ > > > -BTMON(1) > > > -======== > > > -:doctype: manpage > > > - > > > - > > > -NAME > > > ----- > > > -btmon - Bluetooth monitor > > > - > > > - > > > -SYNOPSIS > > > --------- > > > -*btmon* ['OPTIONS'] > > > - > > > - > > > -DESCRIPTION > > > ------------ > > > -The btmon(1) command provides access to the Bluetooth subsystem monitor > > > -infrastructure for reading HCI traces. > > > - > > > - > > > -AUTHOR > > > ------- > > > -btmon was originally written by Marcel Holtmann. > > > - > > > - > > > -RESOURCES > > > ---------- > > > -See <http://www.bluez.org/> > > > - > > > - > > > -COPYING > > > -------- > > > -Free use of this software is granted under ther terms of the GNU Lesser > > > -General Public Licenses (LGPL). > > > diff --git a/monitor/btmon.rst b/monitor/btmon.rst > > > new file mode 100644 > > > index 000000000..29d275eb3 > > > --- /dev/null > > > +++ b/monitor/btmon.rst > > > @@ -0,0 +1,172 @@ > > > +===== > > > +btmon > > > +===== > > > + > > > +----------------- > > > +Bluetooth monitor > > > +----------------- > > > + > > > +:Authors: - Marcel Holtmann <marcel@holtmann.org> > > > + - Tedd Ho-Jeong An <tedd.an@intel.com> > > > +:Copyright: Free use of this software is granted under ther terms of the GNU > > > + Lesser General Public Licenses (LGPL). > > > +:Version: BlueZ > > > +:Date: April 2021 > > > +:Manual section: 1 > > > +:Manual group: Linux System Administration > > > + > > > +SYNOPSYS > > > +======== > > > + > > > +**btmon** [*OPTIONS* ...] > > > + > > > +DESCRIPTION > > > +=========== > > > + > > > +The btmon(1) command provides access to the Bluetooth subsystem monitor > > > +infrastructure for reading HCI traces. > > > + > > > +OPTIONS > > > +======= > > > + > > > +-r FILE, --read FILE Read traces in btsnoop format from *FILE*. > > > +-w FILE, --write FILE Save traces in btsnoop format to *FILE*. > > > +-a FILE, --analyze FILE Analyze traces in btsnoop format from *FILE*. > > > + It displays the devices found in the *FILE* with > > > + its packets by type. > > > +-s SOCKET, --server SOCKET Start monitor server socket. > > > +-p PRIORITY, --priority PRIORITY Show only priority or lower for user log. > > > + > > > +.. list-table:: > > > + :header-rows: 1 > > > + :widths: auto > > > + :stub-columns: 1 > > > + > > > + * - *PRIORITY* > > > + - NAME > > > + > > > + * - **3** > > > + - Error > > > + > > > + * - **4** > > > + - Warning > > > + > > > + * - **6** > > > + - Information (Default) > > > + > > > + * - **7** > > > + - Debug. **debug** can be used. > > > + > > > +-i NUM, --index NUM Show only specified controller. *hciNUM* is also > > > + acceptable. This is useful to capture the traces > > > + from the specific controller when the multiple > > > + controllers are presented. > > > + > > > +-d TTY, --tty TTY Read data from *TTY*. > > > + > > > +-B SPEED, --rate SPEED Set TTY speed. The default *SPEED* is 115300 > > > + > > > +-V COMPID, --vendor COMPID Set the default company identifier. The *COMPID* is > > > + a unique number assigned by the Bluetooth SIG to > > > + a member company and can be found/searched from the > > > + Bluetooth SIG webpage. > > > + > > > + For example, Intel is 2 and Realtek is 93. > > > + > > > +-M, --mgmt Open channel for mgmt events. > > > + > > > +-t, --time Show a time instead of time offset. > > > + > > > +-T, --date Show a time and date information instead of > > > + time offset. > > > + > > > +-S, --sco Dump SCO traffic in raw hex format. > > > + > > > +-A, --a2dp Dump A2DP stream traffic in a raw hex format. > > > + > > > +-E IP, --ellisys IP Send Ellisys HCI Injection. > > > + > > > +-P, --no-pager Disable pager usage while reading the log file. > > > + > > > +-J OPTIONS, --jlink OPTIONS Read data from RTT. Each options are comma(,) > > > + seprated without spaces. > > > + > > > +.. list-table:: > > > + :header-rows: 1 > > > + :widths: auto > > > + :stub-columns: 1 > > > + > > > + * - *OPTIONS* > > > + - Description > > > + > > > + * - **DEVICE** > > > + - Required. Set the target device. > > > + > > > + * - **SERIALNO** > > > + - (Optional) Set the USB serial number. Default is **0**. > > > + > > > + * - **INTERFACE** > > > + - (Optional) Target interface. Default is **swd**. > > > + > > > + * - **SPEED** > > > + - (Optional) Set target interface speed in kHz. Default is **1000**. > > > + > > > +-R OPTIONS, --rtt OPTIONS RTT control block parameters. Each options are > > > + comma(,) seprated without spaces. > > > + > > > +.. list-table:: > > > + :header-rows: 1 > > > + :widths: auto > > > + :stub-columns: 1 > > > + > > > + * - *OPTIONS* > > > + - Description > > > + > > > + * - **ADDRESS** > > > + - (Optional) Address of RTT buffer. Default is **0x00** > > > + > > > + * - **AREA** > > > + - (Optional) Size of range to search in RTT buffer. Default is **0** > > > + > > > + * - **NAME** > > > + - (Optional) Buffer name. Default is **btmonitor** > > > + > > > +-C WIDTH, --columns WIDTH Output width if not a terminal > > > + > > > +-c MODE, --color MODE Set output color. The possible *MODE* values are: > > > + **auto|always|never**. > > > + > > > + Default value is **auto** > > > + > > > +-v, --version Show version > > > + > > > +-h, --help Show help options > > > + > > > +EXAMPLES > > > +======== > > > + > > > +Capture the traces from hci0 to hcidump.log file > > > +------------------------------------------------ > > > + > > > +.. code-block:: bash > > > + > > > + $ btmon -i hci0 -w hcidump.log > > > + > > > +Open the trace file > > > +------------------- > > > + > > > +.. code-block:: bash > > > + > > > + $ btmon -r hcidump.log > > > + > > > + > > > +RESOURCES > > > +========= > > > + > > > +http://www.bluez.org > > > + > > > +REPORTING BUGS > > > +============== > > > + > > > +linux-bluetooth@vger.kernel.org > > > + > > > -- > > > 2.25.1 > > > > > > > >
Hi Luiz, >>>> From: Tedd Ho-Jeong An <tedd.an@intel.com> >>>> >>>> This patch updates the manpage for btmon written in rst format. >>>> --- >>>> Makefile.am | 26 ++++--- >>>> Makefile.tools | 4 ++ >>>> configure.ac | 4 ++ >>>> doc/btmon.txt | 35 ---------- >>>> monitor/btmon.rst | 172 ++++++++++++++++++++++++++++++++++++++++++++++ >>> >>> I do wonder why you change the location from doc to monitor, I think >>> we actually should keep all the documentation under doc and perhaps >>> even have a dedicated make target for those since we would likely want >>> to generate all the manpages from rst which may be time consuming so >>> people not interested on it can just skip it. >> >> I converted all manpages in the tree to .rst and ready to submit. >> Can I combine all in this series or wait for this to merge first? > > Have you added a make target for those? I really don't mind having the > manpages generated within the same location of the binary, although I > think it would be more organized to have it in one place, but a make > target would probably be a good practice. the way how this works is that in a git tree they are always generated unless disabled or rst2man is not available. And in a tarball, the generated manual pages are shipped, which means they are not needed to be generated. So no specific make target required. Lets just copy what iwd repository doing since that is working fine. Regards Marcel
Hi Marcel, On Sat, 2021-05-01 at 03:59 +0200, Marcel Holtmann wrote: > Hi Luiz, > > > > > > From: Tedd Ho-Jeong An <tedd.an@intel.com> > > > > > > > > > > This patch updates the manpage for btmon written in rst format. > > > > > --- > > > > > Makefile.am | 26 ++++--- > > > > > Makefile.tools | 4 ++ > > > > > configure.ac | 4 ++ > > > > > doc/btmon.txt | 35 ---------- > > > > > monitor/btmon.rst | 172 ++++++++++++++++++++++++++++++++++++++++++++++ > > > > > > > > I do wonder why you change the location from doc to monitor, I think > > > > we actually should keep all the documentation under doc and perhaps > > > > even have a dedicated make target for those since we would likely want > > > > to generate all the manpages from rst which may be time consuming so > > > > people not interested on it can just skip it. > > > > > > I converted all manpages in the tree to .rst and ready to submit. > > > Can I combine all in this series or wait for this to merge first? > > > > Have you added a make target for those? I really don't mind having the > > manpages generated within the same location of the binary, although I > > think it would be more organized to have it in one place, but a make > > target would probably be a good practice. > > the way how this works is that in a git tree they are always generated unless disabled or rst2man is not available. And in a tarball, the generated manual pages are shipped, which means they are not > needed to be generated. So no specific make target required. Lets just copy what iwd repository doing since that is working fine. > To align with iwd way, I suggest to make some changes in Makefile as well. For example, disabling manpages are not working because the manpages are added to dist_man_MANS without checking MANPAGES flags. I converted all existing manpages to .rst format and ready to submit. I will add them in this patch set. > Regards > > Marcel > Regards, Tedd
diff --git a/Makefile.am b/Makefile.am index f98243f72..759110cbd 100644 --- a/Makefile.am +++ b/Makefile.am @@ -60,6 +60,11 @@ else build_plugindir = $(plugindir) endif +if MANPAGES +man_MANS = +endif + +manual_pages = monitor/btmon.1 plugin_LTLIBRARIES = @@ -579,13 +584,7 @@ if LIBRARY pkgconfig_DATA = lib/bluez.pc endif -manual_pages = doc/btmon.1 - -if MANPAGES -dist_noinst_MANS += $(manual_pages) -endif - -EXTRA_DIST += $(manual_pages:.1=.txt) +EXTRA_DIST += $(manual_pages:.1=.rst) DISTCHECK_CONFIGURE_FLAGS = --disable-datafiles --enable-library \ --enable-health \ @@ -607,11 +606,20 @@ SED_PROCESS = $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \ $(SED) -e 's,@pkglibexecdir\@,$(pkglibexecdir),g' \ < $< > $@ +if RUN_RST2MAN +RST2MAN_PROCESS = $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \ + $(RST2MAN) --strict --no-raw \ + --no-generator --no-datestamp $< $@ +else +RST2MAN_PROCESS = $(AM_V_GEN)test -f $@ || \ + { echo "Generated manual page $@ does not exist"; false; } +endif + %.service: %.service.in Makefile $(SED_PROCESS) -%.1: %.txt - $(AM_V_GEN)a2x --doctype manpage --format manpage $(srcdir)/$< +%.1: %.rst Makefile + $(RST2MAN_PROCESS) src/builtin.h: src/genbuiltin $(builtin_sources) $(AM_V_GEN)$(srcdir)/src/genbuiltin $(builtin_modules) > $@ diff --git a/Makefile.tools b/Makefile.tools index 57e858290..9b452aa74 100644 --- a/Makefile.tools +++ b/Makefile.tools @@ -49,6 +49,10 @@ monitor_btmon_SOURCES = monitor/main.c monitor/bt.h \ monitor/tty.h monitor_btmon_LDADD = lib/libbluetooth-internal.la \ src/libshared-mainloop.la $(UDEV_LIBS) -ldl + +if MANPAGES +man_MANS += monitor/btmon.1 +endif endif if LOGGER diff --git a/configure.ac b/configure.ac index dbd98c9ad..d7e4766e4 100644 --- a/configure.ac +++ b/configure.ac @@ -326,7 +326,11 @@ AM_CONDITIONAL(DATAFILES, test "${enable_datafiles}" != "no") AC_ARG_ENABLE(manpages, AC_HELP_STRING([--enable-manpages], [enable building of manual pages]), [enable_manpages=${enableval}]) +if (test "${enable_manpages}" != "no"); then + AC_CHECK_PROGS(RST2MAN, [rst2man rst2man.py], "no") +fi AM_CONDITIONAL(MANPAGES, test "${enable_manpages}" = "yes") +AM_CONDITIONAL(RUN_RST2MAN, test "${enable_manpages}" = "yes" && test "${RST2MAN}" != "no") AC_ARG_ENABLE(testing, AC_HELP_STRING([--enable-testing], [enable testing tools]), diff --git a/doc/btmon.txt b/doc/btmon.txt deleted file mode 100644 index 7a7fc537b..000000000 --- a/doc/btmon.txt +++ /dev/null @@ -1,35 +0,0 @@ -BTMON(1) -======== -:doctype: manpage - - -NAME ----- -btmon - Bluetooth monitor - - -SYNOPSIS --------- -*btmon* ['OPTIONS'] - - -DESCRIPTION ------------ -The btmon(1) command provides access to the Bluetooth subsystem monitor -infrastructure for reading HCI traces. - - -AUTHOR ------- -btmon was originally written by Marcel Holtmann. - - -RESOURCES ---------- -See <http://www.bluez.org/> - - -COPYING -------- -Free use of this software is granted under ther terms of the GNU Lesser -General Public Licenses (LGPL). diff --git a/monitor/btmon.rst b/monitor/btmon.rst new file mode 100644 index 000000000..29d275eb3 --- /dev/null +++ b/monitor/btmon.rst @@ -0,0 +1,172 @@ +===== +btmon +===== + +----------------- +Bluetooth monitor +----------------- + +:Authors: - Marcel Holtmann <marcel@holtmann.org> + - Tedd Ho-Jeong An <tedd.an@intel.com> +:Copyright: Free use of this software is granted under ther terms of the GNU + Lesser General Public Licenses (LGPL). +:Version: BlueZ +:Date: April 2021 +:Manual section: 1 +:Manual group: Linux System Administration + +SYNOPSYS +======== + +**btmon** [*OPTIONS* ...] + +DESCRIPTION +=========== + +The btmon(1) command provides access to the Bluetooth subsystem monitor +infrastructure for reading HCI traces. + +OPTIONS +======= + +-r FILE, --read FILE Read traces in btsnoop format from *FILE*. +-w FILE, --write FILE Save traces in btsnoop format to *FILE*. +-a FILE, --analyze FILE Analyze traces in btsnoop format from *FILE*. + It displays the devices found in the *FILE* with + its packets by type. +-s SOCKET, --server SOCKET Start monitor server socket. +-p PRIORITY, --priority PRIORITY Show only priority or lower for user log. + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - *PRIORITY* + - NAME + + * - **3** + - Error + + * - **4** + - Warning + + * - **6** + - Information (Default) + + * - **7** + - Debug. **debug** can be used. + +-i NUM, --index NUM Show only specified controller. *hciNUM* is also + acceptable. This is useful to capture the traces + from the specific controller when the multiple + controllers are presented. + +-d TTY, --tty TTY Read data from *TTY*. + +-B SPEED, --rate SPEED Set TTY speed. The default *SPEED* is 115300 + +-V COMPID, --vendor COMPID Set the default company identifier. The *COMPID* is + a unique number assigned by the Bluetooth SIG to + a member company and can be found/searched from the + Bluetooth SIG webpage. + + For example, Intel is 2 and Realtek is 93. + +-M, --mgmt Open channel for mgmt events. + +-t, --time Show a time instead of time offset. + +-T, --date Show a time and date information instead of + time offset. + +-S, --sco Dump SCO traffic in raw hex format. + +-A, --a2dp Dump A2DP stream traffic in a raw hex format. + +-E IP, --ellisys IP Send Ellisys HCI Injection. + +-P, --no-pager Disable pager usage while reading the log file. + +-J OPTIONS, --jlink OPTIONS Read data from RTT. Each options are comma(,) + seprated without spaces. + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - *OPTIONS* + - Description + + * - **DEVICE** + - Required. Set the target device. + + * - **SERIALNO** + - (Optional) Set the USB serial number. Default is **0**. + + * - **INTERFACE** + - (Optional) Target interface. Default is **swd**. + + * - **SPEED** + - (Optional) Set target interface speed in kHz. Default is **1000**. + +-R OPTIONS, --rtt OPTIONS RTT control block parameters. Each options are + comma(,) seprated without spaces. + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - *OPTIONS* + - Description + + * - **ADDRESS** + - (Optional) Address of RTT buffer. Default is **0x00** + + * - **AREA** + - (Optional) Size of range to search in RTT buffer. Default is **0** + + * - **NAME** + - (Optional) Buffer name. Default is **btmonitor** + +-C WIDTH, --columns WIDTH Output width if not a terminal + +-c MODE, --color MODE Set output color. The possible *MODE* values are: + **auto|always|never**. + + Default value is **auto** + +-v, --version Show version + +-h, --help Show help options + +EXAMPLES +======== + +Capture the traces from hci0 to hcidump.log file +------------------------------------------------ + +.. code-block:: bash + + $ btmon -i hci0 -w hcidump.log + +Open the trace file +------------------- + +.. code-block:: bash + + $ btmon -r hcidump.log + + +RESOURCES +========= + +http://www.bluez.org + +REPORTING BUGS +============== + +linux-bluetooth@vger.kernel.org +
From: Tedd Ho-Jeong An <tedd.an@intel.com> This patch updates the manpage for btmon written in rst format. --- Makefile.am | 26 ++++--- Makefile.tools | 4 ++ configure.ac | 4 ++ doc/btmon.txt | 35 ---------- monitor/btmon.rst | 172 ++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 197 insertions(+), 44 deletions(-) delete mode 100644 doc/btmon.txt create mode 100644 monitor/btmon.rst