1- :mod: `micropython ` -- MicroPython extensions and internals
2- ==========================================================
1+ :mod: `micropython ` -- access and control MicroPython internals
2+ ==============================================================
33
44.. module :: micropython
55 :synopsis: access and control MicroPython internals
@@ -26,3 +26,132 @@ Functions
2626 provided as part of the :mod: `micropython ` module mainly so that scripts can be
2727 written which run under both CPython and MicroPython, by following the above
2828 pattern.
29+
30+ .. function :: opt_level([level])
31+
32+ If *level * is given then this function sets the optimisation level for subsequent
33+ compilation of scripts, and returns ``None ``. Otherwise it returns the current
34+ optimisation level.
35+
36+ The optimisation level controls the following compilation features:
37+
38+ - Assertions: at level 0 assertion statements are enabled and compiled into the
39+ bytecode; at levels 1 and higher assertions are not compiled.
40+ - Built-in ``__debug__ `` variable: at level 0 this variable expands to ``True ``;
41+ at levels 1 and higher it expands to ``False ``.
42+ - Source-code line numbers: at levels 0, 1 and 2 source-code line number are
43+ stored along with the bytecode so that exceptions can report the line number
44+ they occurred at; at levels 3 and higher line numbers are not stored.
45+
46+ The default optimisation level is usually level 0.
47+
48+ .. function :: alloc_emergency_exception_buf(size)
49+
50+ Allocate *size * bytes of RAM for the emergency exception buffer (a good
51+ size is around 100 bytes). The buffer is used to create exceptions in cases
52+ when normal RAM allocation would fail (eg within an interrupt handler) and
53+ therefore give useful traceback information in these situations.
54+
55+ A good way to use this function is to put it at the start of your main script
56+ (eg ``boot.py `` or ``main.py ``) and then the emergency exception buffer will be active
57+ for all the code following it.
58+
59+ .. function :: mem_info([verbose])
60+
61+ Print information about currently used memory. If the *verbose * argument
62+ is given then extra information is printed.
63+
64+ The information that is printed is implementation dependent, but currently
65+ includes the amount of stack and heap used. In verbose mode it prints out
66+ the entire heap indicating which blocks are used and which are free.
67+
68+ .. function :: qstr_info([verbose])
69+
70+ Print information about currently interned strings. If the *verbose *
71+ argument is given then extra information is printed.
72+
73+ The information that is printed is implementation dependent, but currently
74+ includes the number of interned strings and the amount of RAM they use. In
75+ verbose mode it prints out the names of all RAM-interned strings.
76+
77+ .. function :: stack_use()
78+
79+ Return an integer representing the current amount of stack that is being
80+ used. The absolute value of this is not particularly useful, rather it
81+ should be used to compute differences in stack usage at different points.
82+
83+ .. function :: heap_lock()
84+ .. function :: heap_unlock()
85+ .. function :: heap_l
10000
ocked()
86+
87+ Lock or unlock the heap. When locked no memory allocation can occur and a
88+ `MemoryError ` will be raised if any heap allocation is attempted.
89+ `heap_locked() ` returns a true value if the heap is currently locked.
90+
91+ These functions can be nested, ie `heap_lock() ` can be called multiple times
92+ in a row and the lock-depth will increase, and then `heap_unlock() ` must be
93+ called the same number of times to make the heap available again.
94+
95+ Both `heap_unlock() ` and `heap_locked() ` return the current lock depth
96+ (after unlocking for the former) as a non-negative integer, with 0 meaning
97+ the heap is not locked.
98+
99+ If the REPL becomes active with the heap locked then it will be forcefully
100+ unlocked.
101+
102+ Note: `heap_locked() ` is not enabled on most ports by default,
103+ requires ``MICROPY_PY_MICROPYTHON_HEAP_LOCKED ``.
104+
105+ .. function :: kbd_intr(chr)
106+
107+ Set the character that will raise a `KeyboardInterrupt ` exception. By
108+ default this is set to 3 during script execution, corresponding to Ctrl-C.
109+ Passing -1 to this function will disable capture of Ctrl-C, and passing 3
110+ will restore it.
111+
112+ This function can be used to prevent the capturing of Ctrl-C on the
113+ incoming stream of characters that is usually used for the REPL, in case
114+ that stream is used for other purposes.
115+
116+ .. function :: schedule(func, arg)
117+
118+ Schedule the function *func * to be executed "very soon". The function
119+ is passed the value *arg * as its single argument. "Very soon" means that
120+ the MicroPython runtime will do its best to execute the function at the
121+ earliest possible time, given that it is also trying to be efficient, and
122+ that the following conditions hold:
123+
124+ - A scheduled function will never preempt another scheduled function.
125+ - Scheduled functions are always executed "between opcodes" which means
126+ that all fundamental Python operations (such as appending to a list)
127+ are guaranteed to be atomic.
128+ - A given port may define "critical regions" within which scheduled
129+ functions will never be executed. Functions may be scheduled within
130+ a critical region but they will not be executed until that region
131+ is exited. An example of a critical region is a preempting interrupt
132+ handler (an IRQ).
133+
134+ A use for this function is to schedule a callback from a preempting IRQ.
135+ Such an IRQ puts restrictions on the code that runs in the IRQ (for example
136+ the heap may be locked) and scheduling a function to call later will lift
137+ those restrictions.
138+
139+ On multi-threaded ports, the scheduled function's behaviour depends on
140+ whether the Global Interpreter Lock (GIL) is enabled for the specific port:
141+
142+ - If GIL is enabled, the function can preempt any thread and run in its
143+ context.
144+ - If GIL is disabled, the function will only preempt the main thread and run
145+ in its context.
146+
147+ Note: If `schedule() ` is called from a preempting IRQ, when memory
148+ allocation is not allowed and the callback to be passed to `schedule() ` is
149+ a bound method, passing this directly will fail. This is because creating a
150+ reference to a bound method causes memory allocation. A solution is to
151+ create a reference to the method in the class constructor and to pass that
152+ reference to `schedule() `. This is discussed in detail here
153+ :ref: `reference documentation <isr_rules >` under "Creation of Python
154+ objects".
155+
156+ There is a finite queue to hold the scheduled functions and `schedule() `
157+ will raise a `RuntimeError ` if the queue is full.
0 commit comments