From c3f70c603efcb053810dbee8d5cc9f23ed62d01f Mon Sep 17 00:00:00 2001 From: Damien George <damien.p.george@gmail.com> Date: Wed, 4 Jan 2017 23:48:19 +1100 Subject: [PATCH] docs/library/esp: Document esp.set_native_code_location() function. --- docs/library/esp.rst | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/library/esp.rst b/docs/library/esp.rst index 0836bba72..6481d1f91 100644 --- a/docs/library/esp.rst +++ b/docs/library/esp.rst @@ -45,3 +45,43 @@ Functions .. function:: flash_write(byte_offset, bytes) .. function:: flash_erase(sector_no) + +.. function:: set_native_code_location(start, length) + + Set the location that native code will be placed for execution after it is + compiled. Native code is emitted when the ``@micropython.native``, + ``@micropython.viper`` and ``@micropython.asm_xtensa`` decorators are applied + to a function. The ESP8266 must execute code from either iRAM or the lower + 1MByte of flash (which is memory mapped), and this function controls the + location. + + If `start` and `length` are both `None` then the native code location is + set to the unused portion of memory at the end of the iRAM1 region. The + size of this unused portion depends on the firmware and is typically quite + small (around 500 bytes), and is enough to store a few very small + functions. The advantage of using this iRAM1 region is that it does not + get worn out by writing to it. + + If neither `start` nor `length` are `None` then they should be integers. + `start` should specify the byte offset from the beginning of the flash at + which native code should be stored. `length` specifies how many bytes of + flash from `start` can be used to store native code. `start` and `length` + should be multiples of the sector size (being 4096 bytes). The flash will + be automatically erased before writing to it so be sure to use a region of + flash that is not otherwise used, for example by the firmware or the + filesystem. + + With the default boot/filesystem configuration there is one sector of flash + reserved for general use and one can use the following call to use it for + native code generation:: + + esp.set_native_code_location(esp.flash_user_start(), 4096) + + When using the flash to store native code `start+length` must be less + than or equal to 1MByte. Note that the flash can be worn out if repeated + erasures (and writes) are made so use this feature sparingly. + + In both cases above, using iRAM1 or flash, if there is no more room left + in the specified region then the use of a native decorator on a function + will lead to `MemoryError` exception being raised during compilation of + that function. -- GitLab