docs/library/esp: Document esp.set_native_code_location() function.

dpgeorge · dpgeorge · commit c3f70c603efc · 2017-01-04T23:48:19.000+11:00
diff --git 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.
