LWIPMemoryManager.h

00001 /* Copyright (c) 2017 ARM Limited
00002  *
00003  * Licensed under the Apache License, Version 2.0 (the "License");
00004  * you may not use this file except in compliance with the License.
00005  * You may obtain a copy of the License at
00006  *
00007  *     http://www.apache.org/licenses/LICENSE-2.0
00008  *
00009  * Unless required by applicable law or agreed to in writing, software
00010  * distributed under the License is distributed on an "AS IS" BASIS,
00011  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00012  * See the License for the specific language governing permissions and
00013  * limitations under the License.
00014  */
00015 
00016 #ifndef LWIP_MEMORY_MANAGER_H
00017 #define LWIP_MEMORY_MANAGER_H
00018 
00019 #include "EMACMemoryManager.h"
00020 
00021 
00022 class LWIPMemoryManager : public EMACMemoryManager {
00023 public:
00024 
00025     /**
00026      * Allocates memory buffer from the heap
00027      *
00028      * Memory buffer allocated from heap is always contiguous and can be arbitrary size.
00029      *
00030      * @param size     Size of the memory to allocate in bytes
00031      * @param align    Memory alignment requirement in bytes
00032      * @return         Allocated memory buffer, or NULL in case of error
00033      */
00034     virtual net_stack_mem_buf_t *alloc_heap(uint32_t size, uint32_t align);
00035 
00036     /**
00037      * Allocates memory buffer chain from a pool
00038      *
00039      * Memory allocated from pool is contiguous if size is equal or less than
00040      * (aligned) allocation unit, otherwise may be chained. Will typically come from
00041      * fixed-size packet pool memory.
00042      *
00043      * @param  size    Total size of the memory to allocate in bytes
00044      * @param  align   Memory alignment requirement for each buffer in bytes
00045      * @return         Allocated memory buffer chain, or NULL in case of error
00046      */
00047     virtual net_stack_mem_buf_t *alloc_pool(uint32_t size, uint32_t align);
00048 
00049     /**
00050      * Get memory buffer pool allocation unit
00051      *
00052      * Returns the maximum size of contiguous memory that can be allocated from a pool.
00053      *
00054      * @param align    Memory alignment requirement in bytes
00055      * @return         Contiguous memory size
00056      */
00057     virtual uint32_t get_pool_alloc_unit(uint32_t align) const;
00058 
00059     /**
00060      * Free memory buffer chain
00061      *
00062      * If memory buffer is chained must point to the start of the chain. Frees all buffers
00063      * from the chained list.
00064      *
00065      * @param buf      Memory buffer chain to be freed.
00066      */
00067     virtual void free(net_stack_mem_buf_t *buf);
00068 
00069     /**
00070      * Return total length of a memory buffer chain
00071      *
00072      * Returns a total length of this buffer and any following buffers in the chain.
00073      *
00074      * @param buf      Memory buffer chain
00075      * @return         Total length in bytes
00076      */
00077     virtual uint32_t get_total_len(const net_stack_mem_buf_t *buf) const;
00078 
00079     /**
00080      * Copy a memory buffer chain
00081      *
00082      * Copies data from one buffer chain to another. Copy operation does not adjust the lengths
00083      * of the copied-to memory buffer chain, so chain total lengths must be the same.
00084      *
00085      * @param to_buf    Memory buffer chain to copy to
00086      * @param from_buf  Memory buffer chain to copy from
00087      */
00088     virtual void copy(net_stack_mem_buf_t *to_buf, const net_stack_mem_buf_t *from_buf);
00089 
00090     /**
00091      * Copy to a memory buffer chain
00092      *
00093      * Copies data to a buffer chain. Copy operation does not adjust the lengths
00094      * of the copied-to memory buffer chain, so chain total length must match the
00095      * copied length.
00096      *
00097      * @param to_buf    Memory buffer chain to copy to
00098      * @param ptr       Pointer to data
00099      * @param len       Data length
00100      */
00101     virtual void copy_to_buf(net_stack_mem_buf_t *to_buf, const void *ptr, uint32_t len);
00102 
00103     /**
00104      * Copy from a memory buffer chain
00105      *
00106      * Copies data from a memory buffer chain.
00107      *
00108      * @param len       Data length
00109      * @param ptr       Pointer to data
00110      * @param from_buf  Memory buffer chain to copy from
00111      * @return          Length of the data that was copied
00112      */
00113     virtual uint32_t copy_from_buf(void *ptr, uint32_t len, const net_stack_mem_buf_t *from_buf) const;
00114 
00115     /**
00116      * Concatenate two memory buffer chains
00117      *
00118      * Concatenates buffer chain to end of the other buffer chain. Concatenated-to buffer total length
00119      * is adjusted accordingly. cat_buf must point to the start of a the chain. After concatenation
00120      * to_buf's chain now owns those buffers, and they will be freed when the to_buf chain is freed.
00121      *
00122      * @param to_buf   Memory buffer chain to concatenate to
00123      * @param cat_buf  Memory buffer chain to concatenate
00124      */
00125     virtual void cat(net_stack_mem_buf_t *to_buf, net_stack_mem_buf_t *cat_buf);
00126 
00127     /**
00128      * Returns the next buffer
00129      *
00130      * Returns the next buffer from the memory buffer chain.
00131      *
00132      * @param buf      Memory buffer
00133      * @return         The next memory buffer, or NULL if last
00134      */
00135     virtual net_stack_mem_buf_t *get_next(const net_stack_mem_buf_t *buf) const;
00136 
00137     /**
00138      * Return pointer to the payload of the buffer
00139      *
00140      * @param buf      Memory buffer
00141      * @return         Pointer to the payload
00142      */
00143     virtual void *get_ptr(const net_stack_mem_buf_t *buf) const;
00144 
00145     /**
00146      * Return payload size of the buffer
00147      *
00148      * @param buf      Memory buffer
00149      * @return         Size in bytes
00150      */
00151     virtual uint32_t get_len(const net_stack_mem_buf_t *buf) const;
00152 
00153     /**
00154      * Sets the payload size of the buffer
00155      *
00156      * The allocated payload size will not change. It is not permitted
00157      * to change the length of a buffer that is not the first (or only) in a chain.
00158      *
00159      * @param buf      Memory buffer
00160      * @param len      Payload size, must be less or equal allocated size
00161      */
00162     virtual void set_len(net_stack_mem_buf_t *buf, uint32_t len);
00163 
00164 private:
00165 
00166     /**
00167      * Returns a total memory alignment size
00168      *
00169      * Calculates the total memory alignment size for a memory buffer chain.
00170      * Used internally on pool allocation.
00171      *
00172      * @param  size    Size of the memory to allocate in bytes
00173      * @param  align   Memory alignment requirement for each buffer in bytes
00174      * @return         Total alignment needed in bytes
00175      */
00176     uint32_t count_total_align(uint32_t size, uint32_t align);
00177 
00178     /**
00179      * Aligns a memory buffer chain
00180      *
00181      * Aligns a memory buffer chain and updates lengths and total lengths
00182      * accordingly. There needs to be enough overhead to do the alignment
00183      * for all buffers.
00184      *
00185      * @param pbuf     Memory buffer
00186      * @param align    Memory alignment requirement for each buffer in bytes
00187      */
00188     void align_memory(struct pbuf *pbuf, uint32_t align);
00189 
00190     /**
00191      * Sets total lengths of a memory buffer chain
00192      *
00193      * Sets total length fields for a memory buffer chain based on buffer
00194      * length fields. All total lengths are calculated again.
00195      *
00196      * @param pbuf     Memory buffer
00197      */
00198     void set_total_len(struct pbuf *pbuf);
00199 };
00200 
00201 #endif /* LWIP_MEMORY_MANAGER_H */