io.h revision a715cb1840f9a0c813c90707a351687f7a77950e
1/* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 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 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 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. 15 */ 16 17#ifndef NVRAM_MESSAGES_IO_H_ 18#define NVRAM_MESSAGES_IO_H_ 19 20extern "C" { 21#include <stddef.h> 22#include <stdint.h> 23} 24 25#include <nvram/messages/blob.h> 26#include <nvram/messages/compiler.h> 27 28namespace nvram { 29 30// Abstraction used by the protobuf decoder to read data. The idea here is that 31// |InputStreamBuffer| maintains a window of the data to be read. Access to the 32// contents of the current window is direct, i.e. doesn't need to go through 33// virtual dispatch to subclasses. Whenever the window is exhausted, the next 34// window must be set up. This latter operation is left for implementation of 35// the virtual |Advance()| member function in subclasses, which is entirely free 36// to pull its data from anywhere. 37class NVRAM_EXPORT InputStreamBuffer { 38 public: 39 InputStreamBuffer() = default; 40 InputStreamBuffer(const void* data, size_t size); 41 InputStreamBuffer(const void* start, const void* end); 42 virtual ~InputStreamBuffer() = default; 43 44 // Checks whether the stream is exhausted; 45 bool Done(); 46 47 // Consume |size| bytes from the stream and store them in the provided |data| 48 // buffer. Returns false if insufficient bytes are available. 49 bool Read(void* data, size_t size); 50 51 // Consume a single byte and place it in |byte|. Returns true if successful, 52 // i.e. if there was a byte available. 53 bool ReadByte(uint8_t* byte); 54 55 // Discard |size| bytes from the stream. Returns false if there are fewer 56 // bytes available. 57 bool Skip(size_t size); 58 59 protected: 60 // Update the |pos_| and |end_| pointers for the next buffer window. Returns 61 // true if the window was successfully set up, false on I/O errors or stream 62 // exhaustion. The default implementation just returns false to signal 63 // immediate stream exhaustion. Subclasses should override this to pull in 64 // more data from the underlying data source. 65 virtual bool Advance(); 66 67 // Pointers to the buffer to read from. |InputStreamBuffer| only advances 68 // |pos_| until reaching |end_|. At this point, |Advance| is called for the 69 // subclass to initialize the next buffer window and update the pointers. 70 const uint8_t* pos_ = nullptr; 71 const uint8_t* end_ = nullptr; 72 73 // Allow |NestedInputStreamBuffer| to mess with |pos_| and |end_|, also in its 74 // delegate, which isn't necessarily of type |NestedInputStreamBuffer|. 75 friend class NestedInputStreamBuffer; 76}; 77 78// An |InputStreamBuffer| implementation that pulls its data from a delegate, 79// but only up to a predetermined limit of bytes. 80class NVRAM_EXPORT NestedInputStreamBuffer : public InputStreamBuffer { 81 public: 82 // Initialize a |NestedInputStreamBuffer| to provide at most |size| bytes from 83 // |delegate|. Note that |delegate| must remain valid throughout the life time 84 // of this |NestedInputStreamBuffer|. 85 NestedInputStreamBuffer(InputStreamBuffer* delegate, size_t size); 86 ~NestedInputStreamBuffer() override = default; 87 88 private: 89 // InputStreamBuffer: 90 bool Advance() override; 91 92 InputStreamBuffer* delegate_; 93 size_t remaining_; 94}; 95 96// Abstraction used by the protobuf decoder to output data. This class maintains 97// a current window of memory to write output to. Access to the current window's 98// bytes is direct and doesn't require virtual dispatch. Once the capacity of 99// the current window is exhausted, the virtual |Advance()| member function is 100// invoked to set up a new window. Subclasses are entirely free to implement 101// this operation as appropriate for their I/O mechanism, for example a 102// socket-based implementations might flush the buffer to the socket and reset 103// the window pointers to accept more output. 104class NVRAM_EXPORT OutputStreamBuffer { 105 public: 106 OutputStreamBuffer() = default; 107 OutputStreamBuffer(void* data, size_t size); 108 OutputStreamBuffer(void* data, void* end); 109 virtual ~OutputStreamBuffer() = default; 110 111 // Checks whether the stream is exhausted. 112 bool Done(); 113 114 // Writes a blob of |size| bytes provided in |data| to the underlying buffer. 115 // Returns false if there is not enough space available. 116 bool Write(const void* data, size_t size); 117 118 // Writes |byte| to the underlying buffer. Returns false if there is not 119 // enough space available. 120 bool WriteByte(uint8_t byte); 121 122 protected: 123 // Set up the next data buffer window in |pos_| and |end_|. Returns true on 124 // success, false on I/O errors or stream exhaustion. The default 125 // implementation unconditionally returns false, i.e. signaling stream 126 // exhaustion after the initial window is filled. Subclasses should override 127 // this to flush buffers to the underlying data sink and set up a fresh buffer 128 // for more data as appropriate. 129 virtual bool Advance(); 130 131 // The |pos_| and |end_| pointers define a window of writable buffer space for 132 // |OutputStreamBuffer| to place data in. |pos_| grows towards |end_| as 133 // writes occur. Once |pos_| hits |end_|, |OutputStreamBuffer| will call 134 // |Advance|, which subclasses can implement to provide a new buffer window in 135 // |pos_| and |end_|. 136 uint8_t* pos_ = nullptr; 137 uint8_t* end_ = nullptr; 138}; 139 140// An |OutputStream| implementation that doesn't write anything, but just counts 141// the number of bytes written. 142class NVRAM_EXPORT CountingOutputStreamBuffer : public OutputStreamBuffer { 143 public: 144 CountingOutputStreamBuffer(); 145 ~CountingOutputStreamBuffer() override = default; 146 147 size_t bytes_written() const { 148 return bytes_written_ + (pos_ - scratch_space_); 149 } 150 151 protected: 152 // OutputStreamBuffer: 153 bool Advance() override; 154 155 private: 156 // We share a single scratch buffer that all |CountingOutputStreamBuffer| 157 // instances use as the destination for writes. Its contents are pretty much 158 // unpredictable. 159 // 160 // TODO(mnissler): This adds a static 256 bytes memory allocation to each 161 // process linking to this code. If that becomes a problem, we might want to 162 // be smarter here and dynamically allocate a chunk of memory only when it's 163 // needed, or maybe even map some address space that's not even backed by 164 // actual memory (not sure that's possible). 165 static constexpr size_t kScratchSpaceSize = 256; 166 static uint8_t scratch_space_[kScratchSpaceSize]; 167 168 // Number of bytes that had been written when the last |Advance()| call 169 // occurred. 170 size_t bytes_written_ = 0; 171}; 172 173// An |OutputStreamBuffer| implementation that stores all data to a wrapped 174// |Blob|, growing it as necessary. 175class NVRAM_EXPORT BlobOutputStreamBuffer : public OutputStreamBuffer { 176 public: 177 // Construct a |BlobOutputStreamBuffer| that stores all written data to 178 // |blob|, which will get resized as necessary. Note that |blob| must remain 179 // valid for the life time of the |BlobOutputStreamBuffer| object. 180 BlobOutputStreamBuffer(Blob* blob); 181 ~BlobOutputStreamBuffer() override = default; 182 183 // Truncate the blob to match the current output size. 184 bool Truncate(); 185 186 protected: 187 // OutputStreamBuffer: 188 bool Advance() override; 189 190 private: 191 Blob* blob_; 192}; 193 194// Protobuf wire types. 195enum class WireType : int8_t { 196 kVarint = 0, 197 kFixed64 = 1, 198 kLengthDelimited = 2, 199 kStartGroup = 3, 200 kEndGroup = 4, 201 kFixed32 = 5, 202}; 203 204// A class implementing a parser for the low-level protobuf wire format. It 205// obtains raw data from a wrapped |InputStream| and offers member functions 206// that facilitate decoding the data according to the protobuf wire format. 207class NVRAM_EXPORT ProtoReader { 208 public: 209 // Construct a new |ProtoReader| that consumes data from |stream_buffer|. 210 // |stream_buffer| must remain valid throughout the life time of the 211 // |ProtoReader|. 212 explicit ProtoReader(InputStreamBuffer* stream_buffer); 213 214 // Access to the underlying stream buffer. 215 InputStreamBuffer* stream_buffer() { return stream_buffer_; } 216 217 // Wire type of the current field. 218 WireType wire_type() const { return static_cast<WireType>(wire_type_); } 219 220 // Field number of the current field. 221 uint64_t field_number() const { return field_number_; } 222 223 // Size of the field data, if known in advance. 224 size_t field_size() const { return field_size_; } 225 226 // Whether all data is consumed. 227 bool Done() const { return stream_buffer_->Done(); } 228 229 // Reads the next wire tag from the current position in the underlying 230 // |stream_buffer_| and initializes internal fields. Previous state is 231 // discarded silently. 232 bool ReadWireTag(); 233 234 // Read a varint-encoded field and advances to the next field. Returns true if 235 // successful. 236 bool ReadVarint(uint64_t* value); 237 238 // Read field data. Checks that |size| matches |field_size()| and copies out 239 // the data to the provided |data| buffer. Advances to the next field and 240 // returns true if successful. 241 bool ReadLengthDelimited(void* data, size_t size); 242 243 // Skips over the current field data. 244 bool SkipField(); 245 246 private: 247 static constexpr int8_t kInvalidWireType = -1; 248 249 InputStreamBuffer* stream_buffer_; 250 251 // Information about the current field. |wire_type == kInvalidWireType| 252 // indicates that there is no current field to be consumed. 253 int8_t wire_type_ = kInvalidWireType; 254 uint64_t field_number_ = 0; 255 size_t field_size_ = 0; 256}; 257 258// |ProtoWriter| contains logic to write raw data according to the protobuf wire 259// format to an |OutputStreamBuffer|. 260class NVRAM_EXPORT ProtoWriter { 261 public: 262 // Construct a |ProtoWriter| which will send its output to |stream_buffer|. 263 // |stream_buffer| must remain valid for the life time of the |ProtoWriter|. 264 explicit ProtoWriter(OutputStreamBuffer* stream_buffer); 265 266 // Access to the underlying stream buffer. 267 OutputStreamBuffer* stream_buffer() { return stream_buffer_; } 268 269 // Sets the field number to use when emitting a tag. 270 void set_field_number(uint64_t field_number) { field_number_ = field_number; } 271 272 // Whether the writer has exhausted the underlying |OutputStream|'s capacity. 273 bool Done() const { return stream_buffer_->Done(); } 274 275 // Write |value| as a varint-encoded field. Returns true if successful, i.e. 276 // the data was successfully written to |stream_buffer_|. 277 bool WriteVarint(uint64_t value); 278 279 // Write |size| bytes stored at |data| to |stream_buffer_|. Returns true if 280 // successful, i.e. the data was successfully written to |stream_buffer_|. 281 bool WriteLengthDelimited(const void* data, size_t size); 282 283 // Writes a wire tag for a length-delimited field, followed by a length 284 // indication for |size| data bytes. It is up to the caller to emit exactly 285 // |size| bytes to |stream_buffer()|, otherwise the encoded data will be 286 // malformed. 287 bool WriteLengthHeader(size_t size); 288 289 private: 290 // A helper to write a wire tag using the current field number and the 291 // provided wire type. 292 bool WriteWireTag(WireType wire_type); 293 294 OutputStreamBuffer* stream_buffer_; 295 uint64_t field_number_ = 0; 296}; 297 298} // namespace nvram 299 300#endif // NVRAM_MESSAGES_IO_H_ 301