docs: Provide initial documentation for micropython module.

2 files changed, 44 insertions, 0 deletions

diff --git a/docs/library/index.rst b/docs/library/index.rst
index fa4385f86b..b5a7b3ca9c 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -1,6 +1,14 @@
 Micro Python libraries
 ======================
 
+Functionality specific to the Micro Python implementation is available in
+the following library.
+
+.. toctree::
+   :maxdepth: 1
+
+   micropython.rst
+
 Python standard libraries
 -------------------------
 
diff --git a/docs/library/micropython.rst b/docs/library/micropython.rst
new file mode 100644
index 0000000000..c4706c4c61
--- /dev/null
+++ b/docs/library/micropython.rst
@@ -0,0 +1,36 @@
+:mod:`micropython` -- access and control Micro Python internals
+===============================================================
+
+.. module:: micropython
+   :synopsis: access and control Micro Python internals
+
+Functions
+---------
+
+.. function:: mem_info([verbose])
+
+   Print information about currently used memory.  If the ``verbose`` argument
+   is given then extra information is printed.
+
+   The information that is printed is implementation dependent, but currently
+   includes the amount of stack and heap used.  In verbose mode it prints out
+   the entire heap indicating which blocks are used and which are free.
+
+.. function:: qstr_info([verbose])
+
+   Print information about currently interned strings.  If the ``verbose``
+   argument is given then extra information is printed.
+
+   The information that is printed is implementation dependent, but currently
+   includes the number of interned strings and the amount of RAM they use.  In
+   verbose mode it prints out the names of all RAM-interned strings.
+
+.. function:: alloc_emergency_exception_buf(size)
+
+   Allocate ``size`` bytes of RAM for the emergency exception buffer (a good
+   size is around 100 bytes).  The buffer is used to create exceptions in cases
+   when normal RAM allocation would fail (eg within an interrupt handler).
+
+   A good way to use this function is to put it at the start of your main script
+   (eg boot.py or main.py) and then the emergency exception buffer will be active
+   for all the code following it.