osThreadProfileStart (function)

Starts measurement by the thread profiler

Syntax

#include <ultra.h>        /* os.h */
void    osThreadProfileStart(void);

Description

The thread profiler performs measurement operations for individual threads, referring to the ID provided as an argument when the thread was created with the osCreateThread function.

When using a measurement function of the thread profiler, use 1-62 as the ID given to the osCreateThread function. Threads with an ID of 63 or greater will be treated as an error, and their execution times and execution counts will all be accumulated as thread No. 63.

Since the ID's for system threads, such as VI or PI, etc., created in N64OS are all 0 (zero), their results will be accumulated as thread No. 0.

osThreadProfileInit prepares for profile execution by initializing the internal work necessary for the thread profiler. Be sure to call osThreadProfileInit before calling any other thread profiler function.

Call osThreadProfileClear to initialize the profile data (count,time) of only the thread with the specified ID.

Call osThreadProfileStart to start the thread profiler's measurement operation.

Call osThreadProfileStop to stop the thread profiler's operation. The profiled data will be saved, but the measurement operation is interrupted.

Call osThreadProfileReadCount to obtain the number of times that a switch was initiated to a thread with a specified ID.

Call osThreadProfileReadTime to obtain the cumulative execution time for the thread of the specified ID. Units are CPU count register cycles (about 21.33 nanoseconds).

Read-type functions with a Th attached to the end use the pointer to the OSThread structure as their argument instead of id. In this case, the information for a thread currently being executed can be obtained by putting NULL in the argument.

A normal value cannot be obtained if a thread is specified that presents an id that is larger than 63 when osCreateThread is called. In this case, Read-type functions will always return a 0 (zero) as an error value.

In addition, Read-type functions can be used at any time after osThreadProfileInit has been called.

If the debug library is being used, the following errors will be displayed on the Development Tools console.

ERR_OSTHPROFILESTART_FLAG
ERR_OSTHPROFILESTOP_FLAG
ERR_OSTHPROFILEREADCOUNT_FLAG
ERR_OSTHPROFILEREADCOUNTTH_FLAG
ERR_OSTHPROFILEREADTIME_FLAG
ERR_OSTHPROFILEREADTIMETH_FLAG
A non-initialize function was executed before profiling was initialized.
ERR_OSTHPROFILESTART_START A Start command has been issued for profiling even though profiling has already been started.
ERR_OSTHPROFILEREADCOUNTTH_LAR
ERR_OSTHPROFILEREADTIMETH_LAR
The ID given by the thread during osCreateThread exceeds the standard value.
ERR_OSTHPROFILEREADCOUNT_LAR
ERR_OSTHPROFILEREADTIME_LAR
The ID specified as the read target exceeds the standard value.
ERR_OSTHPROFILESTOP_LAR The ID of the thread currently in operation exceeds the standard value.

Notes

The thread profiler cannot be used with the liburtra_rom library.

Values cannot be initialized with osThreadProfileInit while the profiler is running.
If you wish to initialize, you must call osThreadProfileStop to stop operation.

See Also

osCreateThread, osThreadProfileInit, osThreadProfileClear, osThreadProfileStop, osThreadProfileReadCount, osThreadProfileReadCountTh, osThreadProfileReadTime, and osThreadProfileReadTimeTh

Revision History