srecord: output/file.h Source File

srecord 1.65.0

Loading...
Searching...
No Matches
file.h
Go to the documentation of this file.
1//
2// srecord - manipulate eprom load files
3// Copyright (C) 1998-2003, 2005-2012 Peter Miller
4//
5// This program is free software; you can redistribute it and/or modify
6// it under the terms of the GNU Lesser General Public License as published by
7// the Free Software Foundation; either version 3 of the License, or
8// (at your option) any later version.
9//
10// This program is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU Lesser General Public License for more details.
14//
15// You should have received a copy of the GNU Lesser General Public License
16// along with this program. If not, see
17// <http://www.gnu.org/licenses/>.
18//
19
20#ifndef SRECORD_OUTPUT_FILE_H
21#define SRECORD_OUTPUT_FILE_H
22
23#include <string>
24#include <srecord/output.h>
25#include <srecord/format_printf.h>
26
27namespace srecord {
28
29/**
30 * The srecord::output_file class is used to represent a generic output file.
31 * It provides a numnber of services useful to many output file formats.
32 */
33 class output_file:
34 public output
35{
36public:
37 /**
38 * The destructor.
39 */
40 virtual ~output_file();
41
42 /**
43 * The default constructor.
44 * Output will be sent to the standard output.
45 */
46 output_file();
47
48 /**
49 * The constructor. The output will be sent to the named file (or
50 * the standard output if the file name is "-").
51 *
52 * @param file_name
53 * The name of the file to be written.
54 */
55 output_file(const std::string &file_name);
56
57 // See base class for documentation.
58 virtual const std::string filename(void) const;
59
60 /**
61 * The enable_header class method is used to enable or disable
62 * the writing of header records into output file, if the format
63 * supports optional header records.
64 *
65 * @param yesno
66 * true if header records should be written, false if not
67 */
68 static void enable_header(bool yesno);
69
70 /**
71 * The enable_data_count class method is used to enable or disable
72 * the writing of data record count records into output file, if
73 * the format supports optional data record count records.
74 *
75 * @param yesno
76 * true if data record count records should be written, false
77 * if not
78 */
79 static void enable_data_count(bool yesno);
80
81 /**
82 * The enable_goto_addr class method is used to enable or disable
83 * the writing of execution start address records into output file,
84 * if the format supports optional execution start address records.
85 *
86 * @param yesno
87 * true if execution start address records should be written,
88 * false if not
89 */
90 static void enable_goto_addr(bool yesno);
91
92 /**
93 * The enable_footer class method is used to enable or disable
94 * the writing of footer records into output file, if the format
95 * supports optional footer records.
96 *
97 * @param yesno
98 * true if footer records should be written, false if not
99 */
100 static void enable_footer(bool yesno);
101
102 /**
103 * The enable_by_name class method is used to enable or disable
104 * the writing of various records into output file.
105 *
106 * @param name
107 * the name of the record type to enable or disable
108 * @param yesno
109 * true if should be enable, false if sjould be disabled
110 * @returns
111 * true if name understood, false if not (to trigger diagnostic
112 * error message)
113 */
114 static bool enable_by_name(const std::string &name, bool yesno);
115
116 /**
117 * The line_termination_by_name method is used to force line
118 * termination to a particular style, rather than the current
119 * operating system's native text format.
120 *
121 * @param name
122 * The name of the line termination style to be used,
123 * e.g. "crlf" or "nl".
124 * @returns
125 * true if successful, false if name unknown
126 */
127 static bool line_termination_by_name(const std::string &name);
128
129protected:
130 /**
131 * The put_char method is used to send a character to the output.
132 * Usually, this is sufficient, however derived classes may
133 * over-ride it if they have a special case. Over-ride with
134 * caution, as it affects many other methods.
135 */
136 virtual void put_char(int c);
137
138 /**
139 * The put_nibble method is used to send a hexadecimal digit (0..9,
140 * A..F) to the output. It calls put_char to send the output.
141 */
142 void put_nibble(int value);
143
144 /**
145 * The put_byte method is used to send a byte value to the output.
146 * The default implementation is to call the put_nibble method
147 * twice, big-endian (most significant nibble first).
148 *
149 * The value of the byte will be added to the running checksum, via
150 * the #checksum_add method.
151 *
152 * Usually, this #put_byte method implemention is sufficient for
153 * most output classes, however derived classes may over-ride it if
154 * they have a special case. Over-ride with caution, as it affects
155 * many other methods.
156 */
157 virtual void put_byte(unsigned char value);
158
159 /**
160 * The put_word_be method is used to send a 16-bit value to the
161 * output. The #put_byte method is called twice, and the two byte
162 * values are sent big-endian (most significant byte first).
163 */
164 virtual void put_word_be(int value);
165
166 /**
167 * The put_word_le method is used to send a 16-bit value to the
168 * output. The #put_byte method is called twice, and the two byte
169 * values are sent little-endian (least significant byte first).
170 */
171 virtual void put_word_le(int value);
172
173 /**
174 * The put_3bytes_be method is used to send a 24-bit value to the
175 * output. The #put_byte method is called three times, and the
176 * three byte values are sent big-endian (most significant byte
177 * first).
178 */
179 virtual void put_3bytes_be(unsigned long value);
180
181 /**
182 * The put_3bytes_le method is used to send a 24-bit value to the
183 * output. The #put_byte method is called three times, and the
184 * three byte values are sent little-endian (least significant byte
185 * first).
186 */
187 virtual void put_3bytes_le(unsigned long value);
188
189 /**
190 * The put_4bytes_be method is used to send a 32-bit value to the
191 * output. The #put_byte method is called four times, and the
192 * four byte values are sent big-endian (most significant byte
193 * first).
194 */
195 virtual void put_4bytes_be(unsigned long value);
196
197 /**
198 * The put_4bytes_le method is used to send a 32-bit value to the
199 * output. The #put_byte method is called four times, and the
200 * four byte values are sent little-endian (least significant byte
201 * first).
202 */
203 virtual void put_4bytes_le(unsigned long value);
204
205 /**
206 * The checksum_reset method is used to set the running checksum to
207 * zero.
208 */
209 void checksum_reset(void);
210
211 /**
212 * The checksum_add method is used to add another 8-bit value to
213 * the running checksum.
214 *
215 * The default implementation uses a simple addition. Derived
216 * classesmay override if they need to. Do this with caution, as
217 * it affects other methods.
218 */
219 virtual void checksum_add(unsigned char n);
220
221 /**
222 * The checksum_get method is used to get the current value of the
223 * running checksum (added to by the #checksum_add method, usually
224 * called by the #put_byte method). Only the lower 8 bits of the
225 * sum are returned.
226 */
227 int checksum_get(void);
228
229 /**
230 * The checksum_get16 method is used to get the current value of
231 * the running checksum (added to by the #checksum_add method,
232 * usually called by the #put_byte method). Only the lower 16
233 * bits of the sum are returned.
234 */
235 int checksum_get16(void);
236
237 /**
238 * The seek_to method is used to move the output position to the
239 * specified location in the output file.
240 */
241 void seek_to(unsigned long);
242
243 /**
244 * The put_string method is used to send a nul-terminated C string
245 * to the output. Multiple calls to #put_char are made.
246 */
247 void put_string(const char *text);
248
249 /**
250 * The put_string method is used to send C++ string
251 * to the output. Multiple calls to #put_char are made.
252 *
253 * @param text
254 * The string to print.
255 */
256 void put_string(const std::string &text);
257
258 /**
259 * The put_stringf method is used to send a formatted string to the
260 * output. The format and operation ios similar to the standard
261 * printf function. Multiple calls to #put_char are made.
262 */
263 void put_stringf(const char *, ...) FORMAT_PRINTF(2, 3);
264
265 /**
266 * The enable_header_flag class variable is set by the
267 * #enable_header method, to remember whether or not header
268 * records are to be emitted (if the format supports optional
269 * header records).
270 */
271 static bool enable_header_flag;
272
273 /**
274 * The enable_data_count_flag class variable is set by the
275 * #enable_data_count method, to remember whether or not data
276 * record count records are to be emitted (if the format supports
277 * optional data record count records).
278 */
279 static bool enable_data_count_flag;
280
281 /**
282 * The enable_goto_addr_flag class variable is set by the
283 * #enable_goto_addr method, to remember whether or not execution
284 * start address records are to be emitted (if the format supports
285 * optional execution start address records).
286 */
287 static bool enable_goto_addr_flag;
288
289 /**
290 * The enable_footer_flag class variable is set by the
291 * #enable_footer method, to remember whether or not footer
292 * records (end-of-file record) are to be emitted (if the format
293 * supports optional footer records).
294 */
295 static bool enable_footer_flag;
296
297 /**
298 * The enable_optional_address_records class variable is used
299 * to remember whether or not to emit optional address records.
300 * Defaults to true. Set by the #enable_by_name method.
301 */
302 static bool enable_optional_address_flag;
303
304 /**
305 * The enable_footer class method is used to enable or disable
306 * emitting optional address records.
307 *
308 * @param yesno
309 * true if records should be written, false if not
310 */
311 static void enable_optional_address(bool yesno);
312
313 enum line_termination_t
314 {
315 line_termination_native,
316 line_termination_crlf,
317 line_termination_nl,
318 line_termination_binary = line_termination_nl,
319 line_termination_cr,
320 line_termination_primos
321 };
322
323 /**
324 * The line_termination class variable is used to remember the
325 * desired line termination style. Defaults to the native style of
326 * the current operating system.
327 */
328 static line_termination_t line_termination;
329
330 /**
331 * The line_termination_guess class method is used to figure out
332 * the line termination style of the host environment.
333 */
334 static line_termination_t line_termination_guess(void);
335
336private:
337 /**
338 * The file_name instance variable is used by the #filename and
339 * filename_and_line methods to report the name of the input
340 * file. This makes for informative error mesages.
341 */
342 std::string file_name;
343
344 /**
345 * The line_number instance variable is used by the get_char
346 * method to remember the current line number. It us used by the
347 * filename_and_line method to report the current file location.
348 */
349 int line_number;
350
351 /**
352 * The vfp instance variable is used by the #get_fp method to
353 * remember the file pointer. You need to cast it to FILE* befor
354 * you use it. Never access this instance variable directly,
355 * always go via the #get_fp method. This ensures the file has
356 * been opened first!
357 */
358 void *vfp;
359
360protected:
361 /**
362 * The checksum instance variable is used record the running
363 * checksum. NEVER access this variable directly. Always use the
364 * #checksum_reset method to set it mack to its initial state.
365 * Always use the #checksum_add method to add a byte to it.
366 * Always use the #checksum_get or #checksum_get16 methods to
367 * read its value.
368 */
369 int checksum;
370
371 /**
372 * The fatal_alignment_error method is used to report problems
373 * with unaligned data in formats that require aligned data. It
374 * suggests a fill to fix the problem.
375 *
376 * @param alignment
377 * The necessary byte alignment
378 */
379 void fatal_alignment_error(int alignment);
380
381 /**
382 * The fatal_hole_error method is used to report problems with
383 * holes in the data, for formats that cannot cope with them.
384 */
385 void fatal_hole_error(unsigned long lo, unsigned long hi);
386
387 /**
388 * The data_address_too_large method is used to report fatal
389 * problems with data records, in the case where some or all of the
390 * address span of a record falls outside the format's ability to
391 * represent addresses.
392 *
393 * @param record
394 * The offending data record.
395 * @param nbits
396 * The number of bits in the available address range
397 */
398 void data_address_too_large(const record &record, unsigned nbits) const;
399
400private:
401 /**
402 * The position instance variable is used to remember the
403 * current position within the output file. Set by the put_char
404 * method, and the seek_to method. Used by the seek_to method.
405 */
406 unsigned long position;
407
408 /**
409 * The is_regular instance variable is used to remember whther
410 * or not the file is a regular file. This is set by the
411 * set_is_regular method. It is used by the seek_to method.
412 */
413 bool is_regular;
414
415 /**
416 * The set_is_regular method shall be used whenever vfp is assigned,
417 * to estanblish whther the output file is a regular file or a
418 * special file (like a pipe).
419 */
420 void set_is_regular(void);
421
422 /**
423 * The get_fp method is used to get the stdio file pointer
424 * associated with this input file. (By avoiding a FILE*
425 * declaraion, we avoid having to include <stdio.h> for not
426 * particularly good reason. Take care when casting.)
427 *
428 * If the file has not been opened yet, it will be opened by this
429 * method.
430 */
431 void *get_fp(void);
432
433 /**
434 * The is_binary method is used to to determine whether or not
435 * a file format is binary (true) of text (false). The default
436 * implementation always returns false (text).
437 */
438 virtual bool is_binary(void) const;
439
440 /**
441 * The copy constructor. Do not use.
442 */
443 output_file(const output_file &);
444
445 /**
446 * The assignment operator. Do not use.
447 */
448 output_file &operator=(const output_file &);
449};
450
451};
452
453// vim: set ts=8 sw=4 et :
454#endif // SRECORD_OUTPUT_FILE_H
srecord::output_file::put_string
void put_string(const std::string &text)
The put_string method is used to send C++ string to the output.
srecord::output_file::put_4bytes_be
virtual void put_4bytes_be(unsigned long value)
The put_4bytes_be method is used to send a 32-bit value to the output.
srecord::output_file::enable_goto_addr
static void enable_goto_addr(bool yesno)
The enable_goto_addr class method is used to enable or disable the writing of execution start address...
srecord::output_file::line_termination
static line_termination_t line_termination
The line_termination class variable is used to remember the desired line termination style.
Definition file.h:328
srecord::output_file::enable_data_count_flag
static bool enable_data_count_flag
The enable_data_count_flag class variable is set by the enable_data_count method, to remember whether...
Definition file.h:279
srecord::output_file::data_address_too_large
void data_address_too_large(const record &record, unsigned nbits) const
The data_address_too_large method is used to report fatal problems with data records,...
srecord::output_file::checksum
int checksum
The checksum instance variable is used record the running checksum.
Definition file.h:369
srecord::output_file::enable_header_flag
void static bool enable_header_flag
The enable_header_flag class variable is set by the enable_header method, to remember whether or not ...
Definition file.h:271
srecord::output_file::fatal_alignment_error
void fatal_alignment_error(int alignment)
The fatal_alignment_error method is used to report problems with unaligned data in formats that requi...
srecord::output_file::checksum_get
int checksum_get(void)
The checksum_get method is used to get the current value of the running checksum (added to by the che...
srecord::output_file::line_termination_guess
static line_termination_t line_termination_guess(void)
The line_termination_guess class method is used to figure out the line termination style of the host ...
srecord::output_file::seek_to
void seek_to(unsigned long)
The seek_to method is used to move the output position to the specified location in the output file.
srecord::output_file::enable_optional_address_flag
static bool enable_optional_address_flag
The enable_optional_address_records class variable is used to remember whether or not to emit optiona...
Definition file.h:302
srecord::output_file::enable_by_name
static bool enable_by_name(const std::string &name, bool yesno)
The enable_by_name class method is used to enable or disable the writing of various records into outp...
srecord::output_file::enable_data_count
static void enable_data_count(bool yesno)
The enable_data_count class method is used to enable or disable the writing of data record count reco...
srecord::output_file::enable_header
static void enable_header(bool yesno)
The enable_header class method is used to enable or disable the writing of header records into output...
srecord::output_file::put_3bytes_be
virtual void put_3bytes_be(unsigned long value)
The put_3bytes_be method is used to send a 24-bit value to the output.
srecord::output_file::put_4bytes_le
virtual void put_4bytes_le(unsigned long value)
The put_4bytes_le method is used to send a 32-bit value to the output.
srecord::output_file::line_termination_t
line_termination_t
Definition file.h:314
srecord::output_file::line_termination_nl
@ line_termination_nl
Definition file.h:317
srecord::output_file::line_termination_native
@ line_termination_native
Definition file.h:315
srecord::output_file::line_termination_binary
@ line_termination_binary
Definition file.h:318
srecord::output_file::line_termination_cr
@ line_termination_cr
Definition file.h:319
srecord::output_file::line_termination_crlf
@ line_termination_crlf
Definition file.h:316
srecord::output_file::line_termination_primos
@ line_termination_primos
Definition file.h:320
srecord::output_file::line_termination_by_name
static bool line_termination_by_name(const std::string &name)
The line_termination_by_name method is used to force line termination to a particular style,...
srecord::output_file::put_char
virtual void put_char(int c)
The put_char method is used to send a character to the output.
srecord::output_file::enable_footer_flag
static bool enable_footer_flag
The enable_footer_flag class variable is set by the enable_footer method, to remember whether or not ...
Definition file.h:295
srecord::output_file::checksum_reset
void checksum_reset(void)
The checksum_reset method is used to set the running checksum to zero.
srecord::output_file::put_nibble
void put_nibble(int value)
The put_nibble method is used to send a hexadecimal digit (0..9, A..F) to the output.
srecord::output_file::put_3bytes_le
virtual void put_3bytes_le(unsigned long value)
The put_3bytes_le method is used to send a 24-bit value to the output.
srecord::output_file::checksum_get16
int checksum_get16(void)
The checksum_get16 method is used to get the current value of the running checksum (added to by the c...
srecord::output_file::output_file
output_file()
The default constructor.
srecord::output_file::fatal_hole_error
void fatal_hole_error(unsigned long lo, unsigned long hi)
The fatal_hole_error method is used to report problems with holes in the data, for formats that canno...
srecord::output_file::put_stringf
void put_stringf(const char *,...) FORMAT_PRINTF(2
The put_stringf method is used to send a formatted string to the output.
srecord::output_file::put_word_le
virtual void put_word_le(int value)
The put_word_le method is used to send a 16-bit value to the output.
srecord::output_file::enable_goto_addr_flag
static bool enable_goto_addr_flag
The enable_goto_addr_flag class variable is set by the enable_goto_addr method, to remember whether o...
Definition file.h:287
srecord::output_file::enable_optional_address
static void enable_optional_address(bool yesno)
The enable_footer class method is used to enable or disable emitting optional address records.
srecord::output_file::put_byte
virtual void put_byte(unsigned char value)
The put_byte method is used to send a byte value to the output.
srecord::output_file::put_word_be
virtual void put_word_be(int value)
The put_word_be method is used to send a 16-bit value to the output.
srecord::output_file::checksum_add
virtual void checksum_add(unsigned char n)
The checksum_add method is used to add another 8-bit value to the running checksum.
srecord::output_file::~output_file
virtual ~output_file()
The destructor.
srecord::output_file::filename
virtual const std::string filename(void) const
The filename method is used to determine the name of the output file.
srecord::output_file::enable_footer
static void enable_footer(bool yesno)
The enable_footer class method is used to enable or disable the writing of footer records into output...
srecord::output_file::put_string
void put_string(const char *text)
The put_string method is used to send a nul-terminated C string to the output.
srecord::output_file::output_file
output_file(const std::string &file_name)
The constructor.
srecord::output::output
output()
The default constructor.
srecord::record
The srecord::record class is used to represent a data record read from a file.
Definition record.h:35
format_printf.h
FORMAT_PRINTF
#define FORMAT_PRINTF(x, y)
Definition format_printf.h:28
srecord
Definition adler16.h:25
output.h