- Main Page
- Modules
- Data Structures
- Files

# Debug Features
[Introduction]

## Data Structures
struct | PICOEVENT
| Event info structure. More...
struct | PICOTASK
| Task info structure. More...
## Defines
#define | P_ASSERT(text, x) if (!(x)) p_pos_assert((const char*)(text), __FILE__, __LINE__)
| pico]OS assertion macro.
#define | POS_SETTASKNAME(taskhandle, taskname)
| This macro assigns a name to a pico]OS task.
#define | POS_SETEVENTNAME(eventhandle, name)
| This macro assigns a name to a pico]OS event.
## Enumerations
enum | PTASKSTATE { task_notExisting = 0, task_created = 1, task_running = 2, task_suspended = 3, task_sleeping = 4, task_waitingForSemaphore = 5, task_waitingForSemaphoreWithTimeout = 6, task_waitingForMutex = 7, task_waitingForMutexWithTimeout = 8, task_waitingForFlag = 9, task_waitingForFlagWithTimeout = 10, task_waitingForMessage = 11, task_waitingForMessageWithTimeout = 12 }
| Task states (used for debugging when POSCFG_FEATURE_DEBUGHELP is set to 1). More...
enum | PEVENTTYPE { event_semaphore = 0, event_mutex = 1, event_flags = 2 }
| Event types (used for debugging when POSCFG_FEATURE_DEBUGHELP is set to 1). More...
## Variables
PICOTASK * | picodeb_taskhistory [3]
| This array contains the last 3 tasks that run.
PICOTASK * | picodeb_tasklist
| Pointer to the list of active tasks.
PICOEVENT * | picodeb_eventlist
| Pointer to the list of all system events.

## Detailed Description

Sometimes it is really hard to debug multitasking applications. Pico]OS supports you by providing assess to some helpful informations. In conjunction with an incircuit-debugger with the appropriated debugger IDE you will have a powerfull tool to debug your applications.

You need to enable the internal pico]OS debugging support by setting the define POSCFG_FEATURE_DEBUGHELP to 1. It is also required that you compile the code with debug flags set, and the global preprocessor define _DBG must be set.

Pico]OS exports some variables that are helpful for debugging:

- picodeb_tasklist points to the list of all currently started tasks
- picodeb_eventlist points to the list of all used events (semaphores, mutexes, flag events etc.)
- picodeb_taskhistory is a history of the last 3 tasks that run
- posCurrentTask_g contains the handle to the currently running task
- posInInterrupt_g is nonzero when pico]OS executes an interupt

Hint:
The global variables picodeb_tasklist and picodeb_eventlist are pointing to double-chained lists. This lists contain helpful informations about the state of tasks and events. When you observe that some task of your application hangs and you don't know why, you can search the task-list for the appropriated task (simply follow as often as necessary the 'next' pointer in the structure until you have found the task) and then have a look to the tasks state. If the task pends on an event, you can follow the event reference pointer to observe the current state of the event. Some IDE do have a kind of "OS-awareness". The both variables picodeb_tasklist and picodeb_eventlist should make it possible to teach your IDE the pico]OS. Please have a look into the debuggers documentation for how to integrate OS-awareness into your debugger.

If you consider to use the internal pico]OS debug feature, you should name your tasks and events. This simplifies the search for tasks and events in the global lists. Pico]OS provides two macros for doing this: POS_SETTASKNAME and POS_SETEVENTNAME.

## Define Documentation

#define P_ASSERT | ( | text,
|  | x |  | ) | if (!(x)) p_pos_assert((const char*)(text), __FILE__, __LINE__)

| pico]OS assertion macro. For testing and debugging you should enable pico]OS internal assertions. To do so, you must set the define HAVE_PLATFORM_ASSERT in your port.h -file and your platform port must provide this function: void p_pos_assert(const char* text, const char *filename, int linenumber). The function gets called every time pico]OS has failed an assertion.

#define POS_SETEVENTNAME | ( | eventhandle,
|  | name |  | ) |

| This macro assigns a name to a pico]OS event. You can use this macro to assign a name to a pico]OS events, such as semaphores, mutextes and flag events. This is usefull when you are debugging your application by using the global eventlist that is referenced by the variable picodeb_eventlist. It is easier to navigate through the list when the events have names. Example:
       POSSEMA_t sem;
       sem = posSemaCreate(0);
       POS_SETEVENTNAME(sem, "timer semaphore");
Note: If you are using nano-layer functions to create semaphores, mutexes and flag events, you do not need this macro. See also: POS_SETTASKNAME

#define POS_SETTASKNAME | ( | taskhandle,
|  | taskname |  | ) |

| This macro assigns a name to a pico]OS task. This is usefull when you are debugging your application by using the global tasklist that is referenced by the variable picodeb_tasklist. It is easier to navigate through the list when the tasks have names. Examples:
       POSTASK_t htask;
       htask = posTaskCreate(workertaskfunc, NULL, 2);
       POS_SETTASKNAME(htask, "worker task");
       POS_SETTASKNAME(posGetCurrentTask(), "receiver task");
Note: It is not necessary to use this macro when you are using the function nosTaskCreate to start a new task. See also: POS_SETEVENTNAME

## Enumeration Type Documentation

enum PEVENTTYPE

  | Event types (used for debugging when POSCFG_FEATURE_DEBUGHELP is set to 1). See also: POSCFG_FEATURE_DEBUGHELP Enumerator:
  event_semaphore | 0: The event object is a semaphore.
  event_mutex | 1: The event object is a mutex.
  event_flags | 2: The event object is a flags field.

enum PTASKSTATE

  | Task states (used for debugging when POSCFG_FEATURE_DEBUGHELP is set to 1). See also: POSCFG_FEATURE_DEBUGHELP Enumerator:
  task_notExisting | 0: Task does not exist.
  task_created | 1: Task was created but did not run yet.
  task_running | 2: Task is currently running.
  task_suspended | 3: Task was suspended.
  task_sleeping | 4: Task is sleeping for a period of time.
  task_waitingForSemaphore | 5: Task is waiting for a semaphore.
  task_waitingForSemaphoreWithTimeout | 6: Task is waiting for a semaphore, with timeout.
  task_waitingForMutex | 7: Task is waiting for a mutex.
  task_waitingForMutexWithTimeout | 8: Task is waiting for a mutex, with timeout.
  task_waitingForFlag | 9: Task is waiting for a flag event.
  task_waitingForFlagWithTimeout | 10: Task is waiting for a flag event, with timeout.
  task_waitingForMessage | 11: Task is waiting for a message.
  task_waitingForMessageWithTimeout | 12: Task is waiting for a message, with timeout.

## Variable Documentation

struct PICOEVENT* picodeb_eventlist

| Pointer to the list of all system events. This variable can be used for debugging. It points to a list of all active events in the system. An event can be a semaphore, a mutex or a flag object. To differentiate the events, there is a type-field in the PICOEVENT structure. The list is double-chained with next- and prev- pointers. See the description of the PICOEVENT structure for details. Note: You can use the macro POS_SETEVENTNAME to assign a name to an event. POSCFG_FEATURE_DEBUGHELP must be defined to 1 to enable debug support See also: picodeb_tasklist, picodeb_taskhistory

struct PICOTASK* picodeb_taskhistory[3]

| This array contains the last 3 tasks that run. This array can be used for debugging. The array has 3 entries, each is pointing to a task debug structure. This array is a history of the last 3 tasks that has run, and array element 0 is the task that currently runs, element 1 points to the task before, and so on. Note: A NULL pointer in the task history means a hardware interrupt. You can use the macro POS_SETTASKNAME to assign a name to a task. POSCFG_FEATURE_DEBUGHELP must be defined to 1 to enable debug support See also: picodeb_tasklist, picodeb_eventlist

struct PICOTASK* picodeb_tasklist

| Pointer to the list of active tasks. This variable can be used for debugging. It points to a list of all currently active (=created) tasks in the system. The list is double-chained with next- and prev- pointers. See the description of the PICOTASK structure for details. Note: You can use the macro POS_SETTASKNAME to assign a name to a task. POSCFG_FEATURE_DEBUGHELP must be defined to 1 to enable debug support See also: picodeb_eventlist, picodeb_taskhistory