1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
// Copyright 2018 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef COMPONENTS_ZUCCHINI_DISASSEMBLER_ZTF_H_
#define COMPONENTS_ZUCCHINI_DISASSEMBLER_ZTF_H_
#include <stdint.h>
#include <stdlib.h>
#include <memory>
#include <optional>
#include <string>
#include <vector>
#include "components/zucchini/disassembler.h"
#include "components/zucchini/image_utils.h"
#include "components/zucchini/type_ztf.h"
namespace zucchini {
// Disassembler for text based files. This file format is supported for
// debugging Zucchini and is not intended for production usage.
//
// A valid Zucchini Text Format (ZTF) file is specified as follows:
//
// Header:
// The first four bytes must be - 'Z' 'T' 'x' 't'
// Footer:
// The last five bytes must be - 't' 'x' 'T' 'Z' '\n'
// (note that terminating new line is required).
// Content:
// The content can be any sequence of printable ASCII characters and new line
// (but not carriage return). This excludes the sequence that comprises the
// Footer.
// References:
// A reference is either Absolute or Relative. All references must begin and
// end with a pair of enclosing characters <open>, <close>. The options are:
// - Angles: '<' and '>'
// - Braces: '{' and '}'
// - Brackets: '[' and ']'
// - Parentheses: '(' and ')'
//
// A reference contains three items:
// - A line number <line>
// - A delimiter ',' <delimiter>
// - A column number <col>
// <line> and <col> may contain 1-3 digits and both must contain the same
// number of digits. If a number is too short then it can be left-padded
// with '0'.
//
// For Absolute references, <line> and <col> are 1-based (i.e. positive)
// index of line and column numbers of a character in the ZTF. This follows
// standard convention for text editors. Note that "\n" is considered to be
// part of a preceding line.
//
// <open><line><delimiter><col><close>
//
// For Relative references, <line> and <col> are integer offsets deltas of the
// target's (absolute) line and column relative to the line and column of the
// reference's first byte (i.e. <open>). Relative references have <sign> ('+'
// or '-') before <line> and <col>. For the special case of "0", "00", etc.,
// <sign> must be "+".
//
// <open><sign><line><delimiter><sign><col><close>
//
// If a reference points outside the target either in writing or reading it is
// considered invalid and ignored. Similarly if it overflows a line. i.e. if a
// line is 10 characters long and a references targets character 11 of that
// line it is rejected. Lines are delimited with '\n' which is counted toward
// the line length.
//
// If a reference is to be written that would overwrite a '\n' character it is
// ignored as this would break all other line values.
enum : size_t { kMaxDigitCount = 3 };
// Helper class for translating among offset_t, ztf::LineCol and
// ztf::DeltaLineCol.
class ZtfTranslator {
public:
ZtfTranslator();
ZtfTranslator(const ZtfTranslator&) = delete;
const ZtfTranslator& operator=(const ZtfTranslator&) = delete;
~ZtfTranslator();
// Initializes |line_starts_| with the contents of |image|.
bool Init(ConstBufferView image);
// Checks if |lc| is a valid location in the file.
bool IsValid(ztf::LineCol lc) const;
// Checks if |dlc| relative to |offset| is a valid location in the file.
bool IsValid(offset_t offset, ztf::DeltaLineCol dlc) const;
// Returns the offset corresponding to |line_col| if it is valid. Otherwise
// returns |kInvalidOffset|.
offset_t LineColToOffset(ztf::LineCol line_col) const;
// Returns the ztf::LineCol for an |offset| if it is valid. Otherwise returns
// std::nullopt.
std::optional<ztf::LineCol> OffsetToLineCol(offset_t offset) const;
private:
// Returns an iterator to the range containing |offset|. Which is represented
// by the starting offset. The next element will contain the upper bound of
// the range.
std::vector<offset_t>::const_iterator SearchForRange(offset_t offset) const;
// Returns the length of a 1-indexed line. The caller is expected to check
// that the requested line exists.
offset_t LineLength(uint16_t line) const;
offset_t NumLines() const {
return static_cast<offset_t>(line_starts_.size() - 1);
}
// |line_starts_| is a sorted list of each line's starting offset, along with
// the image size as the sentinel; it looks like {0, ..., image.size}.
std::vector<offset_t> line_starts_;
};
// Disassembler for Zucchini Text Format (ZTF).
class DisassemblerZtf : public Disassembler {
public:
static constexpr uint16_t kVersion = 1;
// Target Pools
enum ReferencePool : uint8_t {
kAngles, // <>
kBraces, // {}
kBrackets, // []
kParentheses // ()
};
// Type breakdown. Should contain all permutations of ReferencePool, Abs|Rel
// and the possible number of digits (1-3).
enum ReferenceType : uint8_t {
kAnglesAbs1,
kAnglesAbs2,
kAnglesAbs3,
kAnglesRel1,
kAnglesRel2,
kAnglesRel3,
kBracesAbs1,
kBracesAbs2,
kBracesAbs3,
kBracesRel1,
kBracesRel2,
kBracesRel3,
kBracketsAbs1,
kBracketsAbs2,
kBracketsAbs3,
kBracketsRel1,
kBracketsRel2,
kBracketsRel3,
kParenthesesAbs1,
kParenthesesAbs2,
kParenthesesAbs3,
kParenthesesRel1,
kParenthesesRel2,
kParenthesesRel3,
kNumTypes
};
DisassemblerZtf();
DisassemblerZtf(const DisassemblerZtf&) = delete;
const DisassemblerZtf& operator=(const DisassemblerZtf&) = delete;
~DisassemblerZtf() override;
// Applies quick checks to determine if |image| *may* point to the start of a
// ZTF file. Returns true on success.
static bool QuickDetect(ConstBufferView image);
// Disassembler:
ExecutableType GetExeType() const override;
std::string GetExeTypeString() const override;
std::vector<ReferenceGroup> MakeReferenceGroups() const override;
// Reference Readers, templated to allow configurable digit count and pool.
template <uint8_t digits, ReferencePool pool>
std::unique_ptr<ReferenceReader> MakeReadAbs(offset_t lo, offset_t hi);
template <uint8_t digits, ReferencePool pool>
std::unique_ptr<ReferenceReader> MakeReadRel(offset_t lo, offset_t hi);
// Reference Writers, templated to allow configurable digit count and pool.
template <uint8_t digits, ReferencePool pool>
std::unique_ptr<ReferenceWriter> MakeWriteAbs(MutableBufferView image);
template <uint8_t digits, ReferencePool pool>
std::unique_ptr<ReferenceWriter> MakeWriteRel(MutableBufferView image);
private:
friend Disassembler;
// Disassembler:
bool Parse(ConstBufferView image) override;
ZtfTranslator translator_;
};
} // namespace zucchini
#endif // COMPONENTS_ZUCCHINI_DISASSEMBLER_ZTF_H_
|
