stm32cube: remove HAL Legacy definitions header from build files

Remove the HAL Legacy definitions header from most series using a dummy
replacement (shared by all series!) to ensure proper compilation despite
the missing file, and update the README of affected series to remove entry
documenting patches to the HAL Legacy definitions header.

While it at, get rid of all other legacy headers (can_legacy / eth_legacy)
which Zephyr never uses. This is purely cosmectic as these headers are
only used if the corresponding HAL module is enabled but Zephyr has never
enabled (and will never enable!) the CAN_LEGACY or ETH_LEGACY modules.

The STM32F7 and STM32U5 series are not modified and will continue to use
their current (patched) HAL Legacy definitions header: some drivers have
not been updated(!) and require legacy definitions to build...

Signed-off-by: Mathieu Choplain <mathieu.choplain-ext@st.com>

Author: mathieuchopstm

stm32cube/CMakeLists.txt

@@ -129,6 +129,10 @@ foreach(series ${supported_series})
 	  )
 
     add_subdirectory(${cube_dir})
+
+    # Remember the series' name for next steps
+    # (in the format of CONFIG_SOC_SERIES_<xxx>)
+    set(TARGET_SERIES ${series_to_upper})
   endif()
 endforeach()
 
@@ -139,3 +143,45 @@ endif()
 
 # Add the series-agnostic LL headers to include directories
 zephyr_include_directories(common_ll/include)
+
+# Add placeholder for STM32Cube HAL Legacy definitions header
+#
+# The STM32Cube packages contain header "stm32_hal_legacy.h"
+# which provides aliases of old definitions that have been
+# changed/renamed for backwards compatibility. This is not
+# useful to Zephyr since the STM32 drivers are maintained
+# and never use "legacy" STM32Cube APIs or definitions.
+# More annoyingly, some definitions provided by the legacy
+# header alias with ones provided by Zephyr which results
+# in build failures. As such, we'd like to get rid of this
+# header whenever possible...
+#
+# Unfortunately, the "stm32XXXxx_hal_def.h" header contains:
+#
+#   #include "Legacy/stm32_hal_legacy.h"
+#
+# To ensure this directive does not cause a build failure
+# due to the legacy header no longer existing, we add a
+# carefully crafted directory to the include path such
+# that an empty header file is included by this directive.
+# We can then get rid of the legacy header entirely!
+#
+# ...except that HAL drivers of some series are using the
+# legacy definitions, so we keep an escape hatch for such
+# series even though their drivers are in the wrong.
+set(series_with_legacy_header
+  # Please provide a comment next to series name indicating
+  # which driver(s) are faulty and the ST Internal Reference
+  # used to track the issue.
+
+  STM32F7X # HAL RCC (ST Internal Reference: 220413)
+  STM32U5X # HAL PCD + LL USB
+)
+
+list(FIND series_with_legacy_header ${TARGET_SERIES} index)
+if(${index} EQUAL -1)
+  # Series without legacy header: add placeholder to include path
+  zephyr_include_directories(legacy_placeholder)
+else()
+  # Series with legacy header: it's already in the include path!
+endif()

stm32cube/legacy_placeholder/Legacy/stm32_hal_legacy.h

@@ -0,0 +1 @@
+/* Dummy replacement for HAL Legacy definitions header (c.f. CMakeLists.txt) */

stm32cube/stm32c0xx/README

@@ -40,8 +40,4 @@ Patch List:
     -Added stm32cube/stm32c0xx/drivers/include/stm32_assert.h
     -Removed unused stm32cube/stm32c0xx/drivers/include/stm32_assert_template.h
 
-   *Fix to remove PAGESIZE definition which conflicts with POSIX
-    Impacted files:
-     drivers/include/Legacy/stm32_hal_legacy.h
-
    See release_note.html from STM32Cube