David Saul / nrf51-sdk

R1 code for micro:bit based train controller code, requires second micro:bit running rx code to operate - see https://meanderingpi.wordpress.com/ for more information

Fork of nrf51-sdk by Lancaster University

Embed: (wiki syntax)

« Back to documentation index

Memory pool
Modules | Functions

Memory pool

Memory pool implementation. More...

Modules

 Memory Pool Internal
 

Memory pool internal definitions.


Functions

uint32_t hci_mem_pool_open (void)
 Function for opening the module.
uint32_t hci_mem_pool_close (void)
 Function for closing the module.
uint32_t hci_mem_pool_tx_alloc (void **pp_buffer)
 Function for allocating requested amount of TX memory.
uint32_t hci_mem_pool_tx_free (void)
 Function for freeing previously allocated TX memory.
uint32_t hci_mem_pool_rx_produce (uint32_t length, void **pp_buffer)
 Function for producing a free RX memory block for usage.
uint32_t hci_mem_pool_rx_data_size_set (uint32_t length)
 Function for setting the length of the last produced RX memory block.
uint32_t hci_mem_pool_rx_extract (uint8_t **pp_buffer, uint32_t *p_length)
 Function for extracting a packet, which has been filled with read data, for further processing.
uint32_t hci_mem_pool_rx_consume (uint8_t *p_buffer)
 Function for freeing previously extracted packet, which has been filled with read data.

Detailed Description

Memory pool implementation.

Memory pool implementation, based on circular buffer data structure, which supports asynchronous processing of RX data. The current default implementation supports 1 TX buffer and 4 RX buffers. The memory managed by the pool is allocated from static storage instead of heap. The internal design of the circular buffer implementing the RX memory layout is illustrated in the picture below.

memory_pool.png

Circular buffer design

The expected call order for the RX APIs is as follows:

  • hci_mem_pool_rx_produce
  • hci_mem_pool_rx_data_size_set
  • hci_mem_pool_rx_extract
  • hci_mem_pool_rx_consume
Warning:
If the above mentioned expected call order is violated the end result can be undefined.
Component specific configuration options

The following compile time configuration options are available to suit various implementations:

  • TX_BUF_SIZE TX buffer size in bytes.
  • RX_BUF_SIZE RX buffer size in bytes.
  • RX_BUF_QUEUE_SIZE RX buffer element size.

Function Documentation

uint32_t hci_mem_pool_close ( void   )

Function for closing the module.

Return values:
NRF_SUCCESSOperation success.

Definition at line 79 of file hci_mem_pool.c.

uint32_t hci_mem_pool_open ( void   )

Function for opening the module.

Return values:
NRF_SUCCESSOperation success.

Definition at line 64 of file hci_mem_pool.c.

uint32_t hci_mem_pool_rx_consume ( uint8_t *  p_buffer )

Function for freeing previously extracted packet, which has been filled with read data.

Parameters:
[in]p_bufferPointer to consumed buffer.
Return values:
NRF_SUCCESSOperation success.
NRF_ERROR_NO_MEMOperation failure. No packet available to free.
NRF_ERROR_INVALID_ADDROperation failure. Not a valid pointer.

Definition at line 163 of file hci_mem_pool.c.

uint32_t hci_mem_pool_rx_data_size_set ( uint32_t  length )

Function for setting the length of the last produced RX memory block.

Warning:
If call to this API is omitted the end result is that the following call to mem_pool_rx_extract will return incorrect data in the p_length output parameter.
Parameters:
[in]lengthAmount, in bytes, of actual memory used.
Return values:
NRF_SUCCESSOperation success. Length was set.

Definition at line 210 of file hci_mem_pool.c.

uint32_t hci_mem_pool_rx_extract ( uint8_t **  pp_buffer,
uint32_t *  p_length 
)

Function for extracting a packet, which has been filled with read data, for further processing.

Parameters:
[out]pp_bufferPointer to the packet data.
[out]p_lengthLength of packet data in bytes.
Return values:
NRF_SUCCESSOperation success.
NRF_ERROR_NO_MEMOperation failure. No packet available to extract.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.

Definition at line 222 of file hci_mem_pool.c.

uint32_t hci_mem_pool_rx_produce ( uint32_t  length,
void **  pp_buffer 
)

Function for producing a free RX memory block for usage.

Note:
Upon produce request amount being 0, NRF_SUCCESS is returned.
Parameters:
[in]lengthAmount, in bytes, of free memory to be produced.
[out]pp_bufferPointer to the allocated memory.
Return values:
NRF_SUCCESSOperation success. Free RX memory block produced.
NRF_ERROR_NO_MEMOperation failure. No suitable memory available for allocation.
NRF_ERROR_DATA_SIZEOperation failure. Request size exceeds limit.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.

Definition at line 119 of file hci_mem_pool.c.

uint32_t hci_mem_pool_tx_alloc ( void **  pp_buffer )

Function for allocating requested amount of TX memory.

Parameters:
[out]pp_bufferPointer to the allocated memory.
Return values:
NRF_SUCCESSOperation success. Memory was allocated.
NRF_ERROR_NO_MEMOperation failure. No memory available for allocation.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.

Definition at line 85 of file hci_mem_pool.c.

uint32_t hci_mem_pool_tx_free ( void   )

Function for freeing previously allocated TX memory.

Note:
Memory management follows the FIFO principle meaning that free() order must match the alloc(...) order, which is the reason for omitting exact memory block identifier as an input parameter.
Return values:
NRF_SUCCESSOperation success. Memory was freed.

Definition at line 111 of file hci_mem_pool.c.

Generated on Tue Jul 12 2022 19:00:13 by  doxygen 1.7.2