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