Contents

Chapter 1
The S.Ha.R.K. tracer

The S.Ha.R.K. new Tracer is a powerful tool to understand what happens while a S.Ha.R.K. application is executed. The Tracer logs a set of events corresponding with the most important activities within the kernel, such as preemptions, interrupt activations, mutexes blocks and releases, and much more.

During the execution, the kernel logs the sequence of events in memory; such events are then written to disk or sent through the network, typically at the end of the application execution. Each event is made by: a high resolution timestamp (TSC, Time Stamp Counter) corresponding to the instant at which the event has been logged; the event type; 2 optional parameters to add additional information to the event.

The Tracer can also be used to log custom events, since it reserves a number of free event types for user events.

To use the features made available by the Tracer, the Tracer functions must be enabled into the kernel by specifying

TRACER = NEW

into the shark.cfg configuration file. The S.Ha.R.K. kernel must be built with this option set.

Chapter 2
Primitives

2.1 FTrace_enable

int FTrace_enable();

Enable the Tracer. When this function is called, the Tracer starts the event logging.

2.2 FTrace_disable

int FTrace_disable();

Disable the Tracer. When this function is called, the Tracer stops the event logging.

2.3 FTrace_chunk_create

int FTrace_chunk_create(int normal_size, int emergency_size, FTrace_flags flags);

Create a new chunk.

2.4 FTrace_chunk_delete

int FTrace_chunk_delete(int number);

Delete a Chunk.

2.5 FTrace_set_chunk_flags

int FTrace_set_chunk_flags(int number, FTrace_flags flags);

Set the chunk flags.

2.6 FTrace_get_chunk_flags

int FTrace_get_chunk_flags(int number, FTrace_flags *flags);

Returns chunk flags.

2.7 FTrace_actual_chunk_select

int FTrace_actual_chunk_select(int number);

Select the actual chunk.

2.8 FTrace_chunk_link

int FTrace_chunk_link(int chunk_A, int chunk_B);

Link two chunks.

2.9 FTrace_get_first_chunk

int FTrace_get_first_chunk(FTrace_flags flags);

Find the first chunk with specific flags.

2.10 FTrace_get_chunk_table

FTrace_Chunk_Ptr *FTrace_get_chunk_table();

Get one chunks status.

2.11 FTrace_compress_chunk

int FTrace_compress_chunk(int number, FTrace_flags new_flags);

Create a new memory region where the compressed data are stored.

2.12 FTrace_send_chunk

int FTrace_send_chunk(int number, int osd_flags, FTrace_flags new_flags);

Send the chunk out from the memory.

2.13 FTrace_init_disk_writer

int FTrace_init_disk_writer(char *fname, int flag, char *l_ip, char *t_ip);

Initialize the disk Tracer chunk dumper. It sets the internal chunk sender to the function that writes chunks on disk. It initializes the filename that will be used to open the file for saving chunks.

2.14 FTrace_disk_writer

void FTrace_disk_writer(FTrace_Chunk_Ptr c);

This function is called by the application when it asks to write chunk c on disk. It saves the chunk data into the chunk_to_disk array. At the runlevel after the exit, all the saved chunks will be written to disk.

2.15 FTrace_OSD_init_udp

int FTrace_OSD_init_udp(int flag, char *l_ip, char *t_ip);

Initialize the Tracer chunk network sender using the UDP protocol supported by S.Ha.R.K. If flag = 1 initializes the network driver, otherwise it considers that the network layer has already been initialized. It also sets the internal chunk sender to the function that initializes the task for sending the chunk.

2.16 FTrace_set_filter

void FTrace_set_filter(BYTE family, int status);

Set the filter for a specific family of events (see Table 3.13 for a list of all the event families) . When the filter is enabled for a given family of events, all the events belonging to that family are not logged.

While status set to 1 enables the filter, status set to 0 disables the filter.

2.17 TRACER_LOGEVENT

TRACER_LOGEVENT(WORD type, WORD par1, DWORD par2);

Stores a new event of type type into the current chunk, together with the 2 parameters par1 (2 bytes) and par2 (4 bytes).

Chapter 3
Event types description

This Chapter reports all the available event type codes currently supported by S.Ha.R.K.

Chapter 4
Example of Tracer usage

Chapter 5
Tracer output

When the trace is saved, locally or remotely, into a file, the resulting binary file appears as a sequence of bytes where each event stored within the trace output file is 16 bytes long. The format of each single event is depicted in Table 5.1.

The fields have the following meaning:

• the Code represent the event type (see Chapter 3 for the full list);
• Parameter 1 and 2 are the parameters used when TRACER_LOGEVENT is invoked;
• TSC is the Time Stamp Counter associated with the event;

If prt points to the first byte of an event, the correct TSC value can be obtained with the following instructions:

unsigned long long tsc_value;

tsc_value = (unsigned long long)(*(unsigned int *)(ptr + 4)) << 32;

tsc_value += (unsigned long long)(*(unsigned int *)(ptr + 8));