docs: fix typos, grammar, punctuation

Author: ThomasWaldmann

docs/disassembler.rst

@@ -42,7 +42,7 @@ Disassembling a file
 The simplest and default mode of the disassembler is to disassemble the
 specified file.
 
-Note that the ULP header is validates and files with unknown magic bytes will be
+Note that the ULP header is validated and files with unknown magic bytes will be
 rejected. The correct 4 magic bytes at the start of a ULP binary are ``ulp\x00``.
 
 Example disassembling an ESP32 ULP binary:
@@ -75,13 +75,13 @@ Example disassembling an ESP32-S2 ULP binary:
 Disassembling a byte sequence
 -----------------------------
 
-The ``-m`` option allows disassembling a sequences hex letters representing
+The ``-m`` option allows disassembling a sequence of hex letters representing
 ULP instructions.
 
 This option expects the actual instructions directly, without any ULP header.
 
 The sequence must contain a number of hex letters exactly divisible by 8, i.e.
-8, 16, 24, etc, because each 32-bit word is made up of 8 hex letters. Spaces
+8, 16, 24, etc., because each 32-bit word is made up of 8 hex letters. Spaces
 can be included in the sequence and they are ignored.
 
 The typical use case for this feature is to copy/paste some instructions from
@@ -148,11 +148,11 @@ The disassembler also works when used on an ESP32 device.
 
 To use the disassembler on a real device:
 
-* ensure ``micropython-esp32-ulp`` is installed on the device (see `docs/index.rst </docs/index.rst>`_).
-* upload ``tools/disassemble.py`` ``tools/decode.py`` and ``tools/decode_s2.py`` to the device
+* Ensure ``micropython-esp32-ulp`` is installed on the device (see `docs/index.rst </docs/index.rst>`_).
+* Upload ``tools/disassemble.py``, ``tools/decode.py``, and ``tools/decode_s2.py`` to the device
   (any directory will do, as long as those 3 files are in the same directory)
-* the following example code assumes you placed the 3 files into the device's "root" directory
-* run the following (note, we must specify which the cpu the binary is for):
+* The following example code assumes you placed the 3 files into the device's "root" directory
+* Run the following (note, we must specify which CPU the binary is for):
 
   .. code-block:: python
 

docs/index.rst

@@ -37,7 +37,7 @@ On the ESP32
 ++++++++++++
 
 The simplest example to try on the ESP32 is `counter.py </examples/counter.py>`_.
-It shows how to assemble code, load and run the resulting binary and exchange
+It shows how to assemble code, load and run the resulting binary, and exchange
 data between the ULP and the main CPU.
 
 Run the ``counter.py`` example:
@@ -65,7 +65,7 @@ follows:
    micropython -m esp32_ulp path/to/code.S  # this results in path/to/code.ulp
 
 The assembler supports selecting a CPU to assemble for using the ``-c`` option
-(valid cpu's are ``esp32`` and ``esp32s2``):
+(valid CPUs are ``esp32`` and ``esp32s2``):
 
 .. code-block:: shell
 
@@ -91,7 +91,7 @@ This can be useful in battery-powered applications where every second of sleep
 time matters.
 
 Splitting the assembly and load stage can be combined with other techniques,
-for example to implement a caching mechansim for the ULP binary that
+for example, to implement a caching mechanism for the ULP binary that
 automatically updates the binary every time the assembly source code changes.
 
 The ``esp32_ulp.assemble_file`` function can be used to assemble and link an
@@ -128,7 +128,7 @@ That file can then be loaded directly without assembling the source again.
           # start the ULP
           # assemble_file printed offsets in number of 32-bit words.
           # ulp.run() expects an offset in number of bytes.
-          # Thus, multiply the offset to our entry point by 4.
+          # Thus, multiply the offset of our entry point by 4.
           # e.g. for an offset of 2:
           #   2 words * 4 = 8 bytes
           ulp.run(2*4)  # specify the offset of the entry point label
@@ -173,14 +173,14 @@ Testing
 -------
 
 There are unit tests and also compatibility tests that check whether the binary
-output is identical with what Espressif's esp32-elf-as (from their `binutils-gdb fork
+output is identical to what Espressif's esp32-elf-as (from their `binutils-gdb fork
 <https://github.com/espressif/binutils-gdb/tree/esp32ulp-elf-2.35>`_) produces.
 
 micropython-esp32-ulp has been tested on the Unix port of MicroPython and on real ESP32
 devices with the chip type ESP32D0WDQ6 (revision 1) without SPIRAM as well as ESP32-S2
 (ESP32-S2FH4) and ESP32-S3 (ESP32-S3R8) devices.
 
-Consult the Github Actions `workflow definition file </.github/workflows/run_tests.yaml>`_
+Consult the GitHub Actions `workflow definition file </.github/workflows/run_tests.yaml>`_
 for how to run the different tests.
 
 

docs/preprocess.rst

@@ -11,7 +11,7 @@ provided by the ESP-IDF framework, along with constants defined in the
 framework's include files (such as ``RTC_GPIO_IN_REG``), to make reading
 and writing from/to peripheral registers much easier.
 
-In order to do this the preprocessor has two capabilities:
+In order to do this, the preprocessor has two capabilities:
 
 1. Parse and replace identifiers defined with ``#define``
 2. Recognise the ``WRITE_RTC_*`` and ``READ_RTC_*`` macros and expand
@@ -21,7 +21,7 @@ In order to do this the preprocessor has two capabilities:
 Usage
 ------------------------
 
-Normally the assembler is called as follows
+Normally the assembler is called as follows:
 
 .. code-block:: python
 
@@ -49,8 +49,8 @@ Using a "Defines Database"
 Because the micropython-esp32-ulp assembler was built for running on the ESP32
 microcontroller with limited RAM, the preprocessor aims to work there too.
 
-To handle large number of defined constants (such as the ``RTC_*`` constants from
-the ESP-IDF) the preprocessor can use a database (based on BerkleyDB) stored on the
+To handle a large number of defined constants (such as the ``RTC_*`` constants from
+the ESP-IDF) the preprocessor can use a database (based on Berkeley DB) stored on the
 device's filesystem for looking up defines.
 
 The database needs to be populated before preprocessing. (Usually, when only using
@@ -67,7 +67,7 @@ are not needed on the device either.)
    database from include files. The resulting file will be called
    ``defines.db``.
 
-   (The following assume running on a PC. To do this on device, refer to the
+   (The following assumes running on a PC. To do this on device, refer to the
    `esp32_ulp/parse_to_db.py <../esp32_ulp/parse_to_db.py>`_ file.)
 
    .. code-block:: bash
@@ -83,22 +83,22 @@ are not needed on the device either.)
 
       # if file system space is not a concern, the following can be convenient
       # by including all relevant include files from the ESP-IDF framework.
-      # This results in an approximately 2MB large database.
+      # This results in an approximately 2 MB large database.
       micropython -m esp32_ulp.parse_to_db \
         esp-idf/components/soc/esp32/include/soc/*.h \
         esp-idf/components/esp_common/include/*.h
 
       # most ULP code uses only 5 include files. Parsing only those into the
       # database should thus allow assembling virtually all ULP code one would
       # find or want to write.
-      # This results in an approximately 250kB large database.
+      # This results in an approximately 250 kB large database.
       micropython -m esp32_ulp.parse_to_db \
         esp-idf/components/soc/esp32/include/soc/{soc,soc_ulp,rtc_cntl_reg,rtc_io_reg,sens_reg}.h
 
 
    .. warning::
 
-      `:warning:` Ensure that you include the header files for the correct
+      Ensure that you include the header files for the correct
       variant you are working with. In the example code above, simply switch
       ``esp32`` to ``esp32s2`` or ``esp32s3`` in the path to the include files.
 
@@ -118,7 +118,7 @@ are not needed on the device either.)
    is taken not to create an empty database file, cluttering up the filesystem,
    when not needed).
 
-   If you do not want the preprocessor use use a DefinesDB, pass ``False`` to
+   If you do not want the preprocessor to use a DefinesDB, pass ``False`` to
    the ``use_defines_db`` argument of the ``preprocess`` convenience function,
    or instantiate the ``Preprocessor`` class directly, without passing it a
    DefinesDB instance via ``use_db``.
@@ -129,7 +129,7 @@ Design choices
 
 The preprocessor does not support:
 
-1. Function style macros such as :code:`#define f(a,b) (a+b)`
+1. Function-style macros such as :code:`#define f(a,b) (a+b)`
 
    This is not important, because there are only few RTC macros that need
    to be supported and they are simply implemented as Python functions.