This is an archive of the discontinued LLVM Phabricator instance.

[trace][intel-pt] Create basic SB API
ClosedPublic

Authored by wallace on Jun 1 2021, 6:23 PM.

Details

Summary

This adds a basic SB API for creating and stopping traces.
Note: This doesn't add any APIs for inspecting individual instructions. That'd be a more complicated change and it might be better to enhande the dump functionality to output the data in binary format. I'll leave that for a later diff.

This also enhances the existing tests so that they test the same flow using both the command interface and the SB API.

I also did some cleanup of legacy code.

Diff Detail

Event Timeline

wallace created this revision.Jun 1 2021, 6:23 PM
wallace requested review of this revision.Jun 1 2021, 6:23 PM
Herald added a project: Restricted Project. · View Herald TranscriptJun 1 2021, 6:23 PM
clayborg requested changes to this revision.Jun 7 2021, 2:48 PM
clayborg added inline comments.
lldb/include/lldb/API/SBProcess.h
97

Remove? This is not deprecated right?

279–303

Revert all diffs in this file I think right?

lldb/include/lldb/API/SBStructuredData.h
102

Is this needed?

lldb/include/lldb/API/SBTarget.h
856

Maybe just name this "lldb::SBTrace CreateTrace(SBError &error);". This would return an error if the trace was already created. If we are creating the trace we need to option to specify settings right?

lldb/include/lldb/API/SBTrace.h
38–42

I would remove this and just use the next function. People can just default construct a SBStructuredData and pass it in if they don't want to set any settings.

48–50

It would be nice to not document specific trace settings in this header file. It should be possible to add a way to get the schema from a "SBTrace" object right? Something like "const char * SBTrace::GetSchema()" and then tell users to check that for how and what settings are available and that if none are set that good defaults will be used?

52

Maybe rename to just "Start" and documentation will make it clear. We can also overload the Start below and add a SBThread argument. See comment below.

56

Remove this overload, and just use the one below. People can just default construct a SBStructuredData if they don't want to modify any settings.

65–66

Overload the "Start" method and just add a SBThread parameter to make it clear we are tracing just a specific thread.

79

Rename to "Stop"

83

Rename to "Stop" and allow the overload to happen with the extra thread argument. Do we have the ability to start thread 1, go for a while, start thread 2, go for a while, stop thread 1, go for a while and then stop thread 2?

94–96

Is this now deprecated?

104

Having just one argument will change the layout of the object. We need to keep "lldb::ProcessWP m_opaque_wp;" in from before so that layout of these objects doesn't change. We can mark it as deprecated, but it needs to be there.

lldb/include/lldb/API/SBTraceOptions.h
1

We can probably just mark the entire class as deprecated and avoid marking each method.

lldb/include/lldb/Target/Trace.h
235

rename to "Start" and allow overload with next function based on parameters.

251

Rename to "Start"

lldb/source/Plugins/Trace/intel-pt/constants.h
8 ↗(On Diff #349376)

Add include header for "size_t"

lldb/source/Target/Trace.cpp
294

Revert diffs to this file

This revision now requires changes to proceed.Jun 7 2021, 2:48 PM
wallace marked 18 inline comments as done.Jun 7 2021, 10:19 PM
wallace added inline comments.
lldb/include/lldb/API/SBStructuredData.h
102

yes, to access the actual StructuredData from SBTrace

wallace updated this revision to Diff 350493.Jun 7 2021, 10:19 PM
wallace marked an inline comment as done.

address all comments

clayborg requested changes to this revision.Jun 7 2021, 10:42 PM
clayborg added inline comments.
lldb/include/lldb/API/SBTrace.h
31
37–39
44
48–50

Modify to match the suggested process header doc mentioned above.

54–55
77–79

Can this only be used if we started tracing this specific thread? Or can we start tracing all threads in a process and then turn off tracing for individual threads? Might be good to specify this in these docs.

103–104

Reverse these to match how they were laid out before. That way if anyone accesses m_opaque_wp it will match the type.

lldb/include/lldb/Target/Target.h
1136–1140

Do we need both of these?

lldb/source/Plugins/Trace/intel-pt/constants.h
1 ↗(On Diff #350493)

This header file name is a bit too generic and could end up causing include issues. I would rename to "TraceIntelPTConstants.h" to be safe.

This revision now requires changes to proceed.Jun 7 2021, 10:42 PM
wallace marked 9 inline comments as done.Jun 8 2021, 9:56 AM
wallace added inline comments.
lldb/include/lldb/Target/Target.h
1136–1140

GetTraceOrCreate is quite handy for the CommandObjects. And CreateTrace seems more correct from the SB API side, so I'd like to keep them there.

wallace updated this revision to Diff 350641.Jun 8 2021, 9:57 AM
wallace marked an inline comment as done.

address all comments

vsk added a subscriber: vsk.Jun 8 2021, 10:08 AM
wallace updated this revision to Diff 350647.Jun 8 2021, 10:13 AM

improved the documentation

vsk requested changes to this revision.Jun 8 2021, 10:38 AM
vsk added a subscriber: mib.

Thanks, excited to see this work progress!

lldb/include/lldb/Target/Target.h
1129

See my other note about returning references to shared pointers. This would be nice to clean up either before or after landing this patch.

1131

Dangling 'This'?

1136

I don't think returning a TraceSP & is a good practice. This returns a reference to a SP: unless the SP is stored in a long-lived instance (which would defeat the purpose of using shared pointers in the first place), the returned reference will be dangling.

It might make more sense to either return the shared pointer (lldb::TraceSP) directly, or to return a bare pointer/reference.

lldb/include/lldb/Target/Trace.h
267

Consider using ArrayRef<lldb::tid_t>, as this permits the caller to use a larger variety of vector-like containers.

lldb/packages/Python/lldbsuite/test/tools/intelpt/intelpt_testcase.py
12

I don't think this works. In this wrapper, "USE_SB_API" is a local variable, *not* a reference to a TraceIntelPTTestCaseBase instance's "USE_SB_API" field.

To see why, consider the following example -- it prints "False" twice:

def make_wrapper(func):
    def wrapper(*args):
        FLAG = True
        func(*args)
        FLAG = False
        func(*args)
    return wrapper

class Klass:
    FLAG = False

    @make_wrapper
    def test(self):
        print(self.FLAG)

Klass().test()

How did you verify that the USE_SB_API = True case behaves as expected?

lldb/source/API/SBTarget.cpp
2458

Paging @mib - would you mind taking a closer look at these API/*.cpp changes? You've got more experience than I do in this area :)

This revision now requires changes to proceed.Jun 8 2021, 10:38 AM
JDevlieghere added inline comments.Jun 8 2021, 10:43 AM
lldb/bindings/interface/SBTrace.i
22–41

Do you have clients that already rely on these functions? Writing deprecated above them means nothing. When I was doing the reproducers, I included a warning in the header saying that this was under development and the API wasn't final, which allowed me to iterate on it. Can we just remove these methods and to the same here?

mib added a comment.Jun 8 2021, 12:09 PM

Took a look at the SBAPI changes and left few comments but overall, that part looked good to me. It would be nice if you could delete the depreciated method/class.

lldb/bindings/interface/SBTrace.i
22–41

+1

lldb/bindings/interface/SBTraceOptions.i
0

Same comment as @JDevlieghere here

lldb/include/lldb/API/SBTrace.h
100–101

Same here.

lldb/source/API/SBTrace.cpp
88

No need to use LLDB_RECORD_RESULT on primitive types such as bool.

93

Same here.

99

Either use LLDB_RECORD_DUMMY on all the deprecated method or don't use it at all :) If you could get rid of the deprecated methods that would be even better.

wallace updated this revision to Diff 350725.Jun 8 2021, 3:13 PM
wallace marked 11 inline comments as done.

address all comments. I appreciate your feedback!

  • I ended up deleting all the deprecated methods, as I doubt anyone is using them. Intel wrote those methods several years ago and they were used by the old intel pt plugin, which was effectively deleted by https://reviews.llvm.org/D102866, so I imagine no one using it anymore. Btw, that old plugin has been broken for a while.
  • I also fixed the USE_SB_API error in the python test. Good catch
wallace marked an inline comment as done.Jun 8 2021, 3:13 PM
clayborg requested changes to this revision.Jun 16 2021, 6:21 PM

a few nits!

lldb/include/lldb/API/SBTarget.h
847

rephrase the "It might be undefined.". Maybe "The returned SBTrace object might not be valid, check with a call to "bool SBTrace::IsValid();" to check."

lldb/include/lldb/Target/Trace.h
256

ArrayRef?

This revision now requires changes to proceed.Jun 16 2021, 6:21 PM
wallace updated this revision to Diff 352835.Jun 17 2021, 1:41 PM
wallace marked 2 inline comments as done.

address comments:

  • use llvm::ArrayRef where needed
  • improved documentation
clayborg accepted this revision.Jun 17 2021, 1:57 PM

Looks good!

This revision was not accepted when it landed; it landed in state Needs Review.Jun 17 2021, 3:23 PM
This revision was landed with ongoing or failed builds.
This revision was automatically updated to reflect the committed changes.