docs/library/esp: Document esp.set_native_code_location() function.
This commit is contained in:
parent
bae7798f1e
commit
c3f70c603e
|
@ -45,3 +45,43 @@ Functions
|
||||||
.. function:: flash_write(byte_offset, bytes)
|
.. function:: flash_write(byte_offset, bytes)
|
||||||
|
|
||||||
.. function:: flash_erase(sector_no)
|
.. 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.
|
||||||
|
|
Loading…
Reference in New Issue