Shouldn't esptool provide `map` for system_partition_table_regist()? (ESPTOOL-138)

[bitmandu]

Version 3.0 (released August 2018) of the Non-OS SDK requires calling system_partition_table_regist() in user_pre_init to register the project's partition table (see the README and Partition Table documentation).

The last argument of system_partition_table_regist() is map:

uint32_t map: flash map. The value of this parameter should be the same as the
flash map selected during the compilation and downloading. Otherwise, it may
cause abnormal startup. It’s recommended that Marco SPI_FLASH_SIZE_MAP,
which stores the value of flash map during the compilation, is passed to this
parameter. (API Reference, section 3.3.50)

If map isn't set properly a boot error like the following occurs.

mismatch map 6,spi_size_map 4

As discussed in issue 159 of the espressif/ESP8266_NONOS_SDK issue tracker, the expected spi_size_map is the flash_size_freq byte in the header set by esptool when creating the image (see
write_common_header()).

The Problem

This leads to a circular problem: When we compile our code (to create the .elf) we need to supply map to system_partition_table_regist(). However, the value of map we need to supply is the flash_size_freq byte in the header of the image created from the .elf by esptool.

Solution?

I'm not sure what the best solution is, but it seems to me that esptool should provide the map value needed by system_partition_table_regist() — only esptool knows the "right" flash_size_freq byte to write in the image header.

Here are two possible solutions.

Option 1

Create a new flag, e.g., --spi-flash-size-map, that returns the value of map needed by system_partition_table_regist(). This could then be used in a Makefile when compiling.

MAP=`esptool.py --spi-flash-size-map`
CFLAGS = .... -DSPI_FLASH_SIZE_MAP=${MAP}

This could also be part of the output of flash_id.

Option 2

Since the value of map is based on the detected (or provided) flash_size argument, maybe all that is needed is to update the ESP8266 and Flash Size table with another column?

flash_size arg	Number of OTA slots	OTA Slot Size	Non-OTA Space	map
256KB	1 (no OTA)	256KB	N/A	0
512KB	1 (no OTA)	512KB	N/A	1
1MB	2	512KB	0KB	2
2MB	2	512KB	1024KB	3
4MB	2	512KB	3072KB	4
2MB-c1	2	1024KB	0KB	5
4MB-c1	2	1024KB	2048KB	6
8MB	2	1024KB	6144KB	7
16MB	2	1024KB	14336KB	8

(Note: I don't know if the map values listed here are actually right.)

In this option, you would still have to provide your Makefile or code with map. But at least what value to provide to system_partition_table_regist() would be documented.

---

I'm willing to create a pull request to help this along, but I'm not sure if either option I proposed is the correct approach? However, it does look like the circular problem I described is best resolved by esptool, so I'm creating this issue to get the discussion started.