1 // SPDX-License-Identifier: CDDL-1.0 2 /* 3 * This file and its contents are supplied under the terms of the 4 * Common Development and Distribution License ("CDDL"), version 1.0. 5 * You may only use this file in accordance with the terms of version 6 * 1.0 of the CDDL. 7 * 8 * A full copy of the text of the CDDL should have accompanied this 9 * source. A copy of the CDDL is also available via the Internet at 10 * https://opensource.org/license/CDDL-1.0. 11 */ 12 13 /* 14 * Copyright (c) 2026 by Garth Snyder. All rights reserved. 15 */ 16 17 #ifndef _ZSTREAM_IO_H 18 #define _ZSTREAM_IO_H 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 #include <stddef.h> 25 #include <stdint.h> 26 #include <sys/types.h> 27 #include <sys/zfs_ioctl.h> 28 29 #include "zstream_chain.h" 30 31 #define MAX_IO_STREAMS 4 32 #define MAX_DROP_FILTERS 4 33 34 /* 35 * Masks for serial_drop_record_types() 36 */ 37 38 #define DROP_BEGIN (UINT32_C(1) << DRR_BEGIN) 39 #define DROP_OBJECT (UINT32_C(1) << DRR_OBJECT) 40 #define DROP_FREEOBJECTS (UINT32_C(1) << DRR_FREEOBJECTS) 41 #define DROP_WRITE (UINT32_C(1) << DRR_WRITE) 42 #define DROP_FREE (UINT32_C(1) << DRR_FREE) 43 #define DROP_END (UINT32_C(1) << DRR_END) 44 #define DROP_WRITE_BYREF (UINT32_C(1) << DRR_WRITE_BYREF) 45 #define DROP_SPILL (UINT32_C(1) << DRR_SPILL) 46 #define DROP_WRITE_EMBEDDED (UINT32_C(1) << DRR_WRITE_EMBEDDED) 47 #define DROP_OBJECT_RANGE (UINT32_C(1) << DRR_OBJECT_RANGE) 48 #define DROP_REDACT (UINT32_C(1) << DRR_REDACT) 49 50 /* 51 * The stream offset is the offset within the original source stream. 52 * Changes to the stream (e.g., recompression) will necessarily change 53 * offsets within the final stream. The original stream offset is raw data; 54 * it should never be updated. 55 */ 56 typedef struct { 57 dmu_replay_record_t dp_drr; 58 uint8_t *dp_payload; 59 uint32_t dp_payload_size; 60 off_t dp_stream_offset; 61 } drr_packet_t; 62 63 /* 64 * In the following, the filename or checkpoint names must remain valid 65 * as long as the chain is executing. 66 */ 67 68 chain_step_t 69 serial_read_stream(const char *filename); 70 71 chain_step_t 72 serial_write_stream(const char *filename); 73 74 /* 75 * When payloads change (e.g., after being decompressed), this function 76 * should always be used to intermediate. It frees the old payload and 77 * updates the accounting for total data in flight. To free the old payload 78 * without replacing it, just pass in NULL. 79 */ 80 void 81 set_payload(void *item_in, void *payload, uint64_t size); 82 83 /* 84 * Sometimes, e.g., in the implementation of "zstream raw", we want to take 85 * a payload buffer out of the chain system and hand its control over to some 86 * other system. We need to update the memory accounting but not attempt to 87 * free the buffer. 88 */ 89 void 90 export_payload(void *item_in); 91 92 /* 93 * Report throughput periodically 94 */ 95 chain_step_t 96 serial_checkpoint(const char *name); 97 98 /* 99 * Winnow the stream by dropping records of the given types. This frees up 100 * payload memory used by records you won't be inspecting. If there are 101 * parallel operations downstream of the filter, removing records allows the 102 * parallel queues to be used more efficiently. 103 * 104 * Use the DROP_* defines to construct a mask of the records you want to 105 * remove. If you want to remove most records, it's fine to pass an inverted 106 * mask formed by enumerating only the records you want to keep, e.g.: 107 * 108 * serial_drop_record_types((uint32_t)~(DROP_WRITE | DROP_WRITE_EMBEDDED)) 109 * 110 * This step should be placed downstream of byteswapping, since it relies on 111 * being able to read drr->drr_type. 112 */ 113 chain_step_t 114 serial_drop_record_types(uint32_t drop_mask); 115 116 /* 117 * Usually the output step is responsible for freeing payloads. Subcommands 118 * that don't have stream outputs still need to free this memory. A 119 * serial_null_output step does this and nothing more. 120 */ 121 chain_step_t 122 serial_null_output(void); 123 124 /* Off-the-shelf zstream_queue cost functions */ 125 126 size_t 127 constant_cost_of_one(queue_item_t *packet, void *context); 128 129 size_t 130 payload_size_as_cost(queue_item_t *packet, void *context); 131 132 #ifdef __cplusplus 133 } 134 #endif 135 136 #endif /* _ZSTREAM_IO_H */ 137