Skip to content
Snippets Groups Projects
Commit 89b2841b authored by Sergi Hernandez's avatar Sergi Hernandez
Browse files

Added the documentation for the buffer module.

Modified the Makefile to generate the documentation and added the necessary doxygen configuration files.
parent 279cdf6f
No related branches found
No related tags found
No related merge requests found
......@@ -12,6 +12,8 @@ COMPILE_OPTS_M3 = -mfloat-abi=softfp -mcpu=cortex-m3
INCLUDE_DIRS = -I./include/
DOC_DIR = ./doc
TCHAIN_PREFIX=arm-none-eabi-
CC = $(TCHAIN_PREFIX)gcc
......@@ -71,6 +73,9 @@ $(UTILS_OUT_M3): mkdir_build $(UTILS_M3_OBJS)
mkdir -p lib
$(AR) $(ARFLAGS) $@ $(UTILS_M3_OBJS)
doc:
doxygen $(DOC_DIR)/doxygen.conf
clean:
rm -f $(UTILS_M4_FPU_OBJS)
rm -f $(UTILS_M0_OBJS)
......@@ -78,4 +83,6 @@ clean:
rm -f $(UTILS_M3_OBJS)
rm -rf lib
rm -rf build
rm -rf doc/html
.PHONY: all clean doc
This diff is collapsed.
PROJECT_NAME = "Utilities library for STM32 processors"
<META HTTP-EQUIV="Refresh" CONTENT="0; URL=html/index.html">
/*! \mainpage Utilities library for STM32 processors
\section Installation
\subsection Pre-Requisites
This package requires of the following libraries and packages
- STM32 HAL library.
.
\subsection Compilation
Just download this package, uncompress it, and execute
- make
.
to obtain the static libraries for all processor families (in this case called
<em>utils_m0.a</em> <em>utils_m0plus.a</em> <em>utils_m3.a</em>
<em>utils_m4_fpu.a</em>).
To generate this documentation type
- make doc
.
The files in the <em>build</em> directory are genetated by <em>make</em> and
can be safely removed.
\section License
This package is licensed under a
<a href="http://www.gnu.org/licenses/lgpl.html">
LGPL 3.0 License</a>.
\section Disclaimer
This is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/** @file */
#ifndef _BUFFER_H
#define _BUFFER_H
#ifndef MAX_BUFFER_LENGTH
/**
* \brief Size of the buffer in bytes
*
*/
#define MAX_BUFFER_LENGTH 512
#endif
/**
* \brief Structure to handle a circular buffer of configurable length
*
* This structure is used to implement a FIFO circular buffer of configurable
* length. All buffers must have the same length defined by the MAX_BUFFER_LENGTH
* macro, which can be re-defined by user code.
*
* A buffer structure is first initialized by the buffer_init() function, and
* after that, data can be read and written either byte by byte using the
* buffer_read_byte() and buffer_write_byte() functions respectively, or by
* vectors using the buffer_read and buffer_write functions respectively.
*
* The buffer_get_num_data() functions can be used to get the number of bytes
* in the buffer and the buffer_flush() function can be used to remove all
* data from the buffer.
*/
typedef struct
{
/**
* \brief Data buffer
*
* This is intended as a private variable to be used only internally by
* module functions.
*
* Static memory where the buffer data is stored. The size of this vector
* is defined at build time depending on the value of MAX_BUFFER_LENGTH.
*/
unsigned char data[MAX_BUFFER_LENGTH];
/**
* \brief Write pointer
*
* This is intended as a private variable to be used only internally by
* module functions.
*
* Address inside the buffer where the next byte will be written. This
* pointer is set to 0 when the buffer_init() function is called and
* incremented by the number of bytes written each time a write operation
* is executed.
*
* This pointer wraps to 0 when the buffer size is reached and it is equal
* to the read pointer only when the buffer is either empty or full.
*/
unsigned short int wr_ptr;
/**
* \brief Read pointer
*
* This is intended as a private variable to be used only internally by
* module functions.
*
* Address inside the buffer where the next byte will be read. This
* pointer is set to 0 when the buffer_init() function is called and
* incremented by the number of bytes read each time a read operation
* is executed.
*
* This pointer wraps to 0 when the buffer size is reached and it is equal
* to the write pointer only when the buffer is either empty or full.
*/
unsigned short int rd_ptr;
/**
* \brief Number of bytes in the buffer
*
* This is intended as a private variable to be used only internally by
* module functions.
*
* Number of bytes inside the buffer. This value is automatically updated
* each time a read or write operation is executed on the buffer. This
* value is set to 0 when the buffer_init() function is called.
*/
unsigned short int num_data;
}TBuffer;
/* public functions */
/**
* \brief Function to initialize the buffer structure
*
* This function initializes the TBuffer structure by setting to 0 the read
* and write pointers and the number of data inside the buffer. This function
* should only be called once when the TBuffer variable is first created, to
* empty the buffer at any other time, use the buffer_flush() function.
*
* \param buffer pointer to a valid TBuffer structure to be initialized. If
* memory is not pre-allocated before calling this function, its
* behavior is unpredictable.
*/
void buffer_init(TBuffer *buffer);
/**
* \brief Function to empty the buffer structure
*
* This function empties the TBuffer structure by setting the write pointer equal
* to the read pointer, and the number of data to zero. The data is not actually
* erased from the buffer when this function is called.
*
* \param buffer pointer to a valid TBuffer structure to be initialized. If
* memory is not pre-allocated before calling this function, its
* behavior is unpredictable.
*/
void buffer_flush(TBuffer *buffer);
/**
* \brief Function to get the number of bytes in the buffer
*
* This function returns the number of data in the buffer in bytes. The
* TBuffer structure must be initialized by the buffer_init() function before
* calling this function.
*
* \param buffer pointer to a valid TBuffer structure to be initialized. If
* memory is not pre-allocated before calling this function, its
* behavior is unpredictable.
*
* \return the number of bytes in the buffer. This is a number between 0 and
* MAX_BUFFER_LENGTH.
*/
inline unsigned short int buffer_get_num_data(TBuffer *buffer);
/**
* \brief Function to write a single byte to the buffer
*
* This function writes a single byte to the buffer. If the buffer is full,
* the new data is not written into the buffer, and the function returns an
* error. On success, the write pointer and the number of data is incremented
* by 1 and the new data stored in the internal buffer.
*
* \param buffer pointer to a valid TBuffer structure to be initialized. If
* memory is not pre-allocated before calling this function, its
* behavior is unpredictable.
* \param data new data to be written to the buffer.
*
* \return This function returns 1 on success and 0 otherwise.
*/
unsigned char buffer_write_byte(TBuffer *buffer,unsigned char data);
/**
* \brief Function to read a single byte from the buffer
*
* This function reads a single byte from the buffer. If the buffer is empty,
* the data returned by this function is not valid and an error is returned.
* On success the read pointer is incremented and the number of bytes is
* decreased by 1 and the oldest data is returned.
*
* \param buffer pointer to a valid TBuffer structure to be initialized. If
* memory is not pre-allocated before calling this function, its
* behavior is unpredictable.
* \param data pointer to a byte variable to store the buffer data. Memory for
* this parameter must be pre-allocated before calling this function
* to avoid unexpected behaviour.
*
* \return This function returns 1 on success and 0 otherwise.
*/
unsigned char buffer_read_byte(TBuffer *buffer,unsigned char *data);
/**
* \brief Function to write a vector to the buffer
*
* This functions writes a number of bytes into the buffer. The new data is copied
* into the internal buffer until it is full or all new data has been copied. In
* any case, this function returns the number of bytes actually written into the
* buffer.
*
* The write pointer and the number of bytes is incremented by the number of bytes
* actually written.
*
* \param buffer pointer to a valid TBuffer structure to be initialized. If
* memory is not pre-allocated before calling this function, its
* behavior is unpredictable.
* \param data pointer to a byte vector variable with the data to be written to
* the buffer. Memory for this parameter must be pre-allocated before calling
* this function to avoid unexpected behaviour.
* \param length number of bytes to be written into the buffer.
*
* \return number of bytes actually written into the buffer. This value can be used
* to check wether the function was successfull or not.
*/
unsigned short int buffer_write(TBuffer *buffer,unsigned char *data,unsigned short int length);
/**
* \brief Function to read a vector from the buffer
*
* This function reads a number of bytes from the buffer. Data is read from the buffer
* until it is empty or no more data is requested. In any case, this functions returns
* the number of bytes actually read from the buffer.
*
* The read pointer is incremented by the number of bytes actually read, and the number
* of bytes is decremented by the same value.
*
* \param buffer pointer to a valid TBuffer structure to be initialized. If
* memory is not pre-allocated before calling this function, its
* behavior is unpredictable.
* \param data pointer to a byte vector variable to store the buffer data. Memory for
* this parameter must be pre-allocated before calling this function to avoid
* unexpected behaviour.
* \param length number of bytes to be read from the buffer.
*
* \return number of bytes actually read from the buffer. This value can be used
* to check wether the function was successfull or not.
*/
unsigned short int buffer_read(TBuffer *buffer,unsigned char *data,unsigned short int length);
#endif
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment