cleanup: Clarify use of flash layout CONFIGs

Based on feedback from programmers, it's not clear when
config_std_internal_flash should be used, and when non-standard
chip-specific layouts need to be defined. Add clarity here with the
following changes:

- Explain in-depth the one config that config_std_internal_flash should
  be used for.
- Move non-standard chip-level flash layout CONFIGs to their own new
  chip-level file, config_flash_layout. All chips should either include
  config_std_internal_flash.h OR define their own layout in their own
  config_flash_layout.

Functionally, this change is a NOP.

BUG=chrome-os-partner:23796
TEST=`make buildall -j`
BRANCH=None

Change-Id: I6037b68db9048d90fa2a2da4c9c9e09d1143fa68
Signed-off-by: Shawn Nematbakhsh <shawnn@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/296527
Commit-Ready: Shawn N <shawnn@chromium.org>
Tested-by: Shawn N <shawnn@chromium.org>
Reviewed-by: Shawn N <shawnn@chromium.org>

6 files changed, 152 insertions, 96 deletions

diff --git a/chip/mec1322/config_chip.h b/chip/mec1322/config_chip.h
index 31e85ec3e4..3947c61eba 100644
--- a/chip/mec1322/config_chip.h
+++ b/chip/mec1322/config_chip.h
@@ -104,64 +104,7 @@
 #define CONFIG_CDRAM_BASE		0x00100000
 #define CONFIG_CDRAM_SIZE		0x00020000
 
-/* Size of one firmware image in flash */
-#ifndef CONFIG_FW_IMAGE_SIZE
-#define CONFIG_FW_IMAGE_SIZE		(96 * 1024)
-#endif
-
-/* Loader resides at the beginning of program memory */
-#define CONFIG_LOADER_MEM_OFF		0
-#define CONFIG_LOADER_SIZE		0x1000
-
-/*
- * RO / RW images follow the loader in program memory. Either RO or RW
- * image will be loaded -- both cannot be loaded at the same time.
- */
-#define CONFIG_RO_MEM_OFF		(CONFIG_LOADER_MEM_OFF + \
-					CONFIG_LOADER_SIZE)
-#define CONFIG_RO_SIZE			CONFIG_FW_IMAGE_SIZE
-#define CONFIG_RW_MEM_OFF		CONFIG_RO_MEM_OFF
-#define CONFIG_RW_SIZE			CONFIG_RO_SIZE
-
-#define CONFIG_FLASH_SIZE		CONFIG_FLASH_PHYSICAL_SIZE
-#define CONFIG_FW_INCLUDE_RO
-
-/* Write protect Loader and RO Image */
-#define CONFIG_WP_OFF			(CONFIG_FLASH_PHYSICAL_SIZE >> 1)
-/* Write protect 128k section of 256k physical flash
-which contains Loader and RO Images */
-#define CONFIG_WP_SIZE			(CONFIG_FLASH_PHYSICAL_SIZE >> 1)
-/****************************************************************************/
-/* SPI Flash Memory Mapping */
-
-/* Size of SPI memory used (lfw + RSA Keys + RO + RW + boot header) */
-#define CONFIG_FLASH_BASE_SPI		(CONFIG_SPI_FLASH_SIZE - (0x40000))
-
-/* RW image starts at the beginning of SPI */
-#define CONFIG_RW_STORAGE_OFF		0
-
-/* WP region consists of second half of SPI, and begins with the boot header */
-#define CONFIG_BOOT_HEADER_STORAGE_OFF	CONFIG_WP_OFF
-#define CONFIG_BOOT_HEADER_STORAGE_SIZE	0x240
-
-/* Loader / lfw image immediately follows the boot header on SPI */
-#define CONFIG_LOADER_STORAGE_OFF	(CONFIG_BOOT_HEADER_STORAGE_OFF + \
-					CONFIG_BOOT_HEADER_STORAGE_SIZE)
-
-/* RO image immediately follows the loader image */
-#define CONFIG_RO_STORAGE_OFF		(CONFIG_LOADER_STORAGE_OFF + \
-					CONFIG_LOADER_SIZE)
-
-#define CONFIG_RO_IMAGE_FLASHADDR	(CONFIG_FLASH_BASE_SPI + \
-					CONFIG_RO_STORAGE_OFF)
-#define CONFIG_RW_IMAGE_FLASHADDR	(CONFIG_FLASH_BASE_SPI + \
-					CONFIG_RW_STORAGE_OFF)
-
-/* Non-memmapped, external SPI */
-#define CONFIG_CODERAM_ARCH
-#undef  CONFIG_FLASH_MAPPED
-#undef  CONFIG_FLASH_PSTATE
-#define CONFIG_SPI_FLASH
+#include "config_flash_layout.h"
 
 /****************************************************************************/
 /* Customize the build */
diff --git a/chip/mec1322/config_flash_layout.h b/chip/mec1322/config_flash_layout.h
new file mode 100644
index 0000000000..d7a16085c9
--- /dev/null
+++ b/chip/mec1322/config_flash_layout.h
@@ -0,0 +1,74 @@
+/* Copyright 2015 The Chromium OS Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef __CROS_EC_CONFIG_FLASH_LAYOUT_H
+#define __CROS_EC_CONFIG_FLASH_LAYOUT_H
+
+/*
+ * mec1322 flash layout:
+ * - Non memory-mapped, external SPI.
+ * - RW image at the beginning of writable region.
+ * - Bootloader at the beginning of protected region, followed by RO image.
+ * - Loader + (RO | RW) loaded into program memory.
+ */
+
+/* Non-memmapped, external SPI */
+#define CONFIG_CODERAM_ARCH
+#undef  CONFIG_FLASH_MAPPED
+#undef  CONFIG_FLASH_PSTATE
+#define CONFIG_SPI_FLASH
+
+/* Size of SPI memory used by EC (lfw + RSA Keys + RO + RW + boot header) */
+#define CONFIG_FLASH_BASE_SPI		(CONFIG_SPI_FLASH_SIZE - (0x40000))
+
+/* Size of one firmware image in flash */
+#ifndef CONFIG_FW_IMAGE_SIZE
+#define CONFIG_FW_IMAGE_SIZE		(96 * 1024)
+#endif
+#define CONFIG_FLASH_SIZE		CONFIG_FLASH_PHYSICAL_SIZE
+
+/* Loader resides at the beginning of program memory */
+#define CONFIG_LOADER_MEM_OFF		0
+#define CONFIG_LOADER_SIZE		0x1000
+
+/* Write protect Loader and RO Image */
+#define CONFIG_WP_OFF			(CONFIG_FLASH_PHYSICAL_SIZE >> 1)
+/*
+ * Write protect 128k section of 256k physical flash which contains loader
+ * and RO Images.
+ */
+#define CONFIG_WP_SIZE			(CONFIG_FLASH_PHYSICAL_SIZE >> 1)
+
+/*
+ * RO / RW images follow the loader in program memory. Either RO or RW
+ * image will be loaded -- both cannot be loaded at the same time.
+ */
+#define CONFIG_RO_MEM_OFF		(CONFIG_LOADER_MEM_OFF + \
+					CONFIG_LOADER_SIZE)
+#define CONFIG_RO_SIZE			CONFIG_FW_IMAGE_SIZE
+#define CONFIG_RW_MEM_OFF		CONFIG_RO_MEM_OFF
+#define CONFIG_RW_SIZE			CONFIG_RO_SIZE
+
+/* WP region consists of second half of SPI, and begins with the boot header */
+#define CONFIG_BOOT_HEADER_STORAGE_OFF	CONFIG_WP_OFF
+#define CONFIG_BOOT_HEADER_STORAGE_SIZE	0x240
+
+/* Loader / lfw image immediately follows the boot header on SPI */
+#define CONFIG_LOADER_STORAGE_OFF	(CONFIG_BOOT_HEADER_STORAGE_OFF + \
+					CONFIG_BOOT_HEADER_STORAGE_SIZE)
+
+/* RO image immediately follows the loader image */
+#define CONFIG_RO_STORAGE_OFF		(CONFIG_LOADER_STORAGE_OFF + \
+					CONFIG_LOADER_SIZE)
+
+/* RW image starts at the beginning of SPI */
+#define CONFIG_RW_STORAGE_OFF		0
+
+#define CONFIG_RO_IMAGE_FLASHADDR	(CONFIG_FLASH_BASE_SPI + \
+					CONFIG_RO_STORAGE_OFF)
+#define CONFIG_RW_IMAGE_FLASHADDR	(CONFIG_FLASH_BASE_SPI + \
+					CONFIG_RW_STORAGE_OFF)
+
+#endif /* __CROS_EC_CONFIG_FLASH_LAYOUT_H */
diff --git a/chip/npcx/config_chip.h b/chip/npcx/config_chip.h
index 3b39065220..be2e0c15a0 100644
--- a/chip/npcx/config_chip.h
+++ b/chip/npcx/config_chip.h
@@ -79,43 +79,7 @@
 /* 128 KB alignment for SPI status registers protection */
 #define CONFIG_FLASH_PHYSICAL_SIZE  0x40000 /* 256 KB Flash used for EC */
 
-/* No PSTATE; uses a real SPI flash */
-#undef CONFIG_FLASH_PSTATE
-
-/* Header support which is used by booter to copy FW from flash to code ram */
-#define NPCX_RO_HEADER
-
-/****************************************************************************/
-/* Define npcx flash layout. */
-/* Size of one firmware image in flash */
-#ifndef CONFIG_FW_IMAGE_SIZE
-#define CONFIG_FW_IMAGE_SIZE    (CONFIG_FLASH_PHYSICAL_SIZE / 2)
-#endif
-
-/* The storage offset of ec.RO.flat which is used for CONFIG_CDRAM_ARCH */
-#define CONFIG_RO_STORAGE_OFF   0
-#ifdef NPCX_RO_HEADER
-#define CONFIG_RO_HDR_MEM_OFF   0x0
-#define CONFIG_RO_HDR_SIZE      0x40
-/* RO firmware offset in flash */
-#define CONFIG_RO_MEM_OFF       CONFIG_RO_HDR_SIZE
-#else
-#define CONFIG_RO_MEM_OFF       0x0
-#endif
-#define CONFIG_RO_SIZE          CONFIG_CDRAM_SIZE    /* 96KB for RO FW */
-#define CONFIG_FLASH_SIZE       CONFIG_FLASH_PHYSICAL_SIZE
-
-/* The storage offset of ec.RW.flat which is used for CONFIG_CDRAM_ARCH */
-#define CONFIG_RW_STORAGE_OFF   CONFIG_FW_IMAGE_SIZE /* 128 KB alignemnt */
-/* RW firmware offset in flash */
-#define CONFIG_RW_MEM_OFF       CONFIG_RW_STORAGE_OFF
-#define CONFIG_RW_SIZE          CONFIG_CDRAM_SIZE    /* 96KB for RW FW */
-
-#define CONFIG_WP_OFF           CONFIG_RO_STORAGE_OFF
-#define CONFIG_WP_SIZE          CONFIG_FW_IMAGE_SIZE
-
-/****************************************************************************/
-/* Customize the build */
+#include "config_flash_layout.h"
 
 /* Optional features present on this chip */
 #define CONFIG_ADC
diff --git a/chip/npcx/config_flash_layout.h b/chip/npcx/config_flash_layout.h
new file mode 100644
index 0000000000..0988c3ca35
--- /dev/null
+++ b/chip/npcx/config_flash_layout.h
@@ -0,0 +1,46 @@
+/* Copyright 2015 The Chromium OS Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef __CROS_EC_CONFIG_FLASH_LAYOUT_H
+#define __CROS_EC_CONFIG_FLASH_LAYOUT_H
+
+/*
+ * npcx flash layout:
+ * - Memory-mapped external SPI.
+ * - Image header at the beginning of protected region, followed by RO image.
+ * - RW image starts at the second half of flash.
+ */
+
+/* Memmapped, external SPI */
+#define CONFIG_FLASH_MAPPED
+#undef  CONFIG_FLASH_PSTATE
+
+/* Size of one firmware image in flash */
+#ifndef CONFIG_FW_IMAGE_SIZE
+#define CONFIG_FW_IMAGE_SIZE	(CONFIG_FLASH_PHYSICAL_SIZE / 2)
+#endif
+
+/* Header support which is used by booter to copy FW from flash to code ram */
+#define NPCX_RO_HEADER
+#define CONFIG_RO_HDR_MEM_OFF	0x0
+#define CONFIG_RO_HDR_SIZE	0x40
+
+#define CONFIG_WP_OFF		CONFIG_RO_STORAGE_OFF
+#define CONFIG_WP_SIZE		CONFIG_FW_IMAGE_SIZE
+
+/* RO firmware offset in flash */
+#define CONFIG_RO_MEM_OFF	CONFIG_RO_HDR_SIZE
+#define CONFIG_RO_SIZE		CONFIG_CDRAM_SIZE    /* 96KB for RO FW */
+#define CONFIG_FLASH_SIZE	CONFIG_FLASH_PHYSICAL_SIZE
+
+/* RW firmware offset in flash */
+#define CONFIG_RW_MEM_OFF	CONFIG_RW_STORAGE_OFF
+#define CONFIG_RW_SIZE		CONFIG_CDRAM_SIZE    /* 96KB for RW FW */
+
+/* The storage offset of ec.R*.flat which is used for CONFIG_CDRAM_ARCH */
+#define CONFIG_RO_STORAGE_OFF	0
+#define CONFIG_RW_STORAGE_OFF	CONFIG_FW_IMAGE_SIZE /* 128 KB alignemnt */
+
+#endif /* __CROS_EC_CONFIG_FLASH_LAYOUT_H */
diff --git a/include/config.h b/include/config.h
index 544fcc1ed9..be35fa09c9 100644
--- a/include/config.h
+++ b/include/config.h
@@ -760,6 +760,13 @@
 #undef CONFIG_RW_SIZE
 
 /*
+ * NPCX-specific bootheader geometry.
+ * TODO(crosbug.com/p/23796): Factor these CONFIGs out.
+ */
+#undef CONFIG_RO_HDR_MEM_OFF
+#undef CONFIG_RO_HDR_SIZE
+
+/*
  * Write protect region offset / size. This region normally encompasses the
  * RO image, but may also contain additional images or data.
  */
diff --git a/include/config_std_internal_flash.h b/include/config_std_internal_flash.h
index d918e8a813..10cd5baf5c 100644
--- a/include/config_std_internal_flash.h
+++ b/include/config_std_internal_flash.h
@@ -11,9 +11,31 @@
  * - RO image starts at the beginning of flash.
  * - PSTATE immediately follows the RO image.
  * - RW image starts at the second half of flash.
- * - WP region consists of the first half of flash (RO + PSTATE).
+ * - Protected region consists of the first half of flash (RO image + PSTATE).
+ * - Unprotected region consists of second half of flash (RW image).
+ *
+ *                            PSTATE
+ *                              |
+ *                              v
+ * |<-----Protected Region------>|<------Unprotected Region----->|
+ * |<--------RO image--------->| |<----------RW image----------->|
+ * 0                            N/2                              N
+ *
+ * This layout is used by several supported chips. Chips which do not use
+ * this layout MUST NOT include this header file, and must instead define
+ * the configs below in a chip-level header file (config_flash_layout.h).
+ *
+ * See the following page for additional image geometry discussion:
+ *
+ * https://www.chromium.org/chromium-os/ec-development/ec-image-geometry-spec
+ *
+ * TODO(crosbug.com/p/23796): Finish implementing the spec.
  */
 
+/* Memory-mapped internal flash w/ PSTATE */
+#define CONFIG_FLASH_MAPPED
+#define CONFIG_FLASH_PSTATE
+
 /*
  * The EC uses the one bank of flash to emulate a SPI-like write protect
  * register with persistent state.