docs/reference/glossary.rst: Add new terms and reduce complexity of old.

1 files changed, 161 insertions, 116 deletions

diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst
index a6abc8b9d..d63f37229 100644
--- a/docs/reference/glossary.rst
+++ b/docs/reference/glossary.rst
@@ -4,152 +4,197 @@ Glossary
 .. glossary::
 
     baremetal
-        A system without a (full-fledged) OS, for example an
+        A system without a (full-fledged) operating system, for example an
         :term:`MCU`-based system. When running on a baremetal system,
-        MicroPython effectively becomes its user-facing OS with a command
-        interpreter (REPL).
+        MicroPython effectively functions like a small operating system,
+        running user programs and providing a command interpreter
+        (:term:`REPL`).
+
+    buffer protocol
+        Any Python object that can be automatically converted into bytes, such
+        as ``bytes``, ``bytearray``, ``memoryview`` and ``str`` objects, which
+        all implement the "buffer protocol".
 
     board
-        A PCB board. Oftentimes, the term is used to denote a particular
-        model of an :term:`MCU` system. Sometimes, it is used to actually
-        refer to :term:`MicroPython port` to a particular board (and then
-        may also refer to "boardless" ports like
-        :term:`Unix port <MicroPython Unix port>`).
+        Typically this refers to a printed circuit board (PCB) containing a
+        :term:`microcontroller <MCU>` and supporting components.
+        MicroPython firmware is typically provided per-board, as the firmware
+        contains both MCU-specific functionality but also board-level
+        functionality such as drivers or pin names.
+
+    bytecode
+        A compact representation of a Python program that generated by
+        compiling the Python source code. This is what the VM actually
+        executes. Bytecode is typically generated automatically at runtime and
+        is invisible to the user. Note that while :term:`CPython` and
+        MicroPython both use bytecode, the format is different. You can also
+        pre-compile source code offline using the :term:`cross-compiler`.
 
     callee-owned tuple
-        A tuple returned by some builtin function/method, containing data
-        which is valid for a limited time, usually until next call to the
-        same function (or a group of related functions). After next call,
-        data in the tuple may be changed. This leads to the following
-        restriction on the usage of callee-owned tuples - references to
-        them cannot be stored. The only valid operation is extracting
-        values from them (including making a copy). Callee-owned tuples
-        is a MicroPython-specific construct (not available in the general
-        Python language), introduced for memory allocation optimization.
-        The idea is that callee-owned tuple is allocated once and stored
-        on the callee side. Subsequent calls don't require allocation,
-        allowing to return multiple values when allocation is not possible
-        (e.g. in interrupt context) or not desirable (because allocation
-        inherently leads to memory fragmentation). Note that callee-owned
-        tuples are effectively mutable tuples, making an exception to
-        Python's rule that tuples are immutable. (It may be interesting
-        why tuples were used for such a purpose then, instead of mutable
-        lists - the reason for that is that lists are mutable from user
-        application side too, so a user could do things to a callee-owned
-        list which the callee doesn't expect and could lead to problems;
-        a tuple is protected from this.)
+        This is a MicroPython-specific construct where, for efficiency
+        reasons, some built-in functions or methods may re-use the same
+        underlying tuple object to return data. This avoids having to allocate
+        a new tuple for every call, and reduces heap fragmentation. Programs
+        should not hold references to callee-owned tuples and instead only
+        extract data from them (or make a copy).
+
+    CircuitPython
+        A variant of MicroPython developed by `Adafruit Industries
+        <https://circuitpython.org>`_.
 
     CPython
-        CPython is the reference implementation of Python programming
-        language, and the most well-known one, which most of the people
-        run. It is however one of many implementations (among which
-        Jython, IronPython, PyPy, and many more, including MicroPython).
-        As there is no formal specification of the Python language, only
-        CPython documentation, it is not always easy to draw a line
-        between Python the language and CPython its particular
-        implementation. This however leaves more freedom for other
-        implementations. For example, MicroPython does a lot of things
-        differently than CPython, while still aspiring to be a Python
-        language implementation.
+        CPython is the reference implementation of the Python programming
+        language, and the most well-known one. It is, however, one of many
+        implementations (including Jython, IronPython, PyPy, and MicroPython).
+        While MicroPython's implementation differs substantially from CPython,
+        it aims to maintain as much compatibility as possible.
+
+    cross-compiler
+        Also known as ``mpy-cross``. This tool runs on your PC and converts a
+        :term:`.py file` containing MicroPython code into a :term:`.mpy file`
+        containing MicroPython bytecode. This means it loads faster (the board
+        doesn't have to compile the code), and uses less space on flash (the
+        bytecode is more space efficient).
+
+    driver
+        A MicroPython library that implements support for a particular
+        component, such as a sensor or display.
+
+    FFI
+        Acronym for Foreign Function Interface. A mechanism used by the
+        :term:`MicroPython Unix port` to access operating system functionality.
+        This is not available on :term:`baremetal` ports.
+
+    filesystem
+        Most MicroPython ports and boards provide a filesystem stored in flash
+        that is available to user code via the standard Python file APIs such
+        as ``open()``. Some boards also make this internal filesystem
+        accessible to the host via USB mass-storage.
+
+    frozen module
+        A Python module that has been cross compiled and bundled into the
+        firmware image. This reduces RAM requirements as the code is executed
+        directly from flash.
+
+    Garbage Collector
+        A background process that runs in Python (and MicroPython) to reclaim
+        unused memory in the :term:`heap`.
 
     GPIO
-        General-purpose input/output. The simplest means to control
-        electrical signals. With GPIO, user can configure hardware
-        signal pin to be either input or output, and set or get
-        its digital signal value (logical "0" or "1"). MicroPython
-        abstracts GPIO access using :class:`machine.Pin` and :class:`machine.Signal`
+        General-purpose input/output. The simplest means to control electrical
+        signals (commonly referred to as "pins") on a microcontroller. GPIO
+        typically allows pins to be either input or output, and to set or get
+        their digital value (logical "0" or "1"). MicroPython abstracts GPIO
+        access using the :class:`machine.Pin` and :class:`machine.Signal`
         classes.
 
     GPIO port
-        A group of :term:`GPIO` pins, usually based on hardware
-        properties of these pins (e.g. controllable by the same
-        register).
+        A group of :term:`GPIO` pins, usually based on hardware properties of
+        these pins (e.g. controllable by the same register).
+
+    heap
+        A region of RAM where MicroPython stores dynamic data. It is managed
+        automatically by the :term:`Garbage Collector`. Different MCUs and
+        boards have vastly different amounts of RAM available for the heap, so
+        this will affect how complex your program can be.
 
     interned string
-        A string referenced by its (unique) identity rather than its
-        address. Interned strings are thus can be quickly compared just
-        by their identifiers, instead of comparing by content. The
-        drawbacks of interned strings are that interning operation takes
-        time (proportional to the number of existing interned strings,
-        i.e. becoming slower and slower over time) and that the space
-        used for interned strings is not reclaimable. String interning
-        is done automatically by MicroPython compiler and runtimer when
-        it's either required by the implementation (e.g. function keyword
-        arguments are represented by interned string id's) or deemed
-        beneficial (e.g. for short enough strings, which have a chance
-        to be repeated, and thus interning them would save memory on
-        copies). Most of string and I/O operations don't produce interned
-        strings due to drawbacks described above.
+        An optimisation used by MicroPython to improve the efficiency of
+        working with strings. An interned string is referenced by its (unique)
+        identity rather than its address and can therefore be quickly compared
+        just by its identifier. It also means that identical strings can be
+        de-duplicated in memory. String interning is almost always invisible to
+        the user.
 
     MCU
         Microcontroller. Microcontrollers usually have much less resources
-        than a full-fledged computing system, but smaller, cheaper and
+        than a desktop, laptop, or phone, but are smaller, cheaper and
         require much less power. MicroPython is designed to be small and
         optimized enough to run on an average modern microcontroller.
 
     micropython-lib
         MicroPython is (usually) distributed as a single executable/binary
         file with just few builtin modules. There is no extensive standard
-        library comparable with :term:`CPython`. Instead, there is a related, but
-        separate project
-        `micropython-lib <https://github.com/micropython/micropython-lib>`_
-        which provides implementations for many modules from CPython's
-        standard library. However, large subset of these modules require
-        POSIX-like environment (Linux, FreeBSD, MacOS, etc.; Windows may be
-        partially supported), and thus would work or make sense only with
-        `MicroPython Unix port`. Some subset of modules is however usable
-        for `baremetal` ports too.
-
-        Unlike monolithic :term:`CPython` stdlib, micropython-lib modules
-        are intended to be installed individually - either using manual
-        copying or using :term:`upip`.
+        library comparable with :term:`CPython`'s. Instead, there is a related,
+        but separate project `micropython-lib
+        <https://github.com/micropython/micropython-lib>`_ which provides
+        implementations for many modules from CPython's standard library.
+
+        Some of the modules are are implemented in pure Python, and are able to
+        be used on all ports. However, the majority of these modules use
+        :term:`FFI` to access operating system functionality, and as such can
+        only be used on the :term:`MicroPython Unix port` (with limited support
+        for Windows).
+
+        Unlike the :term:`CPython` stdlib, micropython-lib modules are
+        intended to be installed individually - either using manual copying or
+        using :term:`upip`.
 
     MicroPython port
-        MicroPython supports different :term:`boards <board>`, RTOSes,
-        and OSes, and can be relatively easily adapted to new systems.
-        MicroPython with support for a particular system is called a
-        "port" to that system. Different ports may have widely different
-        functionality. This documentation is intended to be a reference
-        of the generic APIs available across different ports ("MicroPython
-        core"). Note that some ports may still omit some APIs described
-        here (e.g. due to resource constraints). Any such differences,
-        and port-specific extensions beyond MicroPython core functionality,
-        would be described in the separate port-specific documentation.
+        MicroPython supports different :term:`boards <board>`, RTOSes, and
+        OSes, and can be relatively easily adapted to new systems. MicroPython
+        with support for a particular system is called a "port" to that
+        system. Different ports may have widely different functionality. This
+        documentation is intended to be a reference of the generic APIs
+        available across different ports ("MicroPython core"). Note that some
+        ports may still omit some APIs described here (e.g. due to resource
+        constraints). Any such differences, and port-specific extensions
+        beyond the MicroPython core functionality, would be described in the
+        separate port-specific documentation.
 
     MicroPython Unix port
-        Unix port is one of the major :term:`MicroPython ports <MicroPython port>`.
-        It is intended to run on POSIX-compatible operating systems, like
-        Linux, MacOS, FreeBSD, Solaris, etc. It also serves as the basis
-        of Windows port. The importance of Unix port lies in the fact
-        that while there are many different :term:`boards <board>`, so
-        two random users unlikely have the same board, almost all modern
-        OSes have some level of POSIX compatibility, so Unix port serves
-        as a kind of "common ground" to which any user can have access.
-        So, Unix port is used for initial prototyping, different kinds
-        of testing, development of machine-independent features, etc.
-        All users of MicroPython, even those which are interested only
-        in running MicroPython on :term:`MCU` systems, are recommended
-        to be familiar with Unix (or Windows) port, as it is important
-        productivity helper and a part of normal MicroPython workflow.
+        The unix port is one of the major :term:`MicroPython ports
+        <MicroPython port>`. It is intended to run on POSIX-compatible
+        operating systems, like Linux, MacOS, FreeBSD, Solaris, etc. It also
+        serves as the basis of Windows port. The Unix port is very useful for
+        quick development and testing of the MicroPython language and
+        machine-independent features. It can also function in a similar way to
+        :term:`CPython`'s ``python`` executable.
+
+    .mpy file
+        The output of the :term:`cross-compiler`. A compiled form of a
+        :term:`.py file` that contains MicroPython bytecode instead of Python
+        source code.
+
+    native
+        Usually refers to "native code", i.e. machine code for the target
+        microcontroller (such as ARM Thumb, Xtensa, x86/x64). The ``@native``
+        decorator can be applied to a MicroPython function to generate native
+        code instead of bytecode for that function, which will likely be
+        faster but use more RAM.
 
     port
-        Either :term:`MicroPython port` or :term:`GPIO port`. If not clear
-        from context, it's recommended to use full specification like one
-        of the above.
+        Usually short for :term:`MicroPython port`, but could also refer to
+        :term:`GPIO port`.
+
+    .py file
+        A file containing Python source code.
+
+    REPL
+        An acronym for "Read, Eval, Print, Loop". This is the interactive
+        Python prompt, useful for debugging or testing short snippets of code.
+        Most MicroPython boards make a REPL available over a UART, and this is
+        typically accessible on a host PC via USB.
 
     stream
-        Also known as a "file-like object". An object which provides sequential
-        read-write access to the underlying data. A stream object implements
-        a corresponding interface, which consists of methods like ``read()``,
-        ``write()``, ``readinto()``, ``seek()``, ``flush()``, ``close()``, etc.
-        A stream is an important concept in MicroPython, many I/O objects
-        implement the stream interface, and thus can be used consistently and
-        interchangeably in different contexts. For more information on
-        streams in MicroPython, see `uio` module.
+        Also known as a "file-like object". An Python object which provides
+        sequential read-write access to the underlying data. A stream object
+        implements a corresponding interface, which consists of methods like
+        ``read()``, ``write()``, ``readinto()``, ``seek()``, ``flush()``,
+        ``close()``, etc. A stream is an important concept in MicroPython;
+        many I/O objects implement the stream interface, and thus can be used
+        consistently and interchangeably in different contexts. For more
+        information on streams in MicroPython, see the `uio` module.
+
+    UART
+        Acronym for "Universal Asynchronous Receiver/Transmitter". This is a
+        peripheral that sends data over a pair of pins (TX & RX). Many boards
+        include a way to make at least one of the UARTs available to a host PC
+        as a serial port over USB.
 
     upip
-        (Literally, "micro pip"). A package manage for MicroPython, inspired
-        by :term:`CPython`'s pip, but much smaller and with reduced functionality.
-        upip runs both on :term:`Unix port <MicroPython Unix port>` and on
-        :term:`baremetal` ports (those which offer filesystem and networking
-        support).
+        (Literally, "micro pip"). A package manager for MicroPython, inspired
+        by :term:`CPython`'s pip, but much smaller and with reduced
+        functionality.
+        upip runs both on the :term:`Unix port <MicroPython Unix port>` and on
+        :term:`baremetal` ports which offer filesystem and networking support.