mirrors/flipperzero-firmware
1
Fork 0
mirror of https://github.com/flipperdevices/flipperzero-firmware.git synced 2025-12-12 12:51:22 +04:00
Code Issues Activity

Improve bit_buffer.h docs (#3783)

Browse Source 
* Improve bit_buffer.h docs
* Toolbox: update doxygen comments fix spelling
* Toolbox: update bit lib docs

Co-authored-by: あく <alleteam@gmail.com>
Co-authored-by: gornekich <n.gorbadey@gmail.com>
This commit is contained in:
Astra
2024-10-03 02:51:07 +09:00
committed by GitHub
parent 56d2923f1f
commit 00c1611c33
1 changed files with 208 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files

360
lib/toolbox/bit_buffer.h
View File

@@ -1,3 +1,9 @@
/** Bit Buffer
*
* Various bits and bytes manipulation tools.
*
* @file bit_buffer.h
*/
#pragma once #pragma once
#include <stddef.h> #include <stddef.h>
@@ -10,118 +16,128 @@ extern "C" {
typedef struct BitBuffer BitBuffer; typedef struct BitBuffer BitBuffer;
// Construction, deletion, reset /** Allocate a BitBuffer instance.
*
/** * @param[in] capacity_bytes maximum buffer capacity, in bytes
* Allocate a BitBuffer instance.
* *
* @param [in] capacity_bytes maximum buffer capacity, in bytes
* @return pointer to the allocated BitBuffer instance * @return pointer to the allocated BitBuffer instance
*/ */
BitBuffer* bit_buffer_alloc(size_t capacity_bytes); BitBuffer* bit_buffer_alloc(size_t capacity_bytes);
/** /** Delete a BitBuffer instance.
* Delete a BitBuffer instance.
* *
* @param [in,out] buf pointer to a BitBuffer instance * @param[in,out] buf pointer to a BitBuffer instance
*/ */
void bit_buffer_free(BitBuffer* buf); void bit_buffer_free(BitBuffer* buf);
/** /** Clear all data from a BitBuffer instance.
* Clear all data from a BitBuffer instance.
* *
* @param [in,out] buf pointer to a BitBuffer instance * @param[in,out] buf pointer to a BitBuffer instance
*/ */
void bit_buffer_reset(BitBuffer* buf); void bit_buffer_reset(BitBuffer* buf);
// Copy and write // Copy and write
/** /** Copy another BitBuffer instance's contents to this one, replacing all of the
* Copy another BitBuffer instance's contents to this one, replacing * original data.
* all of the original data.
* The destination capacity must be no less than the source data size.
* *
* @param [in,out] buf pointer to a BitBuffer instance to copy into * @warning The destination capacity must be no less than the source data
* @param [in] other pointer to a BitBuffer instance to copy from * size.
* @note *
* @param[in,out] buf pointer to a BitBuffer instance to copy into
* @param[in] other pointer to a BitBuffer instance to copy from
*/ */
void bit_buffer_copy(BitBuffer* buf, const BitBuffer* other); void bit_buffer_copy(BitBuffer* buf, const BitBuffer* other);
/** /** Copy all BitBuffer instance's contents to this one, starting from
* Copy all BitBuffer instance's contents to this one, starting from start_index, * start_index, replacing all of the original data.
* replacing all of the original data.
* The destination capacity must be no less than the source data size
* counting from start_index.
* *
* @param [in,out] buf pointer to a BitBuffer instance to copy into * @warning The destination capacity must be no less than the source data
* @param [in] other pointer to a BitBuffer instance to copy from * size counting from start_index.
* @param [in] start_index index to begin copying source data from *
* @param[in,out] buf pointer to a BitBuffer instance to copy into
* @param[in] other pointer to a BitBuffer instance to copy from
* @param[in] start_index index to begin copying source data from
*/ */
void bit_buffer_copy_right(BitBuffer* buf, const BitBuffer* other, size_t start_index); void bit_buffer_copy_right(BitBuffer* buf, const BitBuffer* other, size_t start_index);
/** /** Copy all BitBuffer instance's contents to this one, ending with end_index,
* Copy all BitBuffer instance's contents to this one, ending with end_index,
* replacing all of the original data. * replacing all of the original data.
* The destination capacity must be no less than the source data size
* counting to end_index.
* *
* @param [in,out] buf pointer to a BitBuffer instance to copy into * @warning The destination capacity must be no less than the source data
* @param [in] other pointer to a BitBuffer instance to copy from * size counting to end_index.
* @param [in] end_index index to end copying source data at *
* @param[in,out] buf pointer to a BitBuffer instance to copy into
* @param[in] other pointer to a BitBuffer instance to copy from
* @param[in] end_index index to end copying source data at
*/ */
void bit_buffer_copy_left(BitBuffer* buf, const BitBuffer* other, size_t end_index); void bit_buffer_copy_left(BitBuffer* buf, const BitBuffer* other, size_t end_index);
/** /** Copy a byte array to a BitBuffer instance, replacing all of the original
* Copy a byte array to a BitBuffer instance, replacing all of the original data. * data.
* The destination capacity must be no less than the source data size.
* *
* @param [in,out] buf pointer to a BitBuffer instance to copy into * @warning The destination capacity must be no less than the source data
* @param [in] data pointer to the byte array to be copied * size.
* @param [in] size_bytes size of the data to be copied, in bytes *
* @param[in,out] buf pointer to a BitBuffer instance to copy into
* @param[in] data pointer to the byte array to be copied
* @param[in] size_bytes size of the data to be copied, in bytes
*/ */
void bit_buffer_copy_bytes(BitBuffer* buf, const uint8_t* data, size_t size_bytes); void bit_buffer_copy_bytes(BitBuffer* buf, const uint8_t* data, size_t size_bytes);
/** /** Copy a byte array to a BitBuffer instance, replacing all of the original
* Copy a byte array to a BitBuffer instance, replacing all of the original data. * data.
* The destination capacity must be no less than the source data size.
* *
* @param [in,out] buf pointer to a BitBuffer instance to copy into * @warning The destination capacity must be no less than the source data
* @param [in] data pointer to the byte array to be copied * size.
* @param [in] size_bits size of the data to be copied, in bits *
* @param[in,out] buf pointer to a BitBuffer instance to copy into
* @param[in] data pointer to the byte array to be copied
* @param[in] size_bits size of the data to be copied, in bits
*/ */
void bit_buffer_copy_bits(BitBuffer* buf, const uint8_t* data, size_t size_bits); void bit_buffer_copy_bits(BitBuffer* buf, const uint8_t* data, size_t size_bits);
/** /** Copy a byte with parity array to a BitBuffer instance, replacing all of the
* Copy a byte with parity array to a BitBuffer instance, replacing all of the original data. * original data.
* The destination capacity must be no less than the source data size.
* *
* @param [in,out] buf pointer to a BitBuffer instance to copy into * @warning The destination capacity must be no less than the source data
* @param [in] data pointer to the byte array to be copied * size.
* @param [in] size_bitss size of the data to be copied, in bits *
* @param[in,out] buf pointer to a BitBuffer instance to copy into
* @param[in] data pointer to the byte array to be copied
* @param[in] size_bits size of the data to be copied, in bits
* @note Parity bits are placed starting with the most significant bit
* of each byte and moving up.
* @note Example: DDDDDDDD PDDDDDDD DPDDDDDD DDP...
*/ */
void bit_buffer_copy_bytes_with_parity(BitBuffer* buf, const uint8_t* data, size_t size_bits); void bit_buffer_copy_bytes_with_parity(BitBuffer* buf, const uint8_t* data, size_t size_bits);
/** /** Write a BitBuffer instance's entire contents to an arbitrary memory location.
* Write a BitBuffer instance's entire contents to an arbitrary memory location.
* The destination memory must be allocated. Additionally, the destination
* capacity must be no less than the source data size.
* *
* @param [in] buf pointer to a BitBuffer instance to write from * @warning The destination memory must be allocated. Additionally, the
* @param [out] dest pointer to the destination memory location * destination capacity must be no less than the source data size.
* @param [in] size_bytes maximum destination data size, in bytes *
* @param[in] buf pointer to a BitBuffer instance to write from
* @param[out] dest pointer to the destination memory location
* @param[in] size_bytes maximum destination data size, in bytes
*/ */
void bit_buffer_write_bytes(const BitBuffer* buf, void* dest, size_t size_bytes); void bit_buffer_write_bytes(const BitBuffer* buf, void* dest, size_t size_bytes);
/** /** Write a BitBuffer instance's entire contents to an arbitrary memory location.
* Write a BitBuffer instance's entire contents to an arbitrary memory location.
* Additionally, place a parity bit after each byte.
* The destination memory must be allocated. Additionally, the destination
* capacity must be no less than the source data size plus parity.
* *
* @param [in] buf pointer to a BitBuffer instance to write from * Additionally, place a parity bit after each byte.
* @param [out] dest pointer to the destination memory location *
* @param [in] size_bytes maximum destination data size, in bytes * @warning The destination memory must be allocated. Additionally, the
* @param [out] bits_written actual number of bits writen, in bits * destination capacity must be no less than the source data size
* plus parity.
*
* @param[in] buf pointer to a BitBuffer instance to write from
* @param[out] dest pointer to the destination memory location
* @param[in] size_bytes maximum destination data size, in bytes
* @param[out] bits_written actual number of bits written, in bits
* @note Parity bits are placed starting with the most significant bit of
* each byte and moving up.
* @note Example: DDDDDDDD PDDDDDDD DPDDDDDD DDP...
*/ */
void bit_buffer_write_bytes_with_parity( void bit_buffer_write_bytes_with_parity(
const BitBuffer* buf, const BitBuffer* buf,
@@ -129,15 +145,17 @@ void bit_buffer_write_bytes_with_parity(
size_t size_bytes, size_t size_bytes,
size_t* bits_written); size_t* bits_written);
/** /** Write a slice of BitBuffer instance's contents to an arbitrary memory
* Write a slice of BitBuffer instance's contents to an arbitrary memory location. * location.
* The destination memory must be allocated. Additionally, the destination
* capacity must be no less than the requested slice size.
* *
* @param [in] buf pointer to a BitBuffer instance to write from * @warning The destination memory must be allocated. Additionally, the
* @param [out] dest pointer to the destination memory location * destination capacity must be no less than the requested slice
* @param [in] start_index index to begin copying source data from * size.
* @param [in] size_bytes data slice size, in bytes *
* @param[in] buf pointer to a BitBuffer instance to write from
* @param[out] dest pointer to the destination memory location
* @param[in] start_index index to begin copying source data from
* @param[in] size_bytes data slice size, in bytes
*/ */
void bit_buffer_write_bytes_mid( void bit_buffer_write_bytes_mid(
const BitBuffer* buf, const BitBuffer* buf,
@@ -147,176 +165,196 @@ void bit_buffer_write_bytes_mid(
// Checks // Checks
/** /** Check whether a BitBuffer instance contains a partial byte (i.e.\ the bit
* Check whether a BitBuffer instance contains a partial byte (i.e. the bit count * count is not divisible by 8).
* is not divisible by 8). *
* @param[in] buf pointer to a BitBuffer instance to be checked
* *
* @param [in] buf pointer to a BitBuffer instance to be checked
* @return true if the instance contains a partial byte, false otherwise * @return true if the instance contains a partial byte, false otherwise
*/ */
bool bit_buffer_has_partial_byte(const BitBuffer* buf); bool bit_buffer_has_partial_byte(const BitBuffer* buf);
/** /** Check whether a BitBuffer instance's contents start with the designated byte.
* Check whether a BitBuffer instance's contents start with the designated byte. *
* @param[in] buf pointer to a BitBuffer instance to be checked
* @param[in] byte byte value to be checked against
* *
* @param [in] buf pointer to a BitBuffer instance to be checked
* @param [in] byte byte value to be checked against
* @return true if data starts with designated byte, false otherwise * @return true if data starts with designated byte, false otherwise
*/ */
bool bit_buffer_starts_with_byte(const BitBuffer* buf, uint8_t byte); bool bit_buffer_starts_with_byte(const BitBuffer* buf, uint8_t byte);
// Getters // Getters
/** /** Get a BitBuffer instance's capacity (i.e.\ the maximum possible amount of
* Get a BitBuffer instance's capacity (i.e. the maximum possible amount of data), in bytes. * data), in bytes.
*
* @param[in] buf pointer to a BitBuffer instance to be queried
* *
* @param [in] buf pointer to a BitBuffer instance to be queried
* @return capacity, in bytes * @return capacity, in bytes
*/ */
size_t bit_buffer_get_capacity_bytes(const BitBuffer* buf); size_t bit_buffer_get_capacity_bytes(const BitBuffer* buf);
/** /** Get a BitBuffer instance's data size (i.e.\ the amount of stored data), in
* Get a BitBuffer instance's data size (i.e. the amount of stored data), in bits. * bits.
* Might be not divisible by 8 (see bit_buffer_is_partial_byte). *
* @warning Might be not divisible by 8 (see bit_buffer_is_partial_byte).
*
* @param[in] buf pointer to a BitBuffer instance to be queried
* *
* @param [in] buf pointer to a BitBuffer instance to be queried
* @return data size, in bits. * @return data size, in bits.
*/ */
size_t bit_buffer_get_size(const BitBuffer* buf); size_t bit_buffer_get_size(const BitBuffer* buf);
/** /**
* Get a BitBuffer instance's data size (i.e. the amount of stored data), in bytes. * Get a BitBuffer instance's data size (i.e.\ the amount of stored data), in
* If a partial byte is present, it is also counted. * bytes.
*
* @warning If a partial byte is present, it is also counted.
*
* @param[in] buf pointer to a BitBuffer instance to be queried
* *
* @param [in] buf pointer to a BitBuffer instance to be queried
* @return data size, in bytes. * @return data size, in bytes.
*/ */
size_t bit_buffer_get_size_bytes(const BitBuffer* buf); size_t bit_buffer_get_size_bytes(const BitBuffer* buf);
/** /** Get a byte value at a specified index in a BitBuffer instance.
* Get a byte value at a specified index in a BitBuffer instance.
* The index must be valid (i.e. less than the instance's data size in bytes).
* *
* @param [in] buf pointer to a BitBuffer instance to be queried * @warning The index must be valid (i.e.\ less than the instance's data size
* @param [in] index index of the byte in question * in bytes).
*
* @param[in] buf pointer to a BitBuffer instance to be queried
* @param[in] index index of the byte in question
*
* @return byte value
*/ */
uint8_t bit_buffer_get_byte(const BitBuffer* buf, size_t index); uint8_t bit_buffer_get_byte(const BitBuffer* buf, size_t index);
/** /** Get a byte value starting from the specified bit index in a BitBuffer
* Get a byte value starting from the specified bit index in a BitBuffer instance. * instance.
* The resulting byte might correspond to a single byte (if the index is a multiple
* of 8), or two overlapping bytes combined.
* The index must be valid (i.e. less than the instance's data size in bits).
* *
* @param [in] buf pointer to a BitBuffer instance to be queried * @warning The resulting byte might correspond to a single byte (if the
* @param [in] index bit index of the byte in question * index is a multiple of 8), or two overlapping bytes combined. The
* index must be valid (i.e.\ less than the instance's data size in
* bits).
*
* @param[in] buf pointer to a BitBuffer instance to be queried
* @param[in] index_bits bit index of the byte in question
*
* @return byte value
*/ */
uint8_t bit_buffer_get_byte_from_bit(const BitBuffer* buf, size_t index_bits); uint8_t bit_buffer_get_byte_from_bit(const BitBuffer* buf, size_t index_bits);
/** /** Get the pointer to a BitBuffer instance's underlying data.
* Get the pointer to a BitBuffer instance's underlying data. *
* @param[in] buf pointer to a BitBuffer instance to be queried
* *
* @param [in] buf pointer to a BitBuffer instance to be queried
* @return pointer to the underlying data * @return pointer to the underlying data
*/ */
const uint8_t* bit_buffer_get_data(const BitBuffer* buf); const uint8_t* bit_buffer_get_data(const BitBuffer* buf);
/** /** Get the pointer to the parity data of a BitBuffer instance.
* Get the pointer to a BitBuffer instance's underlying data.
* *
* @param [in] buf pointer to a BitBuffer instance to be queried * @param[in] buf pointer to a BitBuffer instance to be queried
* @return pointer to the underlying data *
* @return pointer to the parity data
*/ */
const uint8_t* bit_buffer_get_parity(const BitBuffer* buf); const uint8_t* bit_buffer_get_parity(const BitBuffer* buf);
// Setters // Setters
/** /** Set byte value at a specified index in a BitBuffer instance.
* Set byte value at a specified index in a BitBuffer instance.
* The index must be valid (i.e. less than the instance's data size in bytes).
* *
* @param [in,out] buf pointer to a BitBuffer instance to be modified * @warning The index must be valid (i.e.\ less than the instance's data
* @param [in] index index of the byte in question * size in bytes).
* @param [in] byte byte value to be set at index *
* @param[in,out] buf pointer to a BitBuffer instance to be modified
* @param[in] index index of the byte in question
* @param[in] byte byte value to be set at index
*/ */
void bit_buffer_set_byte(BitBuffer* buf, size_t index, uint8_t byte); void bit_buffer_set_byte(BitBuffer* buf, size_t index, uint8_t byte);
/** /** Set byte and parity bit value at a specified index in a BitBuffer instance.
* Set byte and parity bit value at a specified index in a BitBuffer instance.
* The index must be valid (i.e. less than the instance's data size in bytes).
* *
* @param [in,out] buf pointer to a BitBuffer instance to be modified * @warning The index must be valid (i.e.\ less than the instance's data
* @param [in] index index of the byte in question * size in bytes).
* @param [in] byte byte value to be set at index *
* @param [in] parity parity bit value to be set at index * @param[in,out] buff pointer to a BitBuffer instance to be modified
* @param[in] index index of the byte in question
* @param[in] byte byte value to be set at index
* @param[in] parity parity bit value to be set at index
*/ */
void bit_buffer_set_byte_with_parity(BitBuffer* buff, size_t index, uint8_t byte, bool parity); void bit_buffer_set_byte_with_parity(BitBuffer* buff, size_t index, uint8_t byte, bool parity);
/** /** Resize a BitBuffer instance to a new size, in bits.
* Resize a BitBuffer instance to a new size, in bits. *
* @warning May cause bugs. Use only if absolutely necessary. * @warning May cause bugs. Use only if absolutely necessary.
* *
* @param [in,out] buf pointer to a BitBuffer instance to be resized * @param[in,out] buf pointer to a BitBuffer instance to be resized
* @param [in] new_size the new size of the buffer, in bits * @param[in] new_size the new size of the buffer, in bits
*/ */
void bit_buffer_set_size(BitBuffer* buf, size_t new_size); void bit_buffer_set_size(BitBuffer* buf, size_t new_size);
/** /** Resize a BitBuffer instance to a new size, in bytes.
* Resize a BitBuffer instance to a new size, in bytes. *
* @warning May cause bugs. Use only if absolutely necessary. * @warning May cause bugs. Use only if absolutely necessary.
* *
* @param [in,out] buf pointer to a BitBuffer instance to be resized * @param[in,out] buf pointer to a BitBuffer instance to be resized
* @param [in] new_size_bytes the new size of the buffer, in bytes * @param[in] new_size_bytes the new size of the buffer, in bytes
*/ */
void bit_buffer_set_size_bytes(BitBuffer* buf, size_t new_size_bytes); void bit_buffer_set_size_bytes(BitBuffer* buf, size_t new_size_bytes);
// Modification // Modification
/** /** Append all BitBuffer's instance contents to this one.
* Append all BitBuffer's instance contents to this one. The destination capacity
* must be no less than its original data size plus source data size.
* *
* @param [in,out] buf pointer to a BitBuffer instance to be appended to * @warning The destination capacity must be no less than its original
* @param [in] other pointer to a BitBuffer instance to be appended * data size plus source data size.
*
* @param[in,out] buf pointer to a BitBuffer instance to be appended to
* @param[in] other pointer to a BitBuffer instance to be appended
*/ */
void bit_buffer_append(BitBuffer* buf, const BitBuffer* other); void bit_buffer_append(BitBuffer* buf, const BitBuffer* other);
/** /** Append a BitBuffer's instance contents to this one, starting from
* Append a BitBuffer's instance contents to this one, starting from start_index. * start_index.
* The destination capacity must be no less than the source data size
* counting from start_index.
* *
* @param [in,out] buf pointer to a BitBuffer instance to be appended to * @warning The destination capacity must be no less than the source data
* @param [in] other pointer to a BitBuffer instance to be appended * size counting from start_index.
* @param [in] start_index index to begin copying source data from *
* @param[in,out] buf pointer to a BitBuffer instance to be appended to
* @param[in] other pointer to a BitBuffer instance to be appended
* @param[in] start_index index to begin copying source data from
*/ */
void bit_buffer_append_right(BitBuffer* buf, const BitBuffer* other, size_t start_index); void bit_buffer_append_right(BitBuffer* buf, const BitBuffer* other, size_t start_index);
/** /** Append a byte to a BitBuffer instance.
* Append a byte to a BitBuffer instance.
* The destination capacity must be no less its original data size plus one.
* *
* @param [in,out] buf pointer to a BitBuffer instance to be appended to * @warning The destination capacity must be no less its original data
* @param [in] byte byte value to be appended * size plus one.
*
* @param[in,out] buf pointer to a BitBuffer instance to be appended to
* @param[in] byte byte value to be appended
*/ */
void bit_buffer_append_byte(BitBuffer* buf, uint8_t byte); void bit_buffer_append_byte(BitBuffer* buf, uint8_t byte);
/** /** Append a byte array to a BitBuffer instance.
* Append a byte array to a BitBuffer instance.
* The destination capacity must be no less its original data size plus source data size.
* *
* @param [in,out] buf pointer to a BitBuffer instance to be appended to * @warning The destination capacity must be no less its original data
* @param [in] data pointer to the byte array to be appended * size plus source data size.
* @param [in] size_bytes size of the data to be appended, in bytes *
* @param[in,out] buf pointer to a BitBuffer instance to be appended to
* @param[in] data pointer to the byte array to be appended
* @param[in] size_bytes size of the data to be appended, in bytes
*/ */
void bit_buffer_append_bytes(BitBuffer* buf, const uint8_t* data, size_t size_bytes); void bit_buffer_append_bytes(BitBuffer* buf, const uint8_t* data, size_t size_bytes);
/** /** Append a bit to a BitBuffer instance.
* Append a bit to a BitBuffer instance.
* The destination capacity must be sufficient to accomodate the additional bit.
* *
* @param [in,out] buf pointer to a BitBuffer instance to be appended to * @warning The destination capacity must be sufficient to accommodate the
* @param [in] bit bit value to be appended * additional bit.
*
* @param[in,out] buf pointer to a BitBuffer instance to be appended to
* @param[in] bit bit value to be appended
*/ */
void bit_buffer_append_bit(BitBuffer* buf, bool bit); void bit_buffer_append_bit(BitBuffer* buf, bool bit);