Rename Makefile's fwlib2 target to fwlib20.

This accurately reflects what's really happening. Vboot 2.0 is
backwards-compatible with the binary structs used in vboot 1.0,
while vboot 2.1 will not be.

When building firmware, vboot_reference should be invoked in one
of three ways:

  TARGET        OUTPUT           VERSION

  fwlib         vboot_fw.a       1.0
  fwlib20       vboot_fw20.a     2.0
  fwlib21       vboot_fw21.a     2.1

BUG=chromium:228932
BRANCH=ToT
CQ-DEPEND=CL:243981
TEST=manual

  emerge-veyron_pinky coreboot
  emerge-samus coreboot
  emerge-daisy_spring chromeos-u-boot

  make runtests

Change-Id: I98d8ea6b48e5922a470e744d56699cad43eabb3d
Signed-off-by: Bill Richardson <wfrichar@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/243980
Reviewed-by: Randall Spangler <rspangler@chromium.org>

2 files changed, 64 insertions, 37 deletions

diff --git a/Makefile b/Makefile
index 21586e1b..69ab4920 100644
--- a/Makefile
+++ b/Makefile
@@ -247,12 +247,14 @@ endif
 # this source tree locally and link to it directly.
 FWLIB = ${BUILD}/vboot_fw.a
 
-# Smaller firmware library
-# Stuff common to all vboot 2.x
+# Smaller firmware library common to all vboot 2.x, used only for
+# 1) compile-time tests of the public API or
+# 2) linking with an actual 2.0 or 2.1 implementation
 FWLIB2X = ${BUILD}/vboot_fw2x.a
-# Vboot 2.0 (stuck with this filename due to dependencies in coreboot)
-FWLIB20 = ${BUILD}/vboot_fw2.a
-# Vboot 2.1
+
+# Vboot 2.0 (deprecated - see firmware/README)
+FWLIB20 = ${BUILD}/vboot_fw20.a
+# Vboot 2.1 (not yet ready - see firmware/README)
 FWLIB21 = ${BUILD}/vboot_fw21.a
 
 # Firmware library sources needed by VbInit() call
@@ -293,9 +295,8 @@ VBSLK_SRCS = \
 	firmware/lib/vboot_kernel.c \
 	firmware/lib/region-kernel.c \
 
-# Firmware library source needed for smaller library 2
-# Code common to vboot 2.0 (old structs) and 2.1 (new structs)
-FWLIB2_SRCS = \
+# Code common to both vboot 2.0 (old structs) and 2.1 (new structs)
+FWLIB2X_SRCS = \
 	firmware/2lib/2api.c \
 	firmware/2lib/2common.c \
 	firmware/2lib/2crc8.c \
@@ -354,7 +355,7 @@ VBSLK_SRCS += \
 	firmware/stub/vboot_api_stub_disk.c \
 	firmware/stub/vboot_api_stub_stream.c
 
-FWLIB2_SRCS += \
+FWLIB2X_SRCS += \
 	firmware/2lib/2stub.c
 
 endif
@@ -367,10 +368,10 @@ VBSF_OBJS = ${VBSF_SRCS:%.c=${BUILD}/%.o}
 ALL_OBJS +=  ${VBINIT_OBJS} ${VBSF_OBJS}
 
 FWLIB_OBJS = ${FWLIB_SRCS:%.c=${BUILD}/%.o}
-FWLIB2_OBJS = ${FWLIB2_SRCS:%.c=${BUILD}/%.o}
+FWLIB2X_OBJS = ${FWLIB2X_SRCS:%.c=${BUILD}/%.o}
 FWLIB20_OBJS = ${FWLIB20_SRCS:%.c=${BUILD}/%.o}
 FWLIB21_OBJS = ${FWLIB21_SRCS:%.c=${BUILD}/%.o}
-ALL_OBJS += ${FWLIB_OBJS} ${FWLIB2_OBJS} ${FWLIB20_OBJS} ${FWLIB21_OBJS}
+ALL_OBJS += ${FWLIB_OBJS} ${FWLIB2X_OBJS} ${FWLIB20_OBJS} ${FWLIB21_OBJS}
 
 # Intermediate library for the vboot_reference utilities to link against.
 UTILLIB = ${BUILD}/libvboot_util.a
@@ -691,9 +692,7 @@ TEST21_NAMES = \
 	tests/vb21_host_misc_tests \
 	tests/vb21_host_sig_tests
 
-ifneq (${VBOOT2},)
 TEST_NAMES += ${TEST2X_NAMES} ${TEST20_NAMES} ${TEST21_NAMES}
-endif
 
 # And a few more...
 TLCL_TEST_NAMES = \
@@ -736,14 +735,13 @@ _dir_create := $(foreach d, \
 
 # Default target.
 .PHONY: all
-all: fwlib \
-	$(if ${VBOOT2},fwlib2x fwlib2 fwlib21) \
+all: fwlib fwlib2x fwlib20 fwlib21 \
 	$(if ${FIRMWARE_ARCH},,host_stuff) \
 	$(if ${COV},coverage)
 
 # Host targets
 .PHONY: host_stuff
-host_stuff: utillib hostlib cgpt utils futil tests $(if ${VBOOT2},utillib21)
+host_stuff: utillib hostlib cgpt utils futil tests utillib21
 
 .PHONY: clean
 clean:
@@ -786,7 +784,7 @@ ${FWLIB_OBJS}: CFLAGS += -DTPM_BLOCKING_CONTINUESELFTEST
 ifeq (${FIRMWARE_ARCH},i386)
 # Unrolling loops in cryptolib makes it faster
 ${FWLIB_OBJS}: CFLAGS += -DUNROLL_LOOPS
-${FWLIB2_OBJS}: CFLAGS += -DUNROLL_LOOPS
+${FWLIB2X_OBJS}: CFLAGS += -DUNROLL_LOOPS
 ${FWLIB20_OBJS}: CFLAGS += -DUNROLL_LOOPS
 ${FWLIB21_OBJS}: CFLAGS += -DUNROLL_LOOPS
 
@@ -844,17 +842,16 @@ ${FWLIB}: ${FWLIB_OBJS}
 .PHONY: fwlib2x
 fwlib2x: ${FWLIB2X}
 
-${FWLIB2X}: ${FWLIB2_OBJS}
+${FWLIB2X}: ${FWLIB2X_OBJS}
 	@${PRINTF} "    RM            $(subst ${BUILD}/,,$@)\n"
 	${Q}rm -f $@
 	@${PRINTF} "    AR            $(subst ${BUILD}/,,$@)\n"
 	${Q}ar qc $@ $^
 
-# TODO: it'd be nice to call this fwlib20, but coreboot expects fwlib2
-.PHONY: fwlib2
-fwlib2: ${FWLIB20}
+.PHONY: fwlib20
+fwlib20: ${FWLIB20}
 
-${FWLIB20}: ${FWLIB2_OBJS} ${FWLIB20_OBJS}
+${FWLIB20}: ${FWLIB2X_OBJS} ${FWLIB20_OBJS}
 	@${PRINTF} "    RM            $(subst ${BUILD}/,,$@)\n"
 	${Q}rm -f $@
 	@${PRINTF} "    AR            $(subst ${BUILD}/,,$@)\n"
@@ -863,7 +860,7 @@ ${FWLIB20}: ${FWLIB2_OBJS} ${FWLIB20_OBJS}
 .PHONY: fwlib21
 fwlib21: ${FWLIB21}
 
-${FWLIB21}: ${FWLIB2_OBJS} ${FWLIB21_OBJS}
+${FWLIB21}: ${FWLIB2X_OBJS} ${FWLIB21_OBJS}
 	@${PRINTF} "    RM            $(subst ${BUILD}/,,$@)\n"
 	${Q}rm -f $@
 	@${PRINTF} "    AR            $(subst ${BUILD}/,,$@)\n"
@@ -892,7 +889,7 @@ ${UTILLIB}: ${UTILLIB_OBJS} ${FWLIB_OBJS}
 utillib21: ${UTILLIB21}
 
 ${UTILLIB21}: INCLUDES += -Ihost/lib21/include -Ifirmware/lib21/include
-${UTILLIB21}: ${UTILLIB21_OBJS} ${FWLIB2_OBJS} ${FWLIB21_OBJS}
+${UTILLIB21}: ${UTILLIB21_OBJS} ${FWLIB2X_OBJS} ${FWLIB21_OBJS}
 	@${PRINTF} "    RM            $(subst ${BUILD}/,,$@)\n"
 	${Q}rm -f $@
 	@${PRINTF} "    AR            $(subst ${BUILD}/,,$@)\n"
@@ -1004,13 +1001,12 @@ signing_install: ${SIGNING_SCRIPTS} ${SIGNING_SCRIPTS_DEV} ${SIGNING_COMMON}
 .PHONY: futil
 futil: ${FUTIL_STATIC_BIN} ${FUTIL_BIN}
 
-${FUTIL_STATIC_BIN}: ${FUTIL_STATIC_OBJS} ${UTILLIB} \
-		$(if ${VBOOT2},${FWLIB20})
+${FUTIL_STATIC_BIN}: ${FUTIL_STATIC_OBJS} ${UTILLIB}
 	@${PRINTF} "    LD            $(subst ${BUILD}/,,$@)\n"
 	${Q}${LD} -o $@ ${CFLAGS} ${LDFLAGS} -static $^ ${LDLIBS}
 
 ${FUTIL_BIN}: LDLIBS += ${CRYPTO_LIBS}
-${FUTIL_BIN}: ${FUTIL_OBJS} ${UTILLIB} $(if ${VBOOT2},${FWLIB20})
+${FUTIL_BIN}: ${FUTIL_OBJS} ${UTILLIB}
 	@${PRINTF} "    LD            $(subst ${BUILD}/,,$@)\n"
 	${Q}${LD} -o $@ ${CFLAGS} ${LDFLAGS} $^ ${LDLIBS}
 
@@ -1208,7 +1204,7 @@ ${FUTIL_CMD_LIST} ${FUTIL_STATIC_CMD_LIST}:
 
 # Frequently-run tests
 .PHONY: test_targets
-test_targets:: runcgpttests runmisctests $(if ${VBOOT2},run2tests)
+test_targets:: runcgpttests runmisctests run2tests
 
 ifeq (${MINIMAL},)
 # Bitmap utility isn't compiled for minimal variant
@@ -1268,10 +1264,8 @@ runtestscripts: test_setup genfuzztestcases
 	tests/run_rsa_tests.sh
 	tests/run_vbutil_kernel_arg_tests.sh
 	tests/run_vbutil_tests.sh
-ifneq (${VBOOT2},)
 	tests/vb2_rsa_tests.sh
 	tests/vb2_firmware_tests.sh
-endif
 
 .PHONY: runmisctests
 runmisctests: test_setup
@@ -1336,11 +1330,9 @@ runfutiltests: test_setup
 runlongtests: test_setup genkeys genfuzztestcases
 	${RUNTEST} ${BUILD_RUN}/tests/vboot_common2_tests ${TEST_KEYS} --all
 	${RUNTEST} ${BUILD_RUN}/tests/vboot_common3_tests ${TEST_KEYS} --all
-ifneq (${VBOOT2},)
 	${RUNTEST} ${BUILD_RUN}/tests/vb20_common2_tests ${TEST_KEYS} --all
 	${RUNTEST} ${BUILD_RUN}/tests/vb20_common3_tests ${TEST_KEYS} --all
 	${RUNTEST} ${BUILD_RUN}/tests/vb21_common2_tests ${TEST_KEYS} --all
-endif
 	tests/run_preamble_tests.sh --all
 	tests/run_vbutil_tests.sh --all
 
diff --git a/firmware/README b/firmware/README
index ac35e93b..754edf1b 100644
--- a/firmware/README
+++ b/firmware/README
@@ -1,8 +1,43 @@
-arch/ is stuff that defines the architecture-dependent information (only used in
-firmware build mode).
 
-lib/ is stuff that the BIOS needs to link with.
+Here's what's what in the firmware/ directory.
 
-stub/ is stuff to be implemented by the BIOS.
+include/
+lib/
 
-include/ describes the interfaces between the two parts.
+  These are the original structures and APIs used in the earliest
+  Chromebooks and continuing through 2014. It never had a version as such to
+  begin with, but we now refer to this implementation as "vboot1" or
+  "vboot version 1.0".
+
+linktest/
+stub/
+
+  These are stubs used to link the vboot1 libraries into host-side test
+  executables so we can run some tests on the build machine instead of a
+  Chromebook.
+
+2lib/
+
+  In 2014 we began work on a new vboot API. The first step was just a
+  refactoring and renaming of the verification API. The public functions and
+  external headers that are exported for use by the Chrome OS firmware (or
+  anything else that wants to use vboot) live in here. The internal
+  structures and implementations go elsewhere.
+
+lib20/
+
+  This is an early implementation of the public (2lib/) API. It is
+  binary-compatible with vboot1, so although the interface details are
+  different, any existing on-device structures or signatures created by the
+  vboot1 tools can be validated using this implementation.
+
+  This was deployed slightly before it was ready. That's not a problem,
+  thanks to the binary compatibility, but this directory will be abandoned
+  Real Soon Now, except for the product support branches.
+
+lib21/
+
+  This is where the current development of the second-generation vboot API
+  is taking place. It uses the public (2lib/) API, but will NOT be binary
+  compatible with vboot1 structs. Because of the early release of the lib20
+  stuff, we're actually calling this lib21.