1 /******************************************************** 2 Bitstream Library, a module for reading bits of data 3 4 Copyright (C) 2007-2014 Brian Langenberger 5 6 The Bitstream Library is free software; you can redistribute it and/or modify 7 it under the terms of either: 8 9 * the GNU Lesser General Public License as published by the Free 10 Software Foundation; either version 3 of the License, or (at your 11 option) any later version. 12 13 or 14 15 * the GNU General Public License as published by the Free Software 16 Foundation; either version 2 of the License, or (at your option) any 17 later version. 18 19 or both in parallel, as here. 20 21 The Bitstream Library is distributed in the hope that it will be useful, but 22 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 23 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 24 for more details. 25 26 You should have received copies of the GNU General Public License and the 27 GNU Lesser General Public License along with the GNU MP Library. If not, 28 see https://www.gnu.org/licenses/. 29 *******************************************************/ 30 31 #ifndef __BITSTREAMLIB_H__ 32 #define __BITSTREAMLIB_H__ 33 34 #ifdef HAS_PYTHON 35 #include <Python.h> 36 #endif 37 #include <stdio.h> 38 #include <stdint.h> 39 #include <stdlib.h> 40 #include <assert.h> 41 #include <setjmp.h> 42 #include <stdarg.h> 43 #include <limits.h> 44 #include "func_io.h" 45 #include "mini-gmp.h" 46 47 #ifndef MIN 48 #define MIN(x, y) ((x) < (y) ? (x) : (y)) 49 #endif 50 #ifndef MAX 51 #define MAX(x, y) ((x) > (y) ? (x) : (y)) 52 #endif 53 54 /*a jump table state value which must be at least 9 bits wide*/ 55 typedef uint16_t state_t; 56 57 typedef enum {BS_BIG_ENDIAN, BS_LITTLE_ENDIAN} bs_endianness; 58 typedef enum {BR_FILE, BR_BUFFER, BR_QUEUE, BR_EXTERNAL} br_type; 59 typedef enum {BW_FILE, BW_EXTERNAL, BW_RECORDER} bw_type; 60 typedef enum {BS_INST_UNSIGNED, 61 BS_INST_SIGNED, 62 BS_INST_UNSIGNED64, 63 BS_INST_SIGNED64, 64 BS_INST_UNSIGNED_BIGINT, 65 BS_INST_SIGNED_BIGINT, 66 BS_INST_SKIP, 67 BS_INST_SKIP_BYTES, 68 BS_INST_BYTES, 69 BS_INST_ALIGN, 70 BS_INST_EOF} bs_instruction_t; 71 typedef enum {BS_SEEK_SET=0, 72 BS_SEEK_CUR=1, 73 BS_SEEK_END=2} bs_whence; 74 75 typedef void (*bs_callback_f)(uint8_t, void*); 76 77 /*a stackable callback function, 78 used by BitstreamReader and BitstreamWriter*/ 79 struct bs_callback { 80 void (*callback)(uint8_t, void*); 81 void *data; 82 struct bs_callback *next; 83 }; 84 85 /*a stackable exception entry, 86 used by BitstreamReader and BitstreamWriter*/ 87 struct bs_exception { 88 jmp_buf env; 89 struct bs_exception *next; 90 }; 91 92 struct BitstreamReader_s; 93 struct BitstreamQueue_s; 94 struct br_buffer; 95 struct br_queue; 96 97 /*a position on the BitstreamReader's stream which can be rewound to*/ 98 typedef struct br_pos_s { 99 /*our source reader 100 attempting to setpos on some other reader will raise an error*/ 101 struct BitstreamReader_s *reader; 102 103 /*the position in the stream*/ 104 union { 105 fpos_t file; 106 unsigned buffer; 107 struct { 108 unsigned pos; 109 unsigned *pos_count; 110 } queue; 111 struct { 112 void* pos; 113 unsigned buffer_size; 114 uint8_t* buffer; 115 ext_free_pos_f free_pos; 116 } external; 117 } position; 118 119 /*partial reader state*/ 120 state_t state; 121 122 /*a function to delete position when finished with it*/ 123 void (*del)(struct br_pos_s *pos); 124 } br_pos_t; 125 126 /*a Huffman jump table entry 127 128 if continue_ == 0, state indicates the BitstreamReader's new state 129 and value indicates the value to be returned from the Huffman tree 130 131 if continue_ == 1, node indicates the array index of the next 132 br_huffman_table_t row of values to check against the current state*/ 133 typedef struct { 134 int continue_; 135 unsigned node; 136 state_t state; 137 int value; 138 } br_huffman_entry_t; 139 140 /*a list of all the Huffman jump table entries for a given node 141 where the current state is the index of which to use*/ 142 typedef br_huffman_entry_t br_huffman_table_t[0x200]; 143 144 /*typedefs for BitstreamReader methods 145 146 One can pull them out of reader and use them like: 147 148 br_read_f read = bitstreamreader->read; 149 unsigned int value = read(bitstreamreader, bits); 150 */ 151 152 /*returns "count" number of unsigned bits from the current stream 153 in the current endian format up to "count" bits wide*/ 154 typedef unsigned int 155 (*br_read_f)(struct BitstreamReader_s* self, unsigned int count); 156 157 /*returns "count" number of signed bits from the current stream 158 in the current endian format up to "count" bits wide*/ 159 typedef int 160 (*br_read_signed_f)(struct BitstreamReader_s* self, unsigned int count); 161 162 /*returns "count" number of unsigned bits from the current stream 163 in the current endian format up to 64 bits wide*/ 164 typedef uint64_t 165 (*br_read_64_f)(struct BitstreamReader_s* self, unsigned int count); 166 167 /*returns "count" number of signed bits from the current stream 168 in the current endian format up to 64 bits wide*/ 169 typedef int64_t 170 (*br_read_signed_64_f)(struct BitstreamReader_s* self, unsigned int count); 171 172 /*reads "count" number of unsigned bits from the current stream 173 to the given "value" in the current endian format 174 "value" must have been initialized previously*/ 175 typedef void 176 (*br_read_bigint_f)(struct BitstreamReader_s* self, 177 unsigned int count, 178 mpz_t value); 179 180 /*reads "count" number of signed bits from the current stream 181 to the given "value" in the current endian format 182 "value" must have been initialized previous*/ 183 typedef void 184 (*br_read_signed_bigint_f)(struct BitstreamReader_s* self, 185 unsigned int count, 186 mpz_t value); 187 188 /*skips "count" number of bits from the current stream as if read 189 callbacks are called on each skipped byte*/ 190 typedef void 191 (*br_skip_f)(struct BitstreamReader_s* self, unsigned int count); 192 193 /*pushes a single 0 or 1 bit back onto the stream 194 in the current endian format 195 196 unread bits are stored in the local bit buffer but 197 *not* pushed back into the stream itself 198 so a different unread bit will be lost 199 upon calls to seek or setpos, though getpos will preserve it 200 201 only a single bit is guaranteed to be unreadable 202 attempting to unread more than will fit in the buffer 203 will trigger a br_abort()*/ 204 typedef void 205 (*br_unread_f)(struct BitstreamReader_s* self, int unread_bit); 206 207 /*returns the number of non-stop bits before the 0 or 1 stop bit 208 from the current stream in the current endian format*/ 209 typedef unsigned int 210 (*br_read_unary_f)(struct BitstreamReader_s* self, int stop_bit); 211 212 /*skips the number of non-stop bits before the next 0 or 1 stop bit 213 from the current stream in the current endian format*/ 214 typedef void 215 (*br_skip_unary_f)(struct BitstreamReader_s* self, int stop_bit); 216 217 /*reads the next Huffman code from the stream 218 where the code tree is defined from the given compiled table*/ 219 typedef int 220 (*br_read_huffman_code_f)(struct BitstreamReader_s* self, 221 br_huffman_table_t table[]); 222 223 /*reads "byte_count" number of 8-bit bytes and places them in "bytes" 224 225 the stream is not required to be byte-aligned, 226 but reading will often be optimized if it is 227 228 if insufficient bytes can be read, br_abort is called 229 and the contents of "bytes" are undefined*/ 230 typedef void 231 (*br_read_bytes_f)(struct BitstreamReader_s* self, 232 uint8_t* bytes, 233 unsigned int byte_count); 234 235 /*skips "count" number of bytes from the current stream as if read 236 callbacks are called on each skipped byte*/ 237 typedef void 238 (*br_skip_bytes_f)(struct BitstreamReader_s* self, 239 unsigned int byte_count); 240 241 /*returns a new pos instance which can be rewound to 242 may call br_abort() if the position cannot be gotten 243 or the stream is closed*/ 244 typedef br_pos_t* 245 (*br_getpos_f)(struct BitstreamReader_s* self); 246 247 /*sets the stream's position from a pos instance 248 may call br_abort() if the position cannot be set 249 the stream is closed, or the position is from another stream*/ 250 typedef void 251 (*br_setpos_f)(struct BitstreamReader_s* self, br_pos_t* pos); 252 253 /*moves the stream directly to the given location, in bytes, 254 relative to the beginning, current or end of the stream 255 256 no callbacks are called on the intervening bytes*/ 257 typedef void 258 (*br_seek_f)(struct BitstreamReader_s* self, 259 long position, 260 bs_whence whence); 261 262 /******************************************************************* 263 * BitstreamReader * 264 *******************************************************************/ 265 266 #define BITSTREAMREADER_TYPE \ 267 bs_endianness endianness; \ 268 br_type type; \ 269 \ 270 union { \ 271 FILE* file; \ 272 struct br_buffer* buffer; \ 273 struct br_queue* queue; \ 274 struct br_external_input* external; \ 275 } input; \ 276 \ 277 state_t state; \ 278 struct bs_callback* callbacks; \ 279 struct bs_exception* exceptions; \ 280 struct bs_exception* exceptions_used; \ 281 \ 282 br_read_f read; \ 283 br_read_signed_f read_signed; \ 284 br_read_64_f read_64; \ 285 br_read_signed_64_f read_signed_64; \ 286 br_read_bigint_f read_bigint; \ 287 br_read_signed_bigint_f read_signed_bigint; \ 288 br_skip_f skip; \ 289 br_unread_f unread; \ 290 br_read_unary_f read_unary; \ 291 br_skip_unary_f skip_unary; \ 292 \ 293 /*sets the stream's format to big endian or little endian*/ \ 294 /*which automatically byte aligns it*/ \ 295 void \ 296 (*set_endianness)(struct BitstreamReader_s* self, \ 297 bs_endianness endianness); \ 298 \ 299 br_read_huffman_code_f read_huffman_code; \ 300 br_read_bytes_f read_bytes; \ 301 br_skip_bytes_f skip_bytes; \ 302 \ 303 /*takes a format string,*/ \ 304 /*performs the indicated read operations with prefixed numeric lengths*/ \ 305 /*and places the results in the given argument pointers*/ \ 306 /*where the format actions are:*/ \ 307 \ 308 /* | format | action | argument | */ \ 309 /* |--------+--------------------+---------------| */ \ 310 /* | u | read | unsigned int* | */ \ 311 /* | s | read_signed | int* | */ \ 312 /* | U | read_64 | uint64_t* | */ \ 313 /* | S | read_signed_64 | int64_t* | */ \ 314 /* | K | read_bigint | mpz_t* | */ \ 315 /* | L | read_signed_bigint | mpz_t* | */ \ 316 /* | p | skip | N/A | */ \ 317 /* | P | skip_bytes | N/A | */ \ 318 /* | b | read_bytes | uint8_t* | */ \ 319 /* | a | byte_align | N/A | */ \ 320 \ 321 /*For example, one could read a 32 bit header as follows:*/ \ 322 \ 323 /*unsigned int arg1; // 2 unsigned bits */ \ 324 /*unsigned int arg2; // 3 unsigned bits */ \ 325 /*int arg3; // 5 signed bits */ \ 326 /*unsigned int arg4; // 3 unsigned bits */ \ 327 /*uint64_t arg5; // 19 unsigned bits */ \ 328 \ 329 /*reader->parse(reader, "2u3u5s3u19U", */ \ 330 /* &arg1, &arg2, &arg3, &arg4, &arg5); */ \ 331 \ 332 /*the "*" format multiplies the next format by the given amount*/ \ 333 /*For example, to read 4, signed 8 bit values:*/ \ 334 \ 335 /*reader->parse(reader, "4* 8s", &arg1, &arg2, &arg3, &arg4);*/ \ 336 \ 337 /*an I/O error during reading will trigger a call to br_abort*/ \ 338 \ 339 void \ 340 (*parse)(struct BitstreamReader_s* self, const char* format, ...); \ 341 \ 342 /*returns 1 if the stream is byte-aligned, 0 if not*/ \ 343 int \ 344 (*byte_aligned)(const struct BitstreamReader_s* self); \ 345 \ 346 /*aligns the stream to a byte boundary*/ \ 347 void \ 348 (*byte_align)(struct BitstreamReader_s* self); \ 349 \ 350 /*pushes a callback function into the stream*/ \ 351 /*which is called on every byte read*/ \ 352 void \ 353 (*add_callback)(struct BitstreamReader_s* self, \ 354 bs_callback_f callback, \ 355 void* data); \ 356 \ 357 /*pushes the given callback onto the callback stack*/ \ 358 /*data from "callback" is copied onto a new internal struct*/ \ 359 /*it does not need to be allocated from the heap*/ \ 360 void \ 361 (*push_callback)(struct BitstreamReader_s* self, \ 362 struct bs_callback* callback); \ 363 \ 364 /*pops the most recently added callback from the stack*/ \ 365 /*if "callback" is not NULL, data from the popped callback*/ \ 366 /*is copied to that struct*/ \ 367 void \ 368 (*pop_callback)(struct BitstreamReader_s* self, \ 369 struct bs_callback* callback); \ 370 \ 371 /*explicitly call all set callbacks as if "byte" had been read*/ \ 372 /*from the input stream*/ \ 373 void \ 374 (*call_callbacks)(struct BitstreamReader_s* self, \ 375 uint8_t byte); \ 376 \ 377 br_getpos_f getpos; \ 378 br_setpos_f setpos; \ 379 br_seek_f seek; \ 380 \ 381 /*creates a substream from the current stream*/ \ 382 /*containing the given number of bytes*/ \ 383 /*and with the input stream's endianness*/ \ 384 \ 385 /*the substream must be freed when finished*/ \ 386 \ 387 /*br_abort() is called if insufficient bytes*/ \ 388 /*are available on the input stream*/ \ 389 struct BitstreamReader_s* \ 390 (*substream)(struct BitstreamReader_s* self, unsigned bytes); \ 391 \ 392 /*reads the next given number of bytes from the current stream*/ \ 393 /*to the end of the given queue*/ \ 394 \ 395 /*br_abort() is called if insufficient bytes*/ \ 396 /*are available on the input stream*/ \ 397 void \ 398 (*enqueue)(struct BitstreamReader_s* self, \ 399 unsigned bytes, \ 400 struct BitstreamQueue_s* queue); 401 402 typedef struct BitstreamReader_s { 403 BITSTREAMREADER_TYPE 404 405 /*returns the remaining size of the stream in bytes 406 this is only applicable for substreams and queues 407 otherwise it always returns 0*/ 408 unsigned 409 (*size)(const struct BitstreamReader_s* self); 410 411 /*closes the BistreamReader's internal stream 412 413 * for FILE objects, performs fclose 414 * for substreams, does nothing 415 * for external input, calls its .close() method 416 417 once the substream is closed, 418 the reader's methods are updated to generate errors if called again*/ 419 void 420 (*close_internal_stream)(struct BitstreamReader_s* self); 421 422 /*frees the BitstreamReader's allocated data 423 424 for FILE objects, does nothing 425 for substreams, deallocates buffer 426 for external input, calls its .free() method 427 428 deallocates any callbacks 429 deallocates any exceptions/used exceptions 430 431 deallocates the bitstream struct*/ 432 void 433 (*free)(struct BitstreamReader_s* self); 434 435 /*calls close_internal_stream(), followed by free()*/ 436 void 437 (*close)(struct BitstreamReader_s* self); 438 } BitstreamReader; 439 440 441 /*BitstreamQueue is a subclass of BitstreamReader 442 and can be used any place its parent is used 443 but contains additional methods for pushing more data 444 onto the end of the queue to be processed 445 or getting a count of the bits remaining in the queue*/ 446 typedef struct BitstreamQueue_s { 447 BITSTREAMREADER_TYPE 448 449 /*returns the remaining size of the stream in bytes 450 this is only applicable for substreams and queues 451 otherwise it always returns 0*/ 452 unsigned 453 (*size)(const struct BitstreamQueue_s* self); 454 455 /*closes the BistreamQueue's internal stream 456 457 once the substream is closed, 458 the reader's methods are updated to generate errors if called again*/ 459 void 460 (*close_internal_stream)(struct BitstreamQueue_s* self); 461 462 /*frees the BitstreamReader's allocated data 463 464 for queues, deallocates buffer 465 466 deallocates any callbacks 467 deallocates any exceptions/used exceptions 468 469 deallocates the bitstream struct*/ 470 void 471 (*free)(struct BitstreamQueue_s* self); 472 473 /*calls close_internal_stream(), followed by free()*/ 474 void 475 (*close)(struct BitstreamQueue_s* self); 476 477 /*extends the queue with the given amount of data*/ 478 void 479 (*push)(struct BitstreamQueue_s* self, 480 unsigned byte_count, 481 const uint8_t* data); 482 483 /*removes all data in the queue*/ 484 void 485 (*reset)(struct BitstreamQueue_s* self); 486 } BitstreamQueue; 487 488 489 /************************************************************* 490 Bitstream Reader Function Matrix 491 The read functions come in three input variants 492 and two endianness variants named in the format: 493 494 br_function_x_yy 495 496 where "x" is "f" for raw file, "s" for substream 497 or "e" for external functions 498 and "yy" is "be" for big endian or "le" for little endian. 499 For example: 500 501 | Function | Input | Endianness | 502 |-------------------+-----------+---------------| 503 | br_read_bits_f_be | raw file | big endian | 504 | br_read_bits_f_le | raw file | little endian | 505 | br_read_bits_b_be | substream | big endian | 506 | br_read_bits_b_le | substream | little endian | 507 | br_read_bits_e_be | function | big endian | 508 | br_read_bits_e_le | function | little endian | 509 510 *************************************************************/ 511 512 513 /*BistreamReader open functions*/ 514 BitstreamReader* 515 br_open(FILE *f, bs_endianness endianness); 516 517 /*creates a BitstreamReader from the given raw data 518 with the given endianness*/ 519 BitstreamReader* 520 br_open_buffer(const uint8_t *buffer, 521 unsigned buffer_size, 522 bs_endianness endianness); 523 524 /*creates a BitstreamQueue which data can be appended to*/ 525 BitstreamQueue* 526 br_open_queue(bs_endianness endianness); 527 528 /*int read(void* user_data, struct bs_buffer* buffer) 529 where "buffer" is where read output will be placed 530 using buf_putc, buf_append, etc. 531 532 note that "buffer" may already be holding data 533 (especially if a mark is in place) 534 so new data read to the buffer should be appended 535 rather than replacing what's already there 536 537 returns 0 on a successful read, 1 on a read error 538 "size" will be set to 0 once EOF is reached 539 540 541 void close(void* user_data) 542 called when the stream is closed 543 544 545 void free(void* user_data) 546 called when the stream is deallocated 547 */ 548 BitstreamReader* 549 br_open_external(void* user_data, 550 bs_endianness endianness, 551 unsigned buffer_size, 552 ext_read_f read, 553 ext_setpos_f setpos, 554 ext_getpos_f getpos, 555 ext_free_pos_f free_pos, 556 ext_seek_f seek, 557 ext_close_f close, 558 ext_free_f free); 559 560 /*Called by the read functions if one attempts to read past 561 the end of the stream. 562 If an exception stack is available (with br_try), 563 this jumps to that location via longjmp(3). 564 If not, this prints an error message and performs an unconditional exit. 565 */ 566 #ifdef DEBUG 567 #define br_abort(bs) __br_abort__((bs), __LINE__) 568 void 569 __br_abort__(BitstreamReader* bs, int lineno); 570 #else 571 void 572 br_abort(BitstreamReader* bs); 573 #endif 574 575 /*Sets up an exception stack for use by setjmp(3). 576 The basic call procudure is as follows: 577 578 if (!setjmp(*br_try(bs))) { 579 - perform reads here - 580 } else { 581 - catch read exception here - 582 } 583 br_etry(bs); - either way, pop handler off exception stack - 584 585 The idea being to avoid cluttering our read code with lots 586 and lots of error checking tests, but rather assign a spot 587 for errors to go if/when they do occur. 588 */ 589 jmp_buf* 590 br_try(BitstreamReader* bs); 591 592 /*Pops an entry off the current exception stack. 593 (ends a try, essentially)*/ 594 #define br_etry(bs) __br_etry((bs), __FILE__, __LINE__) 595 596 void 597 __br_etry(BitstreamReader* bs, const char *file, int lineno); 598 599 /******************************************************************* 600 * BitstreamWriter * 601 *******************************************************************/ 602 603 /*this is a basic binary tree in which the most common values 604 (those with the smallest amount of bits to write) 605 occur at the top of the tree 606 607 "smaller" and "larger" are array indexes where -1 means value not found*/ 608 typedef struct { 609 int value; 610 611 unsigned int write_count; 612 unsigned int write_value; 613 614 int smaller; 615 int larger; 616 } bw_huffman_table_t; 617 618 struct BitstreamWriter_s; 619 struct recorder_buffer; 620 621 /*a mark on the BitstreamWriter's stream which can be rewound to*/ 622 typedef struct bw_pos_s { 623 /*our source writer 624 attempting to setpos on some other writer will raise an error*/ 625 struct BitstreamWriter_s *writer; 626 627 /*the position in the stream*/ 628 union { 629 fpos_t file; 630 unsigned recorder; 631 struct { 632 void* pos; 633 ext_free_pos_f free_pos; 634 } external; 635 } position; 636 637 /*a function to delete position when finished with it*/ 638 void (*del)(struct bw_pos_s *pos); 639 } bw_pos_t; 640 641 642 struct bw_pos_stack { 643 bw_pos_t* pos; 644 struct bw_pos_stack* next; 645 }; 646 647 /*writes the given value as "count" number of unsigned bits*/ 648 typedef void 649 (*bw_write_f)(struct BitstreamWriter_s* self, 650 unsigned int count, 651 unsigned int value); 652 653 /*writes the given value as "count" number of signed bits*/ 654 typedef void 655 (*bw_write_signed_f)(struct BitstreamWriter_s* self, 656 unsigned int count, 657 int value); 658 659 /*writes the given value as "count" number of unsigned bits*/ 660 typedef void 661 (*bw_write_64_f)(struct BitstreamWriter_s* self, 662 unsigned int count, 663 uint64_t value); 664 665 /*writes the given value as "count" number of signed bits*/ 666 typedef void 667 (*bw_write_signed_64_f)(struct BitstreamWriter_s* self, 668 unsigned int count, 669 int64_t value); 670 671 /*writes the given value as "count" number of unsigned bits*/ 672 typedef void 673 (*bw_write_bigint_f)(struct BitstreamWriter_s* self, 674 unsigned int count, 675 const mpz_t value); 676 677 typedef void 678 (*bw_write_signed_bigint_f)(struct BitstreamWriter_s* self, 679 unsigned int count, 680 const mpz_t value); 681 682 /*writes "value" number of non stop bits to the current stream 683 followed by a single stop bit*/ 684 typedef void 685 (*bw_write_unary_f)(struct BitstreamWriter_s* self, 686 int stop_bit, 687 unsigned int value); 688 689 /*writes "value" is a Huffman code to the stream 690 where the code tree is defined from the given compiled table 691 returns 0 on success, or 1 if the code is not found in the table*/ 692 typedef int 693 (*bw_write_huffman_code_f)(struct BitstreamWriter_s* self, 694 bw_huffman_table_t table[], 695 int value); 696 697 /*writes "byte_count" number of bytes to the output stream*/ 698 typedef void 699 (*bw_write_bytes_f)(struct BitstreamWriter_s* self, 700 const uint8_t* bytes, 701 unsigned int byte_count); 702 703 /*returns a new pos instance which can be rewound to 704 may call bw_abort() if the position cannot be 705 gotten or the stream in closed*/ 706 typedef bw_pos_t* 707 (*bw_getpos_f)(struct BitstreamWriter_s* self); 708 709 /*sets the streams position from a pos instance 710 may call bw_abort() if the position cannot be set 711 the stream is closed, or the position 712 is from another stream*/ 713 typedef void 714 (*bw_setpos_f)(struct BitstreamWriter_s* self, 715 const bw_pos_t* pos); 716 717 #define BITSTREAMWRITER_TYPE \ 718 bs_endianness endianness; \ 719 bw_type type; \ 720 \ 721 union { \ 722 FILE* file; \ 723 struct bw_buffer* recorder; \ 724 struct bw_external_output* external; \ 725 } output; \ 726 \ 727 unsigned int buffer_size; \ 728 unsigned int buffer; \ 729 \ 730 struct bs_callback* callbacks; \ 731 struct bs_exception* exceptions; \ 732 struct bs_exception* exceptions_used; \ 733 \ 734 bw_write_f write; \ 735 \ 736 bw_write_signed_f write_signed; \ 737 \ 738 bw_write_64_f write_64; \ 739 \ 740 bw_write_signed_64_f write_signed_64; \ 741 \ 742 bw_write_bigint_f write_bigint; \ 743 \ 744 bw_write_signed_bigint_f write_signed_bigint; \ 745 \ 746 bw_write_unary_f write_unary; \ 747 \ 748 /*byte aligns the stream and sets its format*/ \ 749 /*to big endian or little endian*/ \ 750 void \ 751 (*set_endianness)(struct BitstreamWriter_s* self, \ 752 bs_endianness endianness); \ 753 \ 754 bw_write_huffman_code_f write_huffman_code; \ 755 \ 756 bw_write_bytes_f write_bytes; \ 757 \ 758 /*takes a format string,*/ \ 759 /*peforms the indicated write operations with prefixed numeric lengths*/ \ 760 /*using the values from the given arguments*/ \ 761 /*where the format actions are*/ \ 762 \ 763 /*| format | action | argument |*/ \ 764 /*|--------+---------------------+--------------|*/ \ 765 /*| u | write | unsigned int |*/ \ 766 /*| s | write_signed | int |*/ \ 767 /*| U | write_64 | uint64_t |*/ \ 768 /*| S | write_signed_64 | int64_t |*/ \ 769 /*| K | write_bigint | mpz_t* |*/ \ 770 /*| L | write_signed_bigint | mpz_t* |*/ \ 771 /*| p | skip | N/A |*/ \ 772 /*| P | skip_bytes | N/A |*/ \ 773 /*| b | write_bytes | uint8_t* |*/ \ 774 /*| a | byte_align | N/A |*/ \ 775 \ 776 /*For example, one could write a 32 bit header as follows:*/ \ 777 \ 778 /*unsigned int arg1; // 2 unsigned bits*/ \ 779 /*unsigned int arg2; // 3 unsigned bits*/ \ 780 /*int arg3; // 5 signed bits */ \ 781 /*unsigned int arg4; // 3 unsigned bits*/ \ 782 /*uint64_t arg5; // 19 unsigned bits*/ \ 783 \ 784 /*writer->build(writer, "2u3u5s3u19U", arg1, arg2, arg3, arg4, arg5);*/ \ 785 \ 786 /*the "*" format multiplies the next format by the given amount*/ \ 787 /*For example, to write 4, signed 8 bit values:*/ \ 788 \ 789 /*reader->parse(reader, "4* 8s", arg1, arg2, arg3, arg4);*/ \ 790 \ 791 /*this is designed to perform the inverse of BitstreamReader->parse()*/ \ 792 void \ 793 (*build)(struct BitstreamWriter_s* self, \ 794 const char* format, ...); \ 795 \ 796 /*returns 1 if the stream is byte-aligned, 0 if not*/ \ 797 int \ 798 (*byte_aligned)(const struct BitstreamWriter_s* self); \ 799 \ 800 /*if the stream is not already byte-aligned*/ \ 801 /*pad it with 0 bits until it is*/ \ 802 void \ 803 (*byte_align)(struct BitstreamWriter_s* self); \ 804 \ 805 /*flushes the current output stream's pending data*/ \ 806 void \ 807 (*flush)(struct BitstreamWriter_s* self); \ 808 \ 809 /*pushes a callback function into the stream*/ \ 810 /*which is called on every byte written*/ \ 811 void \ 812 (*add_callback)(struct BitstreamWriter_s* self, \ 813 bs_callback_f callback, \ 814 void* data); \ 815 \ 816 /*pushes the given callback onto the callback stack*/ \ 817 /*data from "callback" is copied onto a new internal struct*/ \ 818 /*it does not need to be allocated from the heap*/ \ 819 void \ 820 (*push_callback)(struct BitstreamWriter_s* self, \ 821 struct bs_callback* callback); \ 822 \ 823 /*pops the most recently added callback from the stack*/ \ 824 /*if "callback" is not NULL, data from the popped callback*/ \ 825 /*is copied to that struct*/ \ 826 void \ 827 (*pop_callback)(struct BitstreamWriter_s* self, \ 828 struct bs_callback* callback); \ 829 \ 830 /*explicitly call all set callbacks as if "byte" had been written*/ \ 831 /*to the input stream*/ \ 832 void \ 833 (*call_callbacks)(struct BitstreamWriter_s* self, \ 834 uint8_t byte); \ 835 \ 836 bw_getpos_f getpos; \ 837 bw_setpos_f setpos; 838 839 typedef struct BitstreamWriter_s { 840 BITSTREAMWRITER_TYPE 841 842 /*flushes and closes the BitstreamWriter's internal stream */ 843 /*for FILE objects, performs fclose */ 844 /*for external functions, calls the defined close() function*/ 845 /*once the internal stream is closed, */ 846 /*the writer's I/O methods are updated */ 847 /*to generate errors if called again */ 848 void 849 (*close_internal_stream)(struct BitstreamWriter_s* self); 850 851 /*for external functions, call free function on user data*/ 852 /*deallocates any callbacks, exceptions and marks */ 853 /*frees BitstreamWriter struct */ 854 void 855 (*free)(struct BitstreamWriter_s* self); 856 857 /*calls close_internal_stream(), followed by free()*/ 858 void 859 (*close)(struct BitstreamWriter_s* self); 860 } BitstreamWriter; 861 862 863 /*BitstreamRecorder is a subclass of BitstreamWriter 864 and can be used any place its parent is used 865 but contains additional methods for getting a count of bits written 866 and dumping recorded data to another BitstreamWriter*/ 867 typedef struct BitstreamRecorder_s { 868 BITSTREAMWRITER_TYPE 869 870 /*returns the total bits written to the stream thus far*/ 871 unsigned int 872 (*bits_written)(const struct BitstreamRecorder_s* self); 873 874 /*returns the total bytes written to the stream thus far*/ 875 unsigned int 876 (*bytes_written)(const struct BitstreamRecorder_s* self); 877 878 /*resets the stream for new values*/ 879 void 880 (*reset)(struct BitstreamRecorder_s* self); 881 882 /*copies all the recorded data in a recorder to the target writer*/ 883 void 884 (*copy)(const struct BitstreamRecorder_s* self, 885 struct BitstreamWriter_s* target); 886 887 /*returns our internal buffer of data written so far 888 not including any partial bytes 889 use bytes_written() to determine this buffer's total size*/ 890 const uint8_t* 891 (*data)(const struct BitstreamRecorder_s* self); 892 893 /*flushes and closes the internal stream*/ 894 /*for recorders, does nothing */ 895 /*once the internal stream is closed, */ 896 /*the writer's I/O methods are updated */ 897 /*to generate errors if called again */ 898 void 899 (*close_internal_stream)(struct BitstreamRecorder_s* bs); 900 901 /*for recorders, deallocates buffer */ 902 /*deallocates any callbacks, exceptions and marks*/ 903 /*frees BitstreamRecorder struct */ 904 void 905 (*free)(struct BitstreamRecorder_s* bs); 906 907 /*calls close_internal_stream(), followed by free()*/ 908 void 909 (*close)(struct BitstreamRecorder_s* bs); 910 } BitstreamRecorder; 911 912 913 /************************************************************* 914 Bitstream Writer Function Matrix 915 The write functions come in three output variants 916 and two endianness variants for file and recorder output: 917 918 bw_function_x or bw_function_x_yy 919 920 where "x" is "f" for raw file, "e" for external function, 921 "r" for recorder or "a" for accumulator 922 and "yy" is "be" for big endian or "le" for little endian. 923 924 For example: 925 926 | Function | Output | Endianness | 927 |--------------------+-------------+---------------| 928 | bw_write_bits_f_be | raw file | big endian | 929 | bw_write_bits_f_le | raw file | little endian | 930 | bw_write_bits_e_be | function | big endian | 931 | bw_write_bits_e_le | function | little endian | 932 | bw_write_bits_r_be | recorder | big endian | 933 | bw_write_bits_r_le | recorder | little endian | 934 935 *************************************************************/ 936 937 /*BistreamWriter open functions*/ 938 BitstreamWriter* 939 bw_open(FILE *f, bs_endianness endianness); 940 941 /*int write(const uint8_t *data, unsigned data_size, void *user_data) 942 where "data" is the bytes to be written, 943 "data_size" is the amount of bytes to write 944 and "user_data" is some function-specific pointer 945 returns 0 on a successful write, 1 on a write error 946 947 void flush(void* user_data) 948 flushes any pending data 949 950 note that high-level flushing will 951 perform ext_write() followed by ext_flush() 952 so the latter can be a no-op if necessary 953 954 955 void close(void* user_data) 956 closes the stream for further writing 957 958 959 void free(void* user_data) 960 deallocates anything in user_data, if necessary 961 */ 962 BitstreamWriter* 963 bw_open_external(void* user_data, 964 bs_endianness endianness, 965 unsigned buffer_size, 966 ext_write_f write, 967 ext_setpos_f setpos, 968 ext_getpos_f getpos, 969 ext_free_pos_f free_pos, 970 ext_flush_f flush, 971 ext_close_f close, 972 ext_free_f free); 973 974 BitstreamRecorder* 975 bw_open_recorder(bs_endianness endianness); 976 977 978 /*unattached, BitstreamWriter functions*/ 979 980 /*Called by the write functions if a write failure is indicated. 981 If an exception is available (with bw_try), 982 this jumps to that location via longjmp(3). 983 If not, this prints an error message and performs an unconditional exit.*/ 984 void 985 bw_abort(BitstreamWriter* bs); 986 987 /*Sets up an exception stack for use by setjmp(3). 988 The basic call procudure is as follows: 989 990 if (!setjmp(*bw_try(bs))) { 991 - perform writes here - 992 } else { 993 - catch write exception here - 994 } 995 bw_etry(bs); - either way, pop handler off exception stack - 996 997 The idea being to avoid cluttering our write code with lots 998 and lots of error checking tests, but rather assign a spot 999 for errors to go if/when they do occur. 1000 */ 1001 jmp_buf* 1002 bw_try(BitstreamWriter *bs); 1003 1004 /*Pops an entry off the current exception stack. 1005 (ends a try, essentially)*/ 1006 #define bw_etry(bs) __bw_etry((bs), __FILE__, __LINE__) 1007 1008 void 1009 __bw_etry(BitstreamWriter *bs, const char *file, int lineno); 1010 1011 1012 void 1013 recorder_swap(BitstreamRecorder **a, BitstreamRecorder **b); 1014 1015 1016 /******************************************************************* 1017 * format handlers * 1018 *******************************************************************/ 1019 1020 /*parses (or continues parsing) the given format string 1021 and places the results in the "times", "size" and "inst" variables*/ 1022 const char* 1023 bs_parse_format(const char *format, 1024 unsigned *times, unsigned *size, bs_instruction_t *inst); 1025 1026 /*returns the size of the given format string in bits*/ 1027 unsigned 1028 bs_format_size(const char* format); 1029 1030 /*returns the size of the given format string in bytes*/ 1031 unsigned 1032 bs_format_byte_size(const char* format); 1033 1034 1035 /******************************************************************* 1036 * bw_pos_stack handlers * 1037 *******************************************************************/ 1038 1039 void 1040 bw_pos_stack_push(struct bw_pos_stack** stack, bw_pos_t* pos); 1041 1042 bw_pos_t* 1043 bw_pos_stack_pop(struct bw_pos_stack** stack); 1044 1045 1046 #ifdef HAS_PYTHON 1047 /******************************************************************* 1048 * Python-specific * 1049 *******************************************************************/ 1050 1051 unsigned 1052 br_read_python(PyObject *reader, 1053 uint8_t *buffer, 1054 unsigned buffer_size); 1055 1056 int 1057 bw_write_python(PyObject* writer, 1058 const uint8_t *buffer, 1059 unsigned buffer_size); 1060 1061 int 1062 bw_flush_python(PyObject* writer); 1063 1064 int 1065 bs_setpos_python(PyObject* stream, PyObject* pos); 1066 1067 PyObject* 1068 bs_getpos_python(PyObject* stream); 1069 1070 void 1071 bs_free_pos_python(PyObject* pos); 1072 1073 int 1074 bs_fseek_python(PyObject* stream, long position, int whence); 1075 1076 int 1077 bs_close_python(PyObject* obj); 1078 1079 void 1080 bs_free_python_decref(PyObject* obj); 1081 1082 void 1083 bs_free_python_nodecref(PyObject* obj); 1084 1085 int 1086 python_obj_seekable(PyObject* obj); 1087 1088 #endif 1089 1090 /******************************************************************* 1091 * miscellaneous * 1092 *******************************************************************/ 1093 1094 /*a trivial callback which increments "total_bytes" as an unsigned int*/ 1095 void 1096 byte_counter(uint8_t byte, unsigned* total_bytes); 1097 1098 #endif 1099