courgette/courgette.h

   1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef COURGETTE_COURGETTE_H_
   6 #define COURGETTE_COURGETTE_H_
   7
   8 #include <stddef.h>   // Required to define size_t on GCC
   9
  10 #include "base/file_path.h"
  11
  12 namespace courgette {
  13
  14 // Status codes for Courgette APIs.
  15 //
  16 // Client code should only rely on the distintion between C_OK and the other
  17 // status codes.
  18 //
  19 enum Status {
  20   C_OK = 1,                       // Successful operation.
  21
  22   C_GENERAL_ERROR = 2,            // Error other than listed below.
  23
  24   C_READ_OPEN_ERROR = 3,          // Could not open input file for reading.
  25   C_READ_ERROR = 4,               // Could not read from opened input file.
  26
  27   C_WRITE_OPEN_ERROR = 3,         // Could not open output file for writing.
  28   C_WRITE_ERROR = 4,              // Could not write to opened output file.
  29
  30   C_BAD_ENSEMBLE_MAGIC = 5,       // Ensemble patch has bad magic.
  31   C_BAD_ENSEMBLE_VERSION = 6,     // Ensemble patch has wrong version.
  32   C_BAD_ENSEMBLE_HEADER = 7,      // Ensemble patch has corrupt header.
  33   C_BAD_ENSEMBLE_CRC = 8,         // Ensemble patch has corrupt data.
  34
  35   C_BAD_TRANSFORM = 12,           // Transform mis-specified.
  36   C_BAD_BASE = 13,                // Base for transform malformed.
  37
  38   C_BINARY_DIFF_CRC_ERROR = 14,   // Internal diff input doesn't have expected
  39                                   // CRC.
  40
  41   // Internal errors.
  42   C_STREAM_ERROR = 20,            // Unexpected error from streams.h.
  43   C_STREAM_NOT_CONSUMED = 21,     // Stream has extra data, is expected to be
  44                                   // used up.
  45   C_SERIALIZATION_FAILED = 22,    //
  46   C_DESERIALIZATION_FAILED = 23,  //
  47   C_INPUT_NOT_RECOGNIZED = 24,    // Unrecognized input (not an executable).
  48   C_DISASSEMBLY_FAILED = 25,      //
  49   C_ASSEMBLY_FAILED = 26,         //
  50   C_ADJUSTMENT_FAILED = 27,       //
  51 };
  52
  53 // What type of executable is something
  54 // This is part of the patch format. Never reuse an id number.
  55 enum ExecutableType {
  56   EXE_UNKNOWN = 0,
  57   EXE_WIN_32_X86 = 1,
  58   EXE_ELF_32_X86 = 2,
  59 };
  60
  61 class SinkStream;
  62 class SinkStreamSet;
  63 class SourceStream;
  64 class SourceStreamSet;
  65
  66 class AssemblyProgram;
  67 class EncodedProgram;
  68
  69 // Applies the patch to the bytes in |old| and writes the transformed ensemble
  70 // to |output|.
  71 // Returns C_OK unless something went wrong.
  72 Status ApplyEnsemblePatch(SourceStream* old, SourceStream* patch,
  73                           SinkStream* output);
  74
  75 // Applies the patch in |patch_file_name| to the bytes in |old_file_name| and
  76 // writes the transformed ensemble to |new_file_name|.
  77 // Returns C_OK unless something went wrong.
  78 // This function first validates that the patch file has a proper header, so the
  79 // function can be used to 'try' a patch.
  80 Status ApplyEnsemblePatch(const FilePath::CharType* old_file_name,
  81                           const FilePath::CharType* patch_file_name,
  82                           const FilePath::CharType* new_file_name);
  83
  84 // Generates a patch that will transform the bytes in |old| into the bytes in
  85 // |target|.
  86 // Returns C_OK unless something when wrong (unexpected).
  87 Status GenerateEnsemblePatch(SourceStream* old, SourceStream* target,
  88                              SinkStream* patch);
  89
  90 // Detects the type of an executable file, and it's length. The length
  91 // may be slightly smaller than some executables (like ELF), but will include
  92 // all bytes the courgette algorithm has special benefit for.
  93 // On sucess:
  94 //   Fill in type and detected_length, and return C_OK.
  95 // On failure:
  96 //   Fill in type with UNKNOWN, detected_length with 0, and
  97 //   return C_INPUT_NOT_RECOGNIZED
  98 Status DetectExecutableType(const void* buffer, size_t length,
  99                             ExecutableType* type,
 100                             size_t* detected_length);
 101
 102 // Attempts to detect the type of executable, and parse it with the
 103 // appropriate tools, storing the pointer to the AssemblyProgram in |*output|.
 104 // Returns C_OK if successful, otherwise returns an error status and sets
 105 // |*output| to NULL.
 106 Status ParseDetectedExecutable(const void* buffer, size_t length,
 107                                AssemblyProgram** output);
 108
 109 // Converts |program| into encoded form, returning it as |*output|.
 110 // Returns C_OK if succeeded, otherwise returns an error status and
 111 // sets |*output| to NULL
 112 Status Encode(AssemblyProgram* program, EncodedProgram** output);
 113
 114 // Serializes |encoded| into the stream set.
 115 // Returns C_OK if succeeded, otherwise returns an error status.
 116 Status WriteEncodedProgram(EncodedProgram* encoded, SinkStreamSet* sink);
 117
 118 // Assembles |encoded|, emitting the bytes into |buffer|.
 119 // Returns C_OK if succeeded, otherwise returns an error status and leaves
 120 // |buffer| in an undefined state.
 121 Status Assemble(EncodedProgram* encoded, SinkStream* buffer);
 122
 123 // Deserializes program from the stream set.
 124 // Returns C_OK if succeeded, otherwise returns an error status and
 125 // sets |*output| to NULL
 126 Status ReadEncodedProgram(SourceStreamSet* source, EncodedProgram** output);
 127
 128 // Used to free an AssemblyProgram returned by other APIs.
 129 void DeleteAssemblyProgram(AssemblyProgram* program);
 130
 131 // Used to free an EncodedProgram returned by other APIs.
 132 void DeleteEncodedProgram(EncodedProgram* encoded);
 133
 134 // Adjusts |program| to look more like |model|.
 135 //
 136 Status Adjust(const AssemblyProgram& model, AssemblyProgram *program);
 137
 138 }  // namespace courgette
 139 #endif  // COURGETTE_COURGETTE_H_