Update docs, increase max analogWriteFreq to 1MHz (#551)

Author: earlephilhower

cores/rp2040/wiring_analog.cpp

@@ -27,7 +27,7 @@
 #include <hardware/adc.h>
 
 static uint32_t analogScale = 255;
-static uint16_t analogFreq = 1000;
+static uint32_t analogFreq = 1000;
 static bool pwmInitted = false;
 static bool adcInitted = false;
 static uint16_t analogWritePseudoScale = 1;
@@ -42,9 +42,9 @@ extern "C" void analogWriteFreq(uint32_t freq) {
     if (freq < 100) {
         DEBUGCORE("ERROR: analogWriteFreq too low (%d)\n", freq);
         analogFreq = 100;
-    } else if (freq > 60000) {
+    } else if (freq > 1000000) {
         DEBUGCORE("ERROR: analogWriteFreq too high (%d)\n", freq);
-        analogFreq = 60000;
+        analogFreq = 1000000;
     } else {
         analogFreq = freq;
     }

docs/analog.rst

@@ -30,10 +30,21 @@ While up to 16 PWM channels can be generated, they are not independent
 and there are significant restrictions as to allowed pins in parallel.
 See the `RP2040 datasheet <https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf>`_ for full details.
 
+Analog Output Restrictions
+--------------------------
+
+The PWM generator source clock restricts the legal combinations of
+frequency and ranges.  For example, at 1MHz only about 6 bits of range
+are possible.  When you define an ``analogWriteFreq`` and ``analogWriteRange``
+that can't be fulfilled by the hardware, the frequency will be preserved
+but the accuracy (range) will be reduced automatically.  Your code will
+still send in the range you specify, but the core itself will transparently
+map it into the allowable PWN range.
+
 void analogWriteFreq(uint32_t freq)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Sets the master PWM frequency used (i.e. how often the PWM output cycles).
-From 100Hz to 60KHz are supported.
+From 100Hz to 1MHz are supported.
 
 void analogWriteRange(uint32_t range) and analogWriteResolution(int res)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/freertos.rst

@@ -2,14 +2,23 @@ FreeRTOS
 ========
 
 The SMP port of FreeRTOS is included with the core.  This allows complex task operations
-and real preemptive multithreading in your sketches.  To enable FreeRTOS, simply add
+and real preemptive multithreading in your sketches.  While the ``setup1`` and ``loop1``
+way of multitasking is simplest for most folks, FreeRTOS is much more powerful.
+
+Enabling FreeRTOS
+-----------------
+
+To enable FreeRTOS, simply add
 
 .. code:: c++
 
     #include <FreeRTOS.h>
 
 to your sketch and it will be included and enabled automatically.
 
+Configuration and Predefined Tasks
+----------------------------------
+
 FreeRTOS is configured with 8 priority levels (0 through 7) and a process for
 ``setup()/loop()``, ``setup1()/loop1()``, and the USB port will be created.  The task
 quantum is 1 millisecond (i.e. 1,000 switches per second).
@@ -19,8 +28,21 @@ only run in core 1 in this mode, the same as the default multithreading mode.
 
 You can launch and manage additional processes using the standard FreeRTOS routines.
 
-
 ``delay()`` and ``yield()`` free the CPU for other tasks, while ``delayMicroseconds()`` does not.
 
+Caveats
+-------
+
+While the core now supports FreeRTOS, most (probably all) Arduino libraries were not written
+to support preemptive multithreading.  This means that all calls to a particular library should
+be made from a single task.
+
+In particular, the ``LittleFS`` and ``SDFS`` libraries can not be called from different
+threads.  Do all ``File`` operations from a single thread or else undefined behavior
+(aka strange crashes or data corruption) can occur.
+
+More Information
+----------------
+
 For full FreeRTOS documentation look at `FreeRTOS.org <https://freertos.org/index.html>`__
 and `FreeRTOS SMP support <https://freertos.org/symmetric-multiprocessing-introduction.html>`__.