palacios/include/xed/xed-decode.h

   1 /*BEGIN_LEGAL
   2 Intel Open Source License
   3
   4 Copyright (c) 2002-2007 Intel Corporation
   5 All rights reserved.
   6 Redistribution and use in source and binary forms, with or without
   7 modification, are permitted provided that the following conditions are
   8 met:
   9
  10 Redistributions of source code must retain the above copyright notice,
  11 this list of conditions and the following disclaimer.  Redistributions
  12 in binary form must reproduce the above copyright notice, this list of
  13 conditions and the following disclaimer in the documentation and/or
  14 other materials provided with the distribution.  Neither the name of
  15 the Intel Corporation nor the names of its contributors may be used to
  16 endorse or promote products derived from this software without
  17 specific prior written permission.
  18
  19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE INTEL OR
  23 ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30 END_LEGAL */
  31 /// @file xed-decode.h
  32 /// @author Mark Charney   <mark.charney@intel.com>
  33
  34
  35 #ifndef _XED_DECODE_H_
  36 # define _XED_DECODE_H_
  37
  38
  39 #include <xed/xed-decoded-inst.h>
  40 #include <xed/xed-error-enum.h>
  41 ////////////////////////////////////////////////////////////////////////////
  42 // DEFINES
  43 ////////////////////////////////////////////////////////////////////////////
  44
  45 ////////////////////////////////////////////////////////////////////////////
  46 // TYPES
  47 ////////////////////////////////////////////////////////////////////////////
  48
  49 ////////////////////////////////////////////////////////////////////////////
  50
  51 ////////////////////////////////////////////////////////////////////////////
  52 // PROTOTYPES
  53 ////////////////////////////////////////////////////////////////////////////
  54
  55 /// This is the main interface to the decoder.
  56 ///  @param xedd the decoded instruction of type #xed_decoded_inst_t . Mode/state sent in via xedd; See the #xed_state_t
  57 ///  @param itext the pointer to the array of instruction text bytes
  58 ///  @param bytes  the length of the itext input array. 1 to 15 bytes, anything more is ignored.
  59 ///  @return #xed_error_enum_t indiciating success (#XED_ERROR_NONE) or failure. Note failure can be due to not
  60 ///  enough bytes in the input array.
  61 ///
  62 /// The maximum instruction is 15B and XED will tell you how long the
  63 /// actual instruction is via an API function call
  64 /// xed_decoded_inst_get_length().  However, it is not always safe or
  65 /// advisable for XED to read 15 bytes if the decode location is at the
  66 /// boundary of some sort of protection limit. For example, if one is
  67 /// decoding near the end of a page and the XED user does not want to cause
  68 /// extra page faults, one might send in the number of bytes that would
  69 /// stop at the page boundary. In this case, XED might not be able to
  70 /// decode the instruction and would return an error. The XED user would
  71 /// then have to decide if it was safe to touch the next page and try again
  72 /// to decode with more bytes.  Also sometimes the user process does not
  73 /// have read access to the next page and this allows the user to prevent
  74 /// XED from causing process termination by limiting the memory range that
  75 /// XED will access.
  76 ///
  77 /// @ingroup DEC
  78 XED_DLL_EXPORT xed_error_enum_t
  79 xed_decode(xed_decoded_inst_t* xedd,
  80            const xed_uint8_t* itext,
  81            const unsigned int bytes);
  82
  83
  84 ////////////////////////////////////////////////////////////////////////////
  85 // GLOBALS
  86 ////////////////////////////////////////////////////////////////////////////
  87
  88
  89 #endif
  90 ////////////////////////////////////////////////////////////////////////////
  91 //Local Variables:
  92 //pref: "../../xed-decode.cpp"
  93 //End: