bitstream.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472
  1. /* ******************************************************************
  2. bitstream
  3. Part of FSE library
  4. header file (to include)
  5. Copyright (C) 2013-2017, Yann Collet.
  6. BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
  7. Redistribution and use in source and binary forms, with or without
  8. modification, are permitted provided that the following conditions are
  9. met:
  10. * Redistributions of source code must retain the above copyright
  11. notice, this list of conditions and the following disclaimer.
  12. * Redistributions in binary form must reproduce the above
  13. copyright notice, this list of conditions and the following disclaimer
  14. in the documentation and/or other materials provided with the
  15. distribution.
  16. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  17. "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  18. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  19. A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  20. OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21. SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22. LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23. DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24. THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25. (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  26. OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27. You can contact the author at :
  28. - Source repository : https://github.com/Cyan4973/FiniteStateEntropy
  29. ****************************************************************** */
  30. #ifndef BITSTREAM_H_MODULE
  31. #define BITSTREAM_H_MODULE
  32. #if defined (__cplusplus)
  33. extern "C" {
  34. #endif
  35. /*
  36. * This API consists of small unitary functions, which must be inlined for best performance.
  37. * Since link-time-optimization is not available for all compilers,
  38. * these functions are defined into a .h to be included.
  39. */
  40. /*-****************************************
  41. * Dependencies
  42. ******************************************/
  43. #include "mem.h" /* unaligned access routines */
  44. #include "error_private.h" /* error codes and messages */
  45. /*-*************************************
  46. * Debug
  47. ***************************************/
  48. #if defined(BIT_DEBUG) && (BIT_DEBUG>=1)
  49. # include <assert.h>
  50. #else
  51. # ifndef assert
  52. # define assert(condition) ((void)0)
  53. # endif
  54. #endif
  55. /*=========================================
  56. * Target specific
  57. =========================================*/
  58. #if defined(__BMI__) && defined(__GNUC__)
  59. # include <immintrin.h> /* support for bextr (experimental) */
  60. #endif
  61. #define STREAM_ACCUMULATOR_MIN_32 25
  62. #define STREAM_ACCUMULATOR_MIN_64 57
  63. #define STREAM_ACCUMULATOR_MIN ((U32)(MEM_32bits() ? STREAM_ACCUMULATOR_MIN_32 : STREAM_ACCUMULATOR_MIN_64))
  64. /*-******************************************
  65. * bitStream encoding API (write forward)
  66. ********************************************/
  67. /* bitStream can mix input from multiple sources.
  68. * A critical property of these streams is that they encode and decode in **reverse** direction.
  69. * So the first bit sequence you add will be the last to be read, like a LIFO stack.
  70. */
  71. typedef struct
  72. {
  73. size_t bitContainer;
  74. unsigned bitPos;
  75. char* startPtr;
  76. char* ptr;
  77. char* endPtr;
  78. } BIT_CStream_t;
  79. MEM_STATIC size_t BIT_initCStream(BIT_CStream_t* bitC, void* dstBuffer, size_t dstCapacity);
  80. MEM_STATIC void BIT_addBits(BIT_CStream_t* bitC, size_t value, unsigned nbBits);
  81. MEM_STATIC void BIT_flushBits(BIT_CStream_t* bitC);
  82. MEM_STATIC size_t BIT_closeCStream(BIT_CStream_t* bitC);
  83. /* Start with initCStream, providing the size of buffer to write into.
  84. * bitStream will never write outside of this buffer.
  85. * `dstCapacity` must be >= sizeof(bitD->bitContainer), otherwise @return will be an error code.
  86. *
  87. * bits are first added to a local register.
  88. * Local register is size_t, hence 64-bits on 64-bits systems, or 32-bits on 32-bits systems.
  89. * Writing data into memory is an explicit operation, performed by the flushBits function.
  90. * Hence keep track how many bits are potentially stored into local register to avoid register overflow.
  91. * After a flushBits, a maximum of 7 bits might still be stored into local register.
  92. *
  93. * Avoid storing elements of more than 24 bits if you want compatibility with 32-bits bitstream readers.
  94. *
  95. * Last operation is to close the bitStream.
  96. * The function returns the final size of CStream in bytes.
  97. * If data couldn't fit into `dstBuffer`, it will return a 0 ( == not storable)
  98. */
  99. /*-********************************************
  100. * bitStream decoding API (read backward)
  101. **********************************************/
  102. typedef struct
  103. {
  104. size_t bitContainer;
  105. unsigned bitsConsumed;
  106. const char* ptr;
  107. const char* start;
  108. const char* limitPtr;
  109. } BIT_DStream_t;
  110. typedef enum { BIT_DStream_unfinished = 0,
  111. BIT_DStream_endOfBuffer = 1,
  112. BIT_DStream_completed = 2,
  113. BIT_DStream_overflow = 3 } BIT_DStream_status; /* result of BIT_reloadDStream() */
  114. /* 1,2,4,8 would be better for bitmap combinations, but slows down performance a bit ... :( */
  115. MEM_STATIC size_t BIT_initDStream(BIT_DStream_t* bitD, const void* srcBuffer, size_t srcSize);
  116. MEM_STATIC size_t BIT_readBits(BIT_DStream_t* bitD, unsigned nbBits);
  117. MEM_STATIC BIT_DStream_status BIT_reloadDStream(BIT_DStream_t* bitD);
  118. MEM_STATIC unsigned BIT_endOfDStream(const BIT_DStream_t* bitD);
  119. /* Start by invoking BIT_initDStream().
  120. * A chunk of the bitStream is then stored into a local register.
  121. * Local register size is 64-bits on 64-bits systems, 32-bits on 32-bits systems (size_t).
  122. * You can then retrieve bitFields stored into the local register, **in reverse order**.
  123. * Local register is explicitly reloaded from memory by the BIT_reloadDStream() method.
  124. * A reload guarantee a minimum of ((8*sizeof(bitD->bitContainer))-7) bits when its result is BIT_DStream_unfinished.
  125. * Otherwise, it can be less than that, so proceed accordingly.
  126. * Checking if DStream has reached its end can be performed with BIT_endOfDStream().
  127. */
  128. /*-****************************************
  129. * unsafe API
  130. ******************************************/
  131. MEM_STATIC void BIT_addBitsFast(BIT_CStream_t* bitC, size_t value, unsigned nbBits);
  132. /* faster, but works only if value is "clean", meaning all high bits above nbBits are 0 */
  133. MEM_STATIC void BIT_flushBitsFast(BIT_CStream_t* bitC);
  134. /* unsafe version; does not check buffer overflow */
  135. MEM_STATIC size_t BIT_readBitsFast(BIT_DStream_t* bitD, unsigned nbBits);
  136. /* faster, but works only if nbBits >= 1 */
  137. /*-**************************************************************
  138. * Internal functions
  139. ****************************************************************/
  140. MEM_STATIC unsigned BIT_highbit32 (register U32 val)
  141. {
  142. assert(val != 0);
  143. {
  144. # if defined(_MSC_VER) /* Visual */
  145. unsigned long r=0;
  146. _BitScanReverse ( &r, val );
  147. return (unsigned) r;
  148. # elif defined(__GNUC__) && (__GNUC__ >= 3) /* Use GCC Intrinsic */
  149. return 31 - __builtin_clz (val);
  150. # else /* Software version */
  151. static const unsigned DeBruijnClz[32] = { 0, 9, 1, 10, 13, 21, 2, 29,
  152. 11, 14, 16, 18, 22, 25, 3, 30,
  153. 8, 12, 20, 28, 15, 17, 24, 7,
  154. 19, 27, 23, 6, 26, 5, 4, 31 };
  155. U32 v = val;
  156. v |= v >> 1;
  157. v |= v >> 2;
  158. v |= v >> 4;
  159. v |= v >> 8;
  160. v |= v >> 16;
  161. return DeBruijnClz[ (U32) (v * 0x07C4ACDDU) >> 27];
  162. # endif
  163. }
  164. }
  165. /*===== Local Constants =====*/
  166. static const unsigned BIT_mask[] = {
  167. 0, 1, 3, 7, 0xF, 0x1F,
  168. 0x3F, 0x7F, 0xFF, 0x1FF, 0x3FF, 0x7FF,
  169. 0xFFF, 0x1FFF, 0x3FFF, 0x7FFF, 0xFFFF, 0x1FFFF,
  170. 0x3FFFF, 0x7FFFF, 0xFFFFF, 0x1FFFFF, 0x3FFFFF, 0x7FFFFF,
  171. 0xFFFFFF, 0x1FFFFFF, 0x3FFFFFF, 0x7FFFFFF, 0xFFFFFFF, 0x1FFFFFFF,
  172. 0x3FFFFFFF, 0x7FFFFFFF}; /* up to 31 bits */
  173. #define BIT_MASK_SIZE (sizeof(BIT_mask) / sizeof(BIT_mask[0]))
  174. /*-**************************************************************
  175. * bitStream encoding
  176. ****************************************************************/
  177. /*! BIT_initCStream() :
  178. * `dstCapacity` must be > sizeof(size_t)
  179. * @return : 0 if success,
  180. * otherwise an error code (can be tested using ERR_isError()) */
  181. MEM_STATIC size_t BIT_initCStream(BIT_CStream_t* bitC,
  182. void* startPtr, size_t dstCapacity)
  183. {
  184. bitC->bitContainer = 0;
  185. bitC->bitPos = 0;
  186. bitC->startPtr = (char*)startPtr;
  187. bitC->ptr = bitC->startPtr;
  188. bitC->endPtr = bitC->startPtr + dstCapacity - sizeof(bitC->bitContainer);
  189. if (dstCapacity <= sizeof(bitC->bitContainer)) return ERROR(dstSize_tooSmall);
  190. return 0;
  191. }
  192. /*! BIT_addBits() :
  193. * can add up to 31 bits into `bitC`.
  194. * Note : does not check for register overflow ! */
  195. MEM_STATIC void BIT_addBits(BIT_CStream_t* bitC,
  196. size_t value, unsigned nbBits)
  197. {
  198. MEM_STATIC_ASSERT(BIT_MASK_SIZE == 32);
  199. assert(nbBits < BIT_MASK_SIZE);
  200. assert(nbBits + bitC->bitPos < sizeof(bitC->bitContainer) * 8);
  201. bitC->bitContainer |= (value & BIT_mask[nbBits]) << bitC->bitPos;
  202. bitC->bitPos += nbBits;
  203. }
  204. /*! BIT_addBitsFast() :
  205. * works only if `value` is _clean_, meaning all high bits above nbBits are 0 */
  206. MEM_STATIC void BIT_addBitsFast(BIT_CStream_t* bitC,
  207. size_t value, unsigned nbBits)
  208. {
  209. assert((value>>nbBits) == 0);
  210. assert(nbBits + bitC->bitPos < sizeof(bitC->bitContainer) * 8);
  211. bitC->bitContainer |= value << bitC->bitPos;
  212. bitC->bitPos += nbBits;
  213. }
  214. /*! BIT_flushBitsFast() :
  215. * assumption : bitContainer has not overflowed
  216. * unsafe version; does not check buffer overflow */
  217. MEM_STATIC void BIT_flushBitsFast(BIT_CStream_t* bitC)
  218. {
  219. size_t const nbBytes = bitC->bitPos >> 3;
  220. assert(bitC->bitPos < sizeof(bitC->bitContainer) * 8);
  221. MEM_writeLEST(bitC->ptr, bitC->bitContainer);
  222. bitC->ptr += nbBytes;
  223. assert(bitC->ptr <= bitC->endPtr);
  224. bitC->bitPos &= 7;
  225. bitC->bitContainer >>= nbBytes*8;
  226. }
  227. /*! BIT_flushBits() :
  228. * assumption : bitContainer has not overflowed
  229. * safe version; check for buffer overflow, and prevents it.
  230. * note : does not signal buffer overflow.
  231. * overflow will be revealed later on using BIT_closeCStream() */
  232. MEM_STATIC void BIT_flushBits(BIT_CStream_t* bitC)
  233. {
  234. size_t const nbBytes = bitC->bitPos >> 3;
  235. assert(bitC->bitPos < sizeof(bitC->bitContainer) * 8);
  236. MEM_writeLEST(bitC->ptr, bitC->bitContainer);
  237. bitC->ptr += nbBytes;
  238. if (bitC->ptr > bitC->endPtr) bitC->ptr = bitC->endPtr;
  239. bitC->bitPos &= 7;
  240. bitC->bitContainer >>= nbBytes*8;
  241. }
  242. /*! BIT_closeCStream() :
  243. * @return : size of CStream, in bytes,
  244. * or 0 if it could not fit into dstBuffer */
  245. MEM_STATIC size_t BIT_closeCStream(BIT_CStream_t* bitC)
  246. {
  247. BIT_addBitsFast(bitC, 1, 1); /* endMark */
  248. BIT_flushBits(bitC);
  249. if (bitC->ptr >= bitC->endPtr) return 0; /* overflow detected */
  250. return (bitC->ptr - bitC->startPtr) + (bitC->bitPos > 0);
  251. }
  252. /*-********************************************************
  253. * bitStream decoding
  254. **********************************************************/
  255. /*! BIT_initDStream() :
  256. * Initialize a BIT_DStream_t.
  257. * `bitD` : a pointer to an already allocated BIT_DStream_t structure.
  258. * `srcSize` must be the *exact* size of the bitStream, in bytes.
  259. * @return : size of stream (== srcSize), or an errorCode if a problem is detected
  260. */
  261. MEM_STATIC size_t BIT_initDStream(BIT_DStream_t* bitD, const void* srcBuffer, size_t srcSize)
  262. {
  263. if (srcSize < 1) { memset(bitD, 0, sizeof(*bitD)); return ERROR(srcSize_wrong); }
  264. bitD->start = (const char*)srcBuffer;
  265. bitD->limitPtr = bitD->start + sizeof(bitD->bitContainer);
  266. if (srcSize >= sizeof(bitD->bitContainer)) { /* normal case */
  267. bitD->ptr = (const char*)srcBuffer + srcSize - sizeof(bitD->bitContainer);
  268. bitD->bitContainer = MEM_readLEST(bitD->ptr);
  269. { BYTE const lastByte = ((const BYTE*)srcBuffer)[srcSize-1];
  270. bitD->bitsConsumed = lastByte ? 8 - BIT_highbit32(lastByte) : 0; /* ensures bitsConsumed is always set */
  271. if (lastByte == 0) return ERROR(GENERIC); /* endMark not present */ }
  272. } else {
  273. bitD->ptr = bitD->start;
  274. bitD->bitContainer = *(const BYTE*)(bitD->start);
  275. switch(srcSize)
  276. {
  277. case 7: bitD->bitContainer += (size_t)(((const BYTE*)(srcBuffer))[6]) << (sizeof(bitD->bitContainer)*8 - 16);
  278. /* fall-through */
  279. case 6: bitD->bitContainer += (size_t)(((const BYTE*)(srcBuffer))[5]) << (sizeof(bitD->bitContainer)*8 - 24);
  280. /* fall-through */
  281. case 5: bitD->bitContainer += (size_t)(((const BYTE*)(srcBuffer))[4]) << (sizeof(bitD->bitContainer)*8 - 32);
  282. /* fall-through */
  283. case 4: bitD->bitContainer += (size_t)(((const BYTE*)(srcBuffer))[3]) << 24;
  284. /* fall-through */
  285. case 3: bitD->bitContainer += (size_t)(((const BYTE*)(srcBuffer))[2]) << 16;
  286. /* fall-through */
  287. case 2: bitD->bitContainer += (size_t)(((const BYTE*)(srcBuffer))[1]) << 8;
  288. /* fall-through */
  289. default: break;
  290. }
  291. { BYTE const lastByte = ((const BYTE*)srcBuffer)[srcSize-1];
  292. bitD->bitsConsumed = lastByte ? 8 - BIT_highbit32(lastByte) : 0;
  293. if (lastByte == 0) return ERROR(corruption_detected); /* endMark not present */
  294. }
  295. bitD->bitsConsumed += (U32)(sizeof(bitD->bitContainer) - srcSize)*8;
  296. }
  297. return srcSize;
  298. }
  299. MEM_STATIC size_t BIT_getUpperBits(size_t bitContainer, U32 const start)
  300. {
  301. return bitContainer >> start;
  302. }
  303. MEM_STATIC size_t BIT_getMiddleBits(size_t bitContainer, U32 const start, U32 const nbBits)
  304. {
  305. #if defined(__BMI__) && defined(__GNUC__) && __GNUC__*1000+__GNUC_MINOR__ >= 4008 /* experimental */
  306. # if defined(__x86_64__)
  307. if (sizeof(bitContainer)==8)
  308. return _bextr_u64(bitContainer, start, nbBits);
  309. else
  310. # endif
  311. return _bextr_u32(bitContainer, start, nbBits);
  312. #else
  313. assert(nbBits < BIT_MASK_SIZE);
  314. return (bitContainer >> start) & BIT_mask[nbBits];
  315. #endif
  316. }
  317. MEM_STATIC size_t BIT_getLowerBits(size_t bitContainer, U32 const nbBits)
  318. {
  319. assert(nbBits < BIT_MASK_SIZE);
  320. return bitContainer & BIT_mask[nbBits];
  321. }
  322. /*! BIT_lookBits() :
  323. * Provides next n bits from local register.
  324. * local register is not modified.
  325. * On 32-bits, maxNbBits==24.
  326. * On 64-bits, maxNbBits==56.
  327. * @return : value extracted */
  328. MEM_STATIC size_t BIT_lookBits(const BIT_DStream_t* bitD, U32 nbBits)
  329. {
  330. #if defined(__BMI__) && defined(__GNUC__) /* experimental; fails if bitD->bitsConsumed + nbBits > sizeof(bitD->bitContainer)*8 */
  331. return BIT_getMiddleBits(bitD->bitContainer, (sizeof(bitD->bitContainer)*8) - bitD->bitsConsumed - nbBits, nbBits);
  332. #else
  333. U32 const regMask = sizeof(bitD->bitContainer)*8 - 1;
  334. return ((bitD->bitContainer << (bitD->bitsConsumed & regMask)) >> 1) >> ((regMask-nbBits) & regMask);
  335. #endif
  336. }
  337. /*! BIT_lookBitsFast() :
  338. * unsafe version; only works if nbBits >= 1 */
  339. MEM_STATIC size_t BIT_lookBitsFast(const BIT_DStream_t* bitD, U32 nbBits)
  340. {
  341. U32 const regMask = sizeof(bitD->bitContainer)*8 - 1;
  342. assert(nbBits >= 1);
  343. return (bitD->bitContainer << (bitD->bitsConsumed & regMask)) >> (((regMask+1)-nbBits) & regMask);
  344. }
  345. MEM_STATIC void BIT_skipBits(BIT_DStream_t* bitD, U32 nbBits)
  346. {
  347. bitD->bitsConsumed += nbBits;
  348. }
  349. /*! BIT_readBits() :
  350. * Read (consume) next n bits from local register and update.
  351. * Pay attention to not read more than nbBits contained into local register.
  352. * @return : extracted value. */
  353. MEM_STATIC size_t BIT_readBits(BIT_DStream_t* bitD, U32 nbBits)
  354. {
  355. size_t const value = BIT_lookBits(bitD, nbBits);
  356. BIT_skipBits(bitD, nbBits);
  357. return value;
  358. }
  359. /*! BIT_readBitsFast() :
  360. * unsafe version; only works only if nbBits >= 1 */
  361. MEM_STATIC size_t BIT_readBitsFast(BIT_DStream_t* bitD, U32 nbBits)
  362. {
  363. size_t const value = BIT_lookBitsFast(bitD, nbBits);
  364. assert(nbBits >= 1);
  365. BIT_skipBits(bitD, nbBits);
  366. return value;
  367. }
  368. /*! BIT_reloadDStream() :
  369. * Refill `bitD` from buffer previously set in BIT_initDStream() .
  370. * This function is safe, it guarantees it will not read beyond src buffer.
  371. * @return : status of `BIT_DStream_t` internal register.
  372. * when status == BIT_DStream_unfinished, internal register is filled with at least 25 or 57 bits */
  373. MEM_STATIC BIT_DStream_status BIT_reloadDStream(BIT_DStream_t* bitD)
  374. {
  375. if (bitD->bitsConsumed > (sizeof(bitD->bitContainer)*8)) /* overflow detected, like end of stream */
  376. return BIT_DStream_overflow;
  377. if (bitD->ptr >= bitD->limitPtr) {
  378. bitD->ptr -= bitD->bitsConsumed >> 3;
  379. bitD->bitsConsumed &= 7;
  380. bitD->bitContainer = MEM_readLEST(bitD->ptr);
  381. return BIT_DStream_unfinished;
  382. }
  383. if (bitD->ptr == bitD->start) {
  384. if (bitD->bitsConsumed < sizeof(bitD->bitContainer)*8) return BIT_DStream_endOfBuffer;
  385. return BIT_DStream_completed;
  386. }
  387. /* start < ptr < limitPtr */
  388. { U32 nbBytes = bitD->bitsConsumed >> 3;
  389. BIT_DStream_status result = BIT_DStream_unfinished;
  390. if (bitD->ptr - nbBytes < bitD->start) {
  391. nbBytes = (U32)(bitD->ptr - bitD->start); /* ptr > start */
  392. result = BIT_DStream_endOfBuffer;
  393. }
  394. bitD->ptr -= nbBytes;
  395. bitD->bitsConsumed -= nbBytes*8;
  396. bitD->bitContainer = MEM_readLEST(bitD->ptr); /* reminder : srcSize > sizeof(bitD->bitContainer), otherwise bitD->ptr == bitD->start */
  397. return result;
  398. }
  399. }
  400. /*! BIT_endOfDStream() :
  401. * @return : 1 if DStream has _exactly_ reached its end (all bits consumed).
  402. */
  403. MEM_STATIC unsigned BIT_endOfDStream(const BIT_DStream_t* DStream)
  404. {
  405. return ((DStream->ptr == DStream->start) && (DStream->bitsConsumed == sizeof(DStream->bitContainer)*8));
  406. }
  407. #if defined (__cplusplus)
  408. }
  409. #endif
  410. #endif /* BITSTREAM_H_MODULE */