[cfe-commits] r145276 - in /cfe/trunk/docs: AddressSanitizer.html LanguageExtensions.html

Mon Nov 28 12:51:02 PST 2011

Author: kcc
Date: Mon Nov 28 14:51:02 2011
New Revision: 145276

URL: http://llvm.org/viewvc/llvm-project?rev=145276&view=rev
Log:
First version of AddressSanitizer docs; documentation for __has_feature(address_sanitizer)

Added:
    cfe/trunk/docs/AddressSanitizer.html
Modified:
    cfe/trunk/docs/LanguageExtensions.html

Added: cfe/trunk/docs/AddressSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/AddressSanitizer.html?rev=145276&view=auto
==============================================================================

--- cfe/trunk/docs/AddressSanitizer.html (added)
+++ cfe/trunk/docs/AddressSanitizer.html Mon Nov 28 14:51:02 2011
@@ -0,0 +1,85 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
+          "http://www.w3.org/TR/html4/strict.dtd">
+<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
+<html>
+<head>
+  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+  <title>AddressSanitizer, a fast memory error detector</title>
+  <link type="text/css" rel="stylesheet" href="../menu.css">
+  <link type="text/css" rel="stylesheet" href="../content.css">
+  <style type="text/css">
+    td {
+            vertical-align: top;
+    }
+  </style>
+</head>
+<body>
+
+<!--#include virtual="../menu.html.incl"-->
+
+<h1>AddressSanitizer</h1>
+<ul> 
+  <li> <a href="intro">Introduction</a>
+  <li> <a href="usage">Usage</a>
+    <ul><li> <a href="has_feature">__has_feature(address_sanitizer)</a></ul>
+  <li> <a href="platforms">Supported Platforms</a>
+  <li> <a href="limitations">Limitations</a>
+  <li> <a href="status">Current Status</a>
+</ul>
+
+<h2 id="intro">Introduction</h2>
+AddressSanitizer is a fast memory error detector.
+It consists of a compiler instrumentation module and a run-time library.
+The tool can detect the following types of bugs:
+<ul> <li> Out-of-bounds accesses to  <ul><li>heap <li>stack <li>globals</ul>
+  <li> Use-after-free
+  <li> Use-after-return (to some extent)
+  <li> Double-free
+</ul>
+Typical slowdown introduced by AddressSanitizer is <b>2x</b>.
+
+<h2 id="intro">Usage</h2>
+In order to use AddressSanitizer simply compile and link your program with 
+<tt>-faddress-sanitizer</tt> flag and optimization level <tt>-O1</tt> or higher
+and then run it. If a bug is detected, the program will print an error message
+and exit.
+
+<h3 id="has_feature">__has_feature(address_sanitizer)</h3>
+In some cases one may need to execute different code depending on whether
+AddressSanitizer is enabled.
+<a href="LanguageExtensions.html#__has_feature_extension">__has_feature</a>
+can be used for this purpose.
+<pre>
+#if defined(__has_feature) && __has_feature(address_sanitizer)
+  code that runs only under AddressSanitizer
+#else
+  code that does not run under AddressSanitizer
+#endif
+</pre>
+
+<h2 id="platforms">Supported Platforms</h2>
+AddressSanitizer is supported on the following platforms:
+<ul> <li>Linux <ul> <li> i386 <li> x86_64 <li> ARM </ul>
+     <li>Darwin <ul> <li> i386 <li> x86_64 </ul>
+</ul>
+
+<h2 id="limitations">Limitations</h2>
+<ul>
+  <li> AddressSanitizer uses more real memory than a native run.
+  How much -- depends on the allocations sizes. The smaller the
+  allocations you make the bigger the overhead.
+  <li> On 64-bit platforms AddressSanitizer maps (but not reserves)
+  16+ Terabytes of virtual address space.
+  This means that tools like <tt>ulimit</tt> may not work as usually expected.
+  <li> Static linking is not supported.
+</ul>
+
+
+<h2 id="status">Current Status</h2>
+AddressSanitizer is work-in-progress and is not yet fully functional in the LLVM/Clang head.
+For the up-to-date usable version and full documentation refer to
+<a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>.
+
+
+</body>
+</html>

Modified: cfe/trunk/docs/LanguageExtensions.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LanguageExtensions.html?rev=145276&r1=145275&r2=145276&view=diff
==============================================================================
--- cfe/trunk/docs/LanguageExtensions.html (original)
+++ cfe/trunk/docs/LanguageExtensions.html Mon Nov 28 14:51:02 2011
@@ -103,6 +103,10 @@
   </ul>
 </li>
 <li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li>
+<li><a href="#dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</a></li>
+  <ul>
+  <li><a href="#address_sanitizer">AddressSanitizer</a></li>
+  </ul>
 <li><a href="#threadsafety">Thread Safety Annotation Checking</a></li>
     <ul>
     <li><a href="#ts_noanal"><tt>no_thread_safety_analysis</tt></a></li>   
@@ -211,6 +215,11 @@
 non-standardized features, i.e. features not prefixed <code>c_</code>,
 <code>cxx_</code> or <code>objc_</code>.</p>
 
+<p id="has_feature_for_non_language_features">
+Another use of <code>__has_feature</code> is to check for compiler features
+not related to the language standard, such as e.g.
+<a href="AddressSanitizer.html">AddressSanitizer</a>.
+
 <p>If the <code>-pedantic-errors</code> option is given,
 <code>__has_extension</code> is equivalent to <code>__has_feature</code>.</p>
 
@@ -1272,6 +1281,14 @@
 <p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>,
 <tt>__has_attribute(ns_returns_retained)</tt>, etc.</p>
 
+<!-- ======================================================================= -->
+<h2 id="dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</h2>
+<!-- ======================================================================= -->
+<h3 id="address_sanitizer">AddressSanitizer</h3>
+<p> Use <code>__has_feature(address_sanitizer)</code>
+to check if the code is being built with <a
+  href="AddressSanitizer.html">AddressSanitizer</a>.
+</p>
 
 <!-- ======================================================================= -->
 <h2 id="threadsafety">Thread-Safety Annotation Checking</h2>



