arch: Refactor architecture library

This commit splits the "architecture" concept into two, more specific
concepts: the vendor, and the architecture. This allows us to refactor
architecture support into more common parts, and contain
architecture-specific logic more cleanly.

Some architectural functions and definitions have also been renamed to
better reflect their origin and to maintain naming consistency.

As architectures are generally not intended to be built independently of
any firmware, the CI script no longer tries to build the architecture
library.

Change-Id: I04430e3a5503d29247517b869e36c180d6d21eaa
Signed-off-by: Chris Kay <chris.kay@arm.com>

25 files changed, 177 insertions, 66 deletions

diff --git a/arch/arm/armv7-m/arch.mk b/arch/arm/armv7-m/arch.mk
new file mode 100644
index 00000000..d216e197
--- /dev/null
+++ b/arch/arm/armv7-m/arch.mk
@@ -0,0 +1,21 @@
+#
+# Arm SCP/MCP Software
+# Copyright (c) 2018-2020, Arm Limited and Contributors. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+
+BS_LIB_SOURCES_$(BS_ARCH_ARCH) += arch_exceptions.c
+BS_LIB_SOURCES_$(BS_ARCH_ARCH) += arch_handlers.c
+BS_LIB_SOURCES_$(BS_ARCH_ARCH) += arch_main.c
+BS_LIB_SOURCES_$(BS_ARCH_ARCH) += arch_nvic.c
+
+BS_LIB_SOURCES_$(BS_ARCH_ARCH) := $(addprefix $(ARCH_DIR)/$(BS_ARCH_VENDOR)/$(BS_ARCH_ARCH)/src/,$(BS_LIB_SOURCES_$(BS_ARCH_ARCH)))
+
+ifneq ($(filter $(BS_FIRMWARE_CPU),cortex-m3 cortex-m7),)
+    ifeq ($(BS_COMPILER),ARM)
+        BS_LIB_DEPS += $(OS_DIR)/RTX/Library/ARM/RTX_CM3.lib
+    else
+        BS_LIB_DEPS += $(OS_DIR)/RTX/Library/GCC/libRTX_CM3.a
+    endif
+endif
diff --git a/arch/src/armv7-m/exceptions.h b/arch/arm/armv7-m/include/arch_exceptions.h
index 0aa1363d..0aa1363d 100644
--- a/arch/src/armv7-m/exceptions.h
+++ b/arch/arm/armv7-m/include/arch_exceptions.h
diff --git a/arch/src/armv7-m/scatter.h b/arch/arm/armv7-m/include/arch_scatter.h
index 157ded16..157ded16 100644
--- a/arch/src/armv7-m/scatter.h
+++ b/arch/arm/armv7-m/include/arch_scatter.h
diff --git a/arch/src/armv7-m/ld.S b/arch/arm/armv7-m/src/arch.ld.S
index 9b237cca..532f4e43 100644
--- a/arch/src/armv7-m/ld.S
+++ b/arch/arm/armv7-m/src/arch.ld.S
@@ -8,7 +8,7 @@
  *      GNU LD linker script.
  */
 
-#include "scatter.h"
+#include <arch_scatter.h>
 
 ENTRY(arch_exception_reset)
 
diff --git a/arch/src/armv7-m/scatter.S b/arch/arm/armv7-m/src/arch.scatter.S
index 98103100..5359d0df 100644
--- a/arch/src/armv7-m/scatter.S
+++ b/arch/arm/armv7-m/src/arch.scatter.S
@@ -8,7 +8,7 @@
  *      Arm Compiler 6 scatter file.
  */
 
-#include "scatter.h"
+#include <arch_scatter.h>
 
 #if FMW_MEM_MODE == ARCH_MEM_MODE_SINGLE_REGION
 /*
diff --git a/arch/src/armv7-m/exceptions.c b/arch/arm/armv7-m/src/arch_exceptions.c
index 1095d35f..3eb1d1f5 100644
--- a/arch/src/armv7-m/exceptions.c
+++ b/arch/arm/armv7-m/src/arch_exceptions.c
@@ -8,7 +8,7 @@
  *      ARMv7-M exception handlers.
  */
 
-#include "exceptions.h"
+#include <arch_exceptions.h>
 
 #include <fmw_cmsis.h>
 
diff --git a/arch/src/armv7-m/handlers.c b/arch/arm/armv7-m/src/arch_handlers.c
index 5999d1b1..5999d1b1 100644
--- a/arch/src/armv7-m/handlers.c
+++ b/arch/arm/armv7-m/src/arch_handlers.c
diff --git a/arch/src/arm_main.c b/arch/arm/armv7-m/src/arch_main.c
index 333f9b7d..333f9b7d 100644
--- a/arch/src/arm_main.c
+++ b/arch/arm/armv7-m/src/arch_main.c
diff --git a/arch/src/arm_nvic.c b/arch/arm/armv7-m/src/arch_nvic.c
index 0e30fb9d..0e30fb9d 100644
--- a/arch/src/arm_nvic.c
+++ b/arch/arm/armv7-m/src/arch_nvic.c
diff --git a/arch/src/arm_mm.c b/arch/arm/src/arch_mm.c
index 9abb58bf..9abb58bf 100644
--- a/arch/src/arm_mm.c
+++ b/arch/arm/src/arch_mm.c
diff --git a/arch/arm/vendor.mk b/arch/arm/vendor.mk
new file mode 100644
index 00000000..a53fa4f0
--- /dev/null
+++ b/arch/arm/vendor.mk
@@ -0,0 +1,14 @@
+#
+# Arm SCP/MCP Software
+# Copyright (c) 2018-2020, Arm Limited and Contributors. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+
+include $(ARCH_DIR)/$(BS_ARCH_VENDOR)/$(BS_ARCH_ARCH)/arch.mk
+
+BS_LIB_INCLUDES_$(BS_ARCH_VENDOR) += $(TOP_DIR)/cmsis/CMSIS/Core/Include
+
+BS_LIB_SOURCES_$(BS_ARCH_VENDOR) += arch_mm.c
+
+BS_LIB_SOURCES_$(BS_ARCH_VENDOR) := $(addprefix $(ARCH_DIR)/$(BS_ARCH_VENDOR)/src/,$(BS_LIB_SOURCES_$(BS_ARCH_VENDOR)))
diff --git a/arch/none/host/arch.mk b/arch/none/host/arch.mk
new file mode 100644
index 00000000..abfc2b77
--- /dev/null
+++ b/arch/none/host/arch.mk
@@ -0,0 +1,15 @@
+#
+# Arm SCP/MCP Software
+# Copyright (c) 2018-2020, Arm Limited and Contributors. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+
+BS_LIB_SOURCES_$(BS_ARCH_ARCH) += arch_interrupt.c
+BS_LIB_SOURCES_$(BS_ARCH_ARCH) += arch_main.c
+
+ifeq ($(BUILD_HAS_MULTITHREADING),yes)
+    BS_LIB_SOURCES_$(BS_ARCH_ARCH) += arch_thread.c
+endif
+
+BS_LIB_SOURCES_$(BS_ARCH_ARCH) := $(addprefix $(ARCH_DIR)/$(BS_ARCH_VENDOR)/$(BS_ARCH_ARCH)/src/,$(BS_LIB_SOURCES_$(BS_ARCH_ARCH)))
diff --git a/arch/src/host_interrupt.c b/arch/none/host/src/arch_interrupt.c
index 3a517f49..34e6f4db 100644
--- a/arch/src/host_interrupt.c
+++ b/arch/none/host/src/arch_interrupt.c
@@ -31,38 +31,38 @@ static int is_enabled(unsigned int interrupt, bool *state)
 
 static int enable(unsigned int interrupt)
 {
-   return FWK_E_SUPPORT;
+    return FWK_E_SUPPORT;
 }
 
 static int disable(unsigned int interrupt)
 {
-   return FWK_E_SUPPORT;
+    return FWK_E_SUPPORT;
 }
 
 static int is_pending(unsigned int interrupt, bool *state)
 {
-   return FWK_E_SUPPORT;
+    return FWK_E_SUPPORT;
 }
 
 static int set_pending(unsigned int interrupt)
 {
-   return FWK_E_SUPPORT;
+    return FWK_E_SUPPORT;
 }
 
 static int clear_pending(unsigned int interrupt)
 {
-   return FWK_E_SUPPORT;
+    return FWK_E_SUPPORT;
 }
 
-static int set_isr_irq(unsigned int interrupt,
-                           void (*isr)(void))
+static int set_isr_irq(unsigned int interrupt, void (*isr)(void))
 {
-   return FWK_E_SUPPORT;
+    return FWK_E_SUPPORT;
 }
 
-static int set_isr_irq_param(unsigned int interrupt,
-                             void (*isr)(uintptr_t param),
-                             uintptr_t parameter)
+static int set_isr_irq_param(
+    unsigned int interrupt,
+    void (*isr)(uintptr_t param),
+    uintptr_t parameter)
 {
     return FWK_E_SUPPORT;
 }
@@ -79,29 +79,29 @@ static int set_isr_nmi_param(void (*isr)(uintptr_t param), uintptr_t parameter)
 
 static int set_isr_fault(void (*isr)(void))
 {
-   return FWK_E_SUPPORT;
+    return FWK_E_SUPPORT;
 }
 
 static int get_current(unsigned int *interrupt)
 {
-   return FWK_E_SUPPORT;
+    return FWK_E_SUPPORT;
 }
 
 static const struct fwk_arch_interrupt_driver driver = {
-    .global_enable  = global_enable,
+    .global_enable = global_enable,
     .global_disable = global_disable,
-    .is_enabled     = is_enabled,
-    .enable         = enable,
-    .disable        = disable,
-    .is_pending     = is_pending,
-    .set_pending    = set_pending,
-    .clear_pending  = clear_pending,
-    .set_isr_irq    = set_isr_irq,
+    .is_enabled = is_enabled,
+    .enable = enable,
+    .disable = disable,
+    .is_pending = is_pending,
+    .set_pending = set_pending,
+    .clear_pending = clear_pending,
+    .set_isr_irq = set_isr_irq,
     .set_isr_irq_param = set_isr_irq_param,
-    .set_isr_nmi    = set_isr_nmi,
+    .set_isr_nmi = set_isr_nmi,
     .set_isr_nmi_param = set_isr_nmi_param,
-    .set_isr_fault  = set_isr_fault,
-    .get_current    = get_current,
+    .set_isr_fault = set_isr_fault,
+    .get_current = get_current,
 };
 
 int arch_interrupt_init(const struct fwk_arch_interrupt_driver **_driver)
diff --git a/arch/src/host.c b/arch/none/host/src/arch_main.c
index 5e319dc3..5e319dc3 100644
--- a/arch/src/host.c
+++ b/arch/none/host/src/arch_main.c
diff --git a/arch/src/host_thread.c b/arch/none/host/src/arch_thread.c
index 9e76fac4..76e052a6 100644
--- a/arch/src/host_thread.c
+++ b/arch/none/host/src/arch_thread.c
@@ -176,7 +176,9 @@ uint32_t osThreadFlagsClear(uint32_t flags)
     return old_flags;
 }
 
-osThreadId_t osThreadNew(osThreadFunc_t func, void *argument,
+osThreadId_t osThreadNew(
+    osThreadFunc_t func,
+    void *argument,
     const osThreadAttr_t *attr)
 {
     int status;
diff --git a/arch/none/vendor.mk b/arch/none/vendor.mk
new file mode 100644
index 00000000..285a3e0b
--- /dev/null
+++ b/arch/none/vendor.mk
@@ -0,0 +1,8 @@
+#
+# Arm SCP/MCP Software
+# Copyright (c) 2018-2020, Arm Limited and Contributors. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+
+include $(ARCH_DIR)/$(BS_ARCH_VENDOR)/$(BS_ARCH_ARCH)/arch.mk
diff --git a/arch/src/Makefile b/arch/src/Makefile
index 434705f3..53cfba41 100644
--- a/arch/src/Makefile
+++ b/arch/src/Makefile
@@ -10,29 +10,20 @@ include $(BS_DIR)/toolchain.mk
 
 BS_LIB_NAME = arch
 
-BS_LIB_SOURCES_armv7-m += armv7-m/exceptions.c
-BS_LIB_SOURCES_armv7-m += armv7-m/handlers.c
-BS_LIB_SOURCES_armv7-m += arm_nvic.c
-BS_LIB_SOURCES_armv7-m += arm_main.c
-BS_LIB_SOURCES_armv7-m += arm_mm.c
-
-BS_LIB_INCLUDES_armv7-m += $(TOP_DIR)/cmsis/CMSIS/Core/Include/
-
-BS_LIB_SOURCES_host += host.c
-BS_LIB_SOURCES_host += host_interrupt.c
-ifeq ($(BUILD_HAS_MULTITHREADING),yes)
-    BS_LIB_SOURCES_host += host_thread.c
-endif
-
-BS_LIB_INCLUDES += $(ARCH_DIR)/include
-BS_LIB_INCLUDES += $(FWK_DIR)/include
+include $(ARCH_DIR)/$(BS_ARCH_VENDOR)/vendor.mk
 
 #
 # Select arch-specific sources and includes
 #
-BS_LIB_SOURCES += $(BS_LIB_SOURCES_$(BS_ARCH_CPU))
+
+BS_LIB_SOURCES += $(BS_LIB_SOURCES_$(BS_ARCH_VENDOR))
 BS_LIB_SOURCES += $(BS_LIB_SOURCES_$(BS_ARCH_ARCH))
-BS_LIB_INCLUDES += $(BS_LIB_INCLUDES_$(BS_ARCH_CPU))
+
+BS_LIB_INCLUDES += $(BS_LIB_INCLUDES_$(BS_ARCH_VENDOR))
 BS_LIB_INCLUDES += $(BS_LIB_INCLUDES_$(BS_ARCH_ARCH))
 
+BS_LIB_INCLUDES += $(ARCH_DIR)/include
+BS_LIB_INCLUDES += $(ARCH_DIR)/$(BS_ARCH_VENDOR)/include
+BS_LIB_INCLUDES += $(ARCH_DIR)/$(BS_ARCH_VENDOR)/$(BS_ARCH_ARCH)/include
+
 include $(BS_DIR)/lib.mk
diff --git a/doc/architecture_support.md b/doc/architecture_support.md
new file mode 100644
index 00000000..7df8627d
--- /dev/null
+++ b/doc/architecture_support.md
@@ -0,0 +1,47 @@
+# Architecture Support
+
+## Overview
+
+Architectural configuration comes under the `arch` directory. This area provides
+not only instructions for building the architecture library, but for configuring
+any architecture-dependent behaviour required by the framework.
+
+## Structure
+
+The structure of this directory is like so:
+
+    .
+    |-- <vendor>
+    |   |-- <architecture>
+    |   |   |-- arch.mk
+    |   |   |-- include
+    |   |   |   `-- arch_*.h
+    |   |   `-- src
+    |   |       |-- arch.ld.S
+    |   |       |-- arch.scatter.S
+    |   |       |-- arch_*.S
+    |   |       |-- arch_*.c
+    |   |-- include
+    |   |   `-- arch_*.h
+    |   |-- src
+    |   |   `-- arch_*.c
+    |   `-- vendor.mk
+
+### Vendors and architectures
+
+The _vendor_ refers to the umbrella architecture group. For Arm-based
+architectures this is "arm".
+
+The _architecture_ refers to the instruction set architecture of the target
+platform.
+
+### Build system integration
+
+`vendor.mk` is included by the build system when building the architecture
+library, and also when building the firmware. This allows you to configure
+sources to compile in the architecture library, and library dependencies
+(if any) when linking the final firmware binary.
+
+`arch.ld.S` and `arch.scatter.S` also provide the linker scripts for the final
+firmware. They are automatically used by the build system if not targeting the
+*none* vendor (which one is chosen is based on the linker in use).
diff --git a/doc/config.dxy b/doc/config.dxy
index bb93dc7c..8bc057ba 100644
--- a/doc/config.dxy
+++ b/doc/config.dxy
@@ -122,6 +122,7 @@ INPUT                  = $(TOP_DIR)/readme.md \
                          $(DOC_DIR)/cmsis.md \
                          $(DOC_DIR)/glossary.md \
                          $(DOC_DIR)/deferred_response_architecture.md \
+                         $(DOC_DIR)/architecture_support.md \
                          $(FWK_DIR)/include \
                          $(FWK_DIR)/test/fwk_test.h \
                          $(MODULE_INCLUDES) \
diff --git a/doc/framework.md b/doc/framework.md
index 57d97a3b..6970df05 100644
--- a/doc/framework.md
+++ b/doc/framework.md
@@ -77,7 +77,7 @@ For each firmware, linker information must be provided in a *fmw_memory.h* file:
   used regardless of the memory region configuration given by *FMW_MEM_MODE*.
 - FMW_MEM0_SIZE: The size of the MEM0 region in bytes.
 - FMW_STACK_SIZE (if multithreading enabled): The size of each individual
-  thread stack in bytes.
+    thread stack in bytes.
 
 If a dual-region memory configuration is used then *FMW_MEM1_BASE* and
 *FMW_MEM1_SIZE* must also be defined.
diff --git a/framework/src/Makefile b/framework/src/Makefile
index d594d4c6..5e2d47bf 100644
--- a/framework/src/Makefile
+++ b/framework/src/Makefile
@@ -28,7 +28,6 @@ ifeq ($(BUILD_HAS_NOTIFICATION),yes)
 endif
 BS_LIB_SOURCES += fwk_status.c
 
-BS_LIB_INCLUDES += $(ARCH_DIR)/include
 BS_LIB_INCLUDES += $(FWK_DIR)/include
 
 include $(BS_DIR)/lib.mk
diff --git a/tools/build_system/cpu.mk b/tools/build_system/cpu.mk
index e8c50d21..51810293 100644
--- a/tools/build_system/cpu.mk
+++ b/tools/build_system/cpu.mk
@@ -16,8 +16,9 @@ BS_ARCH_CPU := $(BS_FIRMWARE_CPU)
 ARMV7M_CPUS := cortex-m3 cortex-m7
 
 ifneq ($(findstring $(BS_FIRMWARE_CPU),$(ARMV7M_CPUS)),)
+    BS_ARCH_VENDOR := arm
     BS_ARCH_ARCH := armv7-m
-    BS_ARCH_ISA := thumb
+    BS_ARCH_MODE := thumb
 
     LDFLAGS_GCC += --specs=nano.specs
     LDFLAGS_ARM += --target=arm-arm-none-eabi
@@ -25,8 +26,8 @@ ifneq ($(findstring $(BS_FIRMWARE_CPU),$(ARMV7M_CPUS)),)
 
     CFLAGS += -mfloat-abi=soft # No hardware floating point support
 else ifeq ($(BS_FIRMWARE_CPU),host)
+    BS_ARCH_VENDOR := none
     BS_ARCH_ARCH := host
-
 else
     $(erro "$(BS_FIRMWARE_CPU) is not a supported CPU. Aborting...")
 endif
diff --git a/tools/build_system/firmware.mk b/tools/build_system/firmware.mk
index f1c8d9ef..a477e424 100644
--- a/tools/build_system/firmware.mk
+++ b/tools/build_system/firmware.mk
@@ -93,9 +93,9 @@ goal: $(TARGET_BIN)
 
 ifneq ($(BS_ARCH_CPU),host)
     ifeq ($(BS_LINKER),ARM)
-        SCATTER_SRC = $(ARCH_DIR)/src/$(BS_ARCH_ARCH)/scatter.S
+        SCATTER_SRC = $(ARCH_DIR)/$(BS_ARCH_VENDOR)/$(BS_ARCH_ARCH)/src/arch.scatter.S
     else
-        SCATTER_SRC = $(ARCH_DIR)/src/$(BS_ARCH_ARCH)/ld.S
+        SCATTER_SRC = $(ARCH_DIR)/$(BS_ARCH_VENDOR)/$(BS_ARCH_ARCH)/src/arch.ld.S
     endif
 
     SCATTER_PP = $(OBJ_DIR)/ld_preproc.s
@@ -180,14 +180,6 @@ ifeq ($(BS_FIRMWARE_HAS_MULTITHREADING),yes)
     BUILD_SUFFIX := $(MULTHREADING_SUFFIX)
     BUILD_HAS_MULTITHREADING := yes
 
-    ifneq ($(BS_ARCH_ARCH),host)
-        ifeq ($(BS_COMPILER),ARM)
-            LIBS_y += $(OS_DIR)/RTX/Library/ARM/RTX_CM3.lib
-        else
-            LIBS_y += $(OS_DIR)/RTX/Library/GCC/libRTX_CM3.a
-        endif
-    endif
-
     INCLUDES += $(OS_DIR)/RTX/Source
     INCLUDES += $(OS_DIR)/RTX/Include
     INCLUDES += $(OS_DIR)/../Core/Include
@@ -278,6 +270,14 @@ ifeq ($(BUILD_HAS_DEBUGGER),yes)
     LIBS_y += $(call lib_path,debugger$(BUILD_SUFFIX))
 endif
 
+#
+# Additional library dependencies
+#
+
+include $(ARCH_DIR)/$(BS_ARCH_VENDOR)/vendor.mk
+
+LIBS_y += $(BS_LIB_DEPS)
+
 SOURCES += $(BUILD_FIRMWARE_DIR)/fwk_module_list.c
 $(BUILD_FIRMWARE_DIR)/fwk_module_list.c: gen_module
 EXTRA_DEP := gen_module
diff --git a/tools/build_system/lib.mk b/tools/build_system/lib.mk
index 66d35bbe..f86ad372 100644
--- a/tools/build_system/lib.mk
+++ b/tools/build_system/lib.mk
@@ -8,6 +8,7 @@
 ifndef BS_LIB_MK
 BS_LIB_MK := 1
 
+include $(BS_DIR)/cpu.mk
 include $(BS_DIR)/defs.mk
 
 $(info == Building $(BS_LIB_NAME) for $(BS_FIRMWARE_CPU))
@@ -59,6 +60,9 @@ goal: $(LIB)
 INCLUDES += $(shell pwd)
 INCLUDES += $(TOP_DIR)/$(LIB_BASE)/include
 
+INCLUDES += $(ARCH_DIR)/$(BS_ARCH_VENDOR)/include
+INCLUDES += $(ARCH_DIR)/$(BS_ARCH_VENDOR)/$(BS_ARCH_ARCH)/include
+
 include $(BS_DIR)/rules.mk
 
 endif
diff --git a/tools/build_system/rules.mk b/tools/build_system/rules.mk
index 3a06e43a..009baa7c 100644
--- a/tools/build_system/rules.mk
+++ b/tools/build_system/rules.mk
@@ -81,12 +81,12 @@ else
     LDFLAGS_GCC += -mcpu=$(BS_ARCH_CPU)
     LDFLAGS_ARM += -mcpu=$(BS_ARCH_CPU)
 
-    # Optional ISA ("sub-arch") parameter
-    ifneq ($(BS_ARCH_ISA),)
-        CFLAGS  += -m$(BS_ARCH_ISA)
-        ASFLAGS_GCC += -m$(BS_ARCH_ISA)
-        LDFLAGS_GCC += -m$(BS_ARCH_ISA)
-        LDFLAGS_ARM += -m$(BS_ARCH_ISA)
+    # Optional architectural mode parameter
+    ifneq ($(BS_ARCH_MODE),)
+        CFLAGS  += -m$(BS_ARCH_MODE)
+        ASFLAGS_GCC += -m$(BS_ARCH_MODE)
+        LDFLAGS_GCC += -m$(BS_ARCH_MODE)
+        LDFLAGS_ARM += -m$(BS_ARCH_MODE)
     endif
 endif
 
@@ -170,6 +170,14 @@ ifeq ($(BUILD_HAS_DEBUGGER),yes)
 endif
 
 #
+# Always include the architecture librarie
+#
+
+INCLUDES += $(ARCH_DIR)/include
+INCLUDES += $(ARCH_DIR)/$(BS_ARCH_VENDOR)/include
+INCLUDES += $(ARCH_DIR)/$(BS_ARCH_VENDOR)/$(BS_ARCH_ARCH)/include
+
+#
 # Always include the framework library
 #
 INCLUDES += $(FWK_DIR)/include