Support Debug/Release configurations

- Puts shared flags in scripts/standalone and adds "build configurations"
  for debug and release which customize the build flags for specific
  purposes.
- Documents CONFIGURATION in Sphinx docs and makefile help

Signed-off-by: Nathaniel Graff <nathaniel.graff@sifive.com>

8 files changed, 110 insertions, 35 deletions

diff --git a/Makefile b/Makefile
index 355524e..319903a 100644
--- a/Makefile
+++ b/Makefile
@@ -64,31 +64,37 @@ 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 "            [TARGET=$(TARGET)] [CONFIGURATION=$(CONFIGURATION)]:"
+	@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:
@@ -160,6 +166,8 @@ standalone: \
 		$(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,6 +179,9 @@ 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
@@ -183,12 +194,17 @@ standalone: \
 		$(BSP_DIR)/install/lib/libmetal.a \
 		$(BSP_DIR)/install/lib/libmetal-gloss.a \
 		$(SRC_DIR) \
+		debug.mk \
+		release.mk \
 		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/
 
+	cp debug.mk $</debug.mk
+	cp release.mk $</release.mk
+
 	echo "PROGRAM = $(PROGRAM)" > $</Makefile
 	cat scripts/standalone.mk >> $</Makefile
 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/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..0703ddb 100644
--- a/doc/sphinx/userguide/standalone.rst
+++ b/doc/sphinx/userguide/standalone.rst
@@ -15,5 +15,5 @@ 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] [CONFIGURATION=debug] [INCLUDE_METAL_SOURCES=1] 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..97ce543 100644
--- a/scripts/libmetal.mk
+++ b/scripts/libmetal.mk
@@ -13,7 +13,7 @@ $(BSP_DIR)/build/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) \
diff --git a/scripts/standalone.mk b/scripts/standalone.mk
index fd0c28d..6fa3da4 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_HEX ?= $(SRC_DIR)/$(PROGRAM).hex
 
 .PHONY: all
 all: software
@@ -102,10 +139,10 @@ $(PROGRAM_ELF): \
 		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)"
 	touch -c $@
 
 	$(RISCV_SIZE) $@
@@ -121,5 +158,6 @@ endif
 .PHONY: clean-software
 clean-software:
 	$(MAKE) -C $(SRC_DIR) clean
+.PHONY: clean
 clean: clean-software