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/.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: diff --git a/Doxyfile.in b/Doxyfile.in index 4218ea7d..2fab9b99 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,10 @@ 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 \ + @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 @@ -886,13 +887,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 +904,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 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 cc522114..f862e011 100644 --- a/devices/Makefile.am +++ b/devices/Makefile.am @@ -95,6 +95,8 @@ noinst_HEADERS = \ 8139too-4.4-orig.c \ 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/create_driver_table.py b/devices/create_driver_table.py new file mode 100644 index 00000000..d492474b --- /dev/null +++ b/devices/create_driver_table.py @@ -0,0 +1,163 @@ +#!/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) + 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]) + for cell in row[1:]: + 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, + 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 args.markdown[0] as f: + f.write(dump_markdown(table)) + f.write('\n') diff --git a/devices/device_drivers_template.md b/devices/device_drivers_template.md new file mode 100644 index 00000000..9ada925a --- /dev/null +++ b/devices/device_drivers_template.md @@ -0,0 +1,7 @@ +Device Drivers {#devicedrivers} +============== + +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. 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.