src/native_client/src/trusted/validator/x86/ncval_reg_sfi/ncvalidate_iter_detailed.h

   1 /*
   2  * Copyright (c) 2012 The Native Client Authors. All rights reserved.
   3  * Use of this source code is governed by a BSD-style license that can be
   4  * found in the LICENSE file.
   5  */
   6
   7 #ifndef NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_X86_NCVAL_REG_SFI_NCVALIDATE_ITER_DETAILED_H__
   8 #define NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_X86_NCVAL_REG_SFI_NCVALIDATE_ITER_DETAILED_H__
   9
  10 /*
  11  * ncvalidate_iter_details.h: Secondary API for the validator to the
  12  * register-based sandbox.
  13  *
  14  * This is a secondary interface to the x86-64 validator for the register-based
  15  * sandbox. This version should be used when details about reporting errors
  16  * are needed. In particular, this interface should be used when the validator
  17  * is run in verbose or stubout mode. In these cases, getting details right
  18  * (i.e. the instruction that causes a code segment to violate NaCl rules)
  19  * is important. For verbose mode, this implies that the
  20  * error messages will report each instruction that violates a NaCl rule. For
  21  * stubout mode, it will automatically stub out (i.e. replace with HALT
  22  * instructions) instructions that violate NaCl rules.
  23  *
  24  * See ncvalidate_iter.h for the primary interface to the register-based sandbox
  25  * NaCl validator.
  26  *
  27  * This secondary interface is considerbly slower than the primary interface
  28  * in that it does two walks over the code segment instead of one. However, by
  29  * doing this second walk, it can generate more detailed error reports.
  30  * The secondary interface is engaged if one calls
  31  * NaClValidatorStateCreateDetailed  in place of NaClValidatorStateCreate.
  32  * The rest of the interface to the NaCl validator is the same.
  33  *
  34  * Basic usage:
  35  *   -- base is initial address of ELF file.
  36  *   -- limit is the size of the ELF file.
  37  *   -- maddr is the address to the memory of a section.
  38  *   -- vaddr is the starting virtual address associated with a section.
  39  *   -- size is the number of bytes in a section.
  40  *
  41  *   if (!NaClArchSupported()) fail;
  42  *   NaClValidatorState* state =
  43  *     NaClValidatorStateCreateDetailed(base, limit - base, RegR15, features);
  44  *   if (state == NULL) fail;
  45  *   for each section:
  46  *     NaClValidateSegment(maddr, vaddr, size, state);
  47  *   if (!NaClValidatesOk(state)) fail;
  48  *   NaClValidatorStateDestroy(state);
  49  *
  50  * See the README file in this directory for more info on the general
  51  * structure of the validator.
  52  */
  53
  54 #include "native_client/src/trusted/validator/x86/ncval_reg_sfi/ncvalidate_iter.h"
  55
  56 /* Create a validator state to validate the code segment with the given
  57  * parameters, This state is set up to generate detailed errors instead
  58  * of summary (jump) errors.
  59  *
  60  * Note: Messages (if any) produced by the validator are sent to the stream
  61  * defined by native_client/src/shared/platform/nacl_log.h.
  62  *
  63  * Parameters.
  64  *   vbase - The virtual address for the contents of the code segment.
  65  *   sz - The number of bytes in the code segment
  66  *   base_register - OperandKind defining value for base register (or
  67  *     RegUnknown if not defined).
  68  *   features - The CPU features to use. Uses local features of machine if NULL.
  69  * Returns:
  70  *   A pointer to an initialized validator state if everything is ok, NULL
  71  *   otherwise.
  72  */
  73 NaClValidatorState* NaClValidatorStateCreateDetailed(
  74     const NaClPcAddress vbase,
  75     const NaClMemorySize sz,
  76     const NaClOpKind base_register,
  77     const NaClCPUFeaturesX86 *features);
  78
  79 #endif  /* NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_X86_NCVAL_REG_SFI_NCVALIDATE_ITER_DETAILED_H__ */