Merge pull request #200 from sifive/debugrelease

Support Debug/Release build configurations

9 files changed, 138 insertions, 76 deletions

diff --git a/Makefile b/Makefile
index 355524e..3853c53 100644
--- a/Makefile
+++ b/Makefile
@@ -25,8 +25,8 @@ PROGRAM_ROOT ?= $(abspath .)
 
 SRC_DIR = $(PROGRAM_ROOT)/software/$(PROGRAM)
 
-PROGRAM_ELF = $(SRC_DIR)/$(PROGRAM)
-PROGRAM_HEX = $(SRC_DIR)/$(PROGRAM).hex
+PROGRAM_ELF = $(SRC_DIR)/$(CONFIGURATION)/$(PROGRAM).elf
+PROGRAM_HEX = $(SRC_DIR)/$(CONFIGURATION)/$(PROGRAM).hex
 
 #############################################################
 # BSP Loading
@@ -64,31 +64,36 @@ help:
 	@echo " SiFive Freedom E Software Development Kit "
 	@echo " Makefile targets:"
 	@echo ""
-	@echo " software [PROGRAM=$(PROGRAM) TARGET=$(TARGET)]:"
-	@echo "    Build a software program to load with the"
-	@echo "    debugger."
+	@echo " software [PROGRAM=$(PROGRAM)] [TARGET=$(TARGET)]"
+	@echo "          [CONFIGURATION=$(CONFIGURATION)]:"
+	@echo "    Builds the requested PROGRAM for the TARGET using the"
+	@echo "    specified build CONFIGURATION."
 	@echo ""
-	@echo " metal [TARGET=$(TARGET)]"
-	@echo "    Build the Freedom Metal library for TARGET"
+	@echo " metal [TARGET=$(TARGET)] [CONFIGURATION=$(CONFIGURATION)]"
+	@echo "    Builds the Freedom Metal library for TARGET."
 	@echo ""
-	@echo " clean [PROGRAM=$(PROGRAM) TARGET=$(TARGET)]:"
-	@echo "    Clean compiled objects for a specified "
+	@echo " clean [PROGRAM=$(PROGRAM)] [TARGET=$(TARGET)]"
+	@echo "       [CONFIGURATION=$(CONFIGURATION)]:"
+	@echo "    Cleans compiled objects for a specified "
 	@echo "    software program."
 	@echo ""
-	@echo " upload [PROGRAM=$(PROGRAM) TARGET=$(TARGET)]:"
-	@echo "    Launch OpenOCD to flash your program to the"
-	@echo "    on-board Flash."
+	@echo " upload [PROGRAM=$(PROGRAM)] [TARGET=$(TARGET)]"
+	@echo "        [CONFIGURATION=$(CONFIGURATION)]:"
+	@echo "    For board and FPGA TARGETs, uploads the program to the"
+	@echo "    on-board flash."
 	@echo ""
-	@echo " debug [PROGRAM=$(PROGRAM) TARGET=$(TARGET)]:"
-	@echo "    Launch OpenOCD and attach GDB to the running program."
+	@echo " debug [PROGRAM=$(PROGRAM)] [TARGET=$(TARGET)]"
+	@echo "       [CONFIGURATION=$(CONFIGURATION)]:"
+	@echo "    For board and FPGA TARGETs, attaches GDB to the"
+	@echo "    running program."
 	@echo ""
 	@echo " standalone STANDALONE_DEST=/path/to/desired/location"
-	@echo "            [INCLUDE_METAL_SOURCES=1] [PROGRAM=$(PROGRAM)]"
-	@echo "            [TARGET=$(TARGET)]:"
-	@echo "    Export a program for a single target into a standalone"
+	@echo "            [PROGRAM=$(PROGRAM)] [TARGET=$(TARGET)]:"
+	@echo "    Exports a program for a single target into a standalone"
 	@echo "    project directory at STANDALONE_DEST."
 	@echo ""
-	@echo " For more information, read the accompanying README.md"
+	@echo " For more information, view the Freedom E SDK Documentation at"
+	@echo "   https://sifive.github.io/freedom-e-sdk-docs/index.html"
 
 .PHONY: clean
 clean:
@@ -152,14 +157,14 @@ $(STANDALONE_DEST):
 $(STANDALONE_DEST)/%:
 	mkdir -p $@
 
-ifneq ($(INCLUDE_METAL_SOURCES),)
-
 standalone: \
 		$(STANDALONE_DEST) \
 		$(STANDALONE_DEST)/bsp \
 		$(STANDALONE_DEST)/src \
 		$(SRC_DIR) \
 		freedom-metal \
+		debug.mk \
+		release.mk \
 		scripts/standalone.mk \
 		scripts/libmetal.mk
 	cp -r $(addprefix $(BSP_DIR)/,$(filter-out build,$(shell ls $(BSP_DIR)))) $</bsp/
@@ -171,27 +176,13 @@ standalone: \
 	$(MAKE) -C $(SRC_DIR) clean
 	cp -r $(SRC_DIR)/* $</src/
 
+	cp debug.mk $</debug.mk
+	cp release.mk $</release.mk
+
 	echo "PROGRAM = $(PROGRAM)" > $</Makefile
 	cat scripts/standalone.mk >> $</Makefile
 	cat scripts/libmetal.mk >> $</Makefile
 
-else
-standalone: \
-		$(STANDALONE_DEST) \
-		$(STANDALONE_DEST)/bsp \
-		$(STANDALONE_DEST)/src \
-		$(BSP_DIR)/install/lib/libmetal.a \
-		$(BSP_DIR)/install/lib/libmetal-gloss.a \
-		$(SRC_DIR) \
-		scripts/standalone.mk
-	cp -r $(addprefix $(BSP_DIR)/,$(filter-out build,$(shell ls $(BSP_DIR)))) $</bsp/
-
-	$(MAKE) -C $(SRC_DIR) clean
-	cp -r $(SRC_DIR)/* $</src/
-
-	echo "PROGRAM = $(PROGRAM)" > $</Makefile
-	cat scripts/standalone.mk >> $</Makefile
-endif
 endif
 
 #############################################################
diff --git a/debug.mk b/debug.mk
new file mode 100644
index 0000000..b57cfc0
--- /dev/null
+++ b/debug.mk
@@ -0,0 +1,12 @@
+###################################################
+# Build Flags for the Debug Configuration
+###################################################
+
+# Set the optimization level
+RISCV_CFLAGS += -O0
+RISCV_CXXFLAGS += -O0
+
+# Enable debug
+RISCV_CFLAGS += -g
+RISCV_CXXFLAGS += -g
+
diff --git a/doc/html b/doc/html
-Subproject c4ace9ccd13fb0dfbbb5c1d742dfc909f181146
+Subproject de252ca314eb39ec6095d86881ce6f1dd34562e
diff --git a/doc/sphinx/userguide/buildingcoreip.rst b/doc/sphinx/userguide/buildingcoreip.rst
index 986ad68..7fd821e 100644
--- a/doc/sphinx/userguide/buildingcoreip.rst
+++ b/doc/sphinx/userguide/buildingcoreip.rst
@@ -8,17 +8,18 @@ To compile a bare-metal RISC-V program:
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=coreip-e31-rtl] software
+   make [PROGRAM=hello] [TARGET=coreip-e31-rtl] [CONFIGURATION=debug] software
 
 The square brackets in the above command indicate optional parameters for the
 Make invocation. As you can see, the default values of these parameters tell
-the build script to build the ``hello`` example for the ``coreip-e31`` target.
-If, for example, you wished to build the ``timer-interrupt`` example for the S51
-Core IP target, you would instead run the command
+the build script to build the ``hello`` example for the ``coreip-e31`` target
+with the ``debug`` build configuration. If, for example, you wished to build
+the ``timer-interrupt`` example for the S51 Core IP target with the ``release``
+configuration, you would instead run the command
 
 .. code-block:: bash
 
-   make PROGRAM=timer-interrupt TARGET=coreip-s51-rtl software
+   make PROGRAM=timer-interrupt TARGET=coreip-s51-rtl CONFIGURATION=release software
 
 Cleaning a Target Program Build Directory
 -----------------------------------------
@@ -27,5 +28,5 @@ The ``clean`` target can be used to restore a target program's directory to a cl
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=coreip-e31-rtl] clean
+   make [PROGRAM=hello] [TARGET=coreip-e31-rtl] [CONFIGURATION=debug] clean
 
diff --git a/doc/sphinx/userguide/buildingdevboard.rst b/doc/sphinx/userguide/buildingdevboard.rst
index a5d364d..d972b3a 100644
--- a/doc/sphinx/userguide/buildingdevboard.rst
+++ b/doc/sphinx/userguide/buildingdevboard.rst
@@ -8,17 +8,18 @@ To compile a bare-metal RISC-V program:
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=sifive-hifive1] software
+   make [PROGRAM=hello] [TARGET=sifive-hifive1] [CONFIGURATION=debug] software
 
 The square brackets in the above command indicate optional parameters for the
 Make invocation. As you can see, the default values of these parameters tell
-the build script to build the ``hello`` example for the ``sifive-hifive1`` target.
-If, for example, you wished to build the ``timer-interrupt`` example for the S51
-Arty FPGA Evaluation target, you would instead run the command
+the build script to build the ``hello`` example for the ``sifive-hifive1`` target
+using the ``debug`` build configuration. If, for example, you wished to build
+the ``timer-interrupt`` example for the S51 Arty FPGA Evaluation target using
+the ``release`` build configuration, you would instead run the command
 
 .. code-block:: bash
 
-   make PROGRAM=timer-interrupt TARGET=coreip-s51-arty software
+   make PROGRAM=timer-interrupt TARGET=coreip-s51-arty CONFIGURATION=release software
 
 Uploading to the Target Board
 -----------------------------
@@ -32,7 +33,7 @@ the development board into your computer and running the following command:
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=sifive-hifive1] upload
+   make [PROGRAM=hello] [TARGET=sifive-hifive1] [CONFIGURATION=debug] upload
 
 Debugging a Target Program
 --------------------------
@@ -49,7 +50,7 @@ the development board into your computer and running the following command:
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=sifive-hifive1] debug
+   make [PROGRAM=hello] [TARGET=sifive-hifive1] [CONFIGURATION=debug] debug
 
 Cleaning a Target Program Build Directory
 -----------------------------------------
@@ -58,5 +59,5 @@ The ``clean`` target can be used to restore a target program's directory to a cl
 
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=sifive-hifive1] clean
+   make [PROGRAM=hello] [TARGET=sifive-hifive1] [CONFIGURATION=debug] clean
 
diff --git a/doc/sphinx/userguide/standalone.rst b/doc/sphinx/userguide/standalone.rst
index ee31362..e71ecaa 100644
--- a/doc/sphinx/userguide/standalone.rst
+++ b/doc/sphinx/userguide/standalone.rst
@@ -8,12 +8,7 @@ Legacy Freedom E SDK.
 
 ``STANDALONE_DEST`` is a required argument to provide the desired project location.
 
-You can include the argument ``INCLUDE_METAL_SOURCES=1`` if you would like to
-include the sources for the Freedom Metal library in the generated standalone
-project. If this argument is not included, then the Freedom Metal library will
-be included in the generated project as a pre-built archive.
-
 .. code-block:: bash
 
-   make [PROGRAM=hello] [TARGET=sifive-hifive1] [INCLUDE_METAL_SOURCES=1] STANDALONE_DEST=/path/to/desired/location standalone
+   make [PROGRAM=hello] [TARGET=sifive-hifive1] STANDALONE_DEST=/path/to/desired/location standalone
 
diff --git a/release.mk b/release.mk
new file mode 100644
index 0000000..ac7ec8a
--- /dev/null
+++ b/release.mk
@@ -0,0 +1,7 @@
+###################################################
+# Build Flags for the Release Configuration
+###################################################
+
+# Set the optimization level
+RISCV_CFLAGS += -Os
+RISCV_CXXFLAGS += -Os
diff --git a/scripts/libmetal.mk b/scripts/libmetal.mk
index e00c9cf..b50c599 100644
--- a/scripts/libmetal.mk
+++ b/scripts/libmetal.mk
@@ -6,17 +6,22 @@ METAL_SOURCE_PATH ?= freedom-metal
 METAL_LDSCRIPT	   = $(BSP_DIR)/metal.lds
 METAL_HEADER	   = $(BSP_DIR)/metal.h
 
+METAL_PREFIX       = $(abspath $(BSP_DIR)/install)
+METAL_BUILD_DIR    = $(abspath $(BSP_DIR)/build/$(CONFIGURATION))
+METAL_LIB_DIR	   = $(abspath $(BSP_DIR)/install/lib/$(CONFIGURATION))
+
 .PHONY: metal
-metal: $(BSP_DIR)/install/stamp
+metal: $(METAL_LIB_DIR)/stamp
 
-$(BSP_DIR)/build/Makefile:
+$(METAL_BUILD_DIR)/Makefile:
 	@rm -rf $(dir $@)
 	@mkdir -p $(dir $@)
 	cd $(dir $@) && \
-		CFLAGS="-march=$(RISCV_ARCH) -mabi=$(RISCV_ABI) -ffunction-sections -fdata-sections -g -mcmodel=$(RISCV_CMODEL)" \
+		CFLAGS="$(RISCV_CFLAGS)" \
 		$(abspath $(METAL_SOURCE_PATH)/configure) \
 		--host=$(CROSS_COMPILE) \
-		--prefix=$(abspath $(BSP_DIR)/install) \
+		--prefix=$(METAL_PREFIX) \
+		--libdir=$(METAL_LIB_DIR) \
 		--disable-maintainer-mode \
 		--with-preconfigured \
 		--with-machine-name=$(TARGET) \
@@ -25,22 +30,31 @@ $(BSP_DIR)/build/Makefile:
 		--with-builtin-libgloss
 	touch -c $@
 
-$(BSP_DIR)/install/stamp: $(BSP_DIR)/build/Makefile
-	$(MAKE) -C $(abspath $(BSP_DIR)/build) install
+$(METAL_LIB_DIR)/stamp: $(BSP_DIR)/build/$(CONFIGURATION)/Makefile
+	$(MAKE) -C $(abspath $(BSP_DIR)/build/$(CONFIGURATION)) install
 	date > $@
 
-$(BSP_DIR)/install/lib/libriscv%.a: $(BSP_DIR)/install/stamp ;@:
+$(METAL_LIB_DIR)/libriscv%.a: $(METAL_LIB_DIR)/stamp ;@:
 
-$(BSP_DIR)/install/lib/libmetal.a: $(BSP_DIR)/install/lib/libriscv__mmachine__$(TARGET).a
+$(METAL_LIB_DIR)/libmetal.a: $(METAL_LIB_DIR)/libriscv__mmachine__$(TARGET).a
 	cp $< $@
 
-$(BSP_DIR)/install/lib/libmetal-gloss.a: $(BSP_DIR)/install/lib/libriscv__menv__metal.a
+$(METAL_LIB_DIR)/libmetal-gloss.a: $(METAL_LIB_DIR)/libriscv__menv__metal.a
 	cp $< $@
 
+# If we're cleaning the last Metal library for a TARGET, then remove
+# the install directory, otherwise just remove the built libs for that
+# CONFIGURATION.
+ifeq ($(words $(wildcard $(METAL_PREFIX)/lib/*)),1)
+METAL_CLEAN = $(METAL_PREFIX)
+else
+METAL_CLEAN = $(METAL_LIB_DIR)
+endif
+
 .PHONY: clean-metal
 clean-metal:
-	rm -rf $(BSP_DIR)/install
-	rm -rf $(BSP_DIR)/build
+	rm -rf $(METAL_CLEAN)
+	rm -rf $(METAL_BUILD_DIR)
 clean: clean-metal
 
 metal_install: metal
diff --git a/scripts/standalone.mk b/scripts/standalone.mk
index fd0c28d..17fec17 100644
--- a/scripts/standalone.mk
+++ b/scripts/standalone.mk
@@ -7,6 +7,11 @@ BSP_DIR ?= $(abspath bsp)
 # SRC_DIR sets the path to the program source directory
 SRC_DIR ?= $(abspath src)
 
+# The configuration defaults to Debug. Valid choices are:
+#  - debug
+#  - release
+CONFIGURATION ?= debug
+
 #############################################################
 # BSP loading
 #############################################################
@@ -73,10 +78,42 @@ SEGGER_JLINK_EXE := JLinkExe
 SEGGER_JLINK_GDB_SERVER := JLinkGDBServer
 
 #############################################################
+# Software Flags
+#############################################################
+
+# Set the arch, ABI, and code model
+RISCV_CFLAGS   += -march=$(RISCV_ARCH) -mabi=$(RISCV_ABI) -mcmodel=$(RISCV_CMODEL)
+RISCV_CXXFLAGS += -march=$(RISCV_ARCH) -mabi=$(RISCV_ABI) -mcmodel=$(RISCV_CMODEL)
+# Prune unused functions and data
+RISCV_CFLAGS   += -ffunction-sections -fdata-sections
+RISCV_CXXFLAGS += -ffunction-sections -fdata-sections
+# Include the Metal headers
+RISCV_CFLAGS   += -I$(abspath $(BSP_DIR)/install/include/)
+RISCV_CXXFLAGS += -I$(abspath $(BSP_DIR)/install/include/)
+
+# Turn on garbage collection for unused sections
+RISCV_LDFLAGS += -Wl,--gc-sections
+# Turn off the C standard library
+RISCV_LDFLAGS += -nostartfiles -nostdlib
+# Find the archive files and linker scripts
+RISCV_LDFLAGS += -L$(sort $(dir $(abspath $(filter %.a,$^)))) -T$(abspath $(filter %.lds,$^))
+
+# Link to the relevant libraries
+RISCV_LDLIBS += -Wl,--start-group -lc -lgcc -lmetal -lmetal-gloss -Wl,--end-group
+
+# Load the configuration Makefile
+CONFIGURATION_FILE = $(wildcard $(CONFIGURATION).mk)
+ifeq ($(words $(CONFIGURATION_FILE)),0)
+$(error Unable to find the Makefile $(CONFIGURATION).mk for CONFIGURATION=$(CONFIGURATION))
+endif
+include $(CONFIGURATION).mk
+
+#############################################################
 # Software
 #############################################################
 
-PROGRAM_ELF ?= $(SRC_DIR)/$(PROGRAM)
+PROGRAM_ELF ?= $(SRC_DIR)/$(CONFIGURATION)/$(PROGRAM).elf
+PROGRAM_HEX ?= $(SRC_DIR)/$(CONFIGURATION)/$(PROGRAM).hex
 
 .PHONY: all
 all: software
@@ -95,17 +132,19 @@ PROGRAM_SRCS = $(wildcard $(SRC_DIR)/*.c) $(wildcard $(SRC_DIR)/*.h) $(wildcard
 
 $(PROGRAM_ELF): \
 		$(PROGRAM_SRCS) \
-		$(BSP_DIR)/install/lib/libmetal.a \
-		$(BSP_DIR)/install/lib/libmetal-gloss.a \
+		$(BSP_DIR)/install/lib/$(CONFIGURATION)/libmetal.a \
+		$(BSP_DIR)/install/lib/$(CONFIGURATION)/libmetal-gloss.a \
 		$(BSP_DIR)/metal.lds
-	$(MAKE) -C $(dir $@) $(notdir $@) \
+	mkdir -p $(dir $@)
+	$(MAKE) -C $(SRC_DIR) $(basename $(notdir $@)) \
 		AR=$(RISCV_AR) \
 		CC=$(RISCV_GCC) \
 		CXX=$(RISCV_GXX) \
-		CFLAGS="-Os -march=$(RISCV_ARCH) -mabi=$(RISCV_ABI) -ffunction-sections -fdata-sections -g -mcmodel=$(RISCV_CMODEL) -I$(abspath $(BSP_DIR)/install/include/)" \
-		CXXFLAGS="-Os -march=$(RISCV_ARCH) -mabi=$(RISCV_ABI) -ffunction-sections -fdata-sections -g -mcmodel=$(RISCV_CMODEL) -I$(abspath $(BSP_DIR)/install/include/)" \
-		LDFLAGS="-nostartfiles -nostdlib -L$(sort $(dir $(abspath $(filter %.a,$^)))) -T$(abspath $(filter %.lds,$^))" \
-		LDLIBS="-Wl,--gc-sections -Wl,--start-group -lc -lgcc -lmetal -lmetal-gloss -Wl,--end-group"
+		CFLAGS="$(RISCV_CFLAGS)" \
+		CXXFLAGS="$(RISCV_CXXFLAGS)" \
+		LDFLAGS="$(RISCV_LDFLAGS)" \
+		LDLIBS="$(RISCV_LDLIBS)"
+	mv $(SRC_DIR)/$(basename $(notdir $@)) $@
 	touch -c $@
 
 	$(RISCV_SIZE) $@
@@ -121,5 +160,7 @@ endif
 .PHONY: clean-software
 clean-software:
 	$(MAKE) -C $(SRC_DIR) clean
+	rm -rf $(SRC_DIR)/$(CONFIGURATION)
+.PHONY: clean
 clean: clean-software