Makefile*: Allow external CPU dirs

Kconfig

@@ -23,7 +23,7 @@ osource "$(APPDIR)/Kconfig"
 
 # Load board configurations, which might override CPU's
 orsource "$(BOARDDIR)/Kconfig"
-orsource "$(RIOTCPU)/$(CPU)/Kconfig"
+orsource "$(CPUDIR)/Kconfig"
 
 rsource "$(RIOTBOARD)/Kconfig"
 rsource "$(RIOTCPU)/Kconfig"

Makefile.dep

@@ -6,7 +6,7 @@
 -include $(BOARDDIR)/Makefile.dep
 
 # include cpu dependencies
--include $(RIOTCPU)/$(CPU)/Makefile.dep
+-include $(CPUDIR)/Makefile.dep
 
 # include external modules dependencies
 # processed before RIOT ones to be evaluated before the 'default' rules.

Makefile.features

@@ -11,12 +11,28 @@
 
 include $(BOARDDIR)/Makefile.features
 
+CPUSDIRS := $(EXTERNAL_CPU_DIRS) $(RIOTCPU)
+
+# Take the first folder in $(CPUSDIRS) that contains a folder named $(CPU)
+CPUDIR := $(word 1,$(foreach dir,$(CPUSDIRS),$(wildcard $(dir)/$(CPU)/.)))
+# Sanitize folder
+CPUDIR := $(abspath $(CPUDIR))
+
+# Also provide CPUSDIR for compatibility and for accessing common folders
+# (e.g. include $(CPUSDIR)/common/external_common/Makefile.dep)
+CPUSDIR := $(dir $(CPUDIR))
+
+ifeq (,$(CPUDIR))
+  $(info Folders searched for the cpu: $(CPUSDIRS))
+  $(error The specified cpu $(CPU) does not exist.)
+endif
+
 # Sanity check
 ifeq (,$(CPU))
   $(error $(BOARD): CPU must be defined by board / board_common Makefile.features)
 endif
 
-include $(RIOTCPU)/$(CPU)/Makefile.features
+include $(CPUDIR)/Makefile.features
 
 # Provide CPU as a feature to allow listing all boards with a CPU
 FEATURES_PROVIDED += cpu_$(CPU)

Makefile.include

@@ -43,6 +43,7 @@ include $(RIOT_MAKEFILES_GLOBAL_PRE)
 # set undefined variables
 RIOTBASE                        ?= $(_riotbase)
 RIOTCPU                         ?= $(RIOTBASE)/cpu
+EXTERNAL_CPU_DIRS               ?=
 # Deprecated to set RIOTBOARD, use EXTERNAL_BOARD_DIRS
 RIOTBOARD                       ?= $(RIOTBASE)/boards
 EXTERNAL_BOARD_DIRS             ?=
@@ -102,6 +103,9 @@ ifeq ($(INSIDE_DOCKER),0)
   ifeq ($(origin EXTERNAL_PKG_DIRS),command line)
     $(error EXTERNAL_PKG_DIRS must be passed as environment variable, and not as command line argument)
   endif
+  ifeq ($(origin EXTERNAL_CPU_DIRS),command line)
+    $(error EXTERNAL_CPU_DIRS must be passed as environment variable, and not as command line argument)
+  endif
 endif
 
 # Deprecation of configuring 'RIOTBOARD'
@@ -148,6 +152,9 @@ EXTERNAL_MODULE_DIRS            := $(foreach dir,\
 EXTERNAL_PKG_DIRS               := $(foreach dir,\
                                              $(EXTERNAL_PKG_DIRS),\
                                              $(abspath $(dir)))
+EXTERNAL_CPU_DIRS               := $(foreach dir,\
+                                             $(EXTERNAL_CPU_DIRS),\
+                                             $(abspath $(dir)))
 
 # Ensure that all directories are set and don't contain spaces.
 ifneq (, $(filter-out 1, $(foreach v,$(__DIRECTORY_VARIABLES),$(words $($(v))))))
@@ -468,8 +475,8 @@ include $(RIOTMAKE)/boot/riotboot_dfu-util.mk
 # Include Board and CPU configuration
 INCLUDES += $(addprefix -I,$(wildcard $(BOARDDIR)/include))
 include $(BOARDDIR)/Makefile.include
-INCLUDES += -I$(RIOTCPU)/$(CPU)/include
-include $(RIOTCPU)/$(CPU)/Makefile.include
+INCLUDES += -I$(CPUDIR)/include
+include $(CPUDIR)/Makefile.include
 
 # Include common serial logic to define TERMPROG, TERMFLAGS variables based on
 # the content of RIOT_TERMINAL

boards/common/frdm/Makefile.include

@@ -19,7 +19,7 @@ endif
 OPENOCD_CONFIG ?= $(RIOTBOARD)/common/frdm/dist/openocd-$(OPENOCD_KINETIS_FAMILY).cfg
 
 # Check the flash configuration field before flashing
-OPENOCD_PRE_FLASH_CHECK_SCRIPT = $(RIOTCPU)/$(CPU)/dist/check-fcfield.sh
+OPENOCD_PRE_FLASH_CHECK_SCRIPT = $(CPUDIR)/dist/check-fcfield.sh
 
 # The board can become un-flashable after some execution,
 # use connect_assert_srst to always be able to flash or reset the board.

boards/mulle/Makefile.include

@@ -15,9 +15,9 @@ OPENOCD_DEBUG_ADAPTER ?= mulle
 # wdog-disable.bin is a precompiled binary which will disable the watchdog and
 # return control to the debugger (OpenOCD)
 OPENOCD_PRE_VERIFY_CMDS += \
-  -c 'load_image $(RIOTCPU)/$(CPU)/dist/wdog-disable.bin 0x20000000 bin' \
+  -c 'load_image $(CPUDIR)/dist/wdog-disable.bin 0x20000000 bin' \
   -c 'resume 0x20000000'
-OPENOCD_PRE_FLASH_CHECK_SCRIPT = $(RIOTCPU)/$(CPU)/dist/check-fcfield.sh
+OPENOCD_PRE_FLASH_CHECK_SCRIPT = $(CPUDIR)/dist/check-fcfield.sh
 
 # Fall back to PROGRAMMER_SERIAL for backwards compatibility
 DEBUG_ADAPTER_ID ?= $(PROGRAMMER_SERIAL)

boards/pba-d-01-kw2x/Makefile.include

@@ -20,9 +20,9 @@ PROGRAMMERS_SUPPORTED += openocd
 # wdog-disable.bin is a precompiled binary which will disable the watchdog and
 # return control to the debugger (OpenOCD)
 OPENOCD_PRE_VERIFY_CMDS += \
-  -c 'load_image $(RIOTCPU)/$(CPU)/dist/wdog-disable.bin 0x20000000 bin' \
+  -c 'load_image $(CPUDIR)/dist/wdog-disable.bin 0x20000000 bin' \
   -c 'resume 0x20000000'
-OPENOCD_PRE_FLASH_CHECK_SCRIPT = $(RIOTCPU)/$(CPU)/dist/check-fcfield.sh
+OPENOCD_PRE_FLASH_CHECK_SCRIPT = $(CPUDIR)/dist/check-fcfield.sh
 
 OPENOCD_DEBUG_ADAPTER ?= dap
 

cpu/arm7_common/Makefile.include

@@ -15,6 +15,6 @@ CFLAGS_OPT  ?= -Os
 
 CFLAGS      += $(CFLAGS_CPU) $(CFLAGS_LINK) $(CFLAGS_DBG) $(CFLAGS_OPT)
 ASFLAGS     += $(CFLAGS_CPU)
-LINKFLAGS   += -T$(RIOTCPU)/$(CPU)/ldscripts/$(CPU).ld
+LINKFLAGS   += -T$(CPUDIR)/ldscripts/$(CPU).ld
 LINKFLAGS   += $(CFLAGS_CPU) $(CFLAGS_DBG) $(CFLAGS_OPT) -static -lgcc -nostartfiles
 LINKFLAGS   += -Wl,--gc-sections

cpu/esp32/Makefile.include

@@ -120,9 +120,9 @@ PSEUDOMODULES += esp_spi_oct
 PSEUDOMODULES += esp_wifi_enterprise
 PSEUDOMODULES += stdio_usb_serial_jtag_rx
 
-INCLUDES += -I$(RIOTCPU)/$(CPU)/esp-idf/include
-INCLUDES += -I$(RIOTCPU)/$(CPU)/esp-idf/include/log
-INCLUDES += -I$(RIOTCPU)/$(CPU)/vendor/include
+INCLUDES += -I$(CPUDIR)/esp-idf/include
+INCLUDES += -I$(CPUDIR)/esp-idf/include/log
+INCLUDES += -I$(CPUDIR)/vendor/include
 
 INCLUDES += -I$(ESP32_SDK_DIR)/components
 INCLUDES += -I$(ESP32_SDK_DIR)/components/bootloader_support/include
@@ -160,7 +160,7 @@ ifneq (,$(filter esp_ble,$(USEMODULE)))
 endif
 
 ifneq (,$(filter esp_ble_nimble,$(USEMODULE)))
-  INCLUDES += -I$(RIOTCPU)/$(CPU)/include/esp_ble_nimble
+  INCLUDES += -I$(CPUDIR)/include/esp_ble_nimble
   INCLUDES += $(NIMIBASE)/nimble/transport/common/hci_h4/include
 endif
 
@@ -195,7 +195,7 @@ ifneq (,$(filter esp_wifi_enterprise,$(USEMODULE)))
 endif
 
 ifneq (,$(filter esp_eth,$(USEMODULE)))
-  INCLUDES += -I$(RIOTCPU)/$(CPU)/esp-eth
+  INCLUDES += -I$(CPUDIR)/esp-eth
   INCLUDES += -I$(ESP32_SDK_DIR)/components/esp_eth/include
   INCLUDES += -I$(ESP32_SDK_DIR)/components/esp_event/include
   INCLUDES += -I$(ESP32_SDK_DIR)/components/esp_netif/include
@@ -262,7 +262,7 @@ ifneq (,$(filter xtensa%,$(TARGET_ARCH)))
   ARCHIVES += -lxt_hal
 endif
 
-LINKFLAGS += -L$(RIOTCPU)/$(CPU)/ld/$(CPU_FAM)/
+LINKFLAGS += -L$(CPUDIR)/ld/$(CPU_FAM)/
 
 LINKFLAGS += -T$(BINDIR)/memory.ld
 LINKFLAGS += -T$(BINDIR)/sections.ld
@@ -351,11 +351,11 @@ endif
 
 LD_SCRIPTS += $(BINDIR)/memory.ld $(BINDIR)/sections.ld
 
-$(BINDIR)/memory.ld: $(RIOTCPU)/$(CPU)/ld/$(CPU_FAM)/memory.ld.in \
+$(BINDIR)/memory.ld: $(CPUDIR)/ld/$(CPU_FAM)/memory.ld.in \
                      $(BINDIR)/riotbuild/riotbuild.h pkg-prepare
 	$(Q)$(CC) -DLD_FILE_GEN $(INCLUDES) -include '$(BINDIR)/riotbuild/riotbuild.h' \
-				-I$(RIOTCPU)/$(CPU)/ld -P -x c -E $< -o $@
-$(BINDIR)/sections.ld: $(RIOTCPU)/$(CPU)/ld/$(CPU_FAM)/sections.ld.in \
+				-I$(CPUDIR)/ld -P -x c -E $< -o $@
+$(BINDIR)/sections.ld: $(CPUDIR)/ld/$(CPU_FAM)/sections.ld.in \
                        $(BINDIR)/riotbuild/riotbuild.h pkg-prepare
 	$(Q)$(CC) -DLD_FILE_GEN -include '$(BINDIR)/riotbuild/riotbuild.h' -C -P -x c -E $< -o $@
 

cpu/esp8266/Makefile.include

@@ -22,20 +22,20 @@ TARGET_ARCH ?= $(TARGET_ARCH_ESP8266)
 
 PSEUDOMODULES += esp_sw_timer
 
-INCLUDES += -I$(RIOTCPU)/$(CPU)
-INCLUDES += -I$(RIOTCPU)/$(CPU)/include
-INCLUDES += -I$(RIOTCPU)/$(CPU)/vendor
-INCLUDES += -I$(RIOTCPU)/$(CPU)/vendor/esp-idf/
-INCLUDES += -I$(RIOTCPU)/$(CPU)/vendor/esp-idf/bootloader_support/include
-INCLUDES += -I$(RIOTCPU)/$(CPU)/vendor/esp-idf/esp8266/include
-INCLUDES += -I$(RIOTCPU)/$(CPU)/vendor/esp-idf/esp8266/include/esp8266
-INCLUDES += -I$(RIOTCPU)/$(CPU)/vendor/esp-idf/heap/include
-INCLUDES += -I$(RIOTCPU)/$(CPU)/vendor/esp-idf/log/include
+INCLUDES += -I$(CPUDIR)
+INCLUDES += -I$(CPUDIR)/include
+INCLUDES += -I$(CPUDIR)/vendor
+INCLUDES += -I$(CPUDIR)/vendor/esp-idf/
+INCLUDES += -I$(CPUDIR)/vendor/esp-idf/bootloader_support/include
+INCLUDES += -I$(CPUDIR)/vendor/esp-idf/esp8266/include
+INCLUDES += -I$(CPUDIR)/vendor/esp-idf/esp8266/include/esp8266
+INCLUDES += -I$(CPUDIR)/vendor/esp-idf/heap/include
+INCLUDES += -I$(CPUDIR)/vendor/esp-idf/log/include
 
 CFLAGS += -D__ESP_FILE__=__FILE__
 
 ifneq (,$(filter esp_gdbstub,$(USEMODULE)))
-  GDBSTUB_DIR ?= $(RIOTCPU)/$(CPU)/vendor/esp-gdbstub
+  GDBSTUB_DIR ?= $(CPUDIR)/vendor/esp-gdbstub
   CFLAGS += -DGDBSTUB_BREAK_ON_INIT=1
   INCLUDES += -I$(GDBSTUB_DIR)
 endif
@@ -46,7 +46,7 @@ endif
 
 ARCHIVES += -lgcc -lhal -lwpa -lcore -lnet80211 -lphy -lpp -lstdc++
 
-LINKFLAGS += -L$(RIOTCPU)/$(CPU)/ld
+LINKFLAGS += -L$(CPUDIR)/ld
 LINKFLAGS += -Tesp8266.rom.ld
 LINKFLAGS += -Tesp8266.riot-os.ld
 LINKFLAGS += -Tesp8266.peripherals.ld

cpu/esp8266/vendor/esp-idf/wpa_supplicant/port/Makefile

@@ -4,16 +4,16 @@ include $(RIOTBASE)/Makefile.base
 
 # we have to do it in that way to avoid that $(RIOTBASE)/sys/include/crypto
 # is found first
-INCLUDES  = -I$(RIOTCPU)/$(CPU)/vendor/esp-idf/wpa_supplicant/port/include
+INCLUDES  = -I$(CPUDIR)/vendor/esp-idf/wpa_supplicant/port/include
 INCLUDES += -I$(ESP8266_RTOS_SDK_DIR)/components/wpa_supplicant/include
 INCLUDES += -I$(ESP8266_RTOS_SDK_DIR)/components/wpa_supplicant/port/include
 CFLAGS += -D__ets__ -DESPRESSIF_USE -DESP_PLATFORM=1
 CFLAGS += -Wno-strict-aliasing
 
-include $(RIOTCPU)/$(CPU)/Makefile.include
+include $(CPUDIR)/Makefile.include
 
 INCLUDES += -I$(RIOTBASE)/core/include
 INCLUDES += -I$(RIOTBASE)/sys/include
-INCLUDES += -I$(RIOTCPU)/$(CPU)/vendor/esp-idf/log/include
-INCLUDES += -I$(RIOTCPU)/$(CPU)/include
+INCLUDES += -I$(CPUDIR)/vendor/esp-idf/log/include
+INCLUDES += -I$(CPUDIR)/include
 INCLUDES += -I$(BOARDDIR)/include

cpu/esp8266/vendor/esp-idf/wpa_supplicant/src/crypto/Makefile

@@ -4,8 +4,8 @@ include $(RIOTBASE)/Makefile.base
 
 # we have to do it in that way to avoid that $(RIOTBASE)/sys/include/crypto
 # is found first
-PRE_INCLUDES += -I$(RIOTCPU)/$(CPU)/vendor/esp-idf/wpa_supplicant/include
-PRE_INCLUDES += -I$(RIOTCPU)/$(CPU)/vendor/esp-idf/wpa_supplicant/port/include
+PRE_INCLUDES += -I$(CPUDIR)/vendor/esp-idf/wpa_supplicant/include
+PRE_INCLUDES += -I$(CPUDIR)/vendor/esp-idf/wpa_supplicant/port/include
 PRE_INCLUDES += -I$(ESP8266_RTOS_SDK_DIR)/components/wpa_supplicant/include
 PRE_INCLUDES += -I$(ESP8266_RTOS_SDK_DIR)/components/wpa_supplicant/port/include
 CFLAGS += -D__ets__ -DESPRESSIF_USE -DESP_PLATFORM=1

cpu/kinetis/Makefile.include

@@ -14,7 +14,7 @@ ifeq (K, $(KINETIS_SERIES))
 endif
 
 # Add search path for linker scripts
-LINKFLAGS += -L$(RIOTCPU)/$(CPU)/ldscripts
+LINKFLAGS += -L$(CPUDIR)/ldscripts
 
 # Use generic linker script for all Kinetis based CPUs
 LINKER_SCRIPT = kinetis.ld

cpu/lpc23xx/Makefile

@@ -1,6 +1,6 @@
 MODULE =cpu
 
-include $(RIOTCPU)/$(CPU)/Makefile.include
+include $(CPUDIR)/Makefile.include
 
 DIRS = $(RIOTCPU)/arm7_common periph
 

cpu/qn908x/Makefile.include

@@ -1,5 +1,5 @@
 # Add search path for linker scripts
-LINKFLAGS += -L$(RIOTCPU)/$(CPU)/ldscripts
+LINKFLAGS += -L$(CPUDIR)/ldscripts
 LINKER_SCRIPT = qn908x.ld
 
 # Internal FLASH memory is located at address 0x0100000, aliased to address
@@ -34,6 +34,6 @@ CFLAGS += \
 # some files from the include/vendor directory directly so we need to add that
 # include path here.
 PSEUDOMODULES += vendor_%
-INCLUDES += -I$(RIOTCPU)/$(CPU)/include/vendor
+INCLUDES += -I$(CPUDIR)/include/vendor
 
 include $(RIOTMAKE)/arch/cortexm.inc.mk

cpu/qn908x/vendor/Makefile

@@ -7,8 +7,8 @@ SUBMODULES_NOFORCE := 1
 
 CFLAGS  += -Wno-unused-parameter -Wno-sign-compare
 INCLUDES += \
-    -I$(RIOTCPU)/$(CPU)/include/vendor/ \
-    -I$(RIOTCPU)/$(CPU)/include/vendor/drivers/ \
+    -I$(CPUDIR)/include/vendor/ \
+    -I$(CPUDIR)/include/vendor/drivers/ \
     #
 
 include $(RIOTBASE)/Makefile.base

doc/doxygen/src/creating-an-application.md

@@ -144,17 +144,19 @@ add a testrunner Python script. Just answer 'y' when prompted.
 # Creating an out of tree application structure
 
 Applications written for RIOT do not have to reside in the RIOT tree. Out of
-tree applications, modules and boards are supported.
+tree applications, modules boards, and cpus are supported.
 
-For a full application with custom board and modules, the following directory
-tree can be used:
+For a full application with custom board, cpu and modules, the following
+directory tree can be used:
 
 ```
 ├── apps
 │   └── my_app
 │       └── Makefile
 ├── boards
 │   └── my_board
+├── cpu
+│   └── my_cpu
 ├── modules
 │   └── my_module
 │       ├── include
@@ -228,6 +230,18 @@ Note that the make variable (here `USEMODULE_INCLUDES_my_module`) must be unique
 for every module to make this work. Including the module name here is usually
 sufficient.
 
+## External CPUs
+
+Similar to the external boards and external modules, external cpus can be
+written in a similar way as regular in-tree cpus.  There is an optional
+parameter called `EXTERNAL_CPU_DIRS`, which, when populated, can point the RIOT
+build system to an additional directory to search for CPU definitions, the same
+way `EXTERNAL_BOARD_DIRS` provides additional board definitions.  This allows a
+developer to prototype their CPU definition without adding something under
+development upstream prematurely.  It also supports custom native CPUs, such as
+if a custom IO handling scheme is needed, that would not warrant being
+upstreamed.
+
 ## Extra Makefile Scaffolding
 
 A bit of extra, but optional, Makefile scaffolding can help to keep the project

drivers/periph_common/Kconfig.gpio

@@ -58,4 +58,4 @@ config MODULE_PERIPH_INIT_GPIO_TAMPER_WAKE
 
 endif # MODULE_PERIPH_GPIO
 
-osource "$(RIOTCPU)/$(CPU)/periph/Kconfig.gpio"
+osource "$(CPUDIR)/periph/Kconfig.gpio"

drivers/periph_common/Kconfig.i2c

@@ -31,4 +31,4 @@ config MODULE_PERIPH_INIT_I2C_RECONFIGURE
 
 endif # MODULE_PERIPH_I2C
 
-osource "$(RIOTCPU)/$(CPU)/periph/Kconfig.i2c"
+osource "$(CPUDIR)/periph/Kconfig.i2c"

drivers/periph_common/Kconfig.rtc

@@ -43,4 +43,4 @@ config MODULE_PERIPH_INIT_RTC_MEM
     depends on MODULE_PERIPH_RTC_MEM
 
 # Include CPU specific configurations
-osource "$(RIOTCPU)/$(CPU)/periph/Kconfig.rtc"
+osource "$(CPUDIR)/periph/Kconfig.rtc"

drivers/periph_common/Kconfig.spi

@@ -46,6 +46,6 @@ config MODULE_PERIPH_INIT_SPI_GPIO_MODE
     depends on MODULE_PERIPH_SPI_GPIO_MODE
 
 # Include CPU specific configurations
-osource "$(RIOTCPU)/$(CPU)/periph/Kconfig.spi"
+osource "$(CPUDIR)/periph/Kconfig.spi"
 
 endif # MODULE_PERIPH_SPI

drivers/periph_common/Kconfig.timer

@@ -46,5 +46,5 @@ menuconfig KCONFIG_USEMODULE_PERIPH_TIMER
 
 # Include CPU specific configurations
 if KCONFIG_USEMODULE_PERIPH_TIMER
-osource "$(RIOTCPU)/$(CPU)/periph/Kconfig.timer"
+osource "$(CPUDIR)/periph/Kconfig.timer"
 endif

makefiles/application.inc.mk

@@ -1,6 +1,6 @@
 MODULE = $(APPLICATION_MODULE)
 
-DIRS += $(RIOTCPU)/$(CPU) $(BOARDDIR)
+DIRS += $(CPUDIR) $(BOARDDIR)
 DIRS += $(RIOTBASE)/core $(RIOTBASE)/core/lib $(RIOTBASE)/drivers $(RIOTBASE)/sys
 
 # For regular modules, adding files to BLOBS to their Makefile is sufficient to

makefiles/arch/cortexm.inc.mk

@@ -27,7 +27,7 @@ CFLAGS_OPT  ?= -Os
 CFLAGS += $(CFLAGS_CPU) $(CFLAGS_LINK) $(CFLAGS_DBG) $(CFLAGS_OPT)
 
 ASFLAGS += $(CFLAGS_CPU)
-LINKFLAGS += -L$(RIOTCPU)/$(CPU)/ldscripts -L$(RIOTCPU)/cortexm_common/ldscripts
+LINKFLAGS += -L$(CPUDIR)/ldscripts -L$(RIOTCPU)/cortexm_common/ldscripts
 LINKER_SCRIPT ?= $(CPU_MODEL).ld
 LINKFLAGS += -T$(LINKER_SCRIPT) -Wl,--fatal-warnings
 

makefiles/arch/riscv.inc.mk

@@ -85,7 +85,7 @@ CFLAGS_LINK  = -ffunction-sections -fdata-sections
 CFLAGS_DBG  ?= -g3
 CFLAGS_OPT  ?= -Os
 
-LINKFLAGS += -L$(RIOTCPU)/$(CPU)/ldscripts -L$(RIOTCPU)/riscv_common/ldscripts
+LINKFLAGS += -L$(CPUDIR)/ldscripts -L$(RIOTCPU)/riscv_common/ldscripts
 LINKER_SCRIPT ?= $(CPU_MODEL).ld
 LINKFLAGS += -T$(LINKER_SCRIPT)