Advanced Features and Debugging

---

Detailed Description

TiROS has API calls for debugging and per-task customization.

Notification of context switching

Using the TIROS_USER_CTXT_UPCALL feature, a user supplied function, user_ctxt_upcall(), can be kept informed of context switching. This can be used in creative ways to implement per-task hardware customization. For example, the upcall can be used to save the low-power state of the current task and set the low-power state of the next task. This will result in per-task power control.

Debugging with TiROS

Two types of debugging information can be retrieved from TiROS.

1. One is a simple text based error log that is activated by setting TIROS_DEBUG_LEVEL higher than 0. Output messages depend on the debug level.

         0 - No debugging messages.
         1 - Critical error messages.
         2 - Adds warning mesages.
         3 - Adds informational messages.
         4 - Adds trace messages.
         

   The debug output from TiROS gets channeled to the putchar(int char) function. To get debugging information, ensure that putchar() is properly implemented. By implementing putchar() appropriately, the output can be directed to a serial port or to a file.

2. Another method of debugging (and the most powerful) is to periodically capture the internal state of TiROS. This is done by a user task by calling the osint_snapshot function. To enable this function, define TIROSINT_DATA_DEBUG in the proj_config.h file, and include tr_debug.h in your source file. The osint_snapshot() function can be used to capture the TiROS state into a memory buffer (no need for putchar()) which can then be output as desired. An example of the use of this form of debugging is provided as an example in os_examples/os_debug_example

Data Structures
struct	os_data_hdr
	A representation of the debug header data. More...
struct	os_data_global
	This structure is a representation of the global debug data. More...
struct	os_data_per_task
	This structure is a representation of the variable internal data. More...
struct	os_internal_debug_data
	This structure describes the data returned by osint_snapshot. More...
Defines
#define	TIROS_DEBUG_DATA_SZ   (sizeof (struct os_internal_debug_data))
Functions
int	osint_snapshot (unsigned char *buffer, int memsz)

---

Define Documentation

#define TIROS_DEBUG_DATA_SZ   (sizeof (struct os_internal_debug_data))

Recommended size of the buffer to hold the TiROS internal debug data.

Definition at line 188 of file tr_debug.h.

---

Function Documentation

int osint_snapshot	(	unsigned char *	buffer,
		int	memsz
	)

A snapshot of all the internal os data.

This can be used by a dedicated task to send out debugging info The data is packed into a tight architecture independent little-endian byte stream. The type of data that is packed is illustrated in os_internal_debug_data. To use this function, tr_debug.h should be included by the source file and TIROSINT_DATA_DEBUG should be defined in proj_config.h

The TiROS state is written in a compact endian-neutral format. This can be parsed using the tiros_parse program that is included with the distribution. This form of debugging provides a wealth of information. Here is example output, parsed by tiros_parse, showing the debug data output by the example in os_examples/os_debug_example. This output was obtained from an msp430_gcc port.

NOTE: The information about the debugging task itself may not be fully accurate. It will reflect the state of the task at the last context switch.

--------------------------------------------------
os_options = 0x07,  data_sizes1 = 0x15, data_sizes2 = 0x01, max_procs = 8
Record size = 240
 TIROS Settings
PrioSort: 1      reg_passing: 1         stk_chk_info: 1          oswordt_sz: 2
tidtsz: 1        subtimet_sz: 2          flagt_sz: 2    osptrwordt_sz: 2
max_procs: 8 
gdata_len: 12    data_per_task_len: 28  task_tcb_len: 20         record_sz: 240
********************************************************************************
         5:41515        RUN:  1 RDY:  1 WT:  0  NESTING:  0     CTXT_CNT:   12
--------------------------------------------------------------------------------
TSK     CP      PRIO    EFF     FLAGS   MUTXS   TIMEOUT                 LK_PTR  EVTS    ...
0       0x1310    0       0     0x10      0              6:  640        0xffff  0x0000  ...
1       0x13aa    1       1     0x00      0              5:41483        0xffff  0x0000  ...
2       0x1442    2       2     0x10      0     4294967295:65535        0x1530  0x0001  ...
3       0x150e    3       3     0x00      0              0:    0        0xffff  0x0000  ...
4       0xffff    0       0     0x00      0              0:    0        0x0000  0x0000  ...
5       0xffff    0       0     0x00      0              0:    0        0x0000  0x0000  ...
6       0xffff    0       0     0x00      0              0:    0        0x0000  0x0000  ...
7       0xffff    0       0     0x00      0              0:    0        0x0000  0x0000  ...
----------------------------------------------------------------------
  ...    STK     STKSZ   PC      CUR_STK MAX_STK R/W Q   LK Q    
  ...    0x12b8     79   0x472a     35      36   0x02    0xff    
  ...    0x1356     79   0xffff      0      38   0x03    0xff    
  ...    0x13f4     79   0x472a     40      41   0xff    0xff    
  ...    0x1492     79   0x59ec     17      30   0xff    0xff    
  ...    0x0000      0   0xffff      0       0   0xff    0xff    
  ...    0x0000      0   0xffff      0       0   0xff    0xff    
  ...    0x0000      0   0xffff      0       0   0xff    0xff    
  ...    0x0000      0   0xffff      0       0   0xff    0xff    
----------------------------------------------------------------------

As can be seen, there is a prolific amount of information:

• the sizes of all the data types including task control block sizes.
• the TIROS_MAX_PROCS value that was configured into the program during compilation.
• Time.
• The running task ID, task IDs of the heads of the ready queue and wait queue.
• the ISR nesting level.
• number of context switches since reset.

On a per-task basis, the following information is available:

• TSK: The task id.
• CP: The current context pointer.
• PRIO: The priority of the task.
• EFF: The effective priorityof the task.
• FLAGS: Internal flags used to mark the task's state.
• MUTXS: The number of mutexes held by the task.
• TIMEOUT: The wait or sleep timeout.
• LK_PTR: Pointer to a lock that the task is waiting on if any.
• EVTS: Event bitmask that the task is waiting on.
• STK: The base stack pointer provided during task initialization. (only if TIROS_STK_CHECK is defined).
• STKSZ: The stack size provided during task initialization. (only if TIROS_STK_CHECK is defined).
• PC: The program counter (or instruction pointer) is available if the hardware port supports this.
• CUR_STK: The current stack usage is provided if the hardware port supports this.
• MAX_STK: The maximum stack usage of the task (throughout its run so far) is provided if the hardware port supports this.

The R/W Q and LK Q columns can be used to decipher the order of the tasks in the read/wait list and lock list respectively.

Parameters:

[in]	memaddr	Memory address to copy the data structures. If this is set to ILLEGAL_ADDR, the return value contains the size that the data structures would occupy in bytes. It is recommended that buffer be TIROS_DEBUG_DATA_SZ long.
[in]	memsz	Size of the memory location.

Returns:

If memaddr is set to ILLEGAL_ADDR< this returns the size of the data structures, else ERR_FAILED, if not enough memory. the actual length of the byte stream, if success.

---