2 * Copyright (C) 2016 The Android Open Source Project
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
22 // Set TRACE_CHECKSUMHELPER to 1 to debug creation/destruction of GLprotocol
24 #define TRACE_CHECKSUMHELPER 0
26 #if TRACE_CHECKSUMHELPER
27 #define LOG_CHECKSUMHELPER(x...) fprintf(stderr, x)
29 #define LOG_CHECKSUMHELPER(x...)
32 // ChecksumCalculator adds checksum as an array of bytes to GL pipe communication, which
33 // size depends on the protocol version. Each pipe should use one ChecksumCalculator.
35 // (1) take a list of buffers one by one and compute their checksum string,
36 // in this case the checksum should be as the data in those buffers are
38 // (2) compute the checksum of the buffer list, then either write them into
39 // a buffer provided by user, or compare it against a checksum provided
41 // (3) support different checksum version in future.
43 // For backward compatibility, checksum version 0 behaves the same as there is
44 // no checksum (i.e., checksumByteSize returns 0, validate always returns true,
45 // addBuffer and writeCheckSum does nothing).
47 // Notice that to detect package lost, ChecksumCalculator also keeps track of how
48 // many times it generates/validates checksums, and might use it as part of the
51 // To evaluate checksums from a list of data buffers buf1, buf2... Please call
52 // addBuffer(buf1, buf1len), addBuffer(buf2, buf2len) ... in order.
53 // Then if the checksum needs to be encoded into a buffer, one needs to allocate
54 // a checksum buffer with size checksumByteSize(), and call
55 // writeChecksum(checksumBuffer) to write the checksum to the buffer.
56 // If the checksum needs to be validated against an existing one, one needs to
57 // call validate(existChecksum, existChecksumLen).
59 // The checksum generator and validator must be set to the same version, and
60 // the validator must check ALL checksums in the order they are generated,
61 // otherwise the validation function will return false.
63 // It is allowed to change the checksum version between calculating two
64 // checksums. This is designed for backward compatibility reason.
66 // Example 1, encoding and decoding:
68 // bool testChecksum(void* buf, size_t bufLen) {
69 // // encoding message
70 // ChecksumCalculator encoder;
71 // encoder.setVersion(1);
72 // encoder.addBuffer(buf, bufLen);
73 // std::vector<unsigned char> message(bufLen + encoder.checksumByteSize());
74 // memcpy(&message[0], buf, bufLen);
75 // encoder.writeChecksum(&message[0] + bufLen, encoder.checksumByteSize());
77 // // decoding message
78 // ChecksumCalculator decoder;
79 // decoder.setVersion(1);
80 // decoder.addBuffer(&message[0], bufLen);
81 // return decoder.validate(&message[0] + bufLen, decoder.checksumByteSize());
83 // The return value is true.
85 // Example 2, decoding will fail if the order of messages is wrong:
87 // bool testChecksumOrder(void* buf1, size_t bufLen1,
88 // void* buf2, size_t bufLen2) {
89 // // encoding messages
90 // ChecksumCalculator encoder;
91 // encoder.setVersion(1);
93 // std::vector<unsigned char> message1(bufLen1 + encoder.checksumByteSize());
94 // std::vector<unsigned char> message2(bufLen2 + encoder.checksumByteSize());
96 // encoder.addBuffer(buf1, bufLen1);
97 // std::vector<unsigned char> message1(bufLen1 + encoder.checksumByteSize());
98 // memcpy(&message1[0], buf1, bufLen1);
99 // encoder.writeChecksum(&message1[0] + bufLen1, encoder.checksumByteSize());
101 // encoder.addBuffer(buf2, bufLen2);
102 // std::vector<unsigned char> message2(bufLen2 + encoder.checksumByteSize());
103 // memcpy(&message2[0], buf2, bufLen2);
104 // encoder.writeChecksum(&message2[0] + bufLen2, encoder.checksumByteSize());
106 // // decoding messages
107 // ChecksumCalculator decoder;
108 // decoder.setVersion(1);
109 // decoder.addBuffer(&message2[0], bufLen2);
110 // // returns false because the decoding order is not consistent with
112 // if (!decoder.validate(&message2[0]+bufLen2, decoder.checksumByteSize())) {
116 // decoder.addBuffer(&message1[0], bufLen1);
117 // if (!decoder.validate(&message1[0]+bufLen1, decoder.checksumByteSize())) {
124 class ChecksumCalculator {
126 // Get and set current checksum version
127 uint32_t getVersion() const { return m_version; }
128 // Call setVersion to set a checksum version. It should be called before
129 // addBuffer(), writeChecksum() and validate(). And it should be called
130 // exact once per rendering thread if both host and guest support checksum.
131 // It won't be called if either host or guest does not support checksum.
132 bool setVersion(uint32_t version);
134 // Maximum supported checksum version
135 static uint32_t getMaxVersion();
136 // A version string that looks like "ANDROID_EMU_CHECKSUM_HELPER_v1"
137 // Used multiple times when the guest queries the maximum supported version
139 // The library owns the returned pointer. The returned pointer will be
140 // deconstructed when unloading library.
141 static const char* getMaxVersionStr();
142 static const char* getMaxVersionStrPrefix();
144 // Size of checksum in the current version
145 size_t checksumByteSize() const;
147 // Update the current checksum value from the data
148 // at |buf| of |bufLen| bytes. Once all buffers
149 // have been added, call writeChecksum() to store
150 // the final checksum value and reset its state.
151 void addBuffer(const void* buf, size_t bufLen);
152 // Write the checksum from the list of buffers to outputChecksum
153 // Will reset the list of buffers by calling resetChecksum.
154 // Return false if the buffer is not long enough
155 // Please query buffer size from checksumByteSize()
156 bool writeChecksum(void* outputChecksum, size_t outputChecksumLen);
157 // Restore the states for computing checksums.
158 // Automatically called at the end of writeChecksum and validate.
159 // Can also be used to abandon the current checksum being calculated.
160 // Notes: it doesn't update the internal read / write counter
161 void resetChecksum();
163 // Calculate the checksum from the list of buffers and
164 // compare it with the checksum encoded in expectedChecksum
165 // Will reset the list of buffers by calling resetChecksum.
166 bool validate(const void* expectedChecksum, size_t expectedChecksumLen);
168 uint32_t m_version = 0;
169 // A temporary state used to compute the total length of a list of buffers,
170 // if addBuffer is called.
171 uint32_t m_numRead = 0;
172 uint32_t m_numWrite = 0;
173 // m_isEncodingChecksum is true when between addBuffer and writeChecksum
174 bool m_isEncodingChecksum = false;
176 // Compute a 32bit checksum
177 // Used in protocol v1
178 uint32_t computeV1Checksum();
179 // The buffer used in protocol version 1 to compute checksum.
180 uint32_t m_v1BufferTotalLength = 0;