Commit | Line | Data |
---|---|---|
920dae64 AT |
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_ |