Add SBFrame.WatchLocation() to find and watch the location pointed to by

a variable usng the frame as the scope.

Add TestSetWatchpoint.py to exercise this API.  Also fix some SWIG Python
docstrings.

llvm-svn: 140914

lldb/include/lldb/API/SBFrame.h

@@ -183,6 +183,14 @@ public:
     lldb::SBValue
     WatchValue (const char *name, ValueType value_type, uint32_t watch_type);
 
+    /// Find and watch the location pointed to by a variable using the frame as
+    /// the scope.
+    /// It returns an SBValue, similar to FindValue() method, if find-and-watch
+    /// operation succeeds.  Otherwise, an invalid SBValue is returned.
+    /// You can use LLDB_WATCH_TYPE_READ | LLDB_WATCH_TYPE_WRITE for 'rw' watch.
+    lldb::SBValue
+    WatchLocation (const char *name, ValueType value_type, uint32_t watch_type, size_t size);
+
     bool
     GetDescription (lldb::SBStream &description);
 

lldb/scripts/Python/interface/SBFrame.i

@@ -220,10 +220,20 @@ public:
     /// It returns an SBValue, similar to FindValue() method, if find-and-watch
     /// operation succeeds.  Otherwise, an invalid SBValue is returned.
     /// You can use LLDB_WATCH_TYPE_READ | LLDB_WATCH_TYPE_WRITE for 'rw' watch.
-    ") FindValue;
+    ") WatchValue;
     lldb::SBValue
     WatchValue (const char *name, ValueType value_type, uint32_t watch_type);
 
+    %feature("docstring", "
+    /// Find and watch the location pointed to by a variable using the frame as
+    /// the scope.
+    /// It returns an SBValue, similar to FindValue() method, if find-and-watch
+    /// operation succeeds.  Otherwise, an invalid SBValue is returned.
+    /// You can use LLDB_WATCH_TYPE_READ | LLDB_WATCH_TYPE_WRITE for 'rw' watch.
+    ") WatchLocation;
+    lldb::SBValue
+    WatchLocation (const char *name, ValueType value_type, uint32_t watch_type, size_t size);
+
     bool
     GetDescription (lldb::SBStream &description);
 

lldb/scripts/Python/interface/SBModule.i

@@ -48,7 +48,7 @@ And to iterate the symbols within a SBSection, use symbol_in_section_iter(),
             print INDENT2 + repr(sym)
             print INDENT2 + 'symbol type: %s' % symbol_type_to_str(sym.GetType())
 
-might produce this following output:
+produces this following output:
 
     [0x0000000100001780-0x0000000100001d5c) a.out.__TEXT.__text
         id = {0x00000004}, name = 'mask_access(MaskAction, unsigned int)', range = [0x00000001000017c0-0x0000000100001870)

lldb/scripts/Python/interface/SBType.i

@@ -77,7 +77,7 @@ int main (int argc, char const *argv[])
             ++total;
         t = t->next;
     }
-    printf('We have a total number of %d tasks\n', total);
+    printf('We have a total number of %d tasks\\n', total);
 
     // This corresponds to an empty task list.
     Task *empty_task_head = new Task(-1, NULL);

lldb/source/API/SBFrame.cpp

@@ -460,6 +460,65 @@ SBFrame::WatchValue (const char *name, ValueType value_type, uint32_t watch_type
     return wp_loc_sp ? sb_value : sb_value_empty;
 }
 
+/// Find and watch the location pointed to by a variable using the frame as
+/// the scope.
+/// It returns an SBValue, similar to FindValue() method, if find-and-watch
+/// operation succeeds.  Otherwise, an invalid SBValue is returned.
+/// You can use LLDB_WATCH_TYPE_READ | LLDB_WATCH_TYPE_WRITE for 'rw' watch.
+SBValue
+SBFrame::WatchLocation (const char *name, ValueType value_type, uint32_t watch_type, size_t size)
+{
+    SBValue sb_value_empty;
+
+    if (!IsValid())
+        return sb_value_empty;
+
+    // Acquire the API locker, to be released at the end of the method call.
+    Mutex::Locker api_locker (m_opaque_sp->GetThread().GetProcess().GetTarget().GetAPIMutex());
+
+    switch (value_type) {
+    case eValueTypeVariableGlobal:      // global variable
+    case eValueTypeVariableStatic:      // static variable
+    case eValueTypeVariableArgument:    // function argument variables
+    case eValueTypeVariableLocal:       // function local variables
+        break;
+    default:
+        return sb_value_empty;          // these are not eligible for watching
+    }
+
+    SBValue sb_pointer = FindValue(name, value_type);
+    // If the sb_pointer is not valid, there's no point in even trying to watch it.
+    if (!sb_pointer.IsValid() || !sb_pointer.GetType().IsPointerType())
+        return sb_value_empty;
+
+    addr_t addr = sb_pointer.GetValueAsUnsigned(0);
+    if (!addr)
+        return sb_value_empty;
+
+    SBValue sb_value = sb_pointer.CreateValueFromAddress("pointee", addr, sb_pointer.GetType().GetPointeeType());
+    WatchpointLocationSP wp_loc_sp = m_opaque_sp->GetThread().GetProcess().GetTarget().
+        CreateWatchpointLocation(addr, size, watch_type);
+
+    if (wp_loc_sp) {
+        // StackFrame::GetInScopeVariableList(true) to get file globals as well.
+        VariableListSP var_list_sp(m_opaque_sp->GetInScopeVariableList(true));
+        VariableSP var_sp = var_list_sp->FindVariable(ConstString(name));
+        if (var_sp && var_sp->GetDeclaration().GetFile()) {
+            StreamString ss;
+            // True to show fullpath for declaration file.
+            var_sp->GetDeclaration().DumpStopContext(&ss, true);
+            wp_loc_sp->SetDeclInfo(ss.GetString());
+        }
+    }
+
+    LogSP log(GetLogIfAllCategoriesSet (LIBLLDB_LOG_API));
+    if (log)
+        log->Printf ("SBFrame(%p)::WatchLocation (name=\"%s\", value_type=%i, watch_type=%i, size=%lu) => SBValue(%p) & wp_loc(%p)", 
+                     m_opaque_sp.get(), name, value_type, watch_type, size, sb_value.get(), wp_loc_sp.get());
+
+    return wp_loc_sp ? sb_value : sb_value_empty;
+}
+
 SBValue
 SBFrame::FindValue (const char *name, ValueType value_type, lldb::DynamicValueType use_dynamic)
 {

lldb/test/python_api/watchpoint/TestSetWatchpoint.py

@@ -1,5 +1,5 @@
 """
-Use lldb Python SBFrame API to create a watchpoint for read_write of 'globl' var
+Use lldb Python SBFrame API to create a watchpoint for read_write of 'globl' var.
 """
 
 import os, time

lldb/test/python_api/watchpoint/watchlocation/Makefile

@@ -0,0 +1,5 @@
+LEVEL = ../../../make
+
+CXX_SOURCES := main.cpp
+
+include $(LEVEL)/Makefile.rules

lldb/test/python_api/watchpoint/watchlocation/TestSetWatchlocation.py

@@ -0,0 +1,89 @@
+"""
+Use lldb Python SBFrame.WatchLocation() API to create a watchpoint for write of '*g_char_ptr'.
+"""
+
+import os, time
+import re
+import unittest2
+import lldb, lldbutil
+from lldbtest import *
+
+class SetWatchlocationAPITestCase(TestBase):
+
+    mydir = os.path.join("python_api", "watchpoint", "watchlocation")
+
+    def setUp(self):
+        # Call super's setUp().
+        TestBase.setUp(self)
+        # Our simple source filename.
+        self.source = 'main.cpp'
+        # Find the line number to break inside main().
+        self.line = line_number(self.source, '// Set break point at this line.')
+        # This is for verifying that watch location works.
+        self.violating_func = "do_bad_thing_with_location";
+
+    @unittest2.skipUnless(sys.platform.startswith("darwin"), "requires Darwin")
+    @python_api_test
+    def test_watch_val_with_dsym(self):
+        """Exercise SBFrame.WatchLocation() API to set a watchpoint."""
+        self.buildDsym()
+        self.do_set_watchlocation()
+
+    @python_api_test
+    def test_watch_val_with_dwarf(self):
+        """Exercise SBFrame.WatchLocation() API to set a watchpoint."""
+        self.buildDwarf()
+        self.do_set_watchlocation()
+
+    def do_set_watchlocation(self):
+        """Use SBFrame.WatchLocation() to set a watchpoint and verify that the program stops later due to the watchpoint."""
+        exe = os.path.join(os.getcwd(), "a.out")
+
+        # Create a target by the debugger.
+        target = self.dbg.CreateTarget(exe)
+        self.assertTrue(target, VALID_TARGET)
+
+        # Now create a breakpoint on main.c.
+        breakpoint = target.BreakpointCreateByLocation(self.source, self.line)
+        self.assertTrue(breakpoint and
+                        breakpoint.GetNumLocations() == 1,
+                        VALID_BREAKPOINT)
+
+        # Now launch the process, and do not stop at the entry point.
+        process = target.LaunchSimple(None, None, os.getcwd())
+
+        # We should be stopped due to the breakpoint.  Get frame #0.
+        process = target.GetProcess()
+        self.assertTrue(process.GetState() == lldb.eStateStopped,
+                        PROCESS_STOPPED)
+        thread = lldbutil.get_stopped_thread(process, lldb.eStopReasonBreakpoint)
+        frame0 = thread.GetFrameAtIndex(0)
+
+        value = frame0.WatchLocation('g_char_ptr',
+                                     lldb.eValueTypeVariableGlobal,
+                                     lldb.LLDB_WATCH_TYPE_WRITE,
+                                     1)
+        self.assertTrue(value, "Successfully found the location and set a watchpoint")
+        self.DebugSBValue(value)
+
+        # Continue.  Expect the program to stop due to the variable being written to.
+        process.Continue()
+
+        if (self.TraceOn()):
+            lldbutil.print_stacktraces(process)
+
+        thread = lldbutil.get_stopped_thread(process, lldb.eStopReasonWatchpoint)
+        self.assertTrue(thread, "The thread stopped due to watchpoint")
+        self.DebugSBValue(value)
+
+        self.expect(lldbutil.print_stacktrace(thread, string_buffer=True), exe=False,
+            substrs = [self.violating_func])
+
+        # This finishes our test.
+
+
+if __name__ == '__main__':
+    import atexit
+    lldb.SBDebugger.Initialize()
+    atexit.register(lambda: lldb.SBDebugger.Terminate())
+    unittest2.main()

lldb/test/python_api/watchpoint/watchlocation/main.cpp

@@ -0,0 +1,98 @@
+//===-- main.cpp ------------------------------------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+// C includes
+#include <pthread.h>
+#include <stdio.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+pthread_t g_thread_1 = NULL;
+pthread_t g_thread_2 = NULL;
+pthread_t g_thread_3 = NULL;
+
+char *g_char_ptr = NULL;
+
+void
+do_bad_thing_with_location(char *char_ptr, char new_val)
+{
+    *char_ptr = new_val;
+}
+
+uint32_t access_pool (uint32_t flag = 0);
+
+uint32_t
+access_pool (uint32_t flag)
+{
+    static pthread_mutex_t g_access_mutex = PTHREAD_MUTEX_INITIALIZER;
+    if (flag == 0)
+        ::pthread_mutex_lock (&g_access_mutex);
+
+    char old_val = *g_char_ptr;
+    if (flag != 0)
+        do_bad_thing_with_location(g_char_ptr, old_val + 1);
+
+    if (flag == 0)
+        ::pthread_mutex_unlock (&g_access_mutex);
+    return *g_char_ptr;
+}
+
+void *
+thread_func (void *arg)
+{
+    uint32_t thread_index = *((uint32_t *)arg);
+    printf ("%s (thread index = %u) startng...\n", __FUNCTION__, thread_index);
+
+    uint32_t count = 0;
+    uint32_t val;
+    while (count++ < 15)
+    {
+        // random micro second sleep from zero to 3 seconds
+        int usec = ::rand() % 3000000;
+        printf ("%s (thread = %u) doing a usleep (%d)...\n", __FUNCTION__, thread_index, usec);
+        ::usleep (usec);
+        
+        if (count < 7)
+            val = access_pool ();
+        else
+            val = access_pool (1);
+                
+        printf ("%s (thread = %u) after usleep access_pool returns %d (count=%d)...\n", __FUNCTION__, thread_index, val, count);
+    }
+    printf ("%s (thread index = %u) exiting...\n", __FUNCTION__, thread_index);
+    return NULL;
+}
+
+
+int main (int argc, char const *argv[])
+{
+    int err;
+    void *thread_result = NULL;
+    uint32_t thread_index_1 = 1;
+    uint32_t thread_index_2 = 2;
+    uint32_t thread_index_3 = 3;
+
+    g_char_ptr = (char *)malloc (1);
+    *g_char_ptr = 0;
+
+    // Create 3 threads
+    err = ::pthread_create (&g_thread_1, NULL, thread_func, &thread_index_1);
+    err = ::pthread_create (&g_thread_2, NULL, thread_func, &thread_index_2);
+    err = ::pthread_create (&g_thread_3, NULL, thread_func, &thread_index_3);
+
+    printf ("Before turning all three threads loose...\n"); // Set break point at this line.
+
+    // Join all of our threads
+    err = ::pthread_join (g_thread_1, &thread_result);
+    err = ::pthread_join (g_thread_2, &thread_result);
+    err = ::pthread_join (g_thread_3, &thread_result);
+
+    return 0;
+}