fix typos and grammar

.github/workflows/publish.yml

@@ -8,11 +8,11 @@
 name: Publish Python Package
 
 on:
-  # trigger when publishing a release
+  # Trigger when publishing a release.
   release:
     types: [published]
 
-  # also allow triggering this workflow manually for testing
+  # Also allow triggering this workflow manually for testing.
   workflow_dispatch:
 
 jobs:
@@ -24,7 +24,7 @@ jobs:
     - name: Checkout
       uses: actions/checkout@v3
       with:
-        # just fetching 1 commit is not enough for setuptools-scm, so we fetch all
+        # Fetching a single commit is not enough for setuptools-scm, so we fetch all commits.
         fetch-depth: 0
     - name: Set up Python
       uses: actions/setup-python@v2
@@ -36,7 +36,7 @@ jobs:
     - name: Build package
       run: |
         python setup.py sdist
-        rm dist/*.orig  # clean sdist_upip noise
+        rm dist/*.orig  # Remove sdist_upip noise.
     - name: Publish to Test PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
       with:

.github/workflows/run_tests.yaml

@@ -32,7 +32,7 @@ jobs:
     - name: Build MicroPython
       id: build_micropython
       run: |
-        echo "Building micropython"
+        echo "Building MicroPython"
         git clone --depth 1 https://github.com/micropython/micropython.git
         pushd micropython/mpy-cross
         make
@@ -50,8 +50,8 @@ jobs:
     - name: Fetch binutils-esp32ulp
       id: fetch_binutils
       run: |
-        echo "Fetching URL of pre-built esp32ulp-elf binaries"
-        ## URL to pre-built binaries is published in esp-idf
+        echo "Fetching URL of prebuilt esp32ulp-elf binaries"
+        ## The URL to prebuilt binaries is published in ESP-IDF
         IDFVER=v5.0.1
         curl -s \
           -o tools.json \

AUTHORS

@@ -1,4 +1,4 @@
-E-mail addresses listed here are not intended for support.
+Email addresses listed here are not intended for support requests.
 
 micropython-esp32-ulp authors
 -----------------------------

CHANGES

@@ -1,14 +1,13 @@
-ChangeLog
+Changelog
 =========
 
-1.2.0, release 2022-03-26
+1.2.0, released 2022-03-26
 
-- project moved to micropython organization
-- project renamed from py-esp32-ulp to micropython-esp32-ulp
-- (no functional changes)
+- Project moved to the MicroPython organization.
+- Project renamed from py-esp32-ulp to micropython-esp32-ulp.
+- (No functional changes.)
 
+1.1.0, released 2021-12-03
 
-1.1.0, release 2021-12-03
-
-- first pypi release
+- First PyPI release.
 

README.rst

@@ -15,7 +15,7 @@ micropython-esp32-ulp is an assembler toolchain for the ESP32 ULP (Ultra Low-Pow
 Co-Processor, written in MicroPython.
 
 It can translate small assembly language programs to a loadable/executable
-ULP-FSM (not RISC-V) machine code binary, directly on a ESP32 microcontroller.
+ULP-FSM (not RISC-V) machine code binary, directly on an ESP32 microcontroller.
 
 This is intended as an alternative approach to assembling such programs using
 the `binutils-gdb toolchain <https://github.com/espressif/binutils-gdb/tree/esp32ulp-elf-2.35>`_
@@ -39,26 +39,26 @@ The following features are supported:
 * many ESP32 ULP code examples found on the web will work unmodified
 * a simple disassembler is also provided
 
-.. [#f1] Note: the ESP32-S2 and ESP32-S3 have the same ULP binary format between each other
-         but the binary format is different than that of the original ESP32 ULP. You need to
-         select the ``esp32s2`` cpu (`see docs </docs/index.rst>`_) when assembling code for
+.. [#f1] Note: the ESP32-S2 and ESP32-S3 have the same ULP binary format,
+         but the binary format is different from that of the original ESP32 ULP. You need to
+         select the ``esp32s2`` CPU (`see docs </docs/index.rst>`_) when assembling code for
          use on an ESP32-S2/S3.
 
 .. [#f2] Note: The ESP32-S2 and ESP32-S3 have the same ULP binary format, but the peripheral
          register addresses (those accessed with REG_RD and REG_WR) are different. For best
          results, use the correct peripheral register addresses for the specific variant you
          are working with. The assembler (when used with ``cpu=esp32s2``) will accept
          addresses for any of the 3 variants, because they are translated into relative
-         offsets anyway and many registers live at the same relative offset on all 3 variants.
-         This conveniently means that the same assembly code can assembled unmodified for each
+         offsets anyway, and many registers live at the same relative offset on all 3 variants.
+         This conveniently means that the same assembly code can be assembled unmodified for each
          variant and produce a correctly working binary - as long as only peripheral registers
          are used, which have the same relative offset across the variants. Use with care!
 
 
 Quick start
 -----------
 
-To get going run the following directly on the ESP32:
+To get going, run the following directly on the ESP32:
 
 .. code-block:: python
 
@@ -77,7 +77,7 @@ To get going run the following directly on the ESP32:
    import counter
 
 The `examples/counter.py </examples/counter.py>`_ example shows how to assemble code,
-load and run the resulting binary and exchange data between the ULP and the main CPU.
+load and run the resulting binary, and exchange data between the ULP and the main CPU.
 
 
 Documentation
@@ -88,9 +88,9 @@ See `docs/index.rst </docs/index.rst>`_.
 Requirements
 ------------
 
-The minimum supported version of MicroPython is v1.12. (For ESP32-S2 and S3
-devices, a version greater than v1.20 is required as versions before that
-did not enable the ``esp32.ULP`` class).
+The minimum supported version of MicroPython is v1.12. (For ESP32-S2 and ESP32-S3
+devices, a version greater than v1.20 is required, as earlier versions did not
+enable the ``esp32.ULP`` class).
 
 An ESP32 device is required to run the ULP machine code binary produced by
 micropython-esp32-ulp.

demo.S

@@ -27,7 +27,7 @@ textstart:  ld r0, r1, 0    # a comment!
             rsh r0, r1, 42
             move r0, r1
             move r0, 42
-            move r0, textstart  # moves abs addr of textstart to r0
+            move r0, textstart  # Move the absolute address of textstart to r0
             move r0, constant42
             stage_rst
             stage_inc 42
@@ -70,10 +70,10 @@ data1:      .space 4, 0x42
 data2:      .skip 4
 dataw:      .word 1, 2, 3, 4
 datal:      .long 1, 2, 3, 4
-datab:      .byte 1, 2, 3  # test alignment / fill up of section
+datab:      .byte 1, 2, 3  # Test alignment and fill up the section
 dataend:
 
             .bss
 bss0:       .skip 4
-bss1:       .skip 2  # test alignment / fill up of section
+bss1:       .skip 2  # Test alignment and fill up the section
 bssend:

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.

esp32_ulp/__main__.py

@@ -20,7 +20,7 @@ def main(fn, cpu):
         if sys.argv[1] in ('-c', '--mcpu'):
             cpu = sys.argv[2].lower()
             if cpu not in ('esp32', 'esp32s2'):
-                raise ValueError('Invalid cpu')
+                raise ValueError('Invalid CPU')
             filename = sys.argv[3]
     main(filename, cpu)
 

esp32_ulp/assemble.py

@@ -100,7 +100,7 @@ def __init__(self, cpu='esp32', symbols=None, bases=None, globals=None):
         elif cpu == 'esp32s2':
             opcode_module = 'opcodes_s2'
         else:
-            raise ValueError('Invalid cpu')
+            raise ValueError('Invalid CPU')
 
         relative_import = 1 if '/' in __file__ else 0
         self.opcodes = __import__(opcode_module, None, None, [], relative_import)
@@ -111,7 +111,7 @@ def __init__(self, cpu='esp32', symbols=None, bases=None, globals=None):
         # regex for parsing assembly lines
         # format: [[whitespace]label:][whitespace][opcode[whitespace arg[,arg...]]]
         # where [] means optional
-        # initialised here once, instead of compiling once per line
+        # initialized here once, instead of compiling once per line
         self.line_regex = re.compile(r'^(\s*([a-zA-Z0-9_$.]+):)?\s*((\S*)\s*(.*))$')
 
     def init(self, a_pass):

esp32_ulp/preprocess.py

@@ -55,7 +55,7 @@ def parse_define_line(self, line):
         identifier, value = parts
         tmp = identifier.split('(', 1)
         if len(tmp) == 2:
-            # skip parameterised defines (macros)
+            # skip parameterized defines (macros)
             return {}
         value = "".join(nocomment.remove_comments(value)).strip()
         return {identifier: value}
@@ -68,7 +68,7 @@ def parse_defines(self, content):
 
     def expand_defines(self, line):
         found = True
-        while found:  # do as many passed as needed, until nothing was replaced anymore
+        while found:  # do as many passes as needed, until nothing is replaced anymore
             found = False
             tokens = split_tokens(line)
             line = ""
@@ -115,8 +115,8 @@ def expand_rtc_macros(self, line):
         if macro_fn is None:
             return line
 
-        macro_args, _ = macro_args.rsplit(')', 1)  # trim away right bracket. safe as comments already stripped
-        macro_args = macro_args.split(',')  # not safe when args contain ',' but we should not have those
+        macro_args, _ = macro_args.rsplit(')', 1)  # trim away the right bracket; safe as comments are already stripped
+        macro_args = macro_args.split(',')  # not safe when args contain ','; we should not have those
         macro_args = [x.strip() for x in macro_args]
 
         return macro_fn(*macro_args)