nuttx/tools/stm32_pinmap_tool.py

#!/usr/bin/env python3
############################################################################
# tools/stm32_pinmap_tool.py
#
# SPDX-License-Identifier: Apache-2.0
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.  The
# ASF licenses this file to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance with the
# License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
# License for the specific language governing permissions and limitations
# under the License.
#
############################################################################

# for python2.7 compatibility
from __future__ import print_function

import argparse
import os
import re
import sys
from argparse import RawTextHelpFormatter
from glob import glob

suffix = "_0"
remaps_re = re.compile(r"(.*REMAP.*)=y")
ip_block_re = re.compile(r"CONFIG_STM32[A-Z0-9]*_([A-Z0-9]+[0-9]*)=")
stm32f1_re = re.compile(r"stm32f10[0-9][a-z]*_pinmap")
speed_re = re.compile(r"(GPIO_(?:SPEED|MODE)_[zA-Z0-9]+)")
port_re = re.compile(r"GPIO_PORT([A-Z])\|")
pin_re = re.compile(r"GPIO_PIN(\d+)")
define_re = re.compile(r"#\s*define\s+(GPIO.*)\s+(GPIO.*?)\s+")


class GPIODef:
    def __init__(self, original_name, name, description):
        self.original_name = original_name
        self.name = name
        self.block = name.split("_")[1]
        self.speed = None
        s = speed_re.search(description)
        if s:
            self.speed = s.group(1)
        s = port_re.search(description)
        if s:
            self.port = s.group(1)
        s = pin_re.search(description)
        if s:
            self.pin = s.group(1)

    def __str__(self):
        fmt = "#define {0: <20} {1} /* P{2} */"
        if self.speed:
            if "MODE" in self.speed:
                if "MHz" in self.speed:
                    # F1 has mode, MHz is output, we must adjust the speed
                    fmt = "#define {0: <20} GPIO_ADJUST_MODE({1}, {3}) /* P{2} */ "
            else:
                # All others had a OSPEDD reg so we just set it
                fmt = "#define {0: <20} ({1} | {3}) /* P{2} */ "

        return fmt.format(
            self.original_name,
            self.name,
            self.port + self.pin,
            self.speed,
        )

    def __repr__(self):
        return f"<GPIODef block:{self.block} \
                 original_name:{self.original_name} \
                 name:{self.name} port:{self.port} \
                 pin:{self.pin} speed:{self.speed}>"


# Detect python version
if sys.version_info[0] < 3:
    runningPython3 = False
else:
    runningPython3 = True


def parse_args():
    # Parse commandline arguments
    parser = argparse.ArgumentParser(
        formatter_class=RawTextHelpFormatter,
        description="""stm32_pinmap_tool.py

   This tool is used to migrate legacy stm32 pinmap files that
   had included pin speed (slew rate control) in pinmap pin definitions

   These speeds should have never been part of the arch defines as these
   are layout and board dependent. Therefore, the complete definition
   should be a composition of the pinmap defines and speed, and defined in
   board.h

   Furthermore, pinmaps did not suffix pins that had only one ALT
   appearance on a GPIO. Therefore there was no way to change the speed
   or any other pins attribute i.e. Pullup Pulldown, Push pull. Open Drain etc.

    The tool has a conversion mode and a report mode.

 Conversion mode tool use:

    Run the tool to do the conversion:
 i.e tools/stm32_pinmap_tool.py
       --pinmap  arch/arm/src/stm32h7/hardware/stm32h7x3xx_pinmap.h
       --legacy > arch/arm/src/stm32h7/hardware/stm32h7x3xx_pinmap-new.h

   -- pinmap - the file to convert
   --legacy will make a copy of the pinmap. Properly updating the file with
     xxxx/xxxxxxx_legacy to the title block,
     and adding _LEGACY to the #ifdef, #define and endif comment of the inclusion guard.

 Conversion mode follow up edits:
   1.  diff and verify the original pinmap and the pinmap-new.h are as expected.
       delete original pinmap
       rename pinmap-new.h to the original pinmap name.
   2. Edit the top level pinmap (i.e. arch/arm/src/stm32x/stm32x_pinmap.h) file and
      add a CONFIG_STM32xx_USE_LEGACY_PINMAP section
      that includes the legacy pinmap files.

   For example
          if defined(CONFIG_STM32H7_USE_LEGACY_PINMAP)
            if defined(CONFIG_STM32H7_STM32H7X3XX)
              include "hardware/stm32h7x3xx_pinmap_legacy.h"
            elif defined(CONFIG_STM32H7_STM32H7B3XX)
              include "hardware/stm32h7x3xx_pinmap_legacy.h"
            elif defined(CONFIG_STM32H7_STM32H7X7XX)
              include "hardware/stm32h7x3xx_pinmap_legacy.h"
            else
              error "Unsupported STM32 H7 Pin map"
            endif
          else
            if defined(CONFIG_STM32H7_STM32H7X3XX)
              include "hardware/stm32h7x3xx_pinmap.h"
            elif defined(CONFIG_STM32H7_STM32H7B3XX)
              include "hardware/stm32h7x3xx_pinmap.h"
            elif defined(CONFIG_STM32H7_STM32H7X7XX)
              include "hardware/stm32h7x3xx_pinmap.h"
            else
              error "Unsupported STM32 H7 Pin map"
            endif
          endif

   3. Add a STM32Hx_USE_LEGACY_PINMAP to the Kconfig defaulted to y

   For example

       config STM32H7_USE_LEGACY_PINMAP
           bool "Use the legacy pinmap with GPIO_SPEED_xxx included."
           default y
           ---help---
               In the past, pinmap files included GPIO_SPEED_xxxMhz. These speed
               settings should have come from the board.h as it describes the wiring
               of the SoC to the board. The speed is really slew rate control and
               therefore is related to the layout and can only be properly set
               in board.h.

               STM32H7_USE_LEGACY_PINMAP is provided, to allow lazy migration to
               using pinmaps without speeds. The work required to do this can be aided
               by running tools/stm32_pinmap_tool.py. The tools will take a board.h
               file and a legacy pinmap and output the required changes that one needs
               to make to a board.h file.

               Eventually, STM32H7_USE_LEGACY_PINMAP will be deprecated and the legacy
               pinmaps removed from NuttX. Any new boards added should set
               STM32H7_USE_LEGACY_PINMAP=n and fully define the pins in board.h
   4. Add a warning to the xxx_gpio.c file

   For example

       #if defined(CONFIG_STM32_USE_LEGACY_PINMAP)
       #  pragma message "CONFIG_STM32_USE_LEGACY_PINMAP will be deprecated migrate board.h see tools/stm32_pinmap_tool.py"
       #endif

 Report mode tool use:

    Run the tool to aid in migrating a board.h

   tools/stm32_pinmap_tool.py --pinmap arch/arm/src/stm32h7/hardware/stm32h7x3xx_pinmap_legacy.h
   --report <fullpath>/include/board.h

   it will output 2 sections that should be used to update the board.h.
   board.h defines that need to have speeds added.
   board.h defines that will need to be added:
    """,
    )

    parser.add_argument(
        "--pinmap",
        action="store",
        help="""pin map file to convert (changes are printed on stdout) or
                Legacy file pin map file named <filename>_legacy.<ext> to report board.h changes""",
    )
    parser.add_argument(
        "--report",
        default=False,
        action="store",
        help="Generate change set for a board",
    )
    parser.add_argument(
        "--legacy",
        default=False,
        action="store_true",
        help="If one does not exist, create a copy of the original pin map named <filename>_legacy.<ext>",
    )
    args = parser.parse_args()
    return args


def create_legacy(source):
    legacy = source.replace(".h", "_legacy.h")
    sourceshort = source[source.find("arch") :]
    legacyshort = legacy[legacy.find("arch") :]
    srctag = "__" + sourceshort.upper().replace("/", "_")
    destag = "__" + legacyshort.upper().replace("/", "_").replace(".", "_")
    if not os.path.isfile(legacy):
        fout = open(legacy, "w")
        fin = open(source, "r")

        for line in fin:
            out = re.sub(sourceshort, legacyshort, line)
            out = re.sub(srctag, destag, out)
            fout.write(out)
        fout.close()
        fin.close()


def read_defconfigs(boardfile_path):
    configs_lines = []
    defconfigs_files = []

    for dir, _, _ in os.walk(boardfile_path[: boardfile_path.find("include/board.h")]):
        defconfigs_files.extend(glob(os.path.join(dir, "defconfig")))

    for file in defconfigs_files:
        defconfigfile = open(file, "r")
        configs_lines.extend(defconfigfile.readlines())
        defconfigfile.close()
    return configs_lines


def build_ip_remap_list(boardfile_path):
    ip_blocks = []
    ip_remaps = []
    configs_lines = read_defconfigs(boardfile_path)
    configs_lines = sorted(set(configs_lines))

    for line in configs_lines:
        s = ip_block_re.search(line)
        if s:
            ip_blocks.extend([s.group(1)])
        else:
            s = remaps_re.search(line)
            if s:
                ip_remaps.extend([s.group(1)])
    return [ip_blocks, ip_remaps]


def read_board_h(boardfile_path):
    boardfile = open(boardfile_path, "r")
    lines = boardfile.readlines()
    boardfile.close()
    return lines


def formated_print(lines):
    maxlen = 0
    for line in lines:
        linelen = line.find("/*")
        if linelen > maxlen:
            maxlen = linelen

    for line in lines:
        linelen = line.find("/*")
        if linelen > 1 and linelen < maxlen:
            nl = line[:linelen] + " " * (maxlen - linelen) + line[linelen:]
            line = nl
        print(line)


def report(boardfile_path, boards_ip_blocks, changelog, changelog_like):
    output = [
        "",
    ]
    output.extend(
        [
            """
There were 3 issues with the Legacy pinmaps.

 1. The legacy version of the pin defines included speed settings. (These are
    in reality, slew rates).

 2. Legacy pinmaps erroneously added speeds on pins that are only used
    as an inputs (i.e UART4_RX). These speeds can be removed from the board.h
    defines.

 3. Also the legacy version of the pin defines did not have a suffix on all
    pins and therefore all pins could not have the attributes set or changed
    by board.h

The new pinmaps correct these issues:

 Pin that had an explicit (GPIO_SPEED|MODE)_xxxMHz are removed or set to
 the lowest speed.

 If the pin had only one choice previously (un-suffixed) the pin name now
 contains _0 as the suffix.

 N.B. The correct speed setting for a given pin is very dependent on the
 layout of the circuit board and load presented to the SoC on that pin.

 The speeds listed below are from the Legacy pinmaps and are provided ONLY
 to insure these changes do not break existing systems that are relying on
 the legacy speed settings.

 It highly recommended that the speed setting for each pin be verified for
 overshoot and undershoot on real hardware and adjusted in the board,h
 appropriately.


board.h defines that need to have speeds added.

"""
        ]
    )

    boards_blocks = []
    Lines = read_board_h(boardfile_path)
    for line in Lines:
        s = define_re.search(line)
        if s:
            # #define GPIO_SD_CK   GPIO_SD_CK_1  /* PD6  FC_PD6_SD_CK  */
            define = s.group(1)
            original_name = s.group(2)
            change = changelog.get(original_name)
            if change:
                pindef = GPIODef(define, original_name, line)
                if pindef.block not in boards_blocks:
                    boards_blocks.append(pindef.block)
                    output.extend([f"\n/* {pindef.block} */\n"])
                output.extend([str(changelog[original_name])])
    if len(boards_blocks) == 0:
        output.extend(
            [
                """
   No pins are defined in board.h to change speeds on (most likely an stm32f1")
   We will define all the pins used next...
            """
            ]
        )

    formated_print(output)
    output = []

    output.extend(
        [
            """

 Pin that had only one choice previously (un-suffixed) pins will need to be
 defined in board.h to map the un-suffixed) pin name used in the drives to
 the _0 suffixed ones.

 Pins that did not have an explicit (GPIO_SPEED|MODE)_xxxMHz specified are
 listed with the pin name containing the new suffix.


board.h defines that may need to be added if the pins are used on the board:


"""
        ]
    )

    for block in boards_ip_blocks:
        change = changelog_like.get(block)
        if change:
            block_title = f"\n/* {block} */\n"
            for gpio in change:
                if re.search(r"_\d+$", gpio.original_name) is None:
                    if block_title:
                        output.extend([block_title])
                        block_title = None
                    output.extend([str(gpio)])

    formated_print(output)


def formatcols(list, cols):
    lines = ("\t".join(list[i : i + cols]) for i in range(0, len(list), cols))
    return "\n".join(lines)


def parse_conditional(lines, conditions):
    defines = []

    def_remap_re = re.compile(r"\s*defined\s*\((.*REMAP.*)\)")
    def_else_re = re.compile(r"#\s*else")
    def_endif_re = re.compile(r"#\s*endif")

    active_define = None
    output = True
    once = False

    for line in lines:
        # process #[el]if define(...REMAP)
        s = def_remap_re.search(line)
        if s:
            once = True
            define = s.group(1)
            if define in conditions:
                active_define = define
                output = True
            else:
                output = False
        else:
            # process #endif
            s = def_endif_re.search(line)
            if s:
                active_define = None
                output = True
            else:
                # process #elese
                s = def_else_re.search(line)
                if s:
                    once = True
                    # the if or elif was taken do not output the else
                    if active_define:
                        output = False
                    else:
                        output = output ^ True

        if once or output:
            once = False
            defines.extend([line])
    return defines


def formmatter(args):
    # if pinmap passed is a legacy pinmap. Just generate a report
    report_only = args.report is not False

    speed_not_mode = stm32f1_re.search(args.pinmap) is None

    if not report_only and args.legacy is True:
        create_legacy(args.pinmap)

    pinfile = open(args.pinmap, "r")
    Lines = pinfile.readlines()

    if report_only:
        boards_ip_blocks, remaps = build_ip_remap_list(args.report)
        print(
            f"\n\nBoard enabled Blocks:\n\n{formatcols(sorted(boards_ip_blocks), 8)}\n\n"
        )
        if (
            "ADC1" in boards_ip_blocks
            or "ADC2" in boards_ip_blocks
            or "ADC3" in boards_ip_blocks
        ):
            boards_ip_blocks.extend(["ADC12"])
            boards_ip_blocks.extend(["ADC123"])
            boards_ip_blocks = sorted(boards_ip_blocks)
        # Filter out ifdefed by remap conditionals (F1)
        if len(remaps) > 0:
            Lines = parse_conditional(Lines, remaps)

    Pass = False
    inComment = False

    changelog = {}
    changelog_like = {}
    pass_list = [r"#\s*if", r"#\s*else", r"#\s*end", r"#\s*include", r"#\s*undef"]
    pass_list_re = re.compile("|".join(pass_list))

    for line in Lines:
        if len(line.strip()) == 0:
            Pass = True
        if pass_list_re.search(line):
            Pass = True
        if "#define" in line and "GPIO" not in line:
            Pass = True
        if "defined(" in line:
            Pass = True
        if "/*" in line:
            inComment = True
            Pass = True
        if "*/" in line:
            inComment = False
            Pass = True
        if Pass or inComment:
            Pass = False
            if not report_only:
                print(line.rstrip(), end="")
        else:
            changed = False
            # split the line on spaces
            pieces = line.split()
            # deal with white space in the #  define for nested defines
            sel = 0
            # Does it have white space then use next set?
            if pieces[0] == "#":
                sel = 1
            original_name = pieces[sel + 1]
            gpiocgf = pieces[sel + 2]
            new_name = original_name
            if re.search(r"_\d+$", original_name) is None:
                # Add suffix
                pad = ""
                sel = line.find(original_name) + len(original_name)
                if line[sel + len(suffix)] == "(":
                    pad = " "
                if line[sel + len(suffix)] == "G":
                    pad = "  ("
                nl = line[:sel] + suffix + pad + line[sel + len(suffix) :]
                new_name = original_name + suffix
                changed = True
            else:
                nl = line
            # Remove the speed or chege the Mode
            if speed_not_mode:
                ol = re.sub(r"\s*GPIO_SPEED_[zA-Z0-9]+\s*\|", "", nl)
            else:
                ol = re.sub(
                    r"(\s*)GPIO_MODE_[0-9]+MHz(\s*\|)", r"\g<1>GPIO_MODE_2MHz\g<2>", nl
                )

            changed = changed or ol != nl
            if not report_only:
                print(ol.strip(), end="")
            if args.report and changed:
                changelog[original_name] = pindef = GPIODef(
                    original_name, new_name, gpiocgf
                )

                # create changes by block if enabled
                if pindef.block in boards_ip_blocks:
                    # Is block in already?
                    if pindef.block in changelog_like:
                        # do not duplicate it
                        if pindef not in changelog_like[pindef.block]:
                            changelog_like[pindef.block].append(pindef)
                    else:
                        changelog_like[pindef.block] = [pindef]

        if not report_only:
            print("")
    if args.report:
        report(args.report, boards_ip_blocks, changelog, changelog_like)


def main():
    # Python2 is EOL
    if not runningPython3:
        raise RuntimeError(
            "Python 2 is not supported. Please try again using Python 3."
        )
    args = parse_args()
    formmatter(args)


if __name__ == "__main__":
    main()