Added the simppru documentation

index.rst

@@ -28,6 +28,13 @@ Sections
    pocketbeagle/index.rst
    beaglebone-blue/index.rst
 
+.. toctree::
+   :maxdepth: 1
+   :caption: simpPRU
+
+   simppru/index.rst
+   simppru-examples/index.rst
+
 Indices and tables
 ############################
 

simppru-examples/button_click_rpmsg.rst

+Sending state of button using RPMSG
+===================================
+
+!!! info “Schematic” === “Pocket Beagle” |image0|
+
+::
+
+   === "BeagleBone Black / Beagle Bone Black Wireless"
+       ![](images/led_button_beagle_bone_black.png)   
+
+Code
+----
+
+.. code:: python
+
+   init_message_channel();
+
+   while : true {
+       if : digital_read(P1_29) {
+           send_message(1);
+       }
+       else {
+           send_message(0);
+       }
+       delay(100);
+   }
+
+-  Following code works on PocketBeagle, to use on other boards, please
+   change the pins accordingly.
+
+Explaination
+------------
+
+``init_message_channel`` is needed to setup communication channel
+between ARM<->PRU. It only needs to be called once, before using RPMSG
+functions.
+
+``while : true`` loop runs endlessly, inside this, we check for value of
+header pin P1_29, if it reads HIGH, 1 is sent to the ARM core using
+``send_message`` and if it is LOW, 0 is sent to ARM core using
+``send_message``. Then PRU waits for 100ms, and repeats the steps again
+and again.
+
+.. |image0| image:: images/led_button_pocket_beagle.png
\ No newline at end of file

simppru-examples/delay.rst

+Delay example
+=============
+
+!!! info “Schematic” === “Pocket Beagle” |image0|
+
+::
+
+   === "BeagleBone Black / Beagle Bone Black Wireless"
+       ![](images/led_beagle_bone_black.png)   
+
+Code
+----
+
+.. code:: python
+
+   digital_write(P1_31, true);
+   delay(2000);
+   digital_write(P1_31, false);
+   delay(5000);
+   digital_write(P1_31, true);
+
+-  Following code works on PocketBeagle, to use on other boards, please
+   change the pins accordingly.
+
+Explaination
+------------
+
+This code snippet writes HIGH to header pin P1_31, then waits for 2000ms
+using the ``delay`` call, after that it writes LOW to header pin P1_31,
+then again waits for 5000ms using the ``delay`` call, and finally writes
+HIGH to header pin P1_31.
+
+.. |image0| image:: images/led_pocket_beagle.png
\ No newline at end of file

simppru-examples/digital_read.rst

+Digital read example
+====================
+
+!!! info “Schematic” === “Pocket Beagle” |image0|
+
+::
+
+   === "BeagleBone Black / Beagle Bone Black Wireless"
+       ![](images/led_button_beagle_bone_black.png)   
+
+Code
+----
+
+.. code:: python
+
+   while : true {
+       if : digital_read(P1_29) {
+           digital_write(P1_31, false);
+       }
+       else {
+           digital_write(P1_31, true);
+       }
+   }
+
+-  Following code works on PocketBeagle, to use on other boards, please
+   change the pins accordingly.
+
+Explaination
+------------
+
+This code runs a never ending loop, since it is ``while : true``. Inside
+``while`` it checks if header pin P1_29 is HIGH or LOW. If header pin
+P1_29 is HIGH, header pin P1_31 is set to LOW, and if header pin P1_29
+is LOW, header pin P1_31 is set to HIGH.
+
+.. |image0| image:: images/led_button_pocket_beagle.png
\ No newline at end of file

simppru-examples/digital_write.rst

+Digital write example
+=====================
+
+!!! info “Schematic” === “Pocket Beagle” |image0|
+
+::
+
+   === "BeagleBone Black / Beagle Bone Black Wireless"
+      ![](images/led_button_beagle_bone_black.png)
+
+Code
+----
+
+.. code:: python
+
+   while : true {
+       digital_write(P1_31, true);
+   }
+
+-  Following code works on PocketBeagle, to use on other boards, please
+   change the pins accordingly.
+
+Explaination
+------------
+
+This code runs a never ending loop, since it is ``while : true``. Inside
+``while`` it sets header pin P1_31 to HIGH.
+
+.. |image0| image:: images/led_pocket_beagle.png

simppru-examples/hcsr04_example_rpmsg.rst

+HCSR04 Distance Sensor example (sending distance data to ARM using RPMSG)
+=========================================================================
+
+!!! info “Schematic” === “Pocket Beagle” |image0|
+
+::
+
+   === "BeagleBone Black / Beagle Bone Black Wireless"
+       ![](images/hcsr04_beagle_bone_black.png)   
+
+Code
+----
+
+.. code:: python
+
+   def measure : int : {
+       bool timeout := false;
+       int echo := -1;
+
+       start_counter();
+       
+       while : read_counter() <= 2000 {
+           digital_write(5, true);
+       }
+       digital_write(5, false);
+       stop_counter();
+
+       start_counter();
+       while : not (digital_read(6)) and true {
+           if : read_counter() > 200000000 {
+               timeout := true;
+               break;
+           }
+       }   
+       stop_counter();
+       
+       if : not(timeout) and true {
+           start_counter();
+           while : digital_read(6) and true {
+               if : read_counter() > 200000000 {
+                   timeout := true;
+                   break;
+               }
+               echo := read_counter();
+           }
+           stop_counter();
+       }
+       
+       if : timeout and true {
+           echo := 0;
+       } 
+
+       return echo;
+   }
+
+   init_message_channel();
+
+   while : true {
+       int ping:= measure();
+
+       send_message(ping);
+       delay(1000);
+   }
+
+-  Following code works on PocketBeagle, to use on other boards, please
+   change the pins accordingly.
+
+Explaination
+------------
+
+.. |image0| image:: images/hcsr04_pocket_beagle.png

simppru-examples/hcsr04_sensor.rst

+Ultrasonic range sensor example
+===============================
+
+!!! info “Schematic” === “Pocket Beagle” |image0|
+
+::
+
+   === "BeagleBone Black / Beagle Bone Black Wireless"
+       ![](images/hcsr04_beagle_bone_black.png)   
+
+Code
+----
+
+.. code:: python
+
+   def measure : int : {
+       bool timeout := false;
+       int echo := 0;
+
+       start_counter();
+       
+       while : read_counter() <= 2000 {
+           digital_write(7, true);
+       }
+       digital_write(7, false);
+       stop_counter();
+
+       start_counter();
+       while : not (digital_read(1)) and true {
+           if : read_counter() > 200000000 {
+               timeout := true;
+               break;
+           }
+       }   
+       stop_counter();
+       
+       if : not(timeout) and true {
+           start_counter();
+           while : digital_read(1) and true {
+               if : read_counter() > 200000000 {
+                   timeout := true;
+                   break;
+               }
+               echo := read_counter();
+           }
+           stop_counter();
+       }
+       
+       if : timeout and true {
+           echo := 0;
+       } 
+
+       return echo;
+   }
+
+   while : true {
+       int ping:= measure()*1000;
+
+       if : ping > 292200 {
+           digital_write(4, false);
+       }
+       else
+       {
+           digital_write(4, true);
+       }
+       delay(1000);
+   }
+
+-  Following code works on PocketBeagle, to use on other boards, please
+   change the pins accordingly.
+
+Explaination
+------------
+
+.. |image0| image:: images/hcsr04_pocket_beagle.png

simppru-examples/index.rst

+Welcome to simpPRU Docs
+##############
+
+The PRU is a dual core micro-controller system present on the AM335x SoC
+which powers the BeagleBone. It is meant to be used for high speed
+jitter free IO control. Being independent from the linux scheduler and
+having direct access to the IO pins of the BeagleBone Black, the PRU is
+ideal for offloading IO intensive tasks.
+
+Programming the PRU is a uphill task for a beginner, since it involves
+several steps, writing the firmware for the PRU, writing a loader
+program. This can be a easy task for a experienced developer, but it
+keeps many creative developers away. So, I propose to implement a easy
+to understand language for the PRU, hiding away all the low level stuff
+and providing a clean interface to program PRU.
+
+This can be achieved by implementing a language on top of PRU C. It will
+directly compile down to PRU C. This could also be solved by
+implementing a bytecode engine on the PRU, but this will result in waste
+of already limited resources on PRU. With this approach, both PRU cores
+can be run independent of each other.
+
+.. image:: images/simpPRU.png
+   :width: 398
+   :align: center
+   :height: 200
+   :alt: simpPRU
+
+
+What is simpPRU
+---------------
+
+-  simpPRU is a procedural programming language.
+-  It is a statically typed language. Variables and functions must be
+   assigned data types during compilation.
+-  It is typesafe, and data types of variables are decided during
+   compilation.
+-  simPRU codes have a ``.sim`` extension.
+-  simpPRU provides a console app to use Remoteproc functionality.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   build.rst
+   install.rst
+   language.rst
+   io.rst
+   usage-simppru.rst
+   usage-simppru-console.rst
+
+   
+

simppru-examples/led_blink.rst

+LED blink example
+=================
+
+!!! info “Schematic” === “Pocket Beagle” |image0|
+
+::
+
+   === "BeagleBone Black / Beagle Bone Black Wireless"
+       ![](images/led_beagle_bone_black.png)
+
+Code
+----
+
+.. code:: python
+
+   while : 1 == 1 {
+       digital_write(P1_31, true);
+       delay(1000);
+       digital_write(P1_31, false);
+       delay(1000);
+   }
+
+-  Following code works on PocketBeagle, to use on other boards, please
+   change the pins accordingly.
+
+Explaination
+------------
+
+This code runs a never ending loop, since it is ``while : true``. Inside
+``while`` it sets header pin P1_31 to HIGH, waits for 1000ms, then sets
+header pin P1_31 to LOW, then again it waits for 1000ms. This loop runs
+endlessly, so we get a Blinking output if one connects a LED
+
+.. |image0| image:: images/led_pocket_beagle.png

simppru-examples/led_blink_button.rst

+LED blink on button press example
+=================================
+
+!!! info “Schematic” === “Pocket Beagle” |image0|
+
+::
+
+   === "BeagleBone Black / Beagle Bone Black Wireless"
+       ![](images/led_button_beagle_bone_black.png)   
+
+Code
+----
+
+.. code:: python
+
+   while : true {
+       if : digital_read(P1_29) {
+           digital_write(P1_31, false);
+       }
+       else {
+           digital_write(P1_31, true);
+       }
+   }
+
+-  Following code works on PocketBeagle, to use on other boards, please
+   change the pins accordingly.
+
+Explaination
+------------
+
+This code runs a never ending loop, since it is ``while : true``. Inside
+``while`` if header pin P1_29 is HIGH, then header pin P1_31 is set to
+HIGH, waits for 1000ms, then sets header pin P1_31 to LOW, then again it
+waits for 1000ms. This loop runs endlessly as long as header pin P1_29
+is HIGH, so we get a Blinking output if one connects a LED to output
+pin.
+
+.. |image0| image:: images/led_button_pocket_beagle.png

simppru-examples/led_blink_counter.rst

+LED blink using hardware counter
+================================
+
+!!! info “Schematic” === “Pocket Beagle” |image0|
+
+::
+
+   === "BeagleBone Black / Beagle Bone Black Wireless"
+       ![](images/led_beagle_bone_black.png)
+
+Code
+----
+
+.. code:: python
+
+   while : true {
+       start_counter();
+       while : read_counter() < 200000000 {
+           digital_write(P1_31, true);
+       }
+       stop_counter();
+
+       start_counter();
+       while : read_counter() < 200000000 {
+           digital_write(P1_31, false);
+       }
+       stop_counter();
+   }
+
+-  Following code works on PocketBeagle, to use on other boards, please
+   change the pins accordingly.
+
+Explaination
+------------
+
+This code runs a never ending while loop, since it is ``while : true``.
+Inside ``while`` it starts the counter, then in a nested while loop,
+which runs as long as ``read_counter`` returns values less than
+200000000, so for 200000000 cycles, HIGH is written to header pin P1_31,
+and after the while loop ends, the counter is stopped.
+
+Similarly counter is started again, which runs as long as
+``read_counter`` returns a value less than 200000000, so for 200000000
+cycles, LOW is written to header pin P1_31, and after the while loop
+ends, the counter is stopped.
+
+This process goes on endlessly as it is inside a never ending while
+loop. Here, we check if ``read_counter`` is less than 200000000, as
+counter takes exactly 1 second to count this much cycles, so basically
+the LED is turned on for 1 second, and then turned off for 1 second.
+Thus if a LED is connected to the pin, we get a endlessly blinking LED.
+
+.. |image0| image:: images/led_pocket_beagle.png

simppru-examples/led_blink_for.rst

+LED blink using for loop example
+================================
+
+!!! info “Schematic” === “Pocket Beagle” |image0|
+
+::
+
+   === "BeagleBone Black / Beagle Bone Black Wireless"
+       ![](images/led_beagle_bone_bl
+       
+
+Code
+----
+
+.. code:: python
+
+   for : l in 0:10 {
+       digital_write(P1_31, true);
+       delay(1000);
+       digital_write(P1_31, false);
+       delay(1000);
+   }
+
+-  Following code works on PocketBeagle, to use on other boards, please
+   change the pins accordingly.
+
+Explaination
+------------
+
+This code runs for loop with 10 iterations, Inside ``for`` it sets
+header pin P1_31 to HIGH, waits for 1000ms, then sets header pin P1_31
+to LOW, then again it waits for 1000ms. This loop runs endlessly, so we
+get a Blinking output if one connects a LED. So LED will blink 10 times
+with this code.
+
+.. |image0| image:: images/led_pocket_beagle.png

simppru-examples/led_blink_while.rst

+LED blink using while loop example
+==================================
+
+!!! info “Schematic” === “Pocket Beagle” |image0|
+
+::
+
+   === "BeagleBone Black / Beagle Bone Black Wireless"
+       ![](images/led_beagle_bone_black.png)
+
+Code
+----
+
+.. code:: python
+
+   while : true {
+       digital_write(P1_31, true);
+       delay(1000);
+       digital_write(P1_31, false);
+       delay(1000);
+   }
+
+-  Following code works on PocketBeagle, to use on other boards, please
+   change the pins accordingly.
+
+Explaination
+------------
+
+This code runs a never ending while loop, since it is ``while : true``.
+Inside ``while`` it sets header pin P1_31 to HIGH, waits for 1000ms,
+then sets header pin P1_31 to LOW, then again it waits for 1000ms. This
+loop runs endlessly, so we get a Blinking output if one connects a LED
+
+.. |image0| image:: images/led_pocket_beagle.png

simppru-examples/read_counter.rst

+Read hardware counter example
+=============================
+
+Code
+----
+
+.. code:: python
+
+   start_counter();
+   while : read_counter() < 200000000 {
+       digital_write(4, true);
+   }
+   stop_counter();
+
+-  Following code works on PocketBeagle, to use on other boards, please
+   change the pins accordingly.
+
+Explaination
+------------
+
+Since, PRU's hardware counter works at 200 MHz, it counts upto 2 x 108
+cycles in 1 second. So, this can be reliably used to count time without
+using ``delay``, as we can find exactly how much time 1 cycle takes.
+
+| 2 x 108 cycles/second.
+| 1 Cycles = 0.5 x 10-8 seconds.
+
+So, it can be used to count how many cycles have passed since, say we
+received a high input on pin 3. ``start_counter`` starts the counter,
+and ``read_counter`` reads the current state of the counter, and
+``stop_counter`` stops the counter.