mirrors/micropython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Damien George 2017-01-04 23:48:19 +11:00
parent bae7798f1e
commit c3f70c603e
1 changed files with 40 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/library/esp.rst
View File

@ -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.