From 8631fcb308c1627bb9277e00de6225b080cdb501 Mon Sep 17 00:00:00 2001 From: Bjarne von Horn Date: Wed, 9 Aug 2023 19:31:39 +0200 Subject: [PATCH 1/8] initial script to create device table --- devices/Makefile.am | 1 + devices/create_driver_table.py | 137 +++++++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 devices/create_driver_table.py diff --git a/devices/Makefile.am b/devices/Makefile.am index cc522114..4b3931a8 100644 --- a/devices/Makefile.am +++ b/devices/Makefile.am @@ -95,6 +95,7 @@ noinst_HEADERS = \ 8139too-4.4-orig.c \ 8139too-5.10-ethercat.c \ 8139too-5.10-orig.c \ + create_driver_table.py \ e100-2.6.20-ethercat.c \ e100-2.6.20-orig.c \ e100-2.6.24-ethercat.c \ diff --git a/devices/create_driver_table.py b/devices/create_driver_table.py new file mode 100644 index 00000000..a95ff1ba --- /dev/null +++ b/devices/create_driver_table.py @@ -0,0 +1,137 @@ +#!/usr/bin/env python3 + +############################################################################# +# +# Copyright (C) 2007-2023 Bjarne von Horn, Ingenieurgemeinschaft IgH +# +# This file is part of the IgH EtherCAT Master. +# +# The IgH EtherCAT Master is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License version 2, as +# published by the Free Software Foundation. +# +# The IgH EtherCAT Master is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General +# Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with the IgH EtherCAT Master; if not, write to the Free Software +# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +# +# --- +# +# The license mentioned above concerns the source code only. Using the +# EtherCAT technology and brand is only permitted in compliance with the +# industrial property and similar rights of Beckhoff Automation GmbH. +# +############################################################################ + +from os import walk +from os.path import join +from re import compile + +DRIVER_MAP=( + # (subdir, driver name, file prefix) + (".", "8139too", "8139too"), + (".", "e100", "e100"), + ("e1000", "e1000", "e1000_main"), + ("e1000e", "e1000e", "netdev"), + ("igb", "igb", "igb_main"), + (".", "r8169", "r8169"), +) + +DRIVERS = tuple([x[1] for x in DRIVER_MAP]) + +def compile_regex(prefix, file_extension): + """ + :return: Compiled regex to extract Kernel version + """ + return compile("^" + prefix + "-([\d]+)\.([\d]+)-ethercat\."+file_extension+"$") + +def filter_versions(file_list, prefix, file_extension): + """ + :return: Set of tuples with (major, minor) kernel versions. + """ + rex = compile_regex(prefix, file_extension) + ans = set() + for file in file_list: + match = rex.match(file) + if match is None: + continue + maj, min = match.group(1, 2) + ans.add((int(maj), int(min))) + return ans + +def get_all_drivers(drivers_dir): + """ + Walk through "devices" dir and collect all drivers. + + :return: Dict with (major, minor) kernel version key and set of driver + names as values. + """ + files = next(walk(drivers_dir))[2] + driver_table = {} + def add_driver(versions, driver): + for version in versions: + if not version in driver_table: + driver_table[version] = set() + driver_table[version].add(driver) + for subdir, driver_name, file_prefix in DRIVER_MAP: + if subdir == ".": + add_driver(filter_versions(files, file_prefix, "c"), driver_name) + else: + tmp_files = next(walk(join(drivers_dir, subdir)))[2] + add_driver(filter_versions(tmp_files, file_prefix, "c"), driver_name) + return driver_table + +def compute_table(dict_data): + """ + Create a table based on data generated by get_all_drivers(). + + :return: List of rows with "X" or "-", including column and row captions + (driver name / kernel version). + """ + keys = sorted(dict_data.keys(), reverse=True) + ans = [("Kernel", *DRIVERS),] + + def parse_row(key): + row_set = dict_data[key] + row = [] + for driver in DRIVERS: + if driver in row_set: + row.append("X") + else: + row.append("-") + return row + + for key in keys: + c = "{}.{: <2}".format(*key) + ans.append([c] + parse_row(key)) + + return ans + +def get_max_width(row): + ans = 0 + for cell in row: + if len(cell) > ans: + ans = len(cell) + return ans + +def dump_markdown(table_data): + """ + Create a markdown table based on data from compute_table(). + """ + width = get_max_width(table_data[0]) + cell_fmt_center = "| {: ^" + str(width) + "} " + cell_fmt_left = "| {: <" + str(width) + "} " + cell_fmt_right = "| {: >" + str(width) + "} " + ans = cell_fmt_left.format(table_data[0][0]) + for cell in table_data[0][1:]: + ans += cell_fmt_center.format(cell) + for row in table_data[1:]: + ans += '|\n' + cell_fmt_right.format(row[0]) + for cell in row[1:]: + ans += cell_fmt_center.format(cell) + ans += '|' + return ans From f504acf1df764925d1d3f6bd670f0dbb3f459290 Mon Sep 17 00:00:00 2001 From: Bjarne von Horn Date: Wed, 9 Aug 2023 20:25:42 +0200 Subject: [PATCH 2/8] add header separator line --- devices/create_driver_table.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/devices/create_driver_table.py b/devices/create_driver_table.py index a95ff1ba..9bd80da5 100644 --- a/devices/create_driver_table.py +++ b/devices/create_driver_table.py @@ -129,9 +129,12 @@ def dump_markdown(table_data): ans = cell_fmt_left.format(table_data[0][0]) for cell in table_data[0][1:]: ans += cell_fmt_center.format(cell) + ans += '|\n|-' + "-" * width + ":|" + for i in range(len(table_data[0]) - 1): + ans += ':' + "-" * width + ':|' for row in table_data[1:]: - ans += '|\n' + cell_fmt_right.format(row[0]) + ans += '\n' + cell_fmt_right.format(row[0]) for cell in row[1:]: ans += cell_fmt_center.format(cell) - ans += '|' + ans += '|' return ans From 30326154eeecaa5ac9e9edc942a0805c495ca233 Mon Sep 17 00:00:00 2001 From: Bjarne von Horn Date: Wed, 9 Aug 2023 20:26:00 +0200 Subject: [PATCH 3/8] add argument parser --- devices/create_driver_table.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/devices/create_driver_table.py b/devices/create_driver_table.py index 9bd80da5..6780f643 100644 --- a/devices/create_driver_table.py +++ b/devices/create_driver_table.py @@ -138,3 +138,16 @@ def dump_markdown(table_data): ans += cell_fmt_center.format(cell) ans += '|' return ans + + +if __name__ == "__main__": + from sys import argv + import argparse + parser = argparse.ArgumentParser() + parser.add_argument("--markdown", nargs=1) + parser.add_argument("devices_dir", nargs=1) + args = parser.parse_args(argv[1:]) + table = compute_table(get_all_drivers(args.devices_dir[0])) + if args.markdown is not None: + with open(args.markdown[0], "w") as f: + f.write(dump_markdown(table)) From ebfa6ce1c6e8928404b3718325b78f90b315c6cb Mon Sep 17 00:00:00 2001 From: Bjarne von Horn Date: Wed, 9 Aug 2023 20:36:01 +0200 Subject: [PATCH 4/8] Make doxyfile out-of-tree capable --- Doxyfile.in | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doxyfile.in b/Doxyfile.in index 4218ea7d..d9f228db 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -45,7 +45,7 @@ PROJECT_BRIEF = # exceed 55 pixels and the maximum width should not exceed 200 pixels. # Doxygen will copy the logo to the output directory. -PROJECT_LOGO = doxygen-layout/images/igh+logo.svg +PROJECT_LOGO = @top_srcdir@/doxygen-layout/images/igh+logo.svg # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) # base path where the generated documentation will be put. @@ -655,9 +655,9 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = master \ - include \ - devices/ecdev.h +INPUT = @top_srcdir@/master \ + @top_srcdir@/include \ + @top_srcdir@/devices/ecdev.h # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is @@ -886,13 +886,13 @@ HTML_FILE_EXTENSION = .html # have to redo this when upgrading to a newer version of doxygen or when # changing the value of configuration settings such as GENERATE_TREEVIEW! -HTML_HEADER = doxygen-layout/style/html_header.html +HTML_HEADER = @top_srcdir@/doxygen-layout/style/html_header.html # The HTML_FOOTER tag can be used to specify a personal HTML footer for # each generated HTML page. If it is left blank doxygen will generate a # standard footer. -HTML_FOOTER = doxygen-layout/style/html_footer.html +HTML_FOOTER = @top_srcdir@/doxygen-layout/style/html_footer.html # The HTML_STYLESHEET tag can be used to specify a user-defined cascading # style sheet that is used by each HTML page. It can be used to @@ -903,8 +903,8 @@ HTML_FOOTER = doxygen-layout/style/html_footer.html HTML_STYLESHEET = -HTML_EXTRA_STYLESHEET = doxygen-layout/style/custom.css \ - doxygen-layout/style/custom_igh_theme.css +HTML_EXTRA_STYLESHEET = @top_srcdir@/doxygen-layout/style/custom.css \ + @top_srcdir@/doxygen-layout/style/custom_igh_theme.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or From c332e762c1ac7b80d40fe3557f441e33f5a64ef7 Mon Sep 17 00:00:00 2001 From: Bjarne von Horn Date: Wed, 9 Aug 2023 20:37:02 +0200 Subject: [PATCH 5/8] first try to include auto-generated device table in Doxygen --- .gitignore | 3 +++ Doxyfile.in | 3 ++- Makefile.am | 10 ++++++++-- devices/Makefile.am | 1 + devices/device_drivers_template.md | 7 +++++++ 5 files changed, 21 insertions(+), 3 deletions(-) create mode 100644 devices/device_drivers_template.md diff --git a/.gitignore b/.gitignore index 914e5e2f..694273bd 100644 --- a/.gitignore +++ b/.gitignore @@ -43,3 +43,6 @@ script/ethercatctl script/init.d/ethercat stamp-h1 tool/ethercat +device_drivers.md +generated_table.md +doxygen-output/ diff --git a/Doxyfile.in b/Doxyfile.in index d9f228db..2fab9b99 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -657,7 +657,8 @@ WARN_LOGFILE = INPUT = @top_srcdir@/master \ @top_srcdir@/include \ - @top_srcdir@/devices/ecdev.h + @top_srcdir@/devices/ecdev.h \ + @top_builddir@/device_drivers.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is diff --git a/Makefile.am b/Makefile.am index e08d9322..a8901217 100644 --- a/Makefile.am +++ b/Makefile.am @@ -100,10 +100,16 @@ mrproper: clean cleandoc libtool \ stamp-h1 -doc: +generated_table.md: devices/create_driver_table.py + python3 $< --markdown $@ $(abs_srcdir)/devices + +device_drivers.md: $(srcdir)/devices/device_drivers_template.md generated_table.md + cat $^ > $@ + +doc: device_drivers.md doxygen Doxyfile cleandoc: - @rm -rf doxygen-output + @rm -rf doxygen-output generated_table.md device_drivers.md #----------------------------------------------------------------------------- diff --git a/devices/Makefile.am b/devices/Makefile.am index 4b3931a8..f862e011 100644 --- a/devices/Makefile.am +++ b/devices/Makefile.am @@ -96,6 +96,7 @@ noinst_HEADERS = \ 8139too-5.10-ethercat.c \ 8139too-5.10-orig.c \ create_driver_table.py \ + device_drivers_template.md \ e100-2.6.20-ethercat.c \ e100-2.6.20-orig.c \ e100-2.6.24-ethercat.c \ diff --git a/devices/device_drivers_template.md b/devices/device_drivers_template.md new file mode 100644 index 00000000..c6c3cbb5 --- /dev/null +++ b/devices/device_drivers_template.md @@ -0,0 +1,7 @@ +Device Drivers +============== + +This table contains a list of all available native drivers, +depending on the kernel version. + +The `generic` and the `ccat` driver are independent of the kernel version. From aeda2e0ab9d78bc380af3840fc7fbca7c9a24521 Mon Sep 17 00:00:00 2001 From: Bjarne von Horn Date: Wed, 9 Aug 2023 22:26:44 +0200 Subject: [PATCH 6/8] improve cli interface --- devices/create_driver_table.py | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/devices/create_driver_table.py b/devices/create_driver_table.py index 6780f643..d492474b 100644 --- a/devices/create_driver_table.py +++ b/devices/create_driver_table.py @@ -144,10 +144,20 @@ if __name__ == "__main__": from sys import argv import argparse parser = argparse.ArgumentParser() - parser.add_argument("--markdown", nargs=1) - parser.add_argument("devices_dir", nargs=1) + parser.add_argument( + "--markdown", + nargs=1, + help="Markdown output file", + type=argparse.FileType("w") + ) + parser.add_argument( + "devices_dir", + nargs=1, + help="Devices driver source dir" + ) args = parser.parse_args(argv[1:]) table = compute_table(get_all_drivers(args.devices_dir[0])) if args.markdown is not None: - with open(args.markdown[0], "w") as f: + with args.markdown[0] as f: f.write(dump_markdown(table)) + f.write('\n') From efa3f7d738965dd7dffbcf58557512a72dd12d15 Mon Sep 17 00:00:00 2001 From: Bjarne von Horn Date: Thu, 10 Aug 2023 00:22:55 +0200 Subject: [PATCH 7/8] use `make doc` in doxygen job to build device table --- .gitlab-ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 7c229bdf..ae231ce6 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -55,7 +55,7 @@ doxygen: script: - ./bootstrap - ./configure --with-linux-dir=/usr/src/linux-obj/$(uname -i)/default --disable-8139too --enable-tty --with-devices=2 --enable-ccat - - doxygen + - make doc - mv doxygen-output/html/ html/ artifacts: paths: From d08e41f9133958e666b52d8f8e83a41602cfae66 Mon Sep 17 00:00:00 2001 From: Bjarne von Horn Date: Wed, 6 Sep 2023 10:19:49 +0200 Subject: [PATCH 8/8] Add page ref to device drivers page. It's now always in doxygen-output/html/devicedrivers.html --- devices/device_drivers_template.md | 2 +- master/doxygen.c | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/devices/device_drivers_template.md b/devices/device_drivers_template.md index c6c3cbb5..9ada925a 100644 --- a/devices/device_drivers_template.md +++ b/devices/device_drivers_template.md @@ -1,4 +1,4 @@ -Device Drivers +Device Drivers {#devicedrivers} ============== This table contains a list of all available native drivers, diff --git a/master/doxygen.c b/master/doxygen.c index 4d2abb5b..898bdc2c 100644 --- a/master/doxygen.c +++ b/master/doxygen.c @@ -43,6 +43,9 @@ The API documentations are in the modules section. + A list of all native network card drivers can be found + here. + For information how to build and install, see the INSTALL file in the source root.