| 1 | /* |
| 2 | * ========== Copyright Header Begin ========================================== |
| 3 | * |
| 4 | * OpenSPARC T2 Processor File: Rstzip.H |
| 5 | * Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. |
| 6 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES. |
| 7 | * |
| 8 | * The above named program is free software; you can redistribute it and/or |
| 9 | * modify it under the terms of the GNU General Public |
| 10 | * License version 2 as published by the Free Software Foundation. |
| 11 | * |
| 12 | * The above named program is distributed in the hope that it will be |
| 13 | * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 15 | * General Public License for more details. |
| 16 | * |
| 17 | * You should have received a copy of the GNU General Public |
| 18 | * License along with this work; if not, write to the Free Software |
| 19 | * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. |
| 20 | * |
| 21 | * ========== Copyright Header End ============================================ |
| 22 | */ |
| 23 | // ========== Copyright Header Begin ========================================== |
| 24 | // |
| 25 | // OpenSPARC T2 Processor File: Rstzip.H |
| 26 | // Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. |
| 27 | // DO NOT ALTER OR REMOVE COPYRIGHT NOTICES. |
| 28 | // |
| 29 | // The above named program is free software; you can redistribute it and/or |
| 30 | // modify it under the terms of the GNU General Public |
| 31 | // License version 2 as published by the Free Software Foundation. |
| 32 | // |
| 33 | // The above named program is distributed in the hope that it will be |
| 34 | // useful, but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 35 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 36 | // General Public License for more details. |
| 37 | // |
| 38 | // You should have received a copy of the GNU General Public |
| 39 | // License along with this work; if not, write to the Free Software |
| 40 | // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. |
| 41 | // |
| 42 | // ========== Copyright Header End ============================================ |
| 43 | #ifndef _Rstzip_H_ |
| 44 | #define _Rstzip_H_ |
| 45 | |
| 46 | // version number of Rstzip.H interface. not of the rstzip library |
| 47 | #define RSTZIP_VERSION_STR "3.19" |
| 48 | |
| 49 | #include"rstf/rstf.h" |
| 50 | // #include "Compressor.H" |
| 51 | |
| 52 | |
| 53 | #ifdef __cplusplus |
| 54 | extern "C" { |
| 55 | #endif |
| 56 | |
| 57 | typedef enum { |
| 58 | RSTZIP_OK = 1, |
| 59 | RSTZIP_ERROR = -1 |
| 60 | } RstzipReturnVals; |
| 61 | |
| 62 | // this constant is provided as the default optimal buffer size. |
| 63 | // alternative buffer sizes may be specified to the compressor using the options string |
| 64 | // FIXME: the rstzip object can be queried for the buffer size of the input trace after the open() call |
| 65 | |
| 66 | const int rstzip_opt_buffersize = 1<<15; // new since library version 3.22 |
| 67 | |
| 68 | #ifdef __cplusplus |
| 69 | } |
| 70 | #endif |
| 71 | |
| 72 | #ifdef __cplusplus |
| 73 | |
| 74 | // ==== C++ Compression example ==== |
| 75 | // |
| 76 | // rz = new Rstzip; |
| 77 | // rz->open(outfile, "w", "verbose=0"); |
| 78 | // nrecs = fread(rstbuf, sizeof(rstf_unionT), RZ_opt_bufsize, infp); |
| 79 | // while (nrecs > 0) { |
| 80 | // rstzip->compress(rstbuf, nrecs); |
| 81 | // nrecs = fread(rstbuf, sizeof(rstf_unionT), opt_bufsize, infp); |
| 82 | // } |
| 83 | // rz->close(); |
| 84 | // delete rz; |
| 85 | |
| 86 | // ==== C++ Decompression example ==== |
| 87 | // |
| 88 | // rz = new Rstzip; |
| 89 | // rz->open(infile, "r", "verbose=0"); |
| 90 | // nrecs = rstzip->decompress(rstbuf, RZ_opt_bufsize); |
| 91 | // while (nrecs > 0) { |
| 92 | // fwrite(rstbuf, sizeof(rstf_unionT), nrecs, outfp); |
| 93 | // nrecs = rz->decompress(rstbuf, RZ_opt_bufsize; |
| 94 | // } |
| 95 | // rz->close(); |
| 96 | |
| 97 | // class Rstzip : public Compressor { |
| 98 | class Rstzip { |
| 99 | public: |
| 100 | Rstzip(); |
| 101 | |
| 102 | ~Rstzip(); |
| 103 | |
| 104 | // SYNOPSIS |
| 105 | // virtual int getMajorVersion(); |
| 106 | // virtual int getMinorVersion(); |
| 107 | // virtual const char* getVersionStr(); |
| 108 | // |
| 109 | // DESCRIPTION |
| 110 | // Return compressor library version information. |
| 111 | virtual int getMajorVersion(); |
| 112 | |
| 113 | virtual int getMinorVersion(); |
| 114 | |
| 115 | virtual const char* getVersionStr(); |
| 116 | |
| 117 | // SYNOPSIS |
| 118 | // virtual int |
| 119 | // open(const char* file, const char* md, const char* options) |
| 120 | // |
| 121 | // DESCRIPTION |
| 122 | // Opens 'file' for compressing or decompressing, and associates the |
| 123 | // rstzip object with it. |
| 124 | // |
| 125 | // The argument 'md' points to a string with one of the following |
| 126 | // sequences: |
| 127 | // r Open the compressed file for reading (decompression). |
| 128 | // w Open the noncompressed file for writing (compression). |
| 129 | // One of "r" and "w" must be specified. |
| 130 | // |
| 131 | // If the file parameter is NULL, the input file is set to stdin or stdout |
| 132 | // depending on the mode: stdin if "r" and stdout if "w" |
| 133 | // |
| 134 | // options: all rstzip2 options are optional with this version. |
| 135 | // Unrecognized options will be discarded. Recognized options are: |
| 136 | // |
| 137 | // verbose=0|1 <= produce verbose output while compressing/decompressing |
| 138 | // stats=0|1 <= print compression statistics |
| 139 | // ver=0|1|2|3 <= for decompression only: specify version of incoming file |
| 140 | // |
| 141 | // when opening a disk file, rstzip detects its version automatically. |
| 142 | // however, when reading from stdin, rstzip v3 is assumed unless specified in |
| 143 | // this manner. If more than one version is specified, results are unpredictable |
| 144 | // Version 0 indicates a RAW RST trace file. |
| 145 | // |
| 146 | // FIXME: ADD information about buffersize here |
| 147 | // |
| 148 | // Note: normally, a raw RST trace can be detected by the presence of a valid RST |
| 149 | // Header record. However, if this record is absent, manually specifying ver=0 is |
| 150 | // the only way to indicate to rstzip that the input file is a raw rst file. |
| 151 | // |
| 152 | // example: const char * rz3_options = "verbose=0 stats=1" |
| 153 | // |
| 154 | // RETURN VALUES |
| 155 | // Returns RSTZIP_OK (1) if the file is successfully opened; returns |
| 156 | // RSTZIP_ERROR (-1) otherwise. |
| 157 | virtual int open(const char* file, const char* md, const char* options); |
| 158 | |
| 159 | // SYNOPSIS |
| 160 | // virtual int compress(rstf_unionT* rstbuf, int nrecs); |
| 161 | // |
| 162 | // DESCRIPTION |
| 163 | // Compresses exactly 'nrecs' RST records from 'rstbuf', and writes |
| 164 | // the compressed data to the file opened by open(). |
| 165 | // |
| 166 | // For best performance, 'nrecs' should be set to rstzip_opt_buffersize |
| 167 | // or an integral multiple thereof. This minimizes memcpy() overhead. |
| 168 | // |
| 169 | // RETURN VALUES |
| 170 | // The number of RST records compressed is returned; this value |
| 171 | // should be equal to 'nrecs'. |
| 172 | virtual int compress(rstf_unionT* rstbuf, int nrecs); |
| 173 | |
| 174 | // SYNOPSIS |
| 175 | // virtual int decompress(rstf_unionT* rstbuf, int nrecs); |
| 176 | // |
| 177 | // DESCRIPTION |
| 178 | // Decompresses up to 'nrecs' records from the file opened by |
| 179 | // open(), and writes the decompressed records into 'rstbuf'. |
| 180 | // |
| 181 | // For best performance, 'nrecs' should be set to rstzip3_opt_buffersize |
| 182 | // or an integral multiple thereof. This minimizes memcpy() overhead. |
| 183 | // |
| 184 | // |
| 185 | // RETURN VALUES |
| 186 | // The number of RST records decompressed is returned; this value |
| 187 | // should be equal to 'nrecs', unless the end of the compressed |
| 188 | // trace is reached. Subsequent calls to decompress() will return 0. |
| 189 | virtual int decompress(rstf_unionT* rstbuf, int nrecs); |
| 190 | |
| 191 | // SYNOPSIS |
| 192 | // virtual void close(); |
| 193 | // |
| 194 | // DESCRIPTION |
| 195 | // Flushes all internal buffers, and closes the file specified by open(). |
| 196 | // This function must be called before exiting the program, or the |
| 197 | // (de)compressed file will be corrupted. |
| 198 | // |
| 199 | // RETURN VALUES |
| 200 | // None. |
| 201 | virtual void close(); |
| 202 | |
| 203 | // FIXME: add function to flush internal buffer while compressing |
| 204 | // while decompressing, we don't have this option because the |
| 205 | // buffer size is fixed in the input compressed file. |
| 206 | // virtual void flush(); |
| 207 | |
| 208 | // FIXME: add function to return the dynamic optimal buffer size |
| 209 | // |
| 210 | // for compression, the optimal buffer size is one that would exactly |
| 211 | // fill up the internal buffer, if any so that subsequent compress() calls |
| 212 | // would not require memcpy() into the internal buffer. |
| 213 | // |
| 214 | // for decompression, the optimal buffer size is one that would exactly |
| 215 | // empty the internal buffer, if any, so that subsequent decompress() calls |
| 216 | // would directly decompress into the caller's buffer. |
| 217 | // |
| 218 | // virtual int opt_buffer_size(); |
| 219 | |
| 220 | // protected: |
| 221 | // Compressor* rstzip; |
| 222 | private: |
| 223 | struct Rstzip_impl * impl; |
| 224 | |
| 225 | }; // class Rstzip; |
| 226 | |
| 227 | #else // __cplusplus |
| 228 | |
| 229 | typedef struct Rstzip Rstzip; |
| 230 | |
| 231 | #endif // __cplusplus |
| 232 | |
| 233 | #ifdef __cplusplus |
| 234 | extern "C" { |
| 235 | #endif |
| 236 | |
| 237 | // SYNOPSIS |
| 238 | // Rstzip* rzMakeRstzip(); |
| 239 | // |
| 240 | // DESCRIPTION |
| 241 | // Allocate an Rstip Compressor object. The object is deallocated by the |
| 242 | // rzClose() function. |
| 243 | // |
| 244 | // RETURN VALUES |
| 245 | // Pointer to the allocated Rstzip Compressor object. |
| 246 | Rstzip* rzMakeRstzip(); |
| 247 | |
| 248 | int rzGetMajorVersion(Rstzip* rstzip); |
| 249 | |
| 250 | int rzGetMinorVersion(Rstzip* rstzip); |
| 251 | |
| 252 | const char* rzGetVersionStr(Rstzip* rstzip); |
| 253 | |
| 254 | int rzOpen(Rstzip* rstzip, const char* file, const char* md, const char* options); |
| 255 | |
| 256 | int rzCompress(Rstzip* rstzip, rstf_unionT* rstbuf, int nrecs); |
| 257 | |
| 258 | int rzDecompress(Rstzip* rstzip, rstf_unionT* rstbuf, int nrecs); |
| 259 | |
| 260 | void rzClose(Rstzip* rstzip); |
| 261 | |
| 262 | #ifdef __cplusplus |
| 263 | } |
| 264 | #endif |
| 265 | |
| 266 | |
| 267 | |
| 268 | // for backwards compatibility. this structure is not used in rstzip3 |
| 269 | #ifdef __cplusplus |
| 270 | extern "C" { |
| 271 | #endif |
| 272 | |
| 273 | typedef struct { |
| 274 | uint32_t buffersize; |
| 275 | uint8_t numcpus; |
| 276 | uint8_t gzip; |
| 277 | uint8_t stats; |
| 278 | uint8_t version; |
| 279 | uint8_t rstzip; // For Zio.H |
| 280 | } RstzipOptions; |
| 281 | |
| 282 | #ifdef __cplusplus |
| 283 | } |
| 284 | #endif // #ifdef __cplusplus |
| 285 | |
| 286 | char* makeRstzipOptionsString(RstzipOptions* opts); |
| 287 | |
| 288 | |
| 289 | #endif // _Rstzip_H_ |