[nvmewin] driver tracing volunteer
Robert Randall (rrandall)
rrandall at micron.com
Tue Jul 23 14:56:36 PDT 2013
Quick overview and proposal on driver tracing to get the conversation started. My apologies to those already steeped in the WPP tea leaves.
>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 http://msdn.microsoft.com/en-us/library/windows/hardware/ff556204(v=vs.85).aspx. 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:
TRACE(_T_HWINIT, "MaximumTransferLength 0x%x", PortConfig->MaximumTransferLength);
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.
<in some header file, suggested flags, meaning may or may not be obvious ;-) >
#define WPP_CONTROL_GUIDS \
WPP_DEFINE_CONTROL_GUID(nvme,(A_GUID), \
WPP_DEFINE_BIT(_T_ERR) \
WPP_DEFINE_BIT(_T_WARN) \
WPP_DEFINE_BIT(_T_DEBUG) \
WPP_DEFINE_BIT(_T_API_ERR) \
WPP_DEFINE_BIT(_T_IO_ERR) \
WPP_DEFINE_BIT(_T_LOCKS) \
WPP_DEFINE_BIT(_T_INT) \
WPP_DEFINE_BIT(_T_PNP) \
WPP_DEFINE_BIT(_T_PWR) \
WPP_DEFINE_BIT(_T_HWINIT) \
WPP_DEFINE_BIT(_T_IO_TX) \
WPP_DEFINE_BIT(_T_IO_RX) \
WPP_DEFINE_BIT(_T_DEV_ERR) \
WPP_DEFINE_BIT(_T_SCSI_ERR) \
WPP_DEFINE_BIT(_T_FUA) \
WPP_DEFINE_BIT(_T_IOCTL_ERR) \
WPP_DEFINE_BIT(DebugFlag16) \
WPP_DEFINE_BIT(DebugFlag17) \
WPP_DEFINE_BIT(DebugFlag18) \
WPP_DEFINE_BIT(DebugFlag19) \
WPP_DEFINE_BIT(DebugFlag20) \
WPP_DEFINE_BIT(DebugFlag21) \
WPP_DEFINE_BIT(DebugFlag22) \
WPP_DEFINE_BIT(DebugFlag23) \
WPP_DEFINE_BIT(DebugFlag24) \
WPP_DEFINE_BIT(DebugFlag25) \
WPP_DEFINE_BIT(DebugFlag26) \
WPP_DEFINE_BIT(DebugFlag27) \
WPP_DEFINE_BIT(DebugFlag28) \
WPP_DEFINE_BIT(DebugFlag29) \
WPP_DEFINE_BIT(DebugFlag30) \
WPP_DEFINE_BIT(DebugFlag31) \
)
#define WPP_FLAGS_LOGGER(flags) WPP_LEVEL_LOGGER(flags)
#define WPP_FLAGS_ENABLED(flags) WPP_LEVEL_ENABLED(flags)
// enable global logger / boot time logging support
#define WPP_GLOBALLOGGER
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.
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).
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.
A few additional examples:
TRACE(_T_HWINIT, "nvme bar not found");
or
TRACE(_T_HWINIT, "FATAL: passive initialization failed");
Since we are working with C macros we have some freedom. We can, for example, identify the adapter instance using a macro, for example:
TRACE(_T_HWINIT, WPPIDFMT "FATAL: passive initialization failed", EXT_TO_ID(pAE));
Where EXT_TO_ID could be anything we prefer to use such as (BDF).
Have a read and share feedback, questions, etc.
Best regards,
Robert.
From: Kwok Kong [mailto:Kwok.Kong at pmcs.com]
Sent: Monday, July 22, 2013 3:14 PM
To: Robert Randall (rrandall); nvmewin at lists.openfabrics.org
Subject: RE: [nvmewin] driver tracing volunteer
Robert,
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.
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).
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.
Thanks
-Kwok
From: nvmewin-bounces at lists.openfabrics.org<mailto:nvmewin-bounces at lists.openfabrics.org> [mailto:nvmewin-bounces at lists.openfabrics.org] On Behalf Of Robert Randall (rrandall)
Sent: Monday, July 22, 2013 12:54 PM
To: nvmewin at lists.openfabrics.org<mailto:nvmewin at lists.openfabrics.org>
Subject: [nvmewin] driver tracing volunteer
All,
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?
Best regards,
Robert
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openfabrics.org/pipermail/nvmewin/attachments/20130723/a4420f44/attachment.html>
More information about the nvmewin
mailing list