Cornell University ECE4760
ProtoThreads -- Three Simple examples
Pi Pico rp2040/rp2350

Protothreads 1.3 on RP2040
For a complete explanation of Protothreads capibilities and limitations look here.
You should read sections 1.3-1.6 of the reference manual to see all of the implementation details.
Below the description of the examples there is a table with all available protothreads functions, and below that a few debugging hints.

The three examples
In this section we are going to consider how to use protothreads by considering with three simple examples. The examples will show:

• how yield a thread to the scheduler. Remember that this is a cooperative threader, so a thread has control of a cpu core until it yields.
• how prototehreads supports serial input and output with routines which yield the serial input thread between each character received or printed.
  Serial is slow, and so are human typists, so yielding between characters makes the system much more responsive.
• how to synchronize two threads with semaphores.

1. The first example program just starts one thread that blinks the on-board LED.
   Main initializes the serial interface, identifies one function to the scheduler as a thread, and starts the scheduler in round-robin mode.
   Round-robin mode executes each thread in order.
   The one thread (protothread_toggle25):
   1. starts with a macro to identify an entry point: PT_BEGIN(pt);
   2. defines a static boolean variable for the LED state.
      All local variables in a thread must be static!
   3. Sets up gpio25 as an output controlled by the SIO and sets it to true.
   4. Since a scheduled thread function can never exit, the thread falls into a endless loop which
      toggles the LED state variable, copies it to gpio25, then yields the thread for
      100,000 uSec. A that point the scheduler gets control, notices that there are no other
      threads to run and stalls until the thread yield times out.
   5. the thread ends with a marker for the scheduler: PT_END(pt);
      
      
2. The second example program starts two threads on one core. One to blink the LED at a duration set
   by a global variable and another to get user input for the duration variable.
   Main initializes the serial interface, identifies two functions to the scheduler as threads, and starts the scheduler in round-robin mode.
   The toggle thread is essentially identical to the first example, except that the blink time is a variable. User input
   from the serial UART channel needs careful handling because the serial is so slow compared to the cpu.  
   At 115200 baud, each sent character takes around 90 uSec to send, which is around 11000 cpu cycles we do not want to waste.
   Receiving text from a human typist is much slower, and therefore the receiver has to construct a string, while yielding between
   each typed character to any other thread which is ready to run.
   All of the yielding behavior in the serial thread is hidden from the programmer behind some macros and functions.
   
   The serial input thread (protothread_serial):
   1. starts with a macro to identify an entry point: PT_BEGIN(pt);
   2. Since a scheduled thread function can never exit, the thread falls into a endless loop which
      prompts for and receives the value of blink time.
   3. uses sprintf to construct a prompt string in a specific buffer, pt_serial_out_buffer.
   4. invokes serial_write to print the prompt, while blocking only this thread and allowing
      other threads to execute between characters.
   5. invokes serial_read to grab the user response, while blocking only this thread and allowing
      other threads to execute between characters.
   6. converts the input sring returned in pt_serial_in_buffer to an integer using sscanf and stores it in the global blink time variable.
   7. Note that there is no explicit yield in the serial thread because the the serial read/write functions handle the yields.
   8. the thread ends with a marker for the scheduler: PT_END(pt);
      
      
3. The third example program starts two threads on core0 and one thread on core1.
   In this example, one of the threads on core0 turns the LED on for a certain time, while the thread on
   core1 turns off the same LED for a certain length of time. The second thread on core0 prompts the
   user for separate on-time and off-time to control the two other threads. There are two global
   variables to conrol the on/off times, and two semaphores to ensure precise alternation
   between the thread that turns on the LED and the thread that turns it off.
   
   There are now two Main functions, one for core0 and one for core1;
   1. Core1 main adds the protothread_toggle25_off function to the core1 scheduler,
      then starts the core 1 schduler.
   2. Core0 main:
      1. sleeps for a millseccond to let the programmer finish
      2. starts the serial i/o
      3. initializes two core-safe semaphores to control blink excution and
         sets one of them to one and the other to zero.
         Setting a semaphore to one allows immediate execution.
         In this case, to start the blinking.
      4. inits the gpio for the blink threads
      5. resets, then starts core1 and again waits a millisecond
      6. identifies the two core0 threads to the core0 scheduler
      7. starts the core0 scheduler.
         
         
   There are three threads. The first one turns the LED on from core0
   1. The protothread_toggle25_on thread runs on core0. It drops directly into
      an endless loop which immediately waits for the blink_on_go_s semaphore to become
      non-zero, which happens when the semaphore is signaled in the thread on core1.
   2. When the semaphore is non-zero two things happen: It is automatically set to zero
      and allows execution of rest of the program.
   3. The gpio pin is set to true
   4. the thread yields for the on-time
   5. the thread signals the other blink thread to execute using
      PT_SEM_SAFE_SIGNAL(pt, &blink_off_go_s) ;
      
      
   The second thead turns the LED off from core1.
   1. The protothread_toggle25_off thread runs on core1. It drops directly into
      an endless loop which immediately waits for the blink_off_go_s semaphore to become
      non-zero, which happens when the semaphore is signaled in the thread on core0.
   2. When the semaphore is non-zero two things happen: It is automatically set to zero
      and allows execution of rest of the program.
   3. The gpio pin is set to false
   4. the thread yields for the off-time
   5. the thread signals the other blink thread to execute using
      PT_SEM_SAFE_SIGNAL(pt, &blink_on_go_s) ;
      
      
   The third thread allows the user to set the blink on and blink off times.
   1. The protothread_serial thread drops directly into an endless loop
   2. Just as in example 2 above the thread prompts the user
   3. the user responds with two integers for two times in uSec.
   4. sscanf converts the input string into two integers. Since sscanf
      does not yield, you are assured that the two numbers will be stored
      before either of the other threads can see them.

The ZIP file contains all three example codes.

1. Unzip the file
2. Import the project using the Pico exentension in VScode
3. Change the board type to either pico or pico2 (with no risc5)
4. The cmakelists.txt file has two of the three example codes commented out.
   Uncomment the one you want to compile and comment the others.
5. compile and run
6. For examples 2 and 3, you will need to open the serial monitor.

Some more advanced examples
In this section we are going to look at some features of Protothreads which are very handy, but not as heavily used as in the previous examples.

• Spawning a thread.
  All of the threads we have looked at so far are scheduled in main by identifying them to the scheduler using pt_add(thread_function_name). A spawned child thread is started by another application thread, called the parent thread. The parent thread uses the PT_SPAWN(pt, child, thread) macro to start the child thread, then blocks until the child thread exits using PT_EXIT(pt). Spawning a child thread is similar to calling a function from within a thread, but the child can yield to the scheduler, unlike a function. The ability for a child thread to yield is used extensively in the serial communication macros serial_read  and serial_write. These macros yield between every sent or received serial character.
  
  The spawn example code modifies the blinky example to spawn a thread to actually toggle the LED.
  One technical detail is that the user has to explicitly declare a protothreads control structure for the child thread.
  For scheduled threads, that detail is hidden from the user. The syntax is:

  // -- this structure is abstracted away for the scheduler
  // -- but must be specified for a spawned thread
  static struct pt spawn_struct ; 

  Of course, the name can be whatever you choose.
  To try this example, drop it into the folder with the other examples above and point the cmakelists.txt file to the source.
  
  
• Locking a variable, the priority scheduler option (and thread starvation),
  and a better serial command line parser.
  This example piles on a lot of stuff. It takes example three above, and adds two threads and modifies the serial thread.
  -- One of the new threads increments a simple counter, but the count variable needs to be protected because it can be written by two threads on separate cores. The protection scheme uses hardware locks atomically shared between the two cores. This thread also has the ability to restart itself, given a flag from the serial thread. Restart is a protothreads function equivalent to reseting only the one thread to its initial state.
  -- The other new thread toggles GPIO2 at very high rates by using yields on the order of 1 to 10 uSec. It is set to be the highest priority thread running on core1. Being highest priority does not guarantee meeting deadlines, but it gives the thread the best chance to try. You can set the actual yield time from the serial thread and view the effective rate with an oscilloscope.  Below about 10 uSec the effective rate falls below the set rate. At 5 uSec, the effective pulse time is 5.5 to 7.5 uSec. At 1 uSec, all of the other threads on the core fail because of time starvation, and the effective pulse time is 1.4 uSec.
  -- The serial thread from example three is modified to tokenize the input command line so that it can be more easily parsed. There are five defined commands, plus help. Two of the commands set the blinky on/off times. Three commands control the count thread, and one sets the fast toggle time on gpio2.
  
  The example code starts threads on both cores.
  -- Core0 scheduler is set to round-robin mode so that each thread gets a chance to execute in the order they are added.
  -- Core1 scheduler is set to priority mode so that the highest priority thread is the first one added to the scheduler list. Instead of executing in order, the high priority thread get a chance to execute before lower priority threads. After any thread executes, the high priority threads get first chance to execute again. The priority scheduler is tricky because it is possible to starve a thread of execution time, but it provides a way to use very demanding libraries, such as the Light Weight Internet Protocol (LWIP) library. The LWIP must respond to each packet received in a timely manner.
  
  |

Protothreads Function Summary
The following table give the syntax for the thread macros and functions written by Adam Dunkels.

The following table has the protothread macro extensions and functions
we wrote for the RP2040 and which are included in the Cornell header file.

Debugging ProtoThreads

If your program just sits there and does nothing:
-- Did you write each thread to include at least one YIELD (or YIELD_UNTIL, or YIELD_TIME_msec) in the while(1) loop? Remember that the UART input spawned
thread yields betwen eacy typed character. Humans are sooo slow.
-- Did you schedule the threads?
-- Does the board have correct Vdd?

If your program reboots about a few times/sec:
-- Did you exit from any scheduled thread? This blows out the stack.
-- Did you turn on any interrupt source and fail to write an ISR for that source?
-- Did you divide by zero? A divide by zero is an untrapped exception.
-- Did you write to a non-existant memory location, perhaps by using a negative (or very large) array index.
A write to a non-existant memory location is an untrapped exception.

If your thread state variables seem to change on their own:
--- Did you define any automatic local variable?
Local variables in a thread should be static.
-- Are your global arrays big enough the clobber the stack in high memory?
You should be able to use over 200 kbytes.

Copyright Cornell University March 15, 2025