Merge branch 'drivers_table' into 'stable-1.5'

Create Drivers table in doxygen

See merge request etherlab.org/ethercat!76

.gitignore

@@ -43,3 +43,6 @@ script/ethercatctl
 script/init.d/ethercat
 stamp-h1
 tool/ethercat
+device_drivers.md
+generated_table.md
+doxygen-output/

.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:

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 \
+INPUT                  = @top_srcdir@/master \
-                         include \
+                         @top_srcdir@/include \
-                         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
@@ -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 \
+HTML_EXTRA_STYLESHEET  =  @top_srcdir@/doxygen-layout/style/custom.css \
-                          doxygen-layout/style/custom_igh_theme.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

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
 
 #-----------------------------------------------------------------------------

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 \

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')

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.

master/doxygen.c

@@ -43,6 +43,9 @@
    The API documentations are in the <a href="modules.html">modules
    section</a>.
 
+   A list of all native network card drivers can be found
+   <a href="devicedrivers.html">here</a>.
+
    For information how to build and install, see the INSTALL file in the source
    root.