From 384853b41848b0186229b8505a9c4f619533f550 Mon Sep 17 00:00:00 2001 From: Astra Date: Fri, 12 Jul 2024 19:09:12 +0900 Subject: [PATCH 1/3] Improve bit_buffer.h docs --- lib/toolbox/bit_buffer.h | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/lib/toolbox/bit_buffer.h b/lib/toolbox/bit_buffer.h index 5c50e729c60..3e9f3c38f25 100644 --- a/lib/toolbox/bit_buffer.h +++ b/lib/toolbox/bit_buffer.h @@ -98,6 +98,8 @@ void bit_buffer_copy_bits(BitBuffer* buf, const uint8_t* data, size_t size_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_bitss size of the data to be copied, in bits + * @note Parity bits are placed starting with the least significant bit of each byte and moving up. + * @note Example: PDDDDDDD DPDDDDDD DDPD... */ void bit_buffer_copy_bytes_with_parity(BitBuffer* buf, const uint8_t* data, size_t size_bits); @@ -122,6 +124,8 @@ void bit_buffer_write_bytes(const BitBuffer* buf, void* dest, size_t size_bytes) * @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 writen, in bits + * @note Parity bits are placed starting with the least significant bit of each byte and moving up. + * @note Example: PDDDDDDD DPDDDDDD DDPD... */ void bit_buffer_write_bytes_with_parity( const BitBuffer* buf, @@ -222,10 +226,10 @@ uint8_t bit_buffer_get_byte_from_bit(const BitBuffer* buf, size_t index_bits); const uint8_t* bit_buffer_get_data(const BitBuffer* buf); /** - * Get the pointer to a BitBuffer instance's underlying data. + * Get the pointer to the parity data of a BitBuffer instance. * * @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); From 0130d217f6d922911504dd87de61076801780b8b Mon Sep 17 00:00:00 2001 From: Aleksandr Kutuzov Date: Fri, 6 Sep 2024 16:58:25 +0100 Subject: [PATCH 2/3] Toolbox: update doxygen comments fix spelling --- lib/toolbox/bit_buffer.h | 386 +++++++++++++++++++++------------------ 1 file changed, 210 insertions(+), 176 deletions(-) diff --git a/lib/toolbox/bit_buffer.h b/lib/toolbox/bit_buffer.h index 3e9f3c38f25..8f924b724e0 100644 --- a/lib/toolbox/bit_buffer.h +++ b/lib/toolbox/bit_buffer.h @@ -1,3 +1,9 @@ +/** Bit Buffer + * + * Various bits and bytes manipulation tools. + * + * @file bit_buffer.h + */ #pragma once #include @@ -10,122 +16,128 @@ extern "C" { typedef struct BitBuffer BitBuffer; -// Construction, deletion, reset - -/** - * Allocate a BitBuffer instance. +/** Allocate a BitBuffer instance. * - * @param [in] capacity_bytes maximum buffer capacity, in bytes - * @return pointer to the allocated BitBuffer instance + * @param[in] capacity_bytes maximum buffer capacity, in bytes + * + * @return pointer to the allocated BitBuffer instance */ 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); -/** - * 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); // Copy and write -/** - * Copy another BitBuffer instance's contents to this one, replacing - * all of the original data. - * The destination capacity must be no less than the source data size. +/** Copy another BitBuffer instance's contents to this one, replacing all of the + * original data. * - * @param [in,out] buf pointer to a BitBuffer instance to copy into - * @param [in] other pointer to a BitBuffer instance to copy from - * @note + * @warning The destination capacity must be no less than the source data + * size. + * + * @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); -/** - * Copy all BitBuffer instance's contents to this one, starting from start_index, - * replacing all of the original data. - * The destination capacity must be no less than the source data size - * counting from start_index. +/** Copy all BitBuffer instance's contents to this one, starting from + * start_index, replacing all of the original data. * - * @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 + * @warning 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 + * @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); -/** - * 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. - * 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 - * @param [in] other pointer to a BitBuffer instance to copy from - * @param [in] end_index index to end copying source data at + * @warning 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 + * @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); -/** - * Copy a byte array to a BitBuffer instance, replacing all of the original data. - * The destination capacity must be no less than the source data size. +/** Copy a byte array to a BitBuffer instance, replacing all of the original + * data. * - * @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 + * @warning The destination capacity must be no less than the source data + * size. + * + * @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); -/** - * Copy a byte array to a BitBuffer instance, replacing all of the original data. - * The destination capacity must be no less than the source data size. +/** Copy a byte array to a BitBuffer instance, replacing all of the original + * data. * - * @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 + * @warning The destination capacity must be no less than the source data + * size. + * + * @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); -/** - * Copy a byte with parity array to a BitBuffer instance, replacing 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 - * @param [in] data pointer to the byte array to be copied - * @param [in] size_bitss size of the data to be copied, in bits - * @note Parity bits are placed starting with the least significant bit of each byte and moving up. - * @note Example: PDDDDDDD DPDDDDDD DDPD... +/** Copy a byte with parity array to a BitBuffer instance, replacing all of the + * original data. + * + * @warning The destination capacity must be no less than the source data + * size. + * + * @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 least significant bit + * of each byte and moving up. + * @note Example: PDDDDDDD DPDDDDDD DDPD... */ 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. - * The destination memory must be allocated. Additionally, the destination - * capacity must be no less than the source data size. +/** Write a BitBuffer instance's entire contents to an arbitrary memory location. * - * @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 + * @warning 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 + * @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); -/** - * 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 - * @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 writen, in bits - * @note Parity bits are placed starting with the least significant bit of each byte and moving up. - * @note Example: PDDDDDDD DPDDDDDD DDPD... + * + * @warning 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 + * @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 least significant bit of + * each byte and moving up. + * @note Example: PDDDDDDD DPDDDDDD DDPD... */ void bit_buffer_write_bytes_with_parity( const BitBuffer* buf, @@ -133,15 +145,17 @@ void bit_buffer_write_bytes_with_parity( size_t size_bytes, size_t* bits_written); -/** - * Write a slice of BitBuffer instance's contents to an arbitrary memory 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 - * @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 +/** Write a slice of BitBuffer instance's contents to an arbitrary memory + * location. + * + * @warning 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 + * @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( const BitBuffer* buf, @@ -151,176 +165,196 @@ void bit_buffer_write_bytes_mid( // Checks -/** - * Check whether a BitBuffer instance contains a partial byte (i.e. the bit count - * is not divisible by 8). +/** Check whether a BitBuffer instance contains a partial byte (i.e.\ the bit + * count 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); -/** - * 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); // Getters -/** - * Get a BitBuffer instance's capacity (i.e. the maximum possible amount of data), in bytes. +/** Get a BitBuffer instance's capacity (i.e.\ the maximum possible amount of + * 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); -/** - * Get a BitBuffer instance's data size (i.e. the amount of stored data), in bits. - * Might be not divisible by 8 (see bit_buffer_is_partial_byte). +/** Get a BitBuffer instance's data size (i.e.\ the amount of stored data), in + * bits. + * + * @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); /** - * Get a BitBuffer instance's data size (i.e. the amount of stored data), in bytes. - * If a partial byte is present, it is also counted. + * Get a BitBuffer instance's data size (i.e.\ the amount of stored data), in + * bytes. * - * @param [in] buf pointer to a BitBuffer instance to be queried - * @return data size, in bytes. + * @warning If a partial byte is present, it is also counted. + * + * @param[in] buf pointer to a BitBuffer instance to be queried + * + * @return data size, in bytes. */ size_t bit_buffer_get_size_bytes(const BitBuffer* buf); -/** - * 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). +/** Get a byte value at a specified index in a BitBuffer instance. + * + * @warning 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 - * @param [in] index index of the byte in question + * @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); -/** - * Get a byte value starting from the specified bit index in a BitBuffer 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). +/** Get a byte value starting from the specified bit index in a BitBuffer + * instance. + * + * @warning 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 - * @param [in] index bit index of the byte in question + * @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); -/** - * 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 - * @return pointer to the underlying data + * @param[in] buf pointer to a BitBuffer instance to be queried + * + * @return pointer to the underlying data */ 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 the parity data of a BitBuffer instance. * - * @param [in] buf pointer to a BitBuffer instance to be queried - * @return pointer to the parity data + * @param[in] buf pointer to a BitBuffer instance to be queried + * + * @return pointer to the parity data */ const uint8_t* bit_buffer_get_parity(const BitBuffer* buf); // Setters -/** - * 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). +/** Set byte value at a specified index in a BitBuffer instance. * - * @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 + * @warning 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 + * @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); -/** - * 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). +/** Set byte and parity bit value at a specified index in a BitBuffer instance. + * + * @warning 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 - * @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 + * @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); -/** - * Resize a BitBuffer instance to a new size, in bits. - * @warning May cause bugs. Use only if absolutely necessary. +/** Resize a BitBuffer instance to a new size, in bits. + * + * @warning May cause bugs. Use only if absolutely necessary. * - * @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,out] buf pointer to a BitBuffer instance to be resized + * @param[in] new_size the new size of the buffer, in bits */ void bit_buffer_set_size(BitBuffer* buf, size_t new_size); -/** - * Resize a BitBuffer instance to a new size, in bytes. - * @warning May cause bugs. Use only if absolutely necessary. +/** Resize a BitBuffer instance to a new size, in bytes. + * + * @warning May cause bugs. Use only if absolutely necessary. * - * @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,out] buf pointer to a BitBuffer instance to be resized + * @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); // Modification -/** - * 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. +/** Append all BitBuffer's instance contents to this one. + * + * @warning 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 - * @param [in] other pointer to a BitBuffer instance to be appended + * @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); -/** - * Append a BitBuffer's instance contents to this one, starting from start_index. - * The destination capacity must be no less than the source data size - * counting from start_index. +/** Append a BitBuffer's instance contents to this one, starting from + * start_index. + * + * @warning 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 - * @param [in] other pointer to a BitBuffer instance to be appended - * @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); -/** - * Append a byte to a BitBuffer instance. - * The destination capacity must be no less its original data size plus one. +/** Append a byte to a BitBuffer instance. + * + * @warning 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 - * @param [in] byte byte value to be appended + * @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); -/** - * Append a byte array to a BitBuffer instance. - * The destination capacity must be no less its original data size plus source data size. +/** Append a byte array to a BitBuffer instance. + * + * @warning 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 - * @param [in] data pointer to the byte array to be appended - * @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); -/** - * Append a bit to a BitBuffer instance. - * The destination capacity must be sufficient to accomodate the additional bit. +/** Append a bit to a BitBuffer instance. + * + * @warning The destination capacity must be sufficient to accommodate the + * additional bit. * - * @param [in,out] buf pointer to a BitBuffer instance to be appended to - * @param [in] bit bit value to be appended + * @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); From 9fb7583caee279684fef2b999bbb897f74fe1405 Mon Sep 17 00:00:00 2001 From: Aleksandr Kutuzov Date: Wed, 2 Oct 2024 18:21:26 +0100 Subject: [PATCH 3/3] Toolbox: update bit lib docs --- lib/toolbox/bit_buffer.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/toolbox/bit_buffer.h b/lib/toolbox/bit_buffer.h index 8f924b724e0..bd95ec95ce5 100644 --- a/lib/toolbox/bit_buffer.h +++ b/lib/toolbox/bit_buffer.h @@ -106,9 +106,9 @@ void bit_buffer_copy_bits(BitBuffer* buf, const uint8_t* data, size_t size_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 least significant bit + * @note Parity bits are placed starting with the most significant bit * of each byte and moving up. - * @note Example: PDDDDDDD DPDDDDDD DDPD... + * @note Example: DDDDDDDD PDDDDDDD DPDDDDDD DDP... */ void bit_buffer_copy_bytes_with_parity(BitBuffer* buf, const uint8_t* data, size_t size_bits); @@ -135,9 +135,9 @@ void bit_buffer_write_bytes(const BitBuffer* buf, void* dest, size_t size_bytes) * @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 least significant bit of + * @note Parity bits are placed starting with the most significant bit of * each byte and moving up. - * @note Example: PDDDDDDD DPDDDDDD DDPD... + * @note Example: DDDDDDDD PDDDDDDD DPDDDDDD DDP... */ void bit_buffer_write_bytes_with_parity( const BitBuffer* buf,