1 # btrace.cif

     2 # 

     3 # Copyright (c) 2010 Accenture. All rights reserved.

     4 # This component and the accompanying materials are made available

     5 # under the terms of the "Eclipse Public License v1.0"

     6 # which accompanies this distribution, and is available

     7 # at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 # 

     9 # Initial Contributors:

    10 # Accenture - Initial contribution

    11 #

    12 

    13 ==name btrace

    14 

    15 ==short-description

    16 

    17 Configures and fetches data from the btrace buffer.

    18 

    19 ==long-description

    20 

    21 The Symbian OS kernel provides an efficient binary logging mechanism called btrace. This command can be used to configure what data are written to this buffer, and also allows the data to be retrieved. It is functionally similar to the btrace.exe that is released as part of Symbian OS. The main differences are:

    22 

    23 =over 5

    24 

    25 =item a)

    26 

    27 It can repeatedly dump the contents of the buffer each time it gets to a particular percentage full (via the C<-F> and C<-t> options).

    28 

    29 =item b)

    30 

    31 If run without any arguments or in verbose mode (C<-v>), the current btrace configuration is displayed

    32 

    33 =back

    34 

    35 When using atrace to configure what is written to the buffer, if any primary filters are specified using the C<-f> option, all filters are disabled, then the buffer is emptied, then the specified filters are switched on (and thus primed). If a mode is specified, it is set before considering filters or filename arguments. Therefore it is a good idea when retrieving data from the buffer (by specifying a filename) to also specify C<-m0> to switch off output, otherwise the writing to file may never complete if atrace data is constantly being written.

    36 

    37 The arguments needed to begin profiling are C<-m1 -f3,9,15,18>. Then run C<uprofiler start> as normal. To stop run C<uprofiler stop> (optional), then invoke this command with arguments C<-m0 filename.utf>.

    38 

    39 ==see-also

    40 

    41 L<atrace|atrace>

    42 

    43 ==argument filename file_name optional

    44 

    45 The name of the file to write the current trace buffer contents to.

    46 

    47 ==option uint f filter multiple

    48 

    49 Set a primary filter (for suitable values see C<BTrace::TCategory>, defined in F<\epoc32\include\e32btrace.h>).

    50 

    51 ==option uint s secondary multiple

    52 

    53 Set a secondary filter.

    54 

    55 ==option uint m mode

    56 

    57 Set capture mode (for suitable values see C<RBTrace::TMode>, defined in F<\epoc32\include\d32btrace.h>).

    58 

    59 ==option uint b buffer

    60 

    61 Set the buffer size (in KB).

    62 

    63 ==option bool d dump

    64 

    65 Dump contents of trace buffer to debug port. The data is printed in hexdump format.

    66 

    67 ==option bool F follow

    68 

    69 Monitor the trace buffer and automatically write its contents when it gets to (by default) 50% full.

    70 

    71 ==option uint t threshold

    72 

    73 Set the percentage of data present in the trace buffer that triggers a write. Defaults to 50%. If set to zero, the trace buffer will be flushed every time data is written to it. Intended to be used in conjunction with C<--follow>.

    74 

    75 ==option bool T timestamp2

    76 

    77 Enable the btrace timestamp2 field. This causes each btrace frame to store both the fast counter value and the nano-kernel tick count value (ordinarily only the fast counter value is stored).

    78 

    79 ==option bool v verbose

    80 

    81 Print verbose output.

    82 

    83 ==option bool e test

    84 

    85 Tests that data can be written to and read from btrace successfully.

    86 

    87 ==option bool r reset

    88 

    89 Sets the trace buffer's mode to disabled, discards its current contents and removes all filters.

    90 

    91 ==option uint c text-trace-mode

    92 

    93 Set the kernel text trace mode (C<Kern::SetTextTraceMode>). This is included as a btrace option because the default setting C<ESerialOutDefault> will prevent C<RDebug::Print>s from going to the debugport when btrace is configured to capture rdebug.

    94 

    95 ==copyright

    96 

    97 Copyright (c) 2007-2010 Accenture. All rights reserved.

    98