[GitHub] [nuttx] hartmannathan commented on a diff in pull request #8992: stm32 {f1,f2,f3,f4,F412,f7,h7,f0l0g0,wb,l15,l4,l5,g4xx} Remove GPIO_{SPEED|MODE}_xxx and provide a legacy path for lazy migration

["hartmannathan (via GitHub)" <gi...@apache.org>]

hartmannathan commented on code in PR #8992:
URL: https://github.com/apache/nuttx/pull/8992#discussion_r1168967347


##########
arch/arm/src/stm32f0l0g0/hardware/stm32f05x_pinmap_legacy.h:
##########
@@ -0,0 +1,120 @@
+/****************************************************************************
+ * arch/arm/src/stm32f0l0g0/hardware/stm32f05x_pinmap_legacy.h
+ *
+ * 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.
+ *
+ ****************************************************************************/
+
+#ifndef __ARCH_ARM_SRC_STM32F0L0G0_HARDWARE_STM32F05X_PINMAP_LEGACY_H
+#define __ARCH_ARM_SRC_STM32F0L0G0_HARDWARE_STM32F05X_PINMAP_LEGACY_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include "stm32_gpio.h"
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+/* Alternate Pin Functions.
+ *
+ * Alternative pin selections are provided with a numeric suffix like _1,
+ * _2, etc.  Drivers, however, will use the pin selection without the numeric
+ * suffix.  Additional definitions are required in the board.h file.  For
+ * example, if USART1_TX connects vis PA9 on some board, then the following

Review Comment:
   ```suggestion
    * example, if USART1_TX connects via PA9 on some board, then the following
   ```



##########
arch/arm/src/stm32f0l0g0/hardware/stm32f09x_pinmap_legacy.h:
##########
@@ -0,0 +1,415 @@
+/****************************************************************************
+ * arch/arm/src/stm32f0l0g0/hardware/stm32f09x_pinmap_legacy.h
+ *
+ * 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.
+ *
+ ****************************************************************************/
+
+#ifndef __ARCH_ARM_SRC_STM32F0L0G0_HARDWARE_STM32F09X_PINMAP_LEGACY_H
+#define __ARCH_ARM_SRC_STM32F0L0G0_HARDWARE_STM32F09X_PINMAP_LEGACY_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include "stm32_gpio.h"
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+/* Alternate Pin Functions.
+ *
+ * Alternative pin selections are provided with a numeric suffix like _1, _2,
+ * etc. Drivers, however, will use the pin selection without the numeric
+ * suffix. Additional definitions are required in the board.h file.  For
+ * example, if CAN1_RX connects vis PD0 on some board, then the following

Review Comment:
   ```suggestion
    * example, if CAN1_RX connects via PD0 on some board, then the following
   ```



##########
arch/arm/src/stm32f0l0g0/hardware/stm32g0_pinmap_legacy.h:
##########
@@ -0,0 +1,264 @@
+/****************************************************************************
+ * arch/arm/src/stm32f0l0g0/hardware/stm32g0_pinmap_legacy.h
+ *
+ *   Copyright (C) 2019 Gregory Nutt. All rights reserved.
+ *   Author: Mateusz Szafoni <ra...@railab.me>
+ *
+ *   Copyright (C) 2019 Fundação CERTI. All rights reserved.
+ *   Author: Daniel Pereira Volpato <dp...@certi.org.br>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ * 3. Neither the name NuttX nor the names of its contributors may be
+ *    used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+ * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ ****************************************************************************/
+
+#ifndef __ARCH_ARM_SRC_STM32F0L0G0_HARDWARE_STM32G0_PINMAP_LEGACY_H
+#define __ARCH_ARM_SRC_STM32F0L0G0_HARDWARE_STM32G0_PINMAP_LEGACY_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include "stm32_gpio.h"
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+/* Alternate Pin Functions.
+ *
+ * Alternative pin selections are provided with a numeric suffix like _1, _2,
+ * etc. Drivers, however, will use the pin selection without the numeric
+ * suffix. Additional definitions are required in the board.h file.  For
+ * example, if CAN1_RX connects vis PA11 on some board, then the following

Review Comment:
   ```suggestion
    * example, if CAN1_RX connects via PA11 on some board, then the following
   ```



##########
arch/arm/src/stm32f7/Kconfig:
##########
@@ -1749,6 +1749,27 @@ config STM32F7_WWDG
 
 endmenu
 
+config STM32F7_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.
+
+		STM32F7_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 outut the required changes that one needs

Review Comment:
   ```suggestion
   		file and a legacy pinmap and output the required changes that one needs
   ```



##########
arch/arm/src/stm32f7/hardware/stm32f76xx77xx_pinmap_legacy.h:
##########
@@ -0,0 +1,1335 @@
+/****************************************************************************
+ * arch/arm/src/stm32f7/hardware/stm32f76xx77xx_pinmap_legacy.h
+ *
+ * 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.
+ *
+ ****************************************************************************/
+
+#ifndef __ARCH_ARM_SRC_STM32F7_HARDWARE_STM32F76XX77XX_PINMAP_LEGACY_H
+#define __ARCH_ARM_SRC_STM32F7_HARDWARE_STM32F76XX77XX_PINMAP_LEGACY_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include "stm32_gpio.h"
+
+#if defined(CONFIG_STM32F7_STM32F76XX) || defined(CONFIG_STM32F7_STM32F77XX)
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+/* Alternate Pin Functions.
+ * All members of the STM32F76|7xxx family share the same pin multiplexing
+ *(although they may differ in the pins physically available).
+ *
+ * Alternative pin selections are provided with a numeric suffix like _1, _2,
+ * etc. Drivers, however, will use the pin selection without the numeric
+ * suffix.
+ * Additional definitions are required in the board.h file.  For example, if
+ * CAN1_RX connects vis PA11 on some board, then the following definitions

Review Comment:
   ```suggestion
    * CAN1_RX connects via PA11 on some board, then the following definitions
   ```



##########
tools/stm32_pinmap_tool.py:
##########
@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+############################################################################
+# tools/stm32_pinmap_tool.py
+#
+# 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 wee 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 defines as these

Review Comment:
   ```suggestion
      These speeds should have never been part of the arch defines as these
   ```



##########
tools/stm32_pinmap_tool.py:
##########
@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+############################################################################
+# tools/stm32_pinmap_tool.py
+#
+# 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 wee 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 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 on 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

Review Comment:
   ```suggestion
      3. Add a STM32Hx_USE_LEGACY_PINMAP to the Kconfig defaulted to y
   ```



##########
tools/stm32_pinmap_tool.py:
##########
@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+############################################################################
+# tools/stm32_pinmap_tool.py
+#
+# 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 wee 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 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 on 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 outut the required changes that one needs

Review Comment:
   ```suggestion
                  file and a legacy pinmap and output the required changes that one needs
   ```



##########
arch/arm/src/stm32h7/Kconfig:
##########
@@ -944,6 +944,26 @@ config STM32H7_UART8
 endmenu # STM32H7 U[S]ART Selection
 endmenu # STM32H7 Peripheral Selection
 
+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 outut the required changes that one needs

Review Comment:
   ```suggestion
   		file and a legacy pinmap and output the required changes that one needs
   ```



##########
tools/stm32_pinmap_tool.py:
##########
@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+############################################################################
+# tools/stm32_pinmap_tool.py
+#
+# 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 wee 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 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 on 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 outut 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 exitst, 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. Leagcy pinmaps erroneously added speeds on pins that are only used
+    as an inputs (i.e UART4_RX). Theses speed 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 a 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 (mostlikley and stm32f1")

Review Comment:
   ```suggestion
      No pins are defined in board.h to change speeds on (most likely an stm32f1")
   ```



##########
arch/arm/src/stm32f0l0g0/Kconfig:
##########
@@ -945,6 +945,26 @@ config ARCH_BOARD_STM32F0G0L0_CUSTOM_CLOCKCONFIG
 	---help---
 		Enables special, board-specific STM32 clock configuration.
 
+config STM32F0G0L0_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.
+
+		STM32F0G0L0_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 outut the required changes that one needs

Review Comment:
   ditto
   
   ```suggestion
   		file and a legacy pinmap and output the required changes that one needs
   ```



##########
arch/arm/src/stm32f0l0g0/hardware/stm32l0_pinmap_legacy.h:
##########
@@ -0,0 +1,327 @@
+/****************************************************************************
+ * arch/arm/src/stm32f0l0g0/hardware/stm32l0_pinmap_legacy.h
+ *
+ * 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.
+ *
+ ****************************************************************************/
+
+#ifndef __ARCH_ARM_SRC_STM32F0L0G0_HARDWARE_STM32L0_PINMAP_LEGACY_H
+#define __ARCH_ARM_SRC_STM32F0L0G0_HARDWARE_STM32L0_PINMAP_LEGACY_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include "stm32_gpio.h"
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+/* Alternate Pin Functions.
+ *
+ * Alternative pin selections are provided with a numeric suffix like _1, _2,
+ * etc. Drivers, however, will use the pin selection without the numeric
+ * suffix. Additional definitions are required in the board.h file.  For
+ * example, if CAN1_RX connects vis PA11 on some board, then the following

Review Comment:
   ```suggestion
    * example, if CAN1_RX connects via PA11 on some board, then the following
   ```



##########
arch/arm/src/stm32/Kconfig:
##########
@@ -3452,6 +3452,26 @@ config STM32_NOEXT_VECTORS
 		Sometimes you may not need any Vector support beyond SysTick
 		and wish to save memory. This applies only to ARMv7-M architectures.
 
+config STM32_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.
+
+		STM32_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 outut the required changes that one needs

Review Comment:
   very minor nit:
   
   ```suggestion
   		file and a legacy pinmap and output the required changes that one needs
   ```



##########
arch/arm/src/stm32l4/Kconfig:
##########
@@ -1019,6 +1019,26 @@ config STM32L4_SRAM3_HEAP
 		NOTE: you must also select an appropriate number of memory regions in the
 		'Memory Management' section.
 
+config STM32L4_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.
+
+		STM32L4_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 outut the required changes that one needs

Review Comment:
   ```suggestion
   		file and a legacy pinmap and output the required changes that one needs
   ```



##########
arch/arm/src/stm32l5/Kconfig:
##########
@@ -196,6 +196,26 @@ config STM32L5_SRAM2_INIT
 		case, the board should handle the initialization itself at the appropriate
 		time.
 
+config STM32L5_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.
+
+		CONFIG_STM32L5_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 outut the required changes that one needs

Review Comment:
   ```suggestion
   		file and a legacy pinmap and output the required changes that one needs
   ```



##########
arch/arm/src/stm32wb/Kconfig:
##########
@@ -381,6 +381,26 @@ config STM32WB_SRAM2B_INIT
 		avoided by first writing to all locations to force the parity into a valid
 		state.
 
+config STM32WB_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.
+
+		CONFIG_STM32WB_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 outut the required changes that one needs

Review Comment:
   ```suggestion
   		file and a legacy pinmap and output the required changes that one needs
   ```



##########
tools/stm32_pinmap_tool.py:
##########
@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+############################################################################
+# tools/stm32_pinmap_tool.py
+#
+# 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 wee 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 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 on ALT

Review Comment:
   I think this is what was intended?
   
   ```suggestion
      Furthermore, pinmaps did not suffix pins that had only one ALT
   ```



##########
tools/stm32_pinmap_tool.py:
##########
@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+############################################################################
+# tools/stm32_pinmap_tool.py
+#
+# 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 wee just set it

Review Comment:
   ```suggestion
                   # All others had a OSPEDD reg so we just set it
   ```



##########
tools/stm32_pinmap_tool.py:
##########
@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+############################################################################
+# tools/stm32_pinmap_tool.py
+#
+# 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 wee 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 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 on 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 outut 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 exitst, 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. Leagcy pinmaps erroneously added speeds on pins that are only used

Review Comment:
   ```suggestion
    2. Legacy pinmaps erroneously added speeds on pins that are only used
   ```



##########
tools/stm32_pinmap_tool.py:
##########
@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+############################################################################
+# tools/stm32_pinmap_tool.py
+#
+# 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 wee 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 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 on 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 outut 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 exitst, create a copy of the original pin map named <filename>_legacy.<ext>",

Review Comment:
   ```suggestion
           help="If one does not exist, create a copy of the original pin map named <filename>_legacy.<ext>",
   ```



##########
tools/stm32_pinmap_tool.py:
##########
@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+############################################################################
+# tools/stm32_pinmap_tool.py
+#
+# 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 wee 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 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 on 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 outut 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 exitst, 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. Leagcy pinmaps erroneously added speeds on pins that are only used
+    as an inputs (i.e UART4_RX). Theses speed 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.=

Review Comment:
   ```suggestion
    layout of the circuit board and load presented to the SoC on that pin.
   ```



##########
tools/stm32_pinmap_tool.py:
##########
@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+############################################################################
+# tools/stm32_pinmap_tool.py
+#
+# 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 wee 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 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 on 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 outut 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 exitst, 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. Leagcy pinmaps erroneously added speeds on pins that are only used
+    as an inputs (i.e UART4_RX). Theses speed 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 a existing systems that are relying on

Review Comment:
   ```suggestion
    to insure these changes do not break existing systems that are relying on
   ```



##########
tools/stm32_pinmap_tool.py:
##########
@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+############################################################################
+# tools/stm32_pinmap_tool.py
+#
+# 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 wee 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 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 on 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 outut 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 exitst, 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. Leagcy pinmaps erroneously added speeds on pins that are only used
+    as an inputs (i.e UART4_RX). Theses speed can be removed from the board.h

Review Comment:
   ```suggestion
       as an inputs (i.e UART4_RX). These speeds can be removed from the board.h
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org