<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="Generator" content="Microsoft Word 12 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
{font-family:Tahoma;
panose-1:2 11 6 4 3 5 4 4 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:11.0pt;
font-family:"Calibri","sans-serif";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
p.MsoAcetate, li.MsoAcetate, div.MsoAcetate
{mso-style-priority:99;
mso-style-link:"Balloon Text Char";
margin:0in;
margin-bottom:.0001pt;
font-size:8.0pt;
font-family:"Tahoma","sans-serif";}
span.EmailStyle17
{mso-style-type:personal;
font-family:"Calibri","sans-serif";
color:windowtext;}
span.EmailStyle18
{mso-style-type:personal;
font-family:"Calibri","sans-serif";
color:#1F497D;}
span.BalloonTextChar
{mso-style-name:"Balloon Text Char";
mso-style-priority:99;
mso-style-link:"Balloon Text";
font-family:"Tahoma","sans-serif";}
span.EmailStyle21
{mso-style-type:personal-reply;
font-family:"Calibri","sans-serif";
color:#1F497D;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang="EN-US" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Quick overview and proposal on driver tracing to get the conversation started. My apologies to those already steeped in the WPP tea leaves.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">From a code perspective driver tracing has two major pieces. The trace levels and trace flags definitions and the macro used to generate the trace message data. The on-line documentation begins here
<a href="http://msdn.microsoft.com/en-us/library/windows/hardware/ff556204(v=vs.85).aspx">
<span style="color:windowtext">http://msdn.microsoft.com/en-us/library/windows/hardware/ff556204(v=vs.85).aspx</span></a>. The in-kernel tracing stores the raw data only. Microsoft provides utilities to format the raw data into human readable output (tracefmt.exe
for example). There is a collection of default data which is collected automatically like source file name, line number, etc. Data the code inserts works like a printf call for example:<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> TRACE(_T_HWINIT, "MaximumTransferLength 0x%x", PortConfig->MaximumTransferLength);<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal">In STOR Port miniport drivers I’ve not experienced a need for both trace levels and trace flags. I’ve used trace flags only. This allows for up to 32 different trace message classes or types to be defined. Here is a proposed definition
of WPP trace flags and a few required macros.<o:p></o:p></p>
<p class="MsoNormal"><span style="font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""><in some header file, suggested flags, meaning may or may not be obvious ;-) ><o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New"">#define WPP_CONTROL_GUIDS \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_CONTROL_GUID(nvme,(A_GUID), \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_ERR) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_WARN) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_DEBUG) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_API_ERR) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_IO_ERR) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_LOCKS) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_INT) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_PNP) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_PWR) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_HWINIT) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_IO_TX) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_IO_RX) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_DEV_ERR) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_SCSI_ERR) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_FUA) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(_T_IOCTL_ERR) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag16) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag17) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag18) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag19) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag20) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag21) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag22) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag23) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag24) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag25) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag26) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag27) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag28) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag29) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag30) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> WPP_DEFINE_BIT(DebugFlag31) \<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""> )<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New"">#define WPP_FLAGS_LOGGER(flags) WPP_LEVEL_LOGGER(flags)<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New"">#define WPP_FLAGS_ENABLED(flags) WPP_LEVEL_ENABLED(flags)<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New"">// enable global logger / boot time logging support<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New"">#define WPP_GLOBALLOGGER<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal">The WPP preprocessor is executed against each source file containing trace messages. The preprocessor is relatively clever and will catch most argument problems at the time or preprocessing. The cost of determining if a trace call is
invoked is inexpensive (bitwise operation) so the overhead of leaving tracing in a production driver is quite low. Of course, noise in the hot path should be minimal. The preprocessor generates all of the C macros used to generate the trace macro. All of
the formatting information is stored in the PDB of the driver using #pragma statements. The generated header file matches the name of the source file and has a .tmh extension. This header file must be included in the source file.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Collecting trace information can be a bit complicated but it is very useful. For example, you can choose to capture data to in-kernel buffers only and format the human readable output directly in the debugger (Windbg).<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">I tend to find tracing most useful when debugging device bring-up, power state transitions, and plug and play transitions. This can be very handy when an HCK test such as CHAOS fails and you’re left wonder why.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">A few additional examples:<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal"><span style="font-family:"Courier New"">TRACE(_T_HWINIT, "nvme bar not found");<o:p></o:p></span></p>
<p class="MsoNormal">or<o:p></o:p></p>
<p class="MsoNormal"><span style="font-family:"Courier New"">TRACE(_T_HWINIT, "FATAL: passive initialization failed");<o:p></o:p></span></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Since we are working with C macros we have some freedom. We can, for example, identify the adapter instance using a macro, for example:<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal"><span style="font-family:"Courier New"">TRACE(_T_HWINIT, WPPIDFMT "FATAL: passive initialization failed", EXT_TO_ID(pAE));<o:p></o:p></span></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Where EXT_TO_ID could be anything we prefer to use such as (BDF).<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Have a read and share feedback, questions, etc.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Best regards,<o:p></o:p></p>
<p class="MsoNormal">Robert.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal"><span style="color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D"><o:p> </o:p></span></p>
<div>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal"><b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif"">From:</span></b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif""> Kwok Kong [mailto:Kwok.Kong@pmcs.com]
<br>
<b>Sent:</b> Monday, July 22, 2013 3:14 PM<br>
<b>To:</b> Robert Randall (rrandall); nvmewin@lists.openfabrics.org<br>
<b>Subject:</b> RE: [nvmewin] driver tracing volunteer<o:p></o:p></span></p>
</div>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal"><span style="color:#1F497D">Robert,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D">You come to the right place. It is great that you volunteer to implement this feature. Please send out your proposal to this group for review.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D">We don’t have any formal procedure to approve any new features. All you need to do is to implement the new features, fully test it and send the source out for final testing by others and the approval. Once
you get the approval , the code will be checked into by Ray from intel (it is Alex from PMC-Sierra for now as Ray is on Sabbatical).<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D">It is always better to send the proposal to the group before spending lots of time on the implementation to avoid making big changes during code review to get the final approval.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D">Thanks<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D">-Kwok<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D"><o:p> </o:p></span></p>
<div>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal"><b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif"">From:</span></b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif"">
<a href="mailto:nvmewin-bounces@lists.openfabrics.org">nvmewin-bounces@lists.openfabrics.org</a> [<a href="mailto:nvmewin-bounces@lists.openfabrics.org">mailto:nvmewin-bounces@lists.openfabrics.org</a>]
<b>On Behalf Of </b>Robert Randall (rrandall)<br>
<b>Sent:</b> Monday, July 22, 2013 12:54 PM<br>
<b>To:</b> <a href="mailto:nvmewin@lists.openfabrics.org">nvmewin@lists.openfabrics.org</a><br>
<b>Subject:</b> [nvmewin] driver tracing volunteer<o:p></o:p></span></p>
</div>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">All,<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">I believe that implementing driver tracing (the in-kernel WMI based tracing, WPP tracing, etc) is on the to-do list for the project. I am volunteering for the task. Is the correct place to start a formal proposal on how to integrate tracing
into the driver?<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Best regards,<o:p></o:p></p>
<p class="MsoNormal">Robert<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
</body>
</html>