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/files/file_path.h"
11
12namespace 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//
19enum 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  C_TRIM_FAILED = 28,             // TrimLabels failed
52};
53
54// What type of executable is something
55// This is part of the patch format. Never reuse an id number.
56enum ExecutableType {
57  EXE_UNKNOWN = 0,
58  EXE_WIN_32_X86 = 1,
59  EXE_ELF_32_X86 = 2,
60  EXE_ELF_32_ARM = 3,
61  EXE_WIN_32_X64 = 4,
62};
63
64class SinkStream;
65class SinkStreamSet;
66class SourceStream;
67class SourceStreamSet;
68
69class AssemblyProgram;
70class EncodedProgram;
71
72// Applies the patch to the bytes in |old| and writes the transformed ensemble
73// to |output|.
74// Returns C_OK unless something went wrong.
75Status ApplyEnsemblePatch(SourceStream* old, SourceStream* patch,
76                          SinkStream* output);
77
78// Applies the patch in |patch_file_name| to the bytes in |old_file_name| and
79// writes the transformed ensemble to |new_file_name|.
80// Returns C_OK unless something went wrong.
81// This function first validates that the patch file has a proper header, so the
82// function can be used to 'try' a patch.
83Status ApplyEnsemblePatch(const base::FilePath::CharType* old_file_name,
84                          const base::FilePath::CharType* patch_file_name,
85                          const base::FilePath::CharType* new_file_name);
86
87// Generates a patch that will transform the bytes in |old| into the bytes in
88// |target|.
89// Returns C_OK unless something when wrong (unexpected).
90Status GenerateEnsemblePatch(SourceStream* old, SourceStream* target,
91                             SinkStream* patch);
92
93// Detects the type of an executable file, and it's length. The length
94// may be slightly smaller than some executables (like ELF), but will include
95// all bytes the courgette algorithm has special benefit for.
96// On sucess:
97//   Fill in type and detected_length, and return C_OK.
98// On failure:
99//   Fill in type with UNKNOWN, detected_length with 0, and
100//   return C_INPUT_NOT_RECOGNIZED
101Status DetectExecutableType(const void* buffer, size_t length,
102                            ExecutableType* type,
103                            size_t* detected_length);
104
105// Attempts to detect the type of executable, and parse it with the
106// appropriate tools, storing the pointer to the AssemblyProgram in |*output|.
107// Returns C_OK if successful, otherwise returns an error status and sets
108// |*output| to NULL.
109Status ParseDetectedExecutable(const void* buffer, size_t length,
110                               AssemblyProgram** output);
111
112// Trims labels used fewer than a given number of times from an
113// assembly program in-place.
114Status TrimLabels(AssemblyProgram* program);
115
116// Converts |program| into encoded form, returning it as |*output|.
117// Returns C_OK if succeeded, otherwise returns an error status and
118// sets |*output| to NULL
119Status Encode(AssemblyProgram* program, EncodedProgram** output);
120
121// Serializes |encoded| into the stream set.
122// Returns C_OK if succeeded, otherwise returns an error status.
123Status WriteEncodedProgram(EncodedProgram* encoded, SinkStreamSet* sink);
124
125// Assembles |encoded|, emitting the bytes into |buffer|.
126// Returns C_OK if succeeded, otherwise returns an error status and leaves
127// |buffer| in an undefined state.
128Status Assemble(EncodedProgram* encoded, SinkStream* buffer);
129
130// Deserializes program from the stream set.
131// Returns C_OK if succeeded, otherwise returns an error status and
132// sets |*output| to NULL
133Status ReadEncodedProgram(SourceStreamSet* source, EncodedProgram** output);
134
135// Used to free an AssemblyProgram returned by other APIs.
136void DeleteAssemblyProgram(AssemblyProgram* program);
137
138// Used to free an EncodedProgram returned by other APIs.
139void DeleteEncodedProgram(EncodedProgram* encoded);
140
141// Adjusts |program| to look more like |model|.
142//
143Status Adjust(const AssemblyProgram& model, AssemblyProgram *program);
144
145}  // namespace courgette
146#endif  // COURGETTE_COURGETTE_H_
147