How to create a thread

At the system startup there are already two active threads:

• Idle thread. This thread has the lowest priority in the system so it runs only when the other threads in the system are sleeping. This threads usually switches the system in a low power mode and does nothing else.
• Main thread. This thread executes your main() function at startup. The main thread is created at the NORMALPRIO level but it can change its own priority if required. It is from the main thread that the other threads are usually created.

There are two kind of threads in ChibiOS/RT:

• Static Threads. This kind of threads are statically allocated in memory. The memory used by the thread cannot reused except for restarting the threads.
• Dynamic Threads. Threads created by allocating memory from a memory heap or a memory pool.

Creating a static thread

In order to create a static thread a working area must be declared using the macro WORKING_AREA as shown:

static WORKING_AREA(myThreadWorkingArea, 128);

This macro reserves 128 bytes of stack for the thread and space for all the required thread related structures. The total size and the alignment problems are handled inside the macro, you only need to specify the pure stack size.
A thread can be started by invoking chThdCreateStatic() as shown in this example:

  Thread *tp = chThdCreateStatic(myThreadWorkingArea,
                                 sizeof(myThreadWorkingArea),
                                 NORMALPRIO,    /* Initial priority.    */
                                 myThread,      /* Thread function.     */
                                 NULL);         /* Thread parameter.    */

The variable tp receives the pointer to the thread object, it is taken by other APIs as parameter.
Now a complete example:

/*
 * My simple application.
 */

#include <ch.h>

/*
 * Working area for the LED flashing thread.
 */
static WORKING_AREA(myThreadWorkingArea, 128);

/*
 * LED flashing thread.
 */
static msg_t myThread(void *arg) {

  while (TRUE) {
    LED_ON();
    chThdSleepMilliseconds(500);
    LED_OFF();
    chThdSleepMilliseconds(500);
  }
}

int main(int argc, char *argv[]) {

  /* Starting the flashing LEDs thread.*/
  (void)chThdCreateStatic(myThreadWorkingArea, sizeof(myThreadWorkingArea),
                          NORMALPRIO, myThread, NULL);
  .
  .
  .
}

Note that the memory allocated to myThread() is statically defined and cannot be reused. Static threads are ideal for safety applications because there is no risk of a memory allocation failure because progressive heap fragmentation.

Creating a dynamic thread using the heap allocator

In order to create a thread from a memory heap is very easy:

  Thread *tp = chThdCreateFromHeap(NULL,            /* NULL = Default heap. */
                                   THD_WA_SIZE(128),/* Stack size.          */
                                   NORMALPRIO,      /* Initial priority.    */
                                   myThread,        /* Thread function.     */
                                   NULL);           /* Thread parameter.    */

The memory is allocated from the spawned heap and the thread is started. Note that the memory is not freed when the thread terminates but when the thread final status (its return value) is collected by the spawning thread. As example:

static msg_t myThread(void *arg) {

  unsigned i = 10;
  while (i > 0) {
    LED_ON();
    chThdSleepMilliseconds(500);
    LED_OFF();
    chThdSleepMilliseconds(500);
    i--;
  }
  return (msg_t)i;
}

int main(int argc, char *argv[]) {

  Thread *tp = chThdCreateFromHeap(NULL, THD_WA_SIZE(128), NORMALPRIO+1,
                                   myThread, NULL);
  if (tp == NULL)
    chSysHalt();    /* Memory exausted. */
  
  /* The main thread continues its normal execution.*/
  .
  .
  /*
   * Now waits for the spawned thread to terminate (if it has not terminated
   * already) then gets the thread exit message (msg) and returns the
   * terminated thread memory to the heap (default system heap in this
   * example).
   */
  msg_t msg = chThdWait(tp);
  .
  .
}

Creating a dynamic thread using the heap allocator

A pool is a collection of equally sized memory blocks, creating a thread from a memry pool is very similar to the previous example but the memory of terminated threads is returned to the memory pool rather than to a heap:

static msg_t myThread(void *arg) {

  unsigned i = 10;
  while (i > 0) {
    LED_ON();
    chThdSleepMilliseconds(500);
    LED_OFF();
    chThdSleepMilliseconds(500);
    i--;
  }
  return (msg_t)i;
}

int main(int argc, char *argv[]) {

  Thread *tp = chThdCreateFromMemoryPool(myPool, NORMALPRIO+1, myThread, NULL);
  if (tp == NULL)
    chSysHalt();    /* Pool empty. */
  
  /* The main thread continues its normal execution.*/
  .
  .
  /*
   * Now waits for the spawned thread to terminate (if it has not terminated
   * already) then gets the thread exit message (msg) and returns the
   * terminated thread memory to the original memory pool.
   */
  msg_t msg = chThdWait(tp);
  .
  .
}