Initial commit

Initial commit.

bootloader/mcuboot/boot/cypress/MCUBootApp/ExternalMemory.md

@@ -0,0 +1,100 @@
+### External Memory support for Secondary Slot
+
+**Description**
+
+Given document describes the use of external memory module as a secondary (upgrade) slot with Cypress' PSoC6 devices.
+
+The demonstration device is CY8CPROTO-062-4343W board which is PSoC6 device with 2M of Flash available.
+The memory module present on board is S25FL512SAGMFI010 512-Mbit external Quad SPI NOR Flash.
+
+Using external memory for secondary slot allows to nearly double the size of Boot Image.
+
+**Operation Design and Flow**
+
+The design is based on using SFDP command's auto-discovery functionality of memory module IC and Cypress' SMIF PDL driver.
+
+It is assumed that user's design meets following:
+* The memory-module used is SFDP-compliant;
+* There only one module is being used for secondary slot;
+* Only "OWERWRITE" bootloading scheme is used;
+* The address for secondary slot should start from 0x18000000.
+This corresponds to PSoC6's SMIF (Serial Memory InterFace) IP block mapping.
+* The slot size for upgrade slot is even (or smaller) to erase size (0x40000) of given memory module.
+This requirement is accepted for code simplicity.
+
+The default flash map implemented is the following:
+
+Single-image mode.
+
+`[0x10000000, 0x10018000]` - MCUBootApp (bootloader) area;
+
+`[0x10018000, 0x10028000]` - primary slot for BlinkyApp;
+
+`[0x18000000, 0x18010000]` - secondary slot for BlinkyApp;
+
+`[0x10038000, 0x10039000]` - scratch area (not used);
+
+Multi(dual)-image mode.
+
+`[0x10000000, 0x10018000]` - MCUBootApp (bootloader) area;
+
+`[0x10018000, 0x10028000]` - primary1 slot for BlinkyApp;
+
+`[0x18000000, 0x18010000]` - secondary1 slot for BlinkyApp;
+
+`[0x10038000, 0x10048000]` - primary2 slot for user app ;
+
+`[0x18040000, 0x18050000]` - secondary2 slot for user app;
+
+`[0x10058000, 0x10059000]` - scratch area (not used);
+
+Size of slots `0x10000` - 64kB
+
+**Note 1**: make sure primary, secondary slot and bootloader app sizes are appropriate and correspond to flash area size defined in Applications' linker files.
+
+**Note 2**: make sure secondary slot start address is aligned (or smaller) to erase size (0x40000 - 256kB).
+
+MCUBootApp's `main.c` contains the call to Init-SFDP API which performs required GPIO configurations, SMIF IP block configurations, SFDP protocol read and memory-config structure initialization.
+
+After that MCUBootApp is ready to accept upgrade image from external memory module.
+
+Once valid upgrade image was accepted the image in external memory will be erased.
+
+**How to enable external memory support:**
+
+1. Pass `USE_EXTERNAL_FLASH=1` flag to `make` command when building MCUBootApp.
+2. Navigate to `cy_flash_map.c` and check if secondary slot start address and size meet the application's needs.
+3. Define which slave select is used for external memory on a board by setting `smif_id` value in `main.c`.
+4. Build MCUBootApp as described in `Readme.md`.
+
+**Note 3**: External memory code is developed basing on PDL and can be run on CM0p core only. It may require modifications if used on CM4.
+
+**How to build upgrade image for external memory:**
+
+    make app APP_NAME=BlinkyApp PLATFORM=PSOC_062_2M IMG_TYPE=UPGRADE HEADER_OFFSET=0x7FE8000 ERASED_VALUE=0xff
+
+`HEADER_OFFSET` defines the offset from original boot image address. This one in line above suggests secondary slot will start from `0x18000000`.
+
+`ERASED_VALUE` defines the memory cell contents in erased state. It is `0x00` for PSoC6's internal Flash and `0xff` for S25FL512S.
+
+**Programming to external memory**
+
+The MCUBootApp programming can be done similarly to described in `Readme.md`:
+
+        export OPENOCD=/Applications/ModusToolbox/tools_2.1/openocd
+
+        ${OPENOCD}/bin/openocd -s ${OPENOCD}/scripts \
+                            -f ${OPENOCD}/scripts/interface/kitprog3.cfg \
+                            -f ${OPENOCD}/scripts/target/psoc6_2m.cfg \
+                            -c "init; psoc6 sflash_restrictions 1" \
+                            -c "init; reset init; program PATH_TO_APPLICATION.hex" \
+                            -c "resume; reset; exit" 
+
+There is a NULL-pointer placed for SMIF configuration pointer in TOC2 (Table Of Contents, `cy_serial_flash_prog.c`).
+This is done to force CY8PROTO-062-4343W DAP Link firmware to program external memory with hardcoded values.
+
+1. Press SW3 Mode button on a board to switch the board into DAP Link mode.
+2. Once DAP Link removable disk appeared drop (copy) the upgrade image HEX file to it.
+This will invoke firmware to program external memory.
+
+**Note 3:** the programming of external memory is limited to S25FL512S p/n only at this moment.