Cosmetic tweaks to variable output.

Comment on the need to retain the double-slash at the WORK_DIR boundary.
More toolchain documentation.

1 files changed, 54 insertions, 30 deletions

diff --git a/makefiles/toolchain_gnu-arm-eabi.mk b/makefiles/toolchain_gnu-arm-eabi.mk
index 108476782..ac53b0369 100644
--- a/makefiles/toolchain_gnu-arm-eabi.mk
+++ b/makefiles/toolchain_gnu-arm-eabi.mk
@@ -4,6 +4,8 @@
 
 #$(info TOOLCHAIN  gnu-arm-eabi)
 
+# Toolchain commands. Normally only used inside this file.
+#
 CROSSDEV		 = arm-none-eabi-
 
 CC			 = $(CROSSDEV)gcc
@@ -19,7 +21,8 @@ OBJDUMP			 = $(CROSSDEV)objdump
 
 MAXOPTIMIZATION		 = -O3
 
-# base CPU flags
+# Base CPU flags for each of the supported architectures.
+#
 ARCHCPUFLAGS_CORTEXM4F	 = -mcpu=cortex-m4 \
 			   -mthumb \
 			   -march=armv7e-m \
@@ -36,12 +39,15 @@ ARCHCPUFLAGS_CORTEXM3	 = -mcpu=cortex-m3 \
 			   -march=armv7-m \
 			   -mfloat-abi=soft
 
+# Pick the right set of flags for the architecture.
+#
 ARCHCPUFLAGS		 = $(ARCHCPUFLAGS_$(CONFIG_ARCH))
 ifeq ($(ARCHCPUFLAGS),)
 $(error Must set CONFIG_ARCH to one of CORTEXM4F, CORTEXM4 or CORTEXM3)
 endif
 
 # optimisation flags
+#
 ARCHOPTIMIZATION	 = $(MAXOPTIMIZATION) \
 			   -g \
 			   -fno-strict-aliasing \
@@ -56,9 +62,13 @@ ARCHOPTIMIZATION	 = $(MAXOPTIMIZATION) \
 # note - requires corresponding support in NuttX
 INSTRUMENTATIONDEFINES	 = -finstrument-functions \
 			   -ffixed-r10
-
+# Language-specific flags
+#
 ARCHCFLAGS		 = -std=gnu99
 ARCHCXXFLAGS		 = -fno-exceptions -fno-rtti -std=gnu++0x
+
+# Generic warnings
+#
 ARCHWARNINGS		 = -Wall \
 			   -Wextra \
 			   -Wdouble-promotion \
@@ -74,6 +84,8 @@ ARCHWARNINGS		 = -Wall \
 #   -Wconversion - would be nice, but too many "risky-but-safe" conversions in the code
 #   -Wcast-align - would help catch bad casts in some cases, but generates too many false positives
 
+# C-specific warnings
+#
 ARCHCWARNINGS		 = $(ARCHWARNINGS) \
 			   -Wbad-function-cast \
 			   -Wstrict-prototypes \
@@ -82,12 +94,17 @@ ARCHCWARNINGS		 = $(ARCHWARNINGS) \
 			   -Wmissing-prototypes \
 			   -Wnested-externs \
 			   -Wunsuffixed-float-constants
+
+# C++-specific warnings
+#
 ARCHWARNINGSXX		 = $(ARCHWARNINGS)
 
 # pull in *just* libm from the toolchain ... this is grody
 LIBM			:= $(shell $(CC) $(ARCHCPUFLAGS) -print-file-name=libm.a)
 EXTRA_LIBS		+= $(LIBM)
 
+# Flags we pass to the C compiler
+#
 CFLAGS			 = $(ARCHCFLAGS) \
 			   $(ARCHCWARNINGS) \
 			   $(ARCHOPTIMIZATION) \
@@ -99,6 +116,8 @@ CFLAGS			 = $(ARCHCFLAGS) \
 			   -fno-common \
 			   $(addprefix -I,$(INCLUDE_DIRS))
 
+# Flags we pass to the C++ compiler
+#
 CXXFLAGS		 = $(ARCHCXXFLAGS) \
 			   $(ARCHWARNINGSXX) \
 			   $(ARCHOPTIMIZATION) \
@@ -109,76 +128,83 @@ CXXFLAGS		 = $(ARCHCXXFLAGS) \
 			   $(EXTRADEFINES) \
 			   $(addprefix -I,$(INCLUDE_DIRS))
 
-CPPFLAGS		 = $(ARCHINCLUDES) \
-			   $(INSTRUMENTATIONDEFINES) \
-			   $(ARCHDEFINES) \
-			   $(EXTRADEFINES) \
-			   $(addprefix -I,$(INCLUDE_DIRS))
-
+# Flags we pass to the assembler
+#
 AFLAGS			 = $(CFLAGS) -D__ASSEMBLY__
 
+# Flags we pass to the linker
+#
 LDFLAGS			+= --warn-common \
 			   --gc-sections \
 			   $(addprefix -T,$(LDSCRIPT)) \
 			   $(addprefix -L,$(LIB_DIRS))
 
+# Compiler support library
+#
 LIBGCC			:= $(shell $(CC) $(ARCHCPUFLAGS) -print-libgcc-file-name)
 
-# files that the final link depends on
-# XXX add libraries that we know about here...
+# Files that the final link depends on
+#
 LINK_DEPS		+= $(LDSCRIPT)
 
-# files to include to get automated dependencies
+# Files to include to get automated dependencies
+#
 DEP_INCLUDES		 = $(subst .o,.d,$(OBJS))
 
-# compile C source $1 to object $2
+# Compile C source $1 to object $2
 # as a side-effect, generate a dependency file
+#
 define COMPILE
-	@$(ECHO) "CC <- $1"
-	@$(ECHO) "CC   -> $2"
+	@$(ECHO) "CC:      $1"
 	@$(MKDIR) -p $(dir $2)
 	$(Q) $(CC) -MD -c $(CFLAGS) $(abspath $1) -o $2
 endef
 
-# compile C++ source $1 to $2
+# Compile C++ source $1 to $2
 # as a side-effect, generate a dependency file
+#
 define COMPILEXX
-	@$(ECHO) "CXX: $1"
+	@$(ECHO) "CXX:     $1"
 	@$(MKDIR) -p $(dir $2)
 	$(Q) $(CXX) -MD -c $(CXXFLAGS) $(abspath $1) -o $2
 endef
 
-# assemble $1 into $2
+# Assemble $1 into $2
+#
 define ASSEMBLE
-	@$(ECHO) "AS: $1"
+	@$(ECHO) "AS:      $1"
 	@$(MKDIR) -p $(dir $2)
 	$(Q) $(CC) -c $(AFLAGS) $(abspath $1) -o $2
 endef
 
-# produce partially-linked $1 from files in $2
+# Produce partially-linked $1 from files in $2
+#
 define PRELINK
 	@$(ECHO) "PRELINK: $1"
 	@$(MKDIR) -p $(dir $1)
 	$(Q) $(LD) -Ur -o $1 $2 && $(OBJCOPY) --localize-hidden $1
 endef
 
-# update the archive $1 with the files in $2
+# Update the archive $1 with the files in $2
+#
 define ARCHIVE
-	@$(ECHO) "AR: $2"
+	@$(ECHO) "AR:      $2"
 	@$(MKDIR) -p $(dir $1)
 	$(Q) $(AR) $1 $2
 endef
 
-# link the objects in $2 into the binary $1
+# Link the objects in $2 into the binary $1
+#
 define LINK
-	@$(ECHO) "LINK: $1"
+	@$(ECHO) "LINK:    $1"
 	@$(MKDIR) -p $(dir $1)
 	$(Q) $(LD) $(LDFLAGS) -o $1 --start-group $2 $(LIBS) $(EXTRA_LIBS) $(LIBGCC) --end-group
 endef
 
-# convert $1 from a linked object to a raw binary in $2
+# Convert $1 from a linked object to a raw binary in $2
+#
 define SYM_TO_BIN
-	@$(ECHO) "BIN: $2"
+	@$(ECHO) "BIN:     $2"
 	@$(MKDIR) -p $(dir $2)
 	$(Q) $(OBJCOPY) -O binary $1 $2
 endef
@@ -195,15 +221,13 @@ define BIN_SYM_PREFIX
 	_binary_$(subst /,_,$(subst .,_,$1))
 endef
 define BIN_TO_OBJ
-	@$(ECHO) "WRAP: $2"
+	@$(ECHO) "OBJ:     $2"
 	@$(MKDIR) -p $(dir $2)
 	$(Q) $(ECHO) > $2.c
 	$(call COMPILE,$2.c,$2.c.o)
-	$(LD) -r -o $2 $2.c.o -b binary $1
-	$(OBJCOPY) $2 \
+	$(Q) $(LD) -r -o $2 $2.c.o -b binary $1
+	$(Q) $(OBJCOPY) $2 \
 		--redefine-sym $(call BIN_SYM_PREFIX,$1)_start=$3 \
 		--redefine-sym $(call BIN_SYM_PREFIX,$1)_size=$3_len \
 		--strip-symbol $(call BIN_SYM_PREFIX,$1)_end
 endef
-
-#	$(Q) $(OBJCOPY) --add-section .rodata.$3=$1 $2