1 /* 2 * Copyright (C) 2022 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 INCLUDE_PERFETTO_PUBLIC_ABI_STREAM_WRITER_ABI_H_ 18 #define INCLUDE_PERFETTO_PUBLIC_ABI_STREAM_WRITER_ABI_H_ 19 20 #include <stddef.h> 21 #include <stdint.h> 22 23 #include "perfetto/public/abi/export.h" 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 // An opaque structure used to represent the internal implementation of a 30 // protozero stream writer. 31 struct PerfettoStreamWriterImpl; 32 33 // A `PerfettoStreamWriter` owns a chunk of memory that the user can write 34 // to. The section from `begin` (inclusive) to `write_ptr` (non inclusive) 35 // already contains valid data. The section from `write_ptr` (inclusive) to 36 // `end` (non inclusive) is empty and can be used for new data. 37 // 38 // -------------------------------------------------------------------------- 39 // |wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww | 40 // -------------------------------------------------------------------------- 41 // ^ ^ ^ 42 // \ | / 43 // `begin` `write_ptr` `end` 44 struct PerfettoStreamWriter { 45 struct PerfettoStreamWriterImpl* impl; 46 47 // Points to the first byte of the current chunk. 48 uint8_t* begin; 49 50 // Points to the first byte after the end of the current chunk (STL-style). 51 uint8_t* end; 52 53 // Write pointer: points to the first not-yet-written byte of the current 54 // chunk. 55 uint8_t* write_ptr; 56 57 // Keeps track of all the bytes written in previous chunks (bytes written in 58 // the current chunk are not included here). 59 size_t written_previously; 60 }; 61 62 // Tells the writer that the current chunk has been written until `write_ptr` 63 // (non inclusive). 64 // 65 // Returns the new state of the writer. 66 PERFETTO_SDK_EXPORT void PerfettoStreamWriterUpdateWritePtr( 67 struct PerfettoStreamWriter*); 68 69 // Commits the current chunk and gets a new chunk. 70 PERFETTO_SDK_EXPORT void PerfettoStreamWriterNewChunk( 71 struct PerfettoStreamWriter*); 72 73 // Appends `size` from `src` to the writer. 74 PERFETTO_SDK_EXPORT void PerfettoStreamWriterAppendBytesSlowpath( 75 struct PerfettoStreamWriter*, 76 const uint8_t* src, 77 size_t size); 78 79 #define PERFETTO_STREAM_WRITER_PATCH_SIZE 4 80 81 // Tells the stream writer that the part of the current chunk pointed by 82 // `patch_addr` (until `patch_addr`+`PERFETTO_STREAM_WRITER_PATCH_SIZE`) needs 83 // to be changed after the current chunk goes away. 84 // 85 // The caller can write to the returned location (which may have been redirected 86 // by the stream writer) after the current chunk has gone away. The caller 87 // **must write a non-zero value as the first byte** eventually. 88 // 89 // The stream writer can also return NULL, in which case the caller should not 90 // write anything. 91 // 92 // This can be used to backfill the size of a protozero message. 93 PERFETTO_SDK_EXPORT uint8_t* PerfettoStreamWriterAnnotatePatch( 94 struct PerfettoStreamWriter*, 95 uint8_t* patch_addr); 96 97 // Returns a pointer to an area of the chunk long `size` for writing. The 98 // returned area is considered already written by the writer (it will not be 99 // used again). 100 // 101 // WARNING: `size` should be smaller than the chunk size returned by the 102 // `delegate`. 103 PERFETTO_SDK_EXPORT 104 void PerfettoStreamWriterReserveBytesSlowpath(struct PerfettoStreamWriter*, 105 size_t size); 106 107 #ifdef __cplusplus 108 } 109 #endif 110 111 #endif // INCLUDE_PERFETTO_PUBLIC_ABI_STREAM_WRITER_ABI_H_ 112