tracex/chapter5.html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.23">
<meta name="description" content="This chapter contains a description about how to build a TraceX event buffer and also describes the underlying format of the buffer.">
<title>Chapter 5 - Generating trace buffers</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
/* Uncomment the following line when using as a custom stylesheet */
/* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
html{font-family:sans-serif;-webkit-text-size-adjust:100%}
a{background:none}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
b,strong{font-weight:bold}
abbr{font-size:.9em}
abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
dfn{font-style:italic}
hr{height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
audio,video{display:inline-block}
audio:not([controls]){display:none;height:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type=checkbox],input[type=radio]{padding:0}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,::before,::after{box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:0}
p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ul.square{list-style-type:square}
ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
table thead,table tfoot{background:#f7f8f7}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt{background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.center{margin-left:auto;margin-right:auto}
.stretch{width:100%}
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
.clearfix::after,.float-group::after{clear:both}
:not(pre).nobreak{word-wrap:normal}
:not(pre).nowrap{white-space:nowrap}
:not(pre).pre-wrap{white-space:pre-wrap}
:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
pre>code{display:block}
pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
b.button::before{content:"[";padding:0 3px 0 2px}
b.button::after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
#content{margin-top:1.25em}
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child{border-bottom:1px solid #dddddf;padding-bottom:8px}
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span::before{content:"\00a0\2013\00a0"}
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber::after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
#content{margin-bottom:.625em}
.sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
.sect1{padding-bottom:1.25em}}
.sect1:last-child{padding-bottom:0}
.sect1+.sect1{border-top:1px solid #e7e7e9}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
details{margin-left:1.25rem}
details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
details>summary::-webkit-details-marker{display:none}
details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
.paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
.sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child,.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
.listingblock>.content{position:relative}
.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
.listingblock:hover code[data-lang]::before{display:block}
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.prettyprint{background:#f7f7f8}
pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
pre.prettyprint li code[data-lang]::before{opacity:1}
pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
table.linenotable td.code{padding-left:.75em}
table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
pre.pygments span.linenos{display:inline-block;margin-right:.75em}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
.verseblock{margin:0 1em 1.25em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
p.tableblock:last-child{margin-bottom:0}
td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
td.tableblock>.content>:last-child{margin-bottom:-1.25em}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>*>tr>*{border-width:1px}
table.grid-cols>*>tr>*{border-width:0 1px}
table.grid-rows>*>tr>*{border-width:1px 0}
table.frame-all{border-width:1px}
table.frame-ends{border-width:1px 0}
table.frame-sides{border-width:0 1px}
table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
li>p:empty:only-child::before{content:"";display:inline-block}
ul.checklist>li>p:first-child{margin-left:-1em}
ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
ul.inline>li{margin-left:1.25em}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
td.hdlist2{word-wrap:anywhere}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
.colist td:not([class]):first-child img{max-width:none}
.colist td:not([class]):last-child{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
.imageblock.left{margin:.25em .625em 1.25em 0}
.imageblock.right{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active,#footnotes .footnote a:first-of-type:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background:#00fafa}
.black{color:#000}
.black-background{background:#000}
.blue{color:#0000bf}
.blue-background{background:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background:#fa00fa}
.gray{color:#606060}
.gray-background{background:#7d7d7d}
.green{color:#006000}
.green-background{background:#007d00}
.lime{color:#00bf00}
.lime-background{background:#00fa00}
.maroon{color:#600000}
.maroon-background{background:#7d0000}
.navy{color:#000060}
.navy-background{background:#00007d}
.olive{color:#606000}
.olive-background{background:#7d7d00}
.purple{color:#600060}
.purple-background{background:#7d007d}
.red{color:#bf0000}
.red-background{background:#fa0000}
.silver{color:#909090}
.silver-background{background:#bcbcbc}
.teal{color:#006060}
.teal-background{background:#007d7d}
.white{color:#bfbfbf}
.white-background{background:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]::after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{box-shadow:none!important;text-shadow:none!important}
html{font-size:80%}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]{border-bottom:1px dotted}
abbr[title]::after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#header,#content,#footnotes,#footer{max-width:none}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span::before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]::before{display:block}
#footer{padding:0 .9375em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
@media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
.sect1{padding:0!important}
.sect1+.sect1{border:0}
#footer{background:none}
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
</style>
</head>
<body class="article">
<div id="header">
<h1>Chapter 5 - Generating trace buffers</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>This chapter contains a description about how to build a TraceX event buffer and also describes the underlying format of the buffer.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_threadx_event_trace_support">ThreadX Event Trace Support</h2>
<div class="sectionbody">
<div class="paragraph">
<p>ThreadX provides built-in event trace support for all ThreadX services, thread state changes, and user-defined events. The ThreadX event-trace capability is primarily designed as a post-mortem tool to analyze the last "n" activities in the application. From this information, the developer may spot problems and/or potential targets of optimization.</p>
</div>
<div class="paragraph">
<p>TraceX graphically displays the event trace buffer built by ThreadX. The following describes how to build the buffer and describes the underlying format of the buffer.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_enabling_event_trace">Enabling Event Trace</h2>
<div class="sectionbody">
<div class="paragraph">
<p>To enable event trace, define the time-stamp constants, build the ThreadX library with <strong>TX_ENABLE_EVENT_TRACE</strong> defined, and enable tracing by calling the <strong>tx_trace_enable</strong> function.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_defining_time_stamp_constants">Defining Time-Stamp Constants</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The time-stamp constants are designed to provide the developer control over the time-stamp used in the event trace entries. The two time-stamp constants and their default values are as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">#ifndef TX_TRACE_TIME_SOURCE
#define TX_TRACE_TIME_SOURCE ++_tx_trace_simulated_time
#endif
#ifndef TX_TRACE_TIME_MASK
#define TX_TRACE_TIME_MASK   0xFFFFFFFFUL
#endif</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above constants are defined in <strong>tx_port.h</strong> and create a "fake" time-stamp that simply increments by one on each event. The following is an example of an actual timestamp definition:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">#ifndef TX_TRACE_TIME_SOURCE
#define TX_TRACE_TIME_SOURCE ((ULONG) 0x0x13000004)
#endif
#ifndef TX_TRACE_TIME_MASK
#define TX_TRACE_TIME_MASK 0xFFFFFFFFUL
#endif</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above constants specify a 32-bit timer that is obtained by reading the address 0x13000004. Most application specific time-stamps should be setup in a similar fashion.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_exporting_the_trace_buffer">Exporting the Trace Buffer</h2>
<div class="sectionbody">
<div class="paragraph">
<p>TraceX needs the trace buffer in a binary, Intel HEX, or Motorola S-Record file format on the host. The easiest way to accomplish this is to stop the target and instruct your debugger to dump the memory area you supplied to <strong><em>tx_trace_enable</em></strong> function into a file on the host.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
<strong><em>Be careful not to stop the target within a trace gathering code itself. Doing so can cause invalid trace information. If the program is halted within ThreadX, it is best to step over any trace insert macro before dumping the trace buffer.</em></strong>
</td>
</tr>
</table>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
<em>Appendix D shows how to dump the trace buffer from within a variety of development tools.</em>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_extended_event_trace_api">Extended Event Trace API</h2>
<div class="sectionbody">
<div class="paragraph">
<p>When ThreadX is built with <strong>TX_ENABLE_EVENT_TRACE</strong> defined, the following new event trace APIs are available to the application:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>tx_trace_enable: <em>Enable event tracing</em></p>
</li>
<li>
<p>tx_trace_event_filter: <em>Filter specified event(s)</em></p>
</li>
<li>
<p>tx_trace_event_unfilter: <em>Unfilter specified event(s)</em></p>
</li>
<li>
<p>tx_trace_disable: <em>Disable event tracing</em></p>
</li>
<li>
<p>tx_trace_isr_enter_insert: <em>Insert ISR enter trace event</em></p>
</li>
<li>
<p>tx_trace_isr_exit_insert: <em>Insert ISR exit trace event</em></p>
</li>
<li>
<p>tx_trace_buffer_full_notify: <em>Register trace buffer full application callback</em></p>
</li>
<li>
<p>tx_trace_user_event_insert: <em>Insert user event</em></p>
</li>
</ul>
</div>
<div class="sect2">
<h3 id="_tx_trace_enable">tx_trace_enable</h3>
<div class="paragraph">
<p>Enable event tracing</p>
</div>
<div class="sect3">
<h4 id="_prototype">Prototype</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">UINT tx_trace_enable (VOID *trace_buffer_start,
     ULONG trace_buffer_size, ULONG registry_entries);</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_description">Description</h4>
<div class="paragraph">
<p>This service enables event tracing inside ThreadX. The trace buffer and the maximum number of ThreadX objects are supplied by the
application.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
The ThreadX library and application must be built with <strong>TX_ENABLE_EVENT_TRACE</strong> defined in order to use event tracing.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_input_parameters">Input Parameters</h4>
<div class="ulist">
<ul>
<li>
<p><strong>trace_buffer_start</strong>: Pointer to the start of the user-supplied trace buffer.</p>
</li>
<li>
<p><strong>trace_buffer_size</strong>: Total number of bytes in the memory for the trace buffer. The larger the trace buffer, the more entries it is able to store.</p>
</li>
<li>
<p><strong>registry_entries</strong>: Number of application ThreadX objects to keep in the trace registry. The registry is used to correlate object addresses with object names. This is highly useful for GUI trace analysis tools.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_return_values">Return Values</h4>
<div class="ulist">
<ul>
<li>
<p><strong>TX_SUCCESS</strong> (0x00) Successful event trace enable.</p>
</li>
<li>
<p><strong>TX_SIZE_ERROR</strong> (0x05) Specified trace buffer size is too small. It must be large enough for the trace header, the object registry, and at least one trace entry.</p>
</li>
<li>
<p><strong>TX_NOT_DONE</strong> (0x20) Event tracing was already enabled.</p>
</li>
<li>
<p><strong>TX_FEATURE_NOT_ENABLED</strong> (0xFF) System was not compiled with trace enabled.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_allowed_from">Allowed From</h4>
<div class="paragraph">
<p>Initialization and threads</p>
</div>
</div>
<div class="sect3">
<h4 id="_example">Example</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">UCHAR my_trace_buffer[64000];

/* Enable event tracing using the global "my_trace_buffer" memory and supporting a maximum of 30 ThreadX objects in the registry. */
status = tx_trace_enable (&amp;my_trace_buffer, 64000, 30);

/* If status is TX_SUCCESS the event tracing is enabled. */</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_see_also">See Also</h4>
<div class="paragraph">
<p>tx_trace_event_filter, tx_trace_event_unfilter,
tx_trace_disable, tx_trace_isr_enter_insert,
tx_trace_isr_exit_insert, tx_trace_buffer_full_notify,
tx_trace_user_event_insert</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_tx_trace_event_filter">tx_trace_event_filter</h3>
<div class="paragraph">
<p>Filter specified events</p>
</div>
<div class="sect3">
<h4 id="_prototype_2">Prototype</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">UINT tx_trace_event_filter (ULONG  vent_filter_bits);</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_description_2">Description</h4>
<div class="paragraph">
<p>This service filters the specified event(s) from being inserted into the active trace buffer. Note that by default no events are filtered after <em>tx_trace_enable</em> is called.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
The ThreadX library and application must be built with <strong>TX_ENABLE_EVENT_TRACE</strong> defined in order to use event tracing.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_input_parameters_2">Input Parameters</h4>
<div class="ulist">
<ul>
<li>
<p><strong>event_filter_bits</strong>: Bits that correspond to events to filter. Multiple events may be filtered by simply oring together the
appropriate constants. Valid constants for this variable are defined as follows:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">TX_TRACE_ALL_EVENTS                   0x000007FF
TX_TRACE_INTERNAL_EVENTS              0x00000001
TX_TRACE_BLOCK_POOL_EVENTS            0x00000002
TX_TRACE_BYTE_POOL_EVENTS             0x00000004
TX_TRACE_EVENT_FLAGS_EVENTS           0x00000008
TX_TRACE_INTERRUPT_CONTROL_EVENT      0x00000010
TX_TRACE_MUTEX_EVENTS                 0x00000020
TX_TRACE_QUEUE_EVENTS                 0x00000040
TX_TRACE_SEMAPHORE_EVENTS             0x00000080
TX_TRACE_THREAD_EVENTS                0x00000100
TX_TRACE_TIME_EVENTS                  0x00000200
TX_TRACE_TIMER_EVENTS                 0x00000400
FX_TRACE_ALL_EVENTS                   0x00007800
FX_TRACE_INTERNAL_EVENTS              0x00000800
FX_TRACE_MEDIA_EVENTS                 0x00001000
FX_TRACE_DIRECTORY_EVENTS             0x00002000
FX_TRACE_FILE_EVENTS                  0x00004000
NX_TRACE_ALL_EVENTS                   0x00FF8000
NX_TRACE_INTERNAL_EVENTS              0x00008000
NX_TRACE_ARP_EVENTS                   0x00010000
NX_TRACE_ICMP_EVENTS                  0x00020000
NX_TRACE_IGMP_EVENTS                  0x00040000
NX_TRACE_IP_EVENTS                    0x00080000
NX_TRACE_PACKET_EVENTS                0x00100000
NX_TRACE_RARP_EVENTS                  0x00200000
NX_TRACE_TCP_EVENTS                   0x00400000
NX_TRACE_UDP_EVENTS                   0x00800000
UX_TRACE_ALL_EVENTS                   0x7F000000
UX_TRACE_ERRORS                       0x01000000
UX_TRACE_HOST_STACK_EVENTS            0x02000000
UX_TRACE_DEVICE_STACK_EVENTS          0x04000000
UX_TRACE_HOST_CONTROLLER_EVENTS       0x08000000
UX_TRACE_DEVICE_CONTROLLER_EVENTS     0x10000000
UX_TRACE_HOST_CLASS_EVENTS            0x20000000
UX_TRACE_DEVICE_CLASS_EVENTS          0x40000000</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_return_values_2">Return Values</h4>
<div class="ulist">
<ul>
<li>
<p><strong>TX_SUCCESS</strong> (0x00) Successful event filter.</p>
</li>
<li>
<p><strong>TX_FEATURE_NOT_ENABLED</strong> (0xFF) System was not compiled with trace enabled.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_allowed_from_2">Allowed From</h4>
<div class="paragraph">
<p>Initialization and threads</p>
</div>
</div>
<div class="sect3">
<h4 id="_example_2">Example</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">/* Filter queue and byte pool events from trace buffer. */

status = tx_trace_event_filter (TX_TRACE_QUEUE_EVENTS | TX_TRACE_BYTE_POOL_EVENTS);

/* If status is TX_SUCCESS all queue and byte pool events are filtered. */</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_see_also_2">See Also</h4>
<div class="paragraph">
<p>tx_trace_enable, tx_trace_event_unfilter, tx_trace_disable, tx_trace_isr_enter_insert, tx_trace_isr_exit_insert,
tx_trace_buffer_full_notify, tx_trace_user_event_insert</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_tx_trace_event_unfilter">tx_trace_event_unfilter</h3>
<div class="paragraph">
<p>Unfilter specified events</p>
</div>
<div class="sect3">
<h4 id="_prototype_3">Prototype</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">UINT tx_trace_event_unfilter (ULONG event_unfilter_bits);</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_description_3">Description</h4>
<div class="paragraph">
<p>This service unfilters the specified event(s) such that they will be inserted into the active trace buffer.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
The ThreadX library and application must be built with <strong>TX_ENABLE_EVENT_TRACE</strong> defined in order to use event tracing.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_input_parameters_3">Input Parameters</h4>
<div class="ulist">
<ul>
<li>
<p><strong>event_unfilter_bits</strong>: Bits that correspond to events to unfilter. Multiple events may be unfiltered by simply or-ing together the appropriate constants. Valid constants for this variable are defined as follows:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">TX_TRACE_ALL_EVENTS                  0x000007FF
TX_TRACE_INTERNAL_EVENTS             0x00000001
TX_TRACE_BLOCK_POOL_EVENTS           0x00000002
TX_TRACE_BYTE_POOL_EVENTS            0x00000004
TX_TRACE_EVENT_FLAGS_EVENTS          0x00000008
TX_TRACE_INTERRUPT_CONTROL_EVENT     0x00000010
TX_TRACE_MUTEX_EVENTS                0x00000020
TX_TRACE_QUEUE_EVENTS                0x00000040
TX_TRACE_SEMAPHORE_EVENTS            0x00000080
TX_TRACE_THREAD_EVENTS               0x00000100
TX_TRACE_TIME_EVENTS                 0x00000200
TX_TRACE_TIMER_EVENTS                0x00000400
FX_TRACE_ALL_EVENTS                  0x00007800
FX_TRACE_INTERNAL_EVENTS             0x00000800
FX_TRACE_MEDIA_EVENTS                0x00001000
FX_TRACE_DIRECTORY_EVENTS            0x00002000
FX_TRACE_FILE_EVENTS                 0x00004000
NX_TRACE_ALL_EVENTS                  0x00FF8000
NX_TRACE_INTERNAL_EVENTS             0x00008000
NX_TRACE_ARP_EVENTS                  0x00010000
NX_TRACE_ICMP_EVENTS                 0x00020000
NX_TRACE_IGMP_EVENTS                 0x00040000
NX_TRACE_IP_EVENTS                   0x00080000
NX_TRACE_PACKET_EVENTS               0x00100000
NX_TRACE_RARP_EVENTS                 0x00200000
NX_TRACE_TCP_EVENTS                  0x00400000
NX_TRACE_UDP_EVENTS                  0x00800000
UX_TRACE_ALL_EVENTS                  0x7F000000
UX_TRACE_ERRORS                      0x01000000
UX_TRACE_HOST_STACK_EVENTS           0x02000000
UX_TRACE_DEVICE_STACK_EVENTS         0x04000000
UX_TRACE_HOST_CONTROLLER_EVENTS      0x08000000
UX_TRACE_DEVICE_CONTROLLER_EVENTS    0x10000000
UX_TRACE_HOST_CLASS_EVENTS           0x20000000
UX_TRACE_DEVICE_CLASS_EVENTS         0x40000000</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_return_values_3">Return Values</h4>
<div class="ulist">
<ul>
<li>
<p><strong>TX_SUCCESS</strong> (0x00) Successful event unfilter.</p>
</li>
<li>
<p><strong>TX_FEATURE_NOT_ENABLED</strong> (0xFF) System was not compiled with trace enabled.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_allowed_from_3">Allowed From</h4>
<div class="paragraph">
<p>Initialization and threads</p>
</div>
</div>
<div class="sect3">
<h4 id="_example_3">Example</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">/* Un-filter queue and byte pool events from trace buffer. */
status =
  tx_trace_event_unfilter (TX_TRACE_QUEUE_EVENTS | TX_TRACE_BYTE_POOL_EVENTS);

/* If status is TX_SUCCESS all queue and byte pool events are un-filtered. */</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_see_also_3">See Also</h4>
<div class="paragraph">
<p>tx_trace_enable, tx_trace_event_filter, tx_trace_disable, tx_trace_isr_enter_insert, tx_trace_isr_exit_insert, tx_trace_buffer_full_notify, tx_trace_user_event_insert</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_tx_trace_disable">tx_trace_disable</h3>
<div class="sect3">
<h4 id="_disable_event_tracing">Disable event tracing</h4>

</div>
<div class="sect3">
<h4 id="_prototype_4">Prototype</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">UINT tx_trace_disable (VOID);</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_description_4">Description</h4>
<div class="paragraph">
<p>This service disables event tracing inside ThreadX. This can be useful if the application wants to freeze the current event trace buffer and possibly transport it externally during run-time. Once disabled, the <strong>tx_trace_enable</strong> can be called to start tracing again.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
The ThreadX library and application must be built with <strong>TX_ENABLE_EVENT_TRACE</strong> defined in order to use event tracing.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_input_parameters_4">Input Parameters</h4>
<div class="paragraph">
<p>None.</p>
</div>
</div>
<div class="sect3">
<h4 id="_return_values_4">Return Values</h4>
<div class="ulist">
<ul>
<li>
<p><strong>TX_SUCCESS</strong> (0x00) Successful event trace disable.</p>
</li>
<li>
<p><strong>TX_NOT_DONE</strong> (0x20) Event tracing was not enabled.</p>
</li>
<li>
<p><strong>TX_FEATURE_NOT_ENABLED</strong> (0xFF) System was not compiled with trace enabled.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_allowed_from_4">Allowed From</h4>
<div class="paragraph">
<p>Initialization and threads</p>
</div>
</div>
<div class="sect3">
<h4 id="_example_4">Example</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">/* Disable event tracing. */
status = tx_trace_disable ();

/* If status is TX_SUCCESS the event tracing is disabled. */</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_see_also_4">See Also</h4>
<div class="paragraph">
<p>tx_trace_enable, tx_trace_event_filter,
tx_trace_event_unfilter, tx_trace_isr_enter_insert,
tx_trace_isr_exit_insert, tx_trace_buffer_full_notify,
tx_trace_user_event_insert</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_tx_trace_isr_enter_insert">tx_trace_isr_enter_insert</h3>
<div class="sect3">
<h4 id="_insert_isr_enter_event">Insert ISR enter event</h4>

</div>
<div class="sect3">
<h4 id="_prototype_5">Prototype</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">VOID tx_trace_isr_enter_insert (ULONG isr_id);</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_description_5">Description</h4>
<div class="paragraph">
<p>This service inserts the ISR enter event into the event trace buffer. It should be called by the application at the beginning of ISR processing. The supplied parameter should identify the specific ISR to the application.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
The ThreadX library and application must be built with <strong>TX_ENABLE_EVENT_TRACE</strong> defined in order to use event tracing.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_input_parameters_5">Input Parameters</h4>
<div class="ulist">
<ul>
<li>
<p><strong>isr_id</strong>: Application specific value to identify the ISR.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_return_values_5">Return Values</h4>
<div class="paragraph">
<p><strong>None</strong></p>
</div>
</div>
<div class="sect3">
<h4 id="_allowed_from_5">Allowed From</h4>
<div class="paragraph">
<p>ISRs</p>
</div>
</div>
<div class="sect3">
<h4 id="_example_5">Example</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">/* Insert trace event to identify the application's ISR with an ID of 3. */

status = tx_trace_isr_enter_insert (3);

/* If status is TX_SUCCESS the ISR entry event was inserted. */</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_see_also_5">See Also</h4>
<div class="paragraph">
<p>tx_trace_enable, tx_trace_event_filter,
tx_trace_event_unfilter, tx_trace_disable,
tx_trace_isr_exit_insert, tx_trace_buffer_full_notify,
tx_trace_user_event_insert</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_tx_trace_isr_exit_insert">tx_trace_isr_exit_insert</h3>
<div class="sect3">
<h4 id="_insert_isr_exit_event">Insert ISR exit event</h4>

</div>
<div class="sect3">
<h4 id="_prototype_6">Prototype</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">VOID tx_trace_isr_exit_insert (ULONG isr_id);</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_description_6">Description</h4>
<div class="paragraph">
<p>This service inserts the ISR entry event into the event trace buffer. It should be called by the application at the beginning of ISR processing. The supplied parameter should identify the ISR to the application.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
The ThreadX library and application must be built with <strong>TX_ENABLE_EVENT_TRACE</strong> defined in order to use event tracing.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_input_parameters_6">Input Parameters</h4>
<div class="ulist">
<ul>
<li>
<p><strong>isr_id</strong>: Application specific value to identify the ISR.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_return_values_6">Return Values</h4>
<div class="paragraph">
<p><strong>None</strong></p>
</div>
</div>
<div class="sect3">
<h4 id="_allowed_from_6">Allowed From</h4>
<div class="paragraph">
<p>ISRs</p>
</div>
</div>
<div class="sect3">
<h4 id="_example_6">Example</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">/* Insert trace event to identify the application's ISR with an ID of 3. */

status = tx_trace_isr_exit_insert (3);

/* If status is TX_SUCCESS the ISR exit event was inserted. */</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_see_also_6">See Also</h4>
<div class="paragraph">
<p>tx_trace_enable, tx_trace_event_filter, tx_trace_event_unfilter, tx_trace_disable, tx_trace_isr_enter_insert, tx_trace_buffer_full_notify,
tx_trace_user_event_insert</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_tx_trace_buffer_full_notify">tx_trace_buffer_full_notify</h3>
<div class="sect3">
<h4 id="_register_trace_buffer_full_application_callback">Register trace buffer full application callback</h4>

</div>
<div class="sect3">
<h4 id="_prototype_7">Prototype</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">VOID tx_trace_buffer_full_notify (VOID (*full_buffer_callback)(VOID *));</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_description_7">Description</h4>
<div class="paragraph">
<p>This service registers an application callback function that is called by ThreadX when the trace buffer becomes full. The application can then choose to disable tracing and/or possibly setup a new trace buffer.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
The ThreadX library and application must be built with <strong>TX_ENABLE_EVENT_TRACE</strong> defined in order to use event tracing.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_input_parameters_7">Input Parameters</h4>
<div class="ulist">
<ul>
<li>
<p><strong>full_buffer_callback</strong>: Application function to call when the trace buffer is full. A value of NULL disables the notification callback.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_return_values_7">Return Values</h4>
<div class="paragraph">
<p><strong>None</strong></p>
</div>
</div>
<div class="sect3">
<h4 id="_allowed_from_7">Allowed From</h4>
<div class="paragraph">
<p>ISRs</p>
</div>
</div>
<div class="sect3">
<h4 id="_example_7">Example</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">y_trace_is_full(void *trace_buffer_start)

{

     /* Application specific processing goes here! */

}

/* Register the "my_trace_is_full" function to be called whenever the trace buffer fills. */

status = tx_trace_buffer_full_notify (my_trace_is_full);

/* If status is TX_SUCCESS the "my_trace_is_full" function is registered. */</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_see_also_7">See Also</h4>
<div class="paragraph">
<p>tx_trace_enable, tx_trace_event_filter, tx_trace_event_unfilter, tx_trace_disable, tx_trace_isr_enter_insert, tx_trace_isr_exit_insert,
tx_trace_user_event_insert</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_tx_trace_user_event_insert">tx_trace_user_event_insert</h3>
<div class="sect3">
<h4 id="_insert_user_event">Insert user event</h4>

</div>
<div class="sect3">
<h4 id="_prototype_8">Prototype</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">UINT tx_trace_user_event_insert (ULONG event_id,
   ULONG info_field_1, ULONG info_field_2,
   ULONG info_field_3, ULONG info_field_4);</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_description_8">Description</h4>
<div class="paragraph">
<p>This service inserts the user event into the trace buffer. User event IDs must be greater than the constant <strong>TX_TRACE_USER_EVENT_START</strong>, which is defined to be 4096. The maximum user event is defined by the constant <strong>TX_TRACE_USER_EVENT_END</strong>, which is defined to be 65535. All events within this range are available to the application. The information fields are application specific.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
The ThreadX library and application must be built with <strong>TX_ENABLE_EVENT_TRACE</strong> defined in order to use event tracing.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_input_parameters_8">Input Parameters</h4>
<div class="ulist">
<ul>
<li>
<p><strong>event_id</strong>: Application-specific event identification and must start be greater than <strong>TX_TRACE_USER_EVENT_START</strong> and less than or equal to <strong>TX_TRACE_USER_EVENT_END</strong>.</p>
</li>
<li>
<p><strong>info_field_1</strong>: Application-specific information field.</p>
</li>
<li>
<p><strong>info_field_2</strong>: Application-specific information field.</p>
</li>
<li>
<p><strong>info_field_3</strong>: Application-specific information field.</p>
</li>
<li>
<p><strong>info_field_4</strong>: Application-specific information field.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_return_values_8">Return Values</h4>
<div class="ulist">
<ul>
<li>
<p><strong>TX_SUCCESS</strong> (0x00) Successful user event insert.</p>
</li>
<li>
<p><strong>TX_NOT_DONE</strong> (0x20) Event tracing is not enabled.</p>
</li>
<li>
<p><strong>TX_FEATURE_NOT_ENABLED</strong> (0xFF) The system was not compiled with trace enabled.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_allowed_from_8">Allowed From</h4>
<div class="paragraph">
<p>Initialization and threads</p>
</div>
</div>
<div class="sect3">
<h4 id="_example_8">Example</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-c" data-lang="c">/* Insert user event 3000, with info fields of 1, 2, 3, 4. */

status = tx_trace_user_event_insert (3000, 1, 2, 3, 4);

/* If status is TX_SUCCESS the user event was inserted. */</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_see_also_8">See Also</h4>
<div class="paragraph">
<p>tx_trace_enable, tx_trace_event_filter,
tx_trace_event_unfilter, tx_trace_disable,
tx_trace_isr_enter_insert, tx_trace_isr_exit_insert,
tx_trace_buffer_full_notify</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2025-02-07 08:25:21 UTC
</div>
</div>
</body>
</html>