Remove sub sectioning in examples and add examples list in TOC (#73)

* Remove subsection numbering from examples * Add examples list to Table of Contents * Update format of examples' heading
FreeRTOS · Jan 25, 2024 · 0c988ec · 0c988ec
1 parent 2e6e605
commit 0c988ec
Show file tree

Hide file tree

Showing 8 changed files with 188 additions and 135 deletions.
diff --git a/ch04.md b/ch04.md
diff --git a/ch05.md b/ch05.md
@@ -146,7 +146,7 @@ waiting the longest.
 
 Queues can be grouped into sets, allowing a task to enter the Blocked
 state to wait for data to become available on any of the queues in the
-set. Section 4.6, Receiving From Multiple Queues, demonstrates queue
+set. Section 5.6, Receiving From Multiple Queues, demonstrates queue
 sets.
 
 
@@ -415,7 +415,9 @@ UBaseType_t uxQueueMessagesWaiting( QueueHandle_t xQueue );
   then the queue is empty.
 
 
-### 5.3.5 Example 5.1. Blocking when receiving from a queue
+<a name="example5.1" title="Blocking when receiving from a queue"></a>
+
+<h3><i>Example 5.1 Blocking when receiving from a queue</i></h3>
 
 This example demonstrates creating a queue, sending data to the queue
 from multiple tasks, and receiving data from the queue. The queue is
@@ -673,7 +675,9 @@ Chapter (RB-TBD) shows how to extend this design pattern such that
 the controller task can reply directly to the task that queued a structure.
 
 
-### 5.4.1 Example 5.2: Blocking when sending to a queue, and sending structures on a queue
+<a name="example5.2" title="Blocking when sending to a queue, and sending structures on a queue"></a>
+
+<h3><i>Example 5.2 Blocking when sending to a queue, and sending structures on a queue</i></h3>
 
 Example 5.2 is similar to Example 5.1, but with reversed task priorities,
 so the receiving task has a lower priority than the sending tasks. Also,
@@ -1529,7 +1533,9 @@ QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet,
   in the set, but the block time expired before that happened.
 
 
-### 5.6.5 Example 5.3. Using a Queue Set
+<a name="example5.3" title="Using a Queue Set"></a>
+
+<h3><i>Example 5.3 Using a Queue Set</i></h3>
 
 This example creates two sending tasks and one receiving task. The
 sending tasks send data to the receiving task on two separate queues,
@@ -1726,7 +1732,7 @@ twice as often as those sent by `vSenderTask2()`.
 * * *
 
 
-### 5.6.6 More Realistic Queue Set Use Cases
+### 5.6.5 More Realistic Queue Set Use Cases
 
 Example 5.3 demonstrated a very simplistic case; the queue set only
 contained queues, and the two queues it contained were both used to send

diff --git a/ch06.md b/ch06.md
@@ -426,7 +426,7 @@ timers are created in the Dormant state.
 Software timers can be created before the scheduler is running, or from
 a task after the scheduler has been started.
 
-Section 0 describes the data types and naming conventions used.
+[Section 2.5: Data Types and Coding Style Guide](ch02.md#25-data-types-and-coding-style-guide) describes the data types and naming conventions used.
 
 
 <a name="list6.3" title="Listing 6.3 The xTimerCreate() API function prototype"></a>
@@ -587,7 +587,9 @@ BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );
     specified block time expired before that happened.
 
 
-### 6.5.3 Example 6.1. Creating one-shot and auto-reload timers
+<a name="example6.1" title="Creating one-shot and auto-reload timers"></a>
+
+<h3><i>Example 6.1 Creating one-shot and auto-reload timers</i></h3>
 
 This example creates and starts a one-shot timer and an auto-reload
 timer—as shown in Listing 6.5.
@@ -798,7 +800,9 @@ void *pvTimerGetTimerID( const TimerHandle_t xTimer );
   The ID of the software timer being queried.
 
 
-### 6.6.3 Example 6.2. Using the callback function parameter and the software timer ID
+<a name="example6.2" title="Using the callback function parameter and the software timer ID"></a>
+
+<h3><i>Example 6.2 Using the callback function parameter and the software timer ID</i></h3>
 
 The same callback function can be assigned to more than one software
 timer. When that is done, the callback function parameter is used to
@@ -1196,7 +1200,9 @@ BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );
     expired before that happened.
 
 
-### 6.8.2 Example 6.3. Resetting a software timer
+<a name="example6.3" title="Resetting a software timer"></a>
+
+<h3><i>Example 6.3 Resetting a software timer</i></h3>
 
 This example simulates the behavior of the backlight on a cell phone. The backlight:
 

diff --git a/ch07.md b/ch07.md
@@ -628,7 +628,9 @@ BaseType_t xSemaphoreGiveFromISR( SemaphoreHandle_t xSemaphore,
     `xSemaphoreGiveFromISR()` will return `pdFAIL`.
 
 
-### 7.4.4 Example 7.1. Using a binary semaphore to synchronize a task with an interrupt
+<a name="example7.1" title="Using a binary semaphore to synchronize a task with an interrupt"></a>
+
+<h3><i>Example 7.1 Using a binary semaphore to synchronize a task with an interrupt</i></h3>
 
 This example uses a binary semaphore to unblock a task from an interrupt
 service routine, effectively synchronizing the task with the interrupt.
@@ -850,7 +852,7 @@ periodic task. Further explanation is provided in Figure 7.5.
 * * *
 
 
-### 7.4.5 Improving the Implementation of the Task Used in Example 7.1
+### 7.4.4 Improving the Implementation of the Task Used in Example 7.1
 
 Example 7.1 used a binary semaphore to synchronize a task with an
 interrupt. The execution sequence was as follows:
@@ -1103,7 +1105,9 @@ SemaphoreHandle_t xSemaphoreCreateCounting( UBaseType_t uxMaxCount,
   to the created semaphore.
 
 
-### 7.5.2 Example 7.2. Using a counting semaphore to synchronize a task with an interrupt
+<a name="example7.2" title="Using a counting semaphore to synchronize a task with an interrupt"></a>
+
+<h3><i>Example 7.2 Using a counting semaphore to synchronize a task with an interrupt</i></h3>
 
 Example 7.2 improves on the Example 7.1 implementation by using a counting
 semaphore in place of the binary semaphore. `main()` is changed to include
@@ -1334,7 +1338,9 @@ void vPendableFunction( void *pvParameter1, uint32_t ulParameter2 );
     command queue.
 
 
-### 7.6.2 Example 7.3. Centralized deferred interrupt processing
+<a name="example7.3" title="Centralized deferred interrupt processing"></a>
+
+<h3><i>Example 7.3 Centralized deferred interrupt processing</i></h3>
 
 Example 7.3 provides similar functionality to Example 7.1, but without
 using a semaphore, and without creating a task specifically to perform
@@ -1613,8 +1619,9 @@ that are suitable for production code, include:
   than the raw data) to a task. This was previously demonstrated by
   Figure 5.4.
 
+<a name="example7.4" title="Sending and receiving on a queue from within an interrupt"></a>
 
-### 7.7.3 Example 7.4. Sending and receiving on a queue from within an interrupt
+<h3><i>Example 7.4 Sending and receiving on a queue from within an interrupt</i></h3>
 
 This example demonstrates `xQueueSendToBackFromISR()` and
 `xQueueReceiveFromISR()` being used within the same interrupt. As before,

diff --git a/ch08.md b/ch08.md
@@ -531,7 +531,9 @@ SemaphoreHandle_t xSemaphoreCreateMutex( void );
   created mutex.
 
 
-### 8.3.2 Example 8.1. Rewriting vPrintString() to use a semaphore
+<a name="example8.1" title="Rewriting vPrintString() to use a semaphore"></a>
+
+<h3><i>Example 8.1 Rewriting vPrintString() to use a semaphore</i></h3>
 
 This example creates a new version of `vPrintString()` called
 `prvNewPrintString()`, then calls the new function from multiple tasks.
@@ -701,7 +703,7 @@ the random delay periods used by the tasks.
 * * *
 
 
-### 8.3.3 Priority Inversion
+### 8.3.2 Priority Inversion
 
 Figure 8.3 demonstrates one of the potential pitfalls of using a mutex to
 provide mutual exclusion. The sequence of execution depicted shows the
@@ -727,7 +729,7 @@ systems it can often be avoided at system design time by considering
 how resources are accessed.
 
 
-### 8.3.4 Priority Inheritance
+### 8.3.3 Priority Inheritance
 
 FreeRTOS mutexes and binary semaphores are very similar—the difference
 being that mutexes include a basic 'priority inheritance' mechanism,
@@ -758,7 +760,7 @@ tasks that are using the mutex. For that reason, mutexes must not be
 used from interrupt service routines.
 
 
-### 8.3.5 Deadlock (or Deadly Embrace)
+### 8.3.4 Deadlock (or Deadly Embrace)
 
 'Deadlock' is another potential pitfall of using mutexes for mutual
 exclusion. Deadlock is sometimes also known by the more dramatic name
@@ -801,7 +803,7 @@ application, and so can identify and remove the areas where it could
 occur.
 
 
-### 8.3.6 Recursive Mutexes
+### 8.3.5 Recursive Mutexes
 
 It is also possible for a task to deadlock with itself. This will happen
 if a task attempts to take the same mutex more than once, without first
@@ -912,7 +914,7 @@ void vTaskFunction( void *pvParameters )
 * * *
 
 
-### 8.3.7 Mutexes and Task Scheduling
+### 8.3.6 Mutexes and Task Scheduling
 
 If two tasks of different priority use the same mutex, then the FreeRTOS
 scheduling policy makes the order in which the tasks will execute clear;

diff --git a/ch09.md b/ch09.md
@@ -530,8 +530,9 @@ StaticEventGroup_t ** ppxEventGroupBuffer );
 
   - `pdFALSE` will be returned if the buffer was not successfully retrieved.
 
+<a name="example9.1" title="Experimenting with event groups"></a>
 
-### 9.3.6 Example 9.1. Experimenting with event groups
+<h3><i>Example 9.1 Experimenting with event groups</i></h3>
 
 This example demonstrates how to:
 
@@ -1055,7 +1056,9 @@ EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
   condition.
 
 
-### 9.4.2 Example 9.2. Synchronizing tasks
+<a name="example9.2" title="Synchronizing tasks"></a>
+
+<h3><i>Example 9.2 Synchronizing tasks</i></h3>
 
 Example 9.2 uses `xEventGroupSync()` to synchronize three instances of a
 single task implementation. The task parameter is used to pass into each

diff --git a/ch10.md b/ch10.md
@@ -366,7 +366,10 @@ xTicksToWait );
   state to wait for its notification value to be greater than zero, but
   the specified block time expired before that happened.
 
-### 10.3.5 Example 10.1. Using a task notification in place of a semaphore, method 1
+
+<a name="example10.1" title="Using a task notification in place of a semaphore, method 1"></a>
+
+<h3><i>Example 10.1 Using a task notification in place of a semaphore, method 1</i></h3>
 
 Example 7.1 used a binary semaphore to unblock a task from within an
 interrupt service routine—effectively synchronizing the task with the
@@ -505,7 +508,9 @@ produced by the periodic task. Further explanation is provided in Figure 10.4.
 *Figure 10.4 The sequence of execution when Example 10.1 is executed*
 * * *
 
-### 10.3.6 Example 10.2. Using a task notification in place of a semaphore, method 2
+<a name="example10.2" title="Using a task notification in place of a semaphore, method 2"></a>
+
+<h3><i>Example 10.2 Using a task notification in place of a semaphore, method 2</i></h3>
 
 In Example 10.1, the `ulTaskNotifyTake()` `xClearOnExit` parameter was set to
 `pdTRUE`. Example 10.1 modifies Example 10.1 slightly to demonstrate the
@@ -614,7 +619,7 @@ interrupt is generated.
 *Figure 10.5 The output produced when Example 10.2 is executed*
 * * *
 
-### 10.3.7 The xTaskNotify() and xTaskNotifyFromISR() API Functions
+### 10.3.5 The xTaskNotify() and xTaskNotifyFromISR() API Functions
 
 `xTaskNotify()` is a more capable version of `xTaskNotifyGive()` that can be
 used to update the receiving task's notification value in any of the
@@ -740,7 +745,7 @@ Effect on the Receiving Task's Notification Value**
   receiving task had a notification pending before `xTaskNotify()` was
   called or not.
 
-### 10.3.8 The xTaskNotifyWait() API Function
+### 10.3.6 The xTaskNotifyWait() API Function
 
 `xTaskNotifyWait()` is a more capable version of `ulTaskNotifyTake()`. It
 allows a task to wait, with an optional timeout, for the calling task's
@@ -844,7 +849,7 @@ BaseType_t xTaskNotifyWait( uint32_t   ulBitsToClearOnEntry,
     held in the Blocked state to wait for its notification state to become
     pending, but the specified block time expired before that happened.
 
-### 10.3.9 Task Notifications Used in Peripheral Device Drivers: UART Example
+### 10.3.7 Task Notifications Used in Peripheral Device Drivers: UART Example
 
 Peripheral driver libraries provide functions that perform common
 operations on hardware interfaces. Examples of peripherals for which
@@ -1213,7 +1218,7 @@ void xUART_ReceiveISR( xUART *pxUARTInstance )
 *Listing 10.12 Pseudo code demonstrating how a task notification can be used in a driver library receive function*
 * * *
 
-### 10.3.10 Task Notifications Used in Peripheral Device Drivers: ADC Example
+### 10.3.8 Task Notifications Used in Peripheral Device Drivers: ADC Example
 
 The previous section demonstrated how to use `vTaskNotifyGiveFromISR()` to
 send a task notification from an interrupt to a task.
@@ -1324,7 +1329,7 @@ void ADC_ConversionEndISR( xADC *pxADCInstance )
 *Listing 10.13 Pseudo code demonstrating how a task notification can be used to pass a value to a task*
 * * *
 
-### 10.3.11 Task Notifications Used Directly Within an Application
+### 10.3.9 Task Notifications Used Directly Within an Application
 
 This section reinforces the power of task notifications by demonstrating
 their use in a hypothetical application that includes the following