NetStackMemoryManager.h

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