EMACMemoryManager.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 EMAC_MEMORY_MANAGER_H
00017 #define EMAC_MEMORY_MANAGER_H
00018 
00019 /**
00020  * Emac interface memory manager
00021  *
00022  * This interface provides abstraction for memory modules used in different IP stacks (often to accommodate zero
00023  * copy). Emac interface is required to accept output packets and provide received data using this stack-
00024  * independent API. This header should be implemented for each IP stack, so that we keep emacs module independent.
00025  *
00026  * Emac memory interface uses memory buffer chains to store data. Data passed in either direction
00027  * may be either contiguous (a single-buffer chain), or may consist of multiple buffers.
00028  * Chaining of the buffers is made using singly-linked list. The Emac data-passing APIs do not specify
00029  * alignment or structure of the chain in either direction.
00030  *
00031  * Memory buffers can be allocated either from heap or from memory pools. Heap buffers are always contiguous.
00032  * Memory pool buffers may be either contiguous or chained depending on allocation size.
00033  *
00034  * On Emac interface buffer chain ownership is transferred. Emac must free buffer chain that it is given for
00035  * link output and the stack must free the buffer chain that it is given for link input.
00036  *
00037  */
00038 
00039 #include "nsapi.h"
00040 
00041 typedef void emac_mem_buf_t;          // Memory buffer
00042 
00043 class EMACMemoryManager {
00044 public:
00045 
00046     /**
00047      * Allocates memory buffer from the heap
00048      *
00049      * Memory buffer allocated from heap is always contiguous and can be arbitrary size.
00050      *
00051      * @param size     Size of the memory to allocate in bytes
00052      * @param align    Memory alignment requirement in bytes
00053      * @return         Allocated memory buffer, or NULL in case of error
00054      */
00055     virtual emac_mem_buf_t *alloc_heap(uint32_t size, uint32_t align) = 0;
00056 
00057     /**
00058      * Allocates memory buffer chain from a pool
00059      *
00060      * Memory allocated from pool is contiguous if size is equal or less than
00061      * (aligned) allocation unit, otherwise may be chained. Will typically come from
00062      * fixed-size packet pool memory.
00063      *
00064      * @param  size    Total size of the memory to allocate in bytes
00065      * @param  align   Memory alignment requirement for each buffer in bytes
00066      * @return         Allocated memory buffer chain, or NULL in case of error
00067      */
00068     virtual emac_mem_buf_t *alloc_pool(uint32_t size, uint32_t align) = 0;
00069 
00070     /**
00071      * Get memory buffer pool allocation unit
00072      *
00073      * Returns the maximum size of contiguous memory that can be allocated from a pool.
00074      *
00075      * @param align    Memory alignment requirement in bytes
00076      * @return         Contiguous memory size
00077      */
00078     virtual uint32_t get_pool_alloc_unit(uint32_t align) const = 0;
00079 
00080     /**
00081      * Free memory buffer chain
00082      *
00083      * If memory buffer is chained must point to the start of the chain. Frees all buffers
00084      * from the chained list.
00085      *
00086      * @param buf      Memory buffer chain to be freed.
00087      */
00088     virtual void free(emac_mem_buf_t *buf) = 0;
00089 
00090     /**
00091      * Return total length of a memory buffer chain
00092      *
00093      * Returns a total length of this buffer and any following buffers in the chain.
00094      *
00095      * @param buf      Memory buffer chain
00096      * @return         Total length in bytes
00097      */
00098     virtual uint32_t get_total_len(const emac_mem_buf_t *buf) const = 0;
00099 
00100     /**
00101      * Copy a memory buffer chain
00102      *
00103      * Copies data from one buffer chain to another. Copy operation does not adjust the lengths
00104      * of the copied-to memory buffer chain, so chain total lengths must be the same.
00105      *
00106      * @param to_buf    Memory buffer chain to copy to
00107      * @param from_buf  Memory buffer chain to copy from
00108      */
00109     virtual void copy(emac_mem_buf_t *to_buf, const emac_mem_buf_t *from_buf) = 0;
00110 
00111     /**
00112      * Copy to a memory buffer chain
00113      *
00114      * Copies data to a buffer chain. Copy operation does not adjust the lengths
00115      * of the copied-to memory buffer chain, so chain total length must match the
00116      * copied length.
00117      *
00118      * @param to_buf    Memory buffer chain to copy to
00119      * @param ptr       Pointer to data
00120      * @param len       Data length
00121      */
00122     virtual void copy_to_buf(emac_mem_buf_t *to_buf, const void *ptr, uint32_t len);
00123 
00124     /**
00125      * Copy from a memory buffer chain
00126      *
00127      * Copies data from a memory buffer chain.
00128      *
00129      * @param len       Data length
00130      * @param ptr       Pointer to data
00131      * @param from_buf  Memory buffer chain to copy from
00132      * @return          Length of the data that was copied
00133      */
00134     virtual uint32_t copy_from_buf(void *ptr, uint32_t len, const emac_mem_buf_t *from_buf) const;
00135 
00136     /**
00137      * Concatenate two memory buffer chains
00138      *
00139      * Concatenates buffer chain to end of the other buffer chain. Concatenated-to buffer total length
00140      * is adjusted accordingly. cat_buf must point to the start of a the chain. After concatenation
00141      * to_buf's chain now owns those buffers, and they will be freed when the to_buf chain is freed.
00142      *
00143      * @param to_buf   Memory buffer chain to concatenate to
00144      * @param cat_buf  Memory buffer chain to concatenate
00145      */
00146     virtual void cat(emac_mem_buf_t *to_buf, emac_mem_buf_t *cat_buf) = 0;
00147 
00148     /**
00149      * Returns the next buffer
00150      *
00151      * Returns the next buffer from the memory buffer chain.
00152      *
00153      * @param buf      Memory buffer
00154      * @return         The next memory buffer, or NULL if last
00155      */
00156     virtual emac_mem_buf_t *get_next(const emac_mem_buf_t *buf) const = 0;
00157 
00158     /**
00159      * Return pointer to the payload of the buffer
00160      *
00161      * @param buf      Memory buffer
00162      * @return         Pointer to the payload
00163      */
00164     virtual void *get_ptr(const emac_mem_buf_t *buf) const = 0;
00165 
00166     /**
00167      * Return payload size of the buffer
00168      *
00169      * @param buf      Memory buffer
00170      * @return         Size in bytes
00171      */
00172     virtual uint32_t get_len(const emac_mem_buf_t *buf) const = 0;
00173 
00174     /**
00175      * Sets the payload size of the buffer
00176      *
00177      * The allocated payload size will not change. It is not permitted
00178      * to change the length of a buffer that is not the first (or only) in a chain.
00179      *
00180      * @param buf      Memory buffer
00181      * @param len      Payload size, must be less or equal allocated size
00182      */
00183     virtual void set_len(emac_mem_buf_t *buf, uint32_t len) = 0;
00184 };
00185 
00186 #endif /* EMAC_MEMORY_MANAGER_H */