From dc016769feef43efa8a691b6f739e60ffd69e9d6 Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Mon, 16 Oct 2023 12:15:42 -0700 Subject: [PATCH] Add back glossary to fix docs build --- conf.py | 3 +- docs/index.rst | 1 + docs/reference/glossary.rst | 212 ++++++++++++++++++++++++++++++++++++ 3 files changed, 215 insertions(+), 1 deletion(-) create mode 100644 docs/reference/glossary.rst diff --git a/conf.py b/conf.py index efcd455e01..11a589dd3b 100644 --- a/conf.py +++ b/conf.py @@ -202,7 +202,8 @@ exclude_patterns = ["**/build*", "ports/cxd56/spresense-exported-sdk", "ports/espressif/certificates", "ports/espressif/esp-idf", - "ports/espressif/esp32-camera", + "ports/espressif/esp-camera", + "ports/espressif/esp-protocols", "ports/espressif/.idf_tools", "ports/espressif/peripherals", "ports/litex/hw", diff --git a/docs/index.rst b/docs/index.rst index 5bc2034aa2..6d73b1837a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,6 +33,7 @@ Full Table of Contents design_guide porting common_hal + reference/glossary.rst .. toctree:: :maxdepth: 2 diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst new file mode 100644 index 0000000000..6ec613a315 --- /dev/null +++ b/docs/reference/glossary.rst @@ -0,0 +1,212 @@ +Glossary +======== + +.. glossary:: + + baremetal + A system without a (full-fledged) operating system, for example an + :term:`MCU`-based system. When running on a baremetal system, + 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 + Typically this refers to a printed circuit board (PCB) containing a + :term:`microcontroller ` 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 + 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 + `_. + + CPython + 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 :term:`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 (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). + + 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 + 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 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`'s. Instead, there is a related, + but separate project `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:`mip`. + + MicroPython port + MicroPython supports different :term:`boards `, 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 + The unix port is one of the major :term:`MicroPython ports + `. 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. + + mip + A package installer for MicroPython (mip - "mip installs packages"). It + installs MicroPython packages either from :term:`micropython-lib`, + GitHub, or arbitrary URLs. mip can be used on-device on + network-capable boards, and internally by tools such + as :term:`mpremote`. + + mpremote + A tool for interacting with a MicroPython device. + + .mpy file + The output of the :term:`cross-compiler`. A compiled form of a + :term:`.py file` that contains MicroPython :term:`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 :term:`bytecode` for that function, which will likely be + faster but use more RAM. + + port + 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". A 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 `io` 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 + A now-obsolete package manager for MicroPython, inspired + by :term:`CPython`'s pip, but much smaller and with reduced + functionality. See its replacement, :term:`mip`. + + webrepl + A way of connecting to the REPL (and transferring files) on a device + over the internet from a browser. See https://micropython.org/webrepl