From a113abce1d07285c8b73c8e36765c7a2f1e881ff Mon Sep 17 00:00:00 2001
From: Johnny Chen <johnny.chen@apple.com>
Date: Fri, 16 Mar 2012 00:44:02 +0000
Subject: [PATCH] rdar://problem/11057400

Add documentation for watchpoint commands.

llvm-svn: 152882
---
 lldb/www/lldb-gdb.html | 79 +++++++++++++++++++++++++++++++++++++++++-
 lldb/www/tutorial.html | 53 +++++++++++++++++++++++++++-
 2 files changed, 130 insertions(+), 2 deletions(-)

diff --git a/lldb/www/lldb-gdb.html b/lldb/www/lldb-gdb.html
index dd4dfd524e41..bfd25f5f988f 100755
--- a/lldb/www/lldb-gdb.html
+++ b/lldb/www/lldb-gdb.html
@@ -303,9 +303,86 @@
                     </table>
                     <p>
                 </div>
+                <div class="postfooter"></div>
+
+                <h1 class ="postheader">Watchpoint Commands</h1>
+                <div class="post">
+
+                    <p>
+
+                    <table class="stats" width="620" cellspacing="0">
+                    <tr>
+                        <td class="hed" width="50%">LLDB</td>
+                        <td class="hed" width="50%">GDB</td>
+                    </tr>
+
+                    <tr><td class="header" colspan="2">Set a watchpoint on a variable when it is written to.</td></tr>
+                    <tr>
+                        <td class="content">
+                            <b>(lldb)</b> watchpoint set variable -w write global_var<br>
+                            <b>(lldb)</b> watch set var -w write global_var<br>
+                        </td>
+                        <td class="content">
+                            <b>(gdb)</b> watch global_var
+                        </td>
+                    </tr>
+
+                    <tr><td class="header" colspan="2">Set a watchpoint on a memory location when it is written into. The size of the region to watch for defaults to the pointer size if no '-x byte_size' is specified.
+                        This command takes raw input, evaluated as an expression returning an unsigned integer pointing to the start of the region, after the '--' option terminator.</td></tr>
+                    <tr>
+                        <td class="content">
+                            <b>(lldb)</b> watchpoint set expression -w write -- my_ptr<br>
+                            <b>(lldb)</b> watch set exp -w write -- my_ptr<br>
+                      </td>
+                        <td class="content">
+                            <b>(gdb)</b> watch -location g_char_ptr
+                        </td>
+                    </tr>
+
+                    <tr><td class="header" colspan="2">Set a condition on a watchpoint</b>.</td></tr>
+                    <tr>
+                        <td class="content" colspan="2">
+                            <b>(lldb)</b> watch set var -w write global<br>
+                            <b>(lldb)</b> watchpoint modify -c '(global==5)'<br>
+                            <b>(lldb)</b> c<br>
+                            ...<br>
+                            <b>(lldb)</b> bt<br>
+                            * thread #1: tid = 0x1c03, 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16, stop reason = watchpoint 1<br>
+                              frame #0: 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16<br>
+                              frame #1: 0x0000000100000eac a.out`main + 108 at main.cpp:25<br>
+                              frame #2: 0x00007fff8ac9c7e1 libdyld.dylib`start + 1<br>
+                            <b>(lldb)</b> frame var global<br>
+                            (int32_t) global = 5<br>
+                        </td>
+                   </tr>
+
+                   <tr><td class="header" colspan="2">List all watchpoints.</td></tr>
+                    <tr>
+                        <td class="content">
+                            <b>(lldb)</b> watchpoint list<br>
+                            <b>(lldb)</b> watch l<br>
+                        </td>
+                        <td class="content">
+                            <b>(gdb)</b> info break<br>
+                        </td>
+                    </tr>
+
+                    <tr><td class="header" colspan="2">Delete a watchpoint.</td></tr>
+                    <tr>
+                        <td class="content">
+                            <b>(lldb)</b> watchpoint delete 1<br>
+                            <b>(lldb)</b> watch del 1<br>
+                        </td>
+                        <td class="content">
+                            <b>(gdb)</b> delete 1<br>
+                        </td>
+                    </tr>
+
+                    </table>
+                    <p>
+                </div>
 
             <div class="postfooter"></div>
-
             <h1 class ="postheader">Examining Variables</h1>
                 <div class="post">
                     <p>
diff --git a/lldb/www/tutorial.html b/lldb/www/tutorial.html
index 3524011263a7..4da41384d991 100755
--- a/lldb/www/tutorial.html
+++ b/lldb/www/tutorial.html
@@ -336,7 +336,58 @@ Current breakpoints:
                     <br> etc...
                      </code>
 
-			</div>
+			    </div>
+				<div class="postfooter"></div>
+
+                <div class="post">
+    				<h1 class ="postheader">Setting watchpoints</h1>
+    				<div class="postcontent">
+
+                    <p>In addition to breakpoints, you can use <code>help watchpoint</code>
+                    to see all the commands for watchpoint manipulations.  For instance, we might do the following to watch
+                    a variable called 'global' for write operation, but only stop if the condition '(global==5)' is true:</p>
+
+                   <pre><tt>(lldb) watch set var -w write global
+Watchpoint created: Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w
+    declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'
+(lldb) watch modify -c '(global==5)'
+(lldb) watch list
+Current watchpoints:
+Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w
+    declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'
+    condition = '(global==5)'
+(lldb) c
+Process 15562 resuming
+(lldb) about to write to 'global'...
+Process 15562 stopped and was programmatically restarted.
+Process 15562 stopped and was programmatically restarted.
+Process 15562 stopped and was programmatically restarted.
+Process 15562 stopped and was programmatically restarted.
+Process 15562 stopped
+* thread #1: tid = 0x1c03, 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16, stop reason = watchpoint 1
+    frame #0: 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16
+   13  	
+   14  	static void modify(int32_t &var) {
+   15  	    ++var;
+-> 16  	}
+   17  	
+   18  	int main(int argc, char** argv) {
+   19  	    int local = 0;
+(lldb) bt
+* thread #1: tid = 0x1c03, 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16, stop reason = watchpoint 1
+    frame #0: 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16
+    frame #1: 0x0000000100000eac a.out`main + 108 at main.cpp:25
+    frame #2: 0x00007fff8ac9c7e1 libdyld.dylib`start + 1
+(lldb) frame var global
+(int32_t) global = 5
+(lldb) watch list -v
+Current watchpoints:
+Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w
+    declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'
+    condition = '(global==5)'
+    hw_index = 0  hit_count = 5     ignore_count = 0   
+(lldb) </tt></pre>
+			    </div>
 				<div class="postfooter"></div>
 
     			<div class="post">