// This file is part of BOINC. // http://boinc.berkeley.edu // Copyright (C) 2008 University of California // // BOINC is free software; you can redistribute it and/or modify it // under the terms of the GNU Lesser General Public License // as published by the Free Software Foundation, // either version 3 of the License, or (at your option) any later version. // // BOINC is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. // See the GNU Lesser General Public License for more details. // // You should have received a copy of the GNU Lesser General Public License // along with BOINC. If not, see . /* * QTaskMemory.h * */ /* This is part of a backtrace generator for boinc project applications. * * Adapted from Apple Developer Technical Support Sample Code QCrashReport * * This code handles Mac OS X 10.3.x through 10.4.9. It may require some * adjustment for future OS versions; see the discussion of _sigtramp and * PowerPC Signal Stack Frames in file QBacktrace.c. * * For useful tips on using backtrace information, see Apple Tech Note 2123: * http://developer.apple.com/technotes/tn2004/tn2123.html#SECNOSYMBOLS * * To convert addresses to correct symbols, use the atos command-line tool: * atos -o path/to/executable/with/symbols address * Note: if address 1a23 is hex, use 0x1a23. * * To demangle mangled C++ symbols, use the c++filt command-line tool. * You may need to prefix C++ symbols with an additonal underscore before * passing them to c++filt (so they begin with two underscore characters). * * A very useful shell script to add symbols to a crash dump can be found at: * http://developer.apple.com/tools/xcode/symbolizingcrashdumps.html * Pipe the output of the shell script through c++filt to demangle C++ symbols. */ /* File: QTaskMemory.h Contains: Task memory access abstraction. Written by: DTS Copyright: Copyright (c) 2007 Apple Inc. All Rights Reserved. Disclaimer: IMPORTANT: This Apple software is supplied to you by Apple Inc. ("Apple") in consideration of your agreement to the following terms, and your use, installation, modification or redistribution of this Apple software constitutes acceptance of these terms. If you do not agree with these terms, please do not use, install, modify or redistribute this Apple software. In consideration of your agreement to abide by the following terms, and subject to these terms, Apple grants you a personal, non-exclusive license, under Apple's copyrights in this original Apple software (the "Apple Software"), to use, reproduce, modify and redistribute the Apple Software, with or without modifications, in source and/or binary forms; provided that if you redistribute the Apple Software in its entirety and without modifications, you must retain this notice and the following text and disclaimers in all such redistributions of the Apple Software. Neither the name, trademarks, service marks or logos of Apple Inc. may be used to endorse or promote products derived from the Apple Software without specific prior written permission from Apple. Except as expressly stated in this notice, no other rights or licenses, express or implied, are granted by Apple herein, including but not limited to any patent rights that may be infringed by your derivative works or by other works in which the Apple Software may be incorporated. The Apple Software is provided by Apple on an "AS IS" basis. APPLE MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN COMBINATION WITH YOUR PRODUCTS. IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Change History (most recent first): $Log: QTaskMemory.h,v $ Revision 1.1 2007/03/02 12:20:40 First checked in. */ #ifndef _QTASKMEMORY_H #define _QTASKMEMORY_H ///////////////////////////////////////////////////////////////// #include // Put inside extern "C" guards for the C++ build // because the Mach header files don't always have them. #if defined(__cplusplus) extern "C" { #endif #include #if defined(__cplusplus) } #endif ///////////////////////////////////////////////////////////////// #ifdef __cplusplus extern "C" { #endif /*! @header QTaskMemory.h @abstract Abstraction layer for reading another process's memory. @discussion This module lets you read memory from another task. It's implemented using Mach APIs that are designed for that very job. The purpose of this module is to make those routines easier to call, handling the various nasty compatibility problems that arise. See the comments inside "QTaskMemory.c" for the gory details. When using this module, keep in mind that addresses within a remote task are represented by an unsigned 64-bit integer (QTMAddr). This is necessary because it lets a 32-bit tool examine a 64-bit task. -- Changed for BOINC: See comments in QTaskMemory.c Because of oddities in the underlying infrastructure (specifically, mach_vm_read does odd things if you ask for a size of zero -- it returns KERN_SUCCESS, addrLocal == 0, bytesRead == 0), we don't allow clients to request a size of zero. */ /*! @functiongroup Main Interface */ ///////////////////////////////////////////////////////////////// #pragma mark ***** Main Interface /*! @typedef QTMAddr @abstract Represents an address within a task. @discussion This type represents an address within a task. We can't just use use (void *) because we need to be able to represent 64-bit addresses, even if we're built 32-bit. */ #if TARGET_CPU_X86 || TARGET_CPU_X86_64 typedef mach_vm_address_t QTMAddr; #else typedef uint64_t QTMAddr; #endif /*! @typedef QTMOffset @abstract Represents a byte offset between two QTMAddrs. @discussion This type represents a byte offset between two QTMAddrs. We can't just use use ptrdiff_t or size_t because we need to be able to represent a 64-bit offset, even if we're built 32-bit. */ #if TARGET_CPU_X86 || TARGET_CPU_X86_64 typedef mach_vm_offset_t QTMOffset; #else typedef uint64_t QTMOffset; #endif /*! @function QTMRead @abstract Reads memory from a task. @discussion Read size bytes from addrWithinTask of the task to the buffer specified by addrLocal. There are no partial results; you either get size bytes of data or an error. @param task Must be the name of a valid send right for the task control port of the task whose memory you want to read; mach_task_self is just fine. @param addrWithinTask The address within that task of the memory you want to read. @param size The number of bytes that you want to read; there must be this many bytes available in the buffer pointed to by addrLocal. It must not be zero. @param addrLocal The address of the buffer into which you want to read the bytes. @result An errno-style error code per QTMErrnoFromMachError. */ extern int QTMRead(task_t task, QTMAddr addrWithinTask, size_t size, void *addrLocal); /*! @function QTMReadAllocated @abstract Allocates a buffer and reads memory from a task into it. @discussion Read size bytes from addrWithinTask of the task to a newly allocated buffer, and return a pointer to that buffer in *bufPtr. The client is responsible for freeing the buffer by calling QTMFree. @param task Must be the name of a valid send right for the task control port of the task whose memory you want to read; mach_task_self is just fine. @param addrWithinTask The address within that task of the memory you want to read. @param size The number of bytes that you want to read. It must not be zero. @param bufPtr On entry, bufPtr must not be NULL and *bufPtr must be NULL. On success, *bufPtr will point to a buffer of at least size bytes. You must free the buffer by calling QTMFree. On failure, *bufPtr will be NULL. @result An errno-style error code per QTMErrnoFromMachError. */ extern int QTMReadAllocated(task_t task, QTMAddr addrWithinTask, size_t size, const void **bufPtr); /*! @function QTMRemap @abstract Maps memory from a task into your address space. @discussion Maps size bytes of memory from addrWithinTask to the current task and returns the address of the newly mapped data in *bufPtr. The client is responsible for freeing the buffer by calling QTMFree. @param task Must be the name of a valid send right for the task control port of the task whose memory you want to map; mach_task_self is just fine. @param addrWithinTask The address within that task of the memory you want to map. @param size The number of bytes that you want to map. It must not be zero. @param bufPtr On entry, bufPtr must not be NULL and *bufPtr must be NULL. On success, *bufPtr will point to a buffer of at least size bytes. You must free the buffer by calling QTMFree. On failure, *bufPtr will be NULL. @result An errno-style error code per QTMErrnoFromMachError. */ extern int QTMRemap(task_t task, QTMAddr addrWithinTask, size_t size, const void **bufPtr); /*! @function QTMFree @abstract Free data returned by QTMReadAllocated or QTMRemap. @discussion Free data returned by QTMReadAllocated or QTMRemap. @param buf The buffer to free. This may be NULL, in which case the routine does nothing. @param size The size of the buffer to free. If buf is NULL, this value is ignored. If buf is not NULL, this must bee the same value as passed to the routine that allocated the memory (and hence must not be 0). */ extern void QTMFree(const void *buf, size_t size); /*! @functiongroup Utilities */ ///////////////////////////////////////////////////////////////// #pragma mark ***** Utilities /*! @function QTMErrnoFromMachError @abstract Converts a Mach error code to a errno-style error code. @discussion Various other modules call Mach directly for various reasons, and these need to translate Mach-style errors into errno-style errors. This module already has a helper routine to do that job, so I export it. IMPORTANT: This routine can still return errors outside of the errno range. What it does is as follows: 1. If the Mach error is something obvious that we recognise, map it to a specific errno-style error. 2. Failing that, if the Mach error is outside of the errno range (and thus it's not ambiguous as to whether the error is a Mach error or an errno error), just return it. 3. For unrecognised Mach errors within the errno range, just return EINVAL. The upshot is that if an error is outside of the errno range [0..ELAST], you should treat it as a Mach error. @param kr A Mach error code. @result An errno-style error code. */ extern int QTMErrnoFromMachError(kern_return_t kr); /*! @enum QTMDarwinOSMajor @abstract Constants for Darwin OS release major values. @constant kQTMDarwinOSMajorForMacOSX102 The Darwin OS release major value for Mac OS X 10.2.x. @constant kQTMDarwinOSMajorForMacOSX103 The Darwin OS release major value for Mac OS X 10.3.x. @constant kQTMDarwinOSMajorForMacOSX104 The Darwin OS release major value for Mac OS X 10.4.x. */ enum QTMDarwinOSMajor { kQTMDarwinOSMajorForMacOSX102 = 6, kQTMDarwinOSMajorForMacOSX103 = 7, kQTMDarwinOSMajorForMacOSX104 = 8 }; /*! @function QTMGetDarwinOSRelease @abstract Returns the Darwin OS release numbers. @discussion Returns the Darwin OS release numbers for the current system. It gets these values by calling uname and parsing the results. For example, the major/minor/bug values for Mac OS X 10.4.8 will be 8/8/x (where x is dependent on the particular release). This is useful in environments, like a 64-bit process running on Mac OS X 10.4.x, where you can't get gestaltSystemVersion. @param majorPtr May be NULL, in which case no value is return. Otherwise, on entry, *majorPtr is ignored and, on success, *majorPtr will be set to the Darwin OS release major component. @param minorPtr May be NULL, in which case no value is return. Otherwise, on entry, *minorPtr is ignored and, on success, *minorPtr will be set to the Darwin OS release minor component. @param bugPtr May be NULL, in which case no value is return. Otherwise, on entry, *bugPtr is ignored and, on success, *bugPtr will be set to the Darwin OS release bug fix component. @result An errno-style error number. */ extern int QTMGetDarwinOSRelease(int *majorPtr, int *minorPtr, int *bugPtr); // Get the Darwin OS release using uname. I can't use gestaltSystemVersion // because it's part of CoreServices, and CoreServices is not available // to 64-bit programs on Mac OS X 10.4.x. /*! @function QTMTaskIs64Bit @abstract Determines whether a task is 64-bit. @discussion Returns true if the specified task is 64-bit. @param task Must be the name of a valid send right for the task control port of the task; mach_task_self should work just fine. @result Returns true if the task is 64-bit and false otherwise. If something goes wrong, you get the default value of false. */ extern bool QTMTaskIs64Bit(task_t task); /*! @function QTMTaskIsNative @abstract Determines whether a task is native. @discussion Returns false if the specified task is being run using Rosetta. @param task Must be the name of a valid send right for the task control port of the task; mach_task_self should work just fine. @result Returns false if the task is being run by Rosetta and false otherwise. If something goes wrong, you get the default value of true. */ extern bool QTMTaskIsNative(task_t task); // I'm not ever going to try to explain how this works (-: // // Apple doesn't generally recommend, and hence doesn't officially document, // the Mach API. If you search the web for "vm_region", you'll find our // unofficial documentation. #ifdef __cplusplus } #endif #endif