iPXE
memcheck.h
Go to the documentation of this file.
00001 
00002 /*
00003    ----------------------------------------------------------------
00004 
00005    Notice that the following BSD-style license applies to this one
00006    file (memcheck.h) only.  The rest of Valgrind is licensed under the
00007    terms of the GNU General Public License, version 2, unless
00008    otherwise indicated.  See the COPYING file in the source
00009    distribution for details.
00010 
00011    ----------------------------------------------------------------
00012 
00013    This file is part of MemCheck, a heavyweight Valgrind tool for
00014    detecting memory errors.
00015 
00016    Copyright (C) 2000-2010 Julian Seward.  All rights reserved.
00017 
00018    Redistribution and use in source and binary forms, with or without
00019    modification, are permitted provided that the following conditions
00020    are met:
00021 
00022    1. Redistributions of source code must retain the above copyright
00023       notice, this list of conditions and the following disclaimer.
00024 
00025    2. The origin of this software must not be misrepresented; you must 
00026       not claim that you wrote the original software.  If you use this 
00027       software in a product, an acknowledgment in the product 
00028       documentation would be appreciated but is not required.
00029 
00030    3. Altered source versions must be plainly marked as such, and must
00031       not be misrepresented as being the original software.
00032 
00033    4. The name of the author may not be used to endorse or promote 
00034       products derived from this software without specific prior written 
00035       permission.
00036 
00037    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
00038    OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00039    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00040    ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
00041    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00042    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
00043    GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00044    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
00045    WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00046    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00047    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00048 
00049    ----------------------------------------------------------------
00050 
00051    Notice that the above BSD-style license applies to this one file
00052    (memcheck.h) only.  The entire rest of Valgrind is licensed under
00053    the terms of the GNU General Public License, version 2.  See the
00054    COPYING file in the source distribution for details.
00055 
00056    ---------------------------------------------------------------- 
00057 */
00058 
00059 
00060 #ifndef __MEMCHECK_H
00061 #define __MEMCHECK_H
00062 
00063 FILE_LICENCE ( BSD3 );
00064 
00065 
00066 /* This file is for inclusion into client (your!) code.
00067 
00068    You can use these macros to manipulate and query memory permissions
00069    inside your own programs.
00070 
00071    See comment near the top of valgrind.h on how to use them.
00072 */
00073 
00074 #include "valgrind.h"
00075 
00076 /* !! ABIWARNING !! ABIWARNING !! ABIWARNING !! ABIWARNING !! 
00077    This enum comprises an ABI exported by Valgrind to programs
00078    which use client requests.  DO NOT CHANGE THE ORDER OF THESE
00079    ENTRIES, NOR DELETE ANY -- add new ones at the end. */
00080 typedef
00081    enum { 
00082       VG_USERREQ__MAKE_MEM_NOACCESS = VG_USERREQ_TOOL_BASE('M','C'),
00083       VG_USERREQ__MAKE_MEM_UNDEFINED,
00084       VG_USERREQ__MAKE_MEM_DEFINED,
00085       VG_USERREQ__DISCARD,
00086       VG_USERREQ__CHECK_MEM_IS_ADDRESSABLE,
00087       VG_USERREQ__CHECK_MEM_IS_DEFINED,
00088       VG_USERREQ__DO_LEAK_CHECK,
00089       VG_USERREQ__COUNT_LEAKS,
00090 
00091       VG_USERREQ__GET_VBITS,
00092       VG_USERREQ__SET_VBITS,
00093 
00094       VG_USERREQ__CREATE_BLOCK,
00095 
00096       VG_USERREQ__MAKE_MEM_DEFINED_IF_ADDRESSABLE,
00097 
00098       /* Not next to VG_USERREQ__COUNT_LEAKS because it was added later. */
00099       VG_USERREQ__COUNT_LEAK_BLOCKS,
00100 
00101       /* This is just for memcheck's internal use - don't use it */
00102       _VG_USERREQ__MEMCHECK_RECORD_OVERLAP_ERROR 
00103          = VG_USERREQ_TOOL_BASE('M','C') + 256
00104    } Vg_MemCheckClientRequest;
00105 
00106 
00107 
00108 /* Client-code macros to manipulate the state of memory. */
00109 
00110 /* Mark memory at _qzz_addr as unaddressable for _qzz_len bytes. */
00111 #define VALGRIND_MAKE_MEM_NOACCESS(_qzz_addr,_qzz_len)           \
00112    (__extension__({unsigned long _qzz_res;                       \
00113     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0 /* default return */, \
00114                             VG_USERREQ__MAKE_MEM_NOACCESS,       \
00115                             _qzz_addr, _qzz_len, 0, 0, 0);       \
00116     _qzz_res;                                                    \
00117    }))
00118       
00119 /* Similarly, mark memory at _qzz_addr as addressable but undefined
00120    for _qzz_len bytes. */
00121 #define VALGRIND_MAKE_MEM_UNDEFINED(_qzz_addr,_qzz_len)          \
00122    (__extension__({unsigned long _qzz_res;                       \
00123     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0 /* default return */, \
00124                             VG_USERREQ__MAKE_MEM_UNDEFINED,      \
00125                             _qzz_addr, _qzz_len, 0, 0, 0);       \
00126     _qzz_res;                                                    \
00127    }))
00128 
00129 /* Similarly, mark memory at _qzz_addr as addressable and defined
00130    for _qzz_len bytes. */
00131 #define VALGRIND_MAKE_MEM_DEFINED(_qzz_addr,_qzz_len)            \
00132    (__extension__({unsigned long _qzz_res;                       \
00133     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0 /* default return */, \
00134                             VG_USERREQ__MAKE_MEM_DEFINED,        \
00135                             _qzz_addr, _qzz_len, 0, 0, 0);       \
00136     _qzz_res;                                                    \
00137    }))
00138 
00139 /* Similar to VALGRIND_MAKE_MEM_DEFINED except that addressability is
00140    not altered: bytes which are addressable are marked as defined,
00141    but those which are not addressable are left unchanged. */
00142 #define VALGRIND_MAKE_MEM_DEFINED_IF_ADDRESSABLE(_qzz_addr,_qzz_len) \
00143    (__extension__({unsigned long _qzz_res;                       \
00144     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0 /* default return */, \
00145                             VG_USERREQ__MAKE_MEM_DEFINED_IF_ADDRESSABLE, \
00146                             _qzz_addr, _qzz_len, 0, 0, 0);       \
00147     _qzz_res;                                                    \
00148    }))
00149 
00150 /* Create a block-description handle.  The description is an ascii
00151    string which is included in any messages pertaining to addresses
00152    within the specified memory range.  Has no other effect on the
00153    properties of the memory range. */
00154 #define VALGRIND_CREATE_BLOCK(_qzz_addr,_qzz_len, _qzz_desc)     \
00155         (__extension__({unsigned long _qzz_res;                  \
00156     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0 /* default return */, \
00157                             VG_USERREQ__CREATE_BLOCK,            \
00158                             _qzz_addr, _qzz_len, _qzz_desc,      \
00159                             0, 0);                               \
00160     _qzz_res;                                                    \
00161    }))
00162 
00163 /* Discard a block-description-handle. Returns 1 for an
00164    invalid handle, 0 for a valid handle. */
00165 #define VALGRIND_DISCARD(_qzz_blkindex)                          \
00166    (__extension__ ({unsigned long _qzz_res;                      \
00167     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0 /* default return */, \
00168                             VG_USERREQ__DISCARD,                 \
00169                             0, _qzz_blkindex, 0, 0, 0);          \
00170     _qzz_res;                                                    \
00171    }))
00172 
00173 
00174 /* Client-code macros to check the state of memory. */
00175 
00176 /* Check that memory at _qzz_addr is addressable for _qzz_len bytes.
00177    If suitable addressibility is not established, Valgrind prints an
00178    error message and returns the address of the first offending byte.
00179    Otherwise it returns zero. */
00180 #define VALGRIND_CHECK_MEM_IS_ADDRESSABLE(_qzz_addr,_qzz_len)    \
00181    (__extension__({unsigned long _qzz_res;                       \
00182     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0,                      \
00183                             VG_USERREQ__CHECK_MEM_IS_ADDRESSABLE,\
00184                             _qzz_addr, _qzz_len, 0, 0, 0);       \
00185     _qzz_res;                                                    \
00186    }))
00187 
00188 /* Check that memory at _qzz_addr is addressable and defined for
00189    _qzz_len bytes.  If suitable addressibility and definedness are not
00190    established, Valgrind prints an error message and returns the
00191    address of the first offending byte.  Otherwise it returns zero. */
00192 #define VALGRIND_CHECK_MEM_IS_DEFINED(_qzz_addr,_qzz_len)        \
00193    (__extension__({unsigned long _qzz_res;                       \
00194     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0,                      \
00195                             VG_USERREQ__CHECK_MEM_IS_DEFINED,    \
00196                             _qzz_addr, _qzz_len, 0, 0, 0);       \
00197     _qzz_res;                                                    \
00198    }))
00199 
00200 /* Use this macro to force the definedness and addressibility of an
00201    lvalue to be checked.  If suitable addressibility and definedness
00202    are not established, Valgrind prints an error message and returns
00203    the address of the first offending byte.  Otherwise it returns
00204    zero. */
00205 #define VALGRIND_CHECK_VALUE_IS_DEFINED(__lvalue)                \
00206    VALGRIND_CHECK_MEM_IS_DEFINED(                                \
00207       (volatile unsigned char *)&(__lvalue),                     \
00208                       (unsigned long)(sizeof (__lvalue)))
00209 
00210 
00211 /* Do a full memory leak check (like --leak-check=full) mid-execution. */
00212 #define VALGRIND_DO_LEAK_CHECK                                   \
00213    {unsigned long _qzz_res;                                      \
00214     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0,                      \
00215                             VG_USERREQ__DO_LEAK_CHECK,           \
00216                             0, 0, 0, 0, 0);                      \
00217    }
00218 
00219 /* Do a summary memory leak check (like --leak-check=summary) mid-execution. */
00220 #define VALGRIND_DO_QUICK_LEAK_CHECK                             \
00221    {unsigned long _qzz_res;                                      \
00222     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0,                      \
00223                             VG_USERREQ__DO_LEAK_CHECK,           \
00224                             1, 0, 0, 0, 0);                      \
00225    }
00226 
00227 /* Return number of leaked, dubious, reachable and suppressed bytes found by
00228    all previous leak checks.  They must be lvalues.  */
00229 #define VALGRIND_COUNT_LEAKS(leaked, dubious, reachable, suppressed)     \
00230    /* For safety on 64-bit platforms we assign the results to private
00231       unsigned long variables, then assign these to the lvalues the user
00232       specified, which works no matter what type 'leaked', 'dubious', etc
00233       are.  We also initialise '_qzz_leaked', etc because
00234       VG_USERREQ__COUNT_LEAKS doesn't mark the values returned as
00235       defined. */                                                        \
00236    {unsigned long _qzz_res;                                              \
00237     unsigned long _qzz_leaked    = 0, _qzz_dubious    = 0;               \
00238     unsigned long _qzz_reachable = 0, _qzz_suppressed = 0;               \
00239     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0,                              \
00240                                VG_USERREQ__COUNT_LEAKS,                  \
00241                                &_qzz_leaked, &_qzz_dubious,              \
00242                                &_qzz_reachable, &_qzz_suppressed, 0);    \
00243     leaked     = _qzz_leaked;                                            \
00244     dubious    = _qzz_dubious;                                           \
00245     reachable  = _qzz_reachable;                                         \
00246     suppressed = _qzz_suppressed;                                        \
00247    }
00248 
00249 /* Return number of leaked, dubious, reachable and suppressed bytes found by
00250    all previous leak checks.  They must be lvalues.  */
00251 #define VALGRIND_COUNT_LEAK_BLOCKS(leaked, dubious, reachable, suppressed) \
00252    /* For safety on 64-bit platforms we assign the results to private
00253       unsigned long variables, then assign these to the lvalues the user
00254       specified, which works no matter what type 'leaked', 'dubious', etc
00255       are.  We also initialise '_qzz_leaked', etc because
00256       VG_USERREQ__COUNT_LEAKS doesn't mark the values returned as
00257       defined. */                                                        \
00258    {unsigned long _qzz_res;                                              \
00259     unsigned long _qzz_leaked    = 0, _qzz_dubious    = 0;               \
00260     unsigned long _qzz_reachable = 0, _qzz_suppressed = 0;               \
00261     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0,                              \
00262                                VG_USERREQ__COUNT_LEAK_BLOCKS,            \
00263                                &_qzz_leaked, &_qzz_dubious,              \
00264                                &_qzz_reachable, &_qzz_suppressed, 0);    \
00265     leaked     = _qzz_leaked;                                            \
00266     dubious    = _qzz_dubious;                                           \
00267     reachable  = _qzz_reachable;                                         \
00268     suppressed = _qzz_suppressed;                                        \
00269    }
00270 
00271 
00272 /* Get the validity data for addresses [zza..zza+zznbytes-1] and copy it
00273    into the provided zzvbits array.  Return values:
00274       0   if not running on valgrind
00275       1   success
00276       2   [previously indicated unaligned arrays;  these are now allowed]
00277       3   if any parts of zzsrc/zzvbits are not addressable.
00278    The metadata is not copied in cases 0, 2 or 3 so it should be
00279    impossible to segfault your system by using this call.
00280 */
00281 #define VALGRIND_GET_VBITS(zza,zzvbits,zznbytes)                 \
00282    (__extension__({unsigned long _qzz_res;                       \
00283     char* czza     = (char*)zza;                                 \
00284     char* czzvbits = (char*)zzvbits;                             \
00285     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0,                      \
00286                             VG_USERREQ__GET_VBITS,               \
00287                             czza, czzvbits, zznbytes, 0, 0 );    \
00288     _qzz_res;                                                    \
00289    }))
00290 
00291 /* Set the validity data for addresses [zza..zza+zznbytes-1], copying it
00292    from the provided zzvbits array.  Return values:
00293       0   if not running on valgrind
00294       1   success
00295       2   [previously indicated unaligned arrays;  these are now allowed]
00296       3   if any parts of zza/zzvbits are not addressable.
00297    The metadata is not copied in cases 0, 2 or 3 so it should be
00298    impossible to segfault your system by using this call.
00299 */
00300 #define VALGRIND_SET_VBITS(zza,zzvbits,zznbytes)                 \
00301    (__extension__({unsigned int _qzz_res;                        \
00302     char* czza     = (char*)zza;                                 \
00303     char* czzvbits = (char*)zzvbits;                             \
00304     VALGRIND_DO_CLIENT_REQUEST(_qzz_res, 0,                      \
00305                             VG_USERREQ__SET_VBITS,               \
00306                             czza, czzvbits, zznbytes, 0, 0 );    \
00307     _qzz_res;                                                    \
00308    }))
00309 
00310 #endif
00311