update - see revision.md

Author: duff2013

README.md

@@ -1,14 +1,16 @@
-ulptool v2.4.0
+ulptool v2.4.1
 ==================
-This guide explains how to setup Arduino to use ULP coprocessor assembly files for your esp32 projects. This guide assumes you installed the esp32 core with the preferred method of the board manager.
+Now Arduino can program the ULP coprocessor for your esp32 projects. The guide below assumes you installed the esp32 core with the preferred method using the board manager.
 
-Typically in Arduino you can compile assembly files using the '.S' extension. Using the ESP32 Arduino core framework these files would correspond to the Xtensa processors whose toolchain is incompatible with the ULP coprocessor. Luckily, Arduino provides a fairly easy albeit not that flexible build framework using series of recipes. This guide extends those esp32 recipes for building the ULP assembly files. We will use the '.s' extensions for ULP assembly files which Arduino will let you create. Remember thats a lower case 's'. I tried to keep the ulp build process the same as the esp-if framework with only a few small modifications the user needs to do in order to compile in Arduino.
+Typically in Arduino you can compile assembly files using the '.S' extension. Using the ESP32 Arduino core framework these files would correspond to the Xtensa processors whose toolchain is incompatible with the ULP coprocessor. Luckily, Arduino provides a fairly easy series of recipes for building the ULP assembly files by using the '.s' extension which Arduino will let you create. Take note, the extension is a lower case **s**. In tring to keep the ulp build process the same as the esp-idf framework only a few small modifications are needed to the esp32 Arduino installation.
 
-New experimental c compiler (lcc) for the ulp implemented by Jason Fuller included now. Currently only Mac and Linux have been built but hopefully we will have Windows soon. There are many limitations and those can found at his github page here: https://github.com/jasonful/lcc
+A new experimental c compiler (lcc) for the ulp implemented by Jason Fuller is included now. Currently only Mac and Linux have been built but hopefully I'll have Windows soon:) There are many limitations and those can found at his github page here: https://github.com/jasonful/lcc
 Examples can be found in the ulp_examples/ulpcc folder.
 
+Note - platform.local.txt version does not follow ulptool version.
+
 Manual Setup Steps:
-============
+==================
 1. Download the latest release of this repository and unpack-> https://github.com/duff2013/ulptool/releases/latest
 delete the release version number so the folder is just called 'ulptool'
 
@@ -22,19 +24,19 @@ delete the release version number so the folder is just called 'ulptool'
 
             Typically (Linux) -> ~/.arduino15/packages/esp32
 
-4. Move the **ulptool** folder you downloaded and unpacked to the tools folder here -> **.../esp32/tools/**.
+4. Move the **ulptool** folder you downloaded and unpacked to the tools folder here -> **... /esp32/tools/ulptool/**.
 
 5. Copy the 'platform.local.txt' file to **... /esp32/hardware/esp32/1.0.0/**. Remember **1.0.0** has to match your esp32 core version.
 
-6. In the **ulptool** release you downloaded, move or copy the **... /esp32/tools/ulptool/src/ulp_examples** folder to where Arduino saves your sketches.
+6. In the **ulptool** folder, move or copy the **... /ulptool/src/ulp_examples** folder to where Arduino saves your sketches.
 
-7. Move **esp32ulp-elf-binutils** folder you downloaded and unpacked to -> **... /esp32/tools/ulptool/src/**.
+7. Move **esp32ulp-elf-binutils** folder you downloaded and unpacked to -> **... /esp32/tools/ulptool/src/esp32ulp-elf-binutils/**.
 
-Thats it, you now have all the files in place, lets look at very simple example to get you compiling ulp assembly code!
+That's it, you now have all the files in place, lets look at very simple example to get you compiling ulp assembly code!
 
-Example:
-========
-Open a blank Arduino sketch and copy and paste the code below into the that sketch.
+Assembly Example:
+-----------------
+Open a blank Arduino sketch and copy and paste the code below into that sketch.
 ```
 #include "esp32/ulp.h"// Must have this!!!
 
@@ -73,7 +75,7 @@ static void init_run_ulp(uint32_t usec) {
 }
 ```
 
-Create a new tab named <b>ulp.s</b>, take notice that the extension is a lower case 's'. Copy the code below into that ulp assembly file tab.
+Create a new tab named <b>ulp.s</b>, take notice that the extension is a lower case **s**. Copy the code below into the ulp assembly file you just created.
 ```
 /* Define variables, which go into .bss section (zero-initialized data) */
     .bss
@@ -93,7 +95,7 @@ entry:
     halt
 ```
 
-Create a new tab named <b>ulp_main.h</b>. This header allows your sketch to see global variables whose memory is allocated in your ulp assembly file. This memory is in the SLOW RTC section. Copy the code below into that header file. As with the esp-idf you have to add 'ulp_' to the front of the variable name. Unlike esp-idf the name of this header is always this name.
+Create a new tab named <b>ulp_main.h</b>. This header allows your sketch to see global variables whose memory is allocated in your ulp assembly file. This memory is from the SLOW RTC section. Copy the code below into the header file. As with the esp-idf you have to add 'ulp_' to the front of the variable name. Unlike esp-idf the name of this header is always **ulp_main.h**.
 ```
 /*
     Put your ULP globals here you want visibility
@@ -106,9 +108,9 @@ extern uint32_t ulp_entry;
 extern uint32_t ulp_count;
 ```
 
-Compile and run and you should see the variable 'ulp_count' increment every 100 msecs.
+Upload the code then open your serial monitor, you should see the variable 'ulp_count' increment every 100 msecs.
 
-ULPCC Examples:
+ULPCC Example:
 ---------------
 Open a blank Arduino sketch and copy and paste the code below into the that sketch. This is basically the same as the example above but written in c:)
 ```
@@ -167,7 +169,7 @@ void entry() {
 #endif // do not add code after here
 ```
 
-Create a new tab named <b>ulp_main.h</b>. This header allows your sketch to see global variables whose memory is allocated in your ulp c file. This memory is in the SLOW RTC section. Copy the code below into that header file. As with the esp-idf you have to add 'ulp_' to the front of the variable name. Unlike esp-idf the name of this header is always this name.
+Create a new tab named <b>ulp_main.h</b>. This header allows your sketch to see global variables whose memory is allocated in your ulp assembly file. This memory is from the SLOW RTC section. Copy the code below into the header file. As with the esp-idf you have to add 'ulp_' to the front of the variable name. Unlike esp-idf the name of this header is always **ulp_main.h**.
 ```
 /*
     Put your ULP globals here you want visibility
@@ -181,11 +183,11 @@ extern uint32_t ulp_entry;
 extern uint32_t ulp_counter;
 ```
 
-Compile and run and you should see the variable 'ulp_counter' increment every 100 msecs.
+Upload the code then open your serial monitor, you should see the variable 'ulp_counter' increment every 100 msecs.
 
 Under the Hood:
 ===============
-All the magic happens in the python script called esp32ulp_build_recipe.py. This along with espressif's esp32ulp_mapgen.py in which both are located in the ulp directory from this repository.
+All the magic happens in the python script called esp32ulp_build_recipe.py along with espressif's esp32ulp_mapgen.py script.
 
 Limitations:
 ============

revisions.md

@@ -1,3 +1,8 @@
+><b>Updated (8/20/19 v2.4.1)</b><br>
+* Added lcc copyright file.<br>
+* Fix grammar and spelling of README.md.<br>
+* Fix lcc examples.<br>
+
 ><b>Updated (7/14/19 v2.4.0)</b><br>
 * Added support for ulpcc c compiler :)<br>
 * Cleaned up code.<br>

src/esp32ulp_build_recipe.py

@@ -16,7 +16,7 @@
 #   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 #   DEALINGS IN THE SOFTWARE.
 
-# version 2.4.0
+# version 2.4.1
 import os
 import re
 import sys

src/ulp_examples/ulpcc/ulpcc_adc/adc.c

@@ -1,9 +1,4 @@
-/*
- * do not add code above here all 
- * ulp c code must be between this 
- * ifdef.
- */
-#ifdef _ULPCC_
+#ifdef _ULPCC_ // do not add code above this line
 // must include ulpcc helper functions
 #include <ulp_c.h>
 #include "common.h"
@@ -15,18 +10,20 @@
 unsigned threshold;
 /*
  * esp32 main processor can reach this variable.
- * It is used to signal that a result is ready.
+ * It is used to signal that a result is ready
+ * and when the main processor read the value.
  */
 unsigned mutex = 0;
 
 // # of samples
 unsigned sample_counter = 0;
-/* 
- * ulp registers are only 32 bits but
- * can only hold 16 bits of data so we
- * use sum_hi and sum_lo to hold 32 bits 
+/*
+ * ulp registers are 32 bits but can
+ * only hold 16 bits of data. We use
+ * sum_hi (upper 16-bits) and sum_lo
+ * (lower 16-bits) to hold 32 bits
  * of data. The averaged data is computed
- * from sum_hi and sum_lo.
+ * from this proto 32-bit number.
  */
 unsigned sum_lo = 0;
 unsigned sum_hi = 0;
@@ -36,7 +33,7 @@ void entry() {
   unsigned tmp = 0, i = 0;
   sum_hi = 0;
   sum_lo = 0;
-  // # of adc samples set by the adc_oversampling_factor in common.h
+  // avg routine
   for (i = 0; i < adc_oversampling_factor; i++) {
     // get adc reading
     tmp = adc(0, adc_channel + 1);

src/ulp_examples/ulpcc/ulpcc_adc/ulpcc_adc.ino

@@ -31,7 +31,6 @@ void loop() {
                   adc_oversampling_factor,
                   ulp_adc_avg_result & 0xffff
                  );
-    //Serial.printf("%i\n", ulp_result & 0xffff);
     Serial.flush();
     // tell ulp we are done reading result
     ulp_mutex = false;
@@ -46,8 +45,8 @@ static void init_run_ulp(uint32_t usec) {
   //rtc_gpio_hold_en(GPIO_NUM_15);
   ulp_set_wakeup_period(0, usec);
   esp_err_t err = ulptool_load_binary(0, ulp_main_bin_start, (ulp_main_bin_end - ulp_main_bin_start) / sizeof(uint32_t));
-  // all shared ulp variables have to inialize after ulptool_load_binary for the ulp to see it.
-  // Set the high threshold you want the ulp to trigger a main processor wakeup
+  // all shared ulp variables have to be intialized after ulptool_load_binary for the ulp to see it.
+  // Set the high threshold reading you want the ulp to trigger a main processor wakeup.
   ulp_threshold = 0x20;
   err = ulp_run((&ulp_entry - RTC_SLOW_MEM) / sizeof(uint32_t));
   if (err) Serial.println("Error Starting ULP Coprocessor");

src/ulp_examples/ulpcc/ulpcc_counter/ulp_counter.c

@@ -1,9 +1,4 @@
-/*
- * do not add code above here all 
- * ulp c code must be between this 
- * ifdef.
- */
-#ifdef _ULPCC_
+#ifdef _ULPCC_ // do not add code above this line
 // must include ulpcc helper functions
 #include <ulp_c.h>
 

src/ulpcc/CPYRIGHT

@@ -0,0 +1,60 @@
+The authors of this software are Christopher W. Fraser and
+David R. Hanson.
+
+Copyright (c) 1991,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002
+by AT&T, Christopher W. Fraser, and David R. Hanson. All Rights Reserved.
+
+Permission to use, copy, modify, and distribute this software for any
+purpose, subject to the provisions described below, without fee is
+hereby granted, provided that this entire notice is included in all
+copies of any software that is or includes a copy or modification of
+this software and in all copies of the supporting documentation for
+such software.
+
+THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTY. IN PARTICULAR, NEITHER THE AUTHORS NOR AT&T MAKE ANY
+REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
+OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
+
+lcc is not public-domain software, shareware, and it is not protected
+by a `copyleft' agreement, like the code from the Free Software
+Foundation.
+
+lcc is available free for your personal research and instructional use
+under the `fair use' provisions of the copyright law. You may, however,
+redistribute lcc in whole or in part provided you acknowledge its
+source and include this CPYRIGHT file. You may, for example, include
+the distribution in a CDROM of free software, provided you charge only
+for the media, or mirror the distribution files at your site.
+
+You may not sell lcc or any product derived from it in which it is a
+significant part of the value of the product. Using the lcc front end
+to build a C syntax checker is an example of this kind of product.
+
+You may use parts of lcc in products as long as you charge for only
+those components that are entirely your own and you acknowledge the use
+of lcc clearly in all product documentation and distribution media. You
+must state clearly that your product uses or is based on parts of lcc
+and that lcc is available free of charge. You must also request that
+bug reports on your product be reported to you. Using the lcc front
+end to build a C compiler for the Motorola 88000 chip and charging for
+and distributing only the 88000 code generator is an example of this
+kind of product.
+
+Using parts of lcc in other products is more problematic. For example,
+using parts of lcc in a C++ compiler could save substantial time and
+effort and therefore contribute significantly to the profitability of
+the product. This kind of use, or any use where others stand to make a
+profit from what is primarily our work, requires a license agreement
+with Addison-Wesley.  Per-copy and unlimited use licenses are
+available; for more information, contact
+
+   Kim Boedigheimer
+   Addison Wesley
+   75 Arlington St., Suite 300
+   Boston, MA 02116
+   617/848-6559 kim.boedigheimer@pearsoned.com
+-----
+Chris Fraser / cwf@aya.yale.edu
+David Hanson / drh@drhanson.net
+$Revision$ $Date$