Merge ObjCPropertyDebugInfo.html into SourceLevelDebugging.html

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@144724 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 224 insertions, 0 deletions

diff --git a/docs/SourceLevelDebugging.html b/docs/SourceLevelDebugging.html
index 6eaaa240c1..f2741a2e01 100644
--- a/docs/SourceLevelDebugging.html
+++ b/docs/SourceLevelDebugging.html
@@ -53,6 +53,19 @@
     <li><a href="#ccxx_composite_types">C/C++ struct/union types</a></li>
     <li><a href="#ccxx_enumeration_types">C/C++ enumeration types</a></li>
   </ol></li>
+  <li><a href="#llvmdwarfextension">LLVM Dwarf Extensions</a>
+    <ol>
+      <li><a href="#objcproperty">Debugging Information Extension 
+	  for Objective C Properties</a></li>
+      <ul>
+	<li><a href="#objcpropertyintroduction">Introduction</a></li>
+	<li><a href="#objcpropertyproposal">Proposal</a></li>
+	<li><a href="#objcpropertynewattributes">New DWARF Attributes</a></li>
+	<li><a href="#objcpropertynewconstants">New DWARF Constants</a></li>
+      </ul>
+
+    </ol>
+  </li>
 </ul>
 </td>
 <td class="right">
@@ -1803,6 +1816,217 @@ enum Trees {
 
 </div>
 
+
+<!-- *********************************************************************** -->
+<h2>
+  <a name="llvmdwarfextension">Debugging information format</a>
+</h2>
+<!-- *********************************************************************** -->
+<div>
+<!-- ======================================================================= -->
+<h3>
+  <a name="objcproperty">Debugging Information Extension for Objective C
+Properties</a></li>
+</h3>
+<div>
+<!-- *********************************************************************** -->
+<h4>
+  <a name="objcpropertyintroduction">Introduction</a>
+</h4>
+<!-- *********************************************************************** -->
+
+<div>
+<p>Objective C provides a simpler way to declare and define accessor methods 
+using declared properties. The language provides features to declare a 
+property and to let compiler synthesize accessor methods.
+</p>
+
+<p>The debugger lets developer inspect Objective C interfaces and their 
+instance variables and class variables. However, the debugger does not know 
+anything about the properties defined in Objective C interfaces. The debugger
+consumes information generated by compiler in DWARF format. The format does 
+not support encoding of Objective C properties. This proposal describes DWARF
+extensions to encode Objective C properties, which the debugger can use to let
+developers inspect Objective C properties.
+</p>
+
+</div>
+
+
+<!-- *********************************************************************** -->
+<h4>
+  <a name="objcpropertyproposal">Proposal</a>
+</h4>
+<!-- *********************************************************************** -->
+
+<div>
+<p>Objective C properties are always backed by an instance variable. The 
+instance variables backing properties are identified using 
+DW_AT_APPLE_property_name attribute. The instance variables with this 
+attribute may not have data location attributes. The location of instance 
+variables is determined by debugger only after consulting Objective C runtime.
+</p>
+
+<div class="doc_code">
+<pre>
+@interface I1 { 
+  int n2;
+} 
+
+@property p1; 
+@property p2; 
+@end
+
+@implementation I1 
+@synthesize p1; 
+@synthesize p2 = n2; 
+@end
+
+
+TAG_structure_type [7] * 
+  AT_APPLE_runtime_class( 0x10 )
+  AT_name( "I1" )
+  AT_decl_file( "Objc_Property.m" ) 
+  AT_decl_line( 3 )
+
+  TAG_member [8] 
+    AT_name( "p1" )
+    AT_APPLE_property_name(“p1”) 
+    AT_type( {0x00000147} ( int ) )
+
+  TAG_member [8] 
+    AT_name( "n2" )
+    AT_APPLE_property_name(“p2”) 
+    AT_type( {0x00000147} ( int ) )
+</pre>
+</div>
+
+<p> Developers can decorate a property with attributes which are encoded using 
+DW_AT_APPLE_property_attribute.
+</p>
+
+<div class="doc_code">
+<pre>
+@property (readonly, nonatomic) int pr;
+
+
+TAG_member [8] 
+  AT_name(“pr”) 
+  AT_APPLE_property_name(“pr”) 
+  AT_type ( {0x00000147} (int) ) 
+  AT_APPLE_property_attribute (DW_APPLE_PROPERTY_readonly, DW_APPLE_PROPERTY_nonatomic)
+</pre>
+</div>
+
+<p> The setter and getter method names are attached to the property using 
+DW_AT_APPLE_property_setter and DW_AT_APPLE_property_getter attributes.
+</p>
+<div class="doc_code">
+<pre>
+@interface I1 
+@property (setter=myOwnP3Setter:) int p3; 
+-(void)myOwnP3Setter:(int)a; 
+@end
+
+@implementation I1 
+@synthesize p3;
+-(void)myOwnP3Setter:(int)a{ } 
+@end
+
+0x000003bd: TAG_structure_type [7] * 
+              AT_APPLE_runtime_class( 0x10 )
+              AT_name( "I1" )
+              AT_decl_file( "Objc_Property.m" ) 
+              AT_decl_line( 3 )
+0x000003f3: TAG_member [8] 
+              AT_name( "p3" ) 
+              AT_APPLE_property_name(“p3”) 
+              AT_APPLE_property_setter(“myOwnP3Setter:”)
+              AT_type( {0x00000147} ( int ) )
+</pre>
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h4>
+  <a name="objcpropertynewattributes">New DWARF Attributes</a>
+</h4>
+<!-- *********************************************************************** -->
+
+<div>
+<table border="1" cellspacing="0">
+  <tr>
+    <th width=200 >Attribute</th>
+    <th width=200 >Value</th>
+    <th width=200 >Classes</th>
+  </tr>
+  <tr>
+    <td width=200 >DW_AT_APPLE_property_name</td>
+    <td width=200 >0x3fe8</td>
+    <td width=200 >String</td>
+  </tr>
+  <tr>
+    <td width=200 >DW_AT_APPLE_property_getter</td>
+    <td width=200 >0x3fe9</td>
+    <td width=200 >String</td>
+  </tr>
+  <tr>
+    <td width=200 >DW_AT_APPLE_property_setter</td>
+    <td width=200 >0x3fea</td>
+    <td width=200 >String</td>
+  </tr>
+  <tr>
+    <td width=200 >DW_AT_APPLE_property_attribute</td>
+    <td width=200 >0x3feb</td>
+    <td width=200 >Constant</td>
+  </tr>
+</table>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h4>
+  <a name="objcpropertynewconstants">New DWARF Constants</a>
+</h4>
+<!-- *********************************************************************** -->
+
+<div>
+<table border="1" cellspacing="0">
+  <tr>
+    <th width=200 >Name</th>
+    <th width=200 >Value</th>
+  </tr>
+  <tr>
+    <td width=200 >DW_AT_APPLE_PROPERTY_readonly</td>
+    <td width=200 >0x1</td>
+  </tr>
+  <tr>
+    <td width=200 >DW_AT_APPLE_PROPERTY_readwrite</td>
+    <td width=200 >0x2</td>
+  </tr>
+  <tr>
+    <td width=200 >DW_AT_APPLE_PROPERTY_assign</td>
+    <td width=200 >0x4</td>
+  </tr>
+  <tr>
+    <td width=200 >DW_AT_APPLE_PROPERTY_retain</td>
+    <td width=200 >0x8</td>
+  </tr>
+  <tr>
+    <td width=200 >DW_AT_APPLE_PROPERTY_copy</td>
+    <td width=200 >0x10</td>
+  </tr>
+  <tr>
+    <td width=200 >DW_AT_APPLE_PROPERTY_nonatomic</td>
+    <td width=200 >0x20</td>
+  </tr>
+</table>
+
+</div>
+</div>
+</div>
+
 <!-- *********************************************************************** -->
 
 <hr>