emac_TestMemoryManager.h

00001 /*
00002  * Copyright (c) 2018, ARM Limited, All Rights Reserved
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License"); you may
00006  * 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, WITHOUT
00013  * 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 EMAC_TEST_MEMORY_MANAGER_H
00019 #define EMAC_TEST_MEMORY_MANAGER_H
00020 
00021 #include <list>
00022 
00023 #include "EMACMemoryManager.h"
00024 
00025 #define MEM_CHECK       0x01
00026 #define MEM_NO_ALIGN    0x02
00027 
00028 typedef struct emac_memory {
00029     struct emac_memory *next;
00030     void *buffer;              /**< Pointer to allocated buffer */
00031     unsigned int orig_len;     /**< Original buffer length (set_len() does not change) */
00032     unsigned int len;          /**< Buffer length */
00033     void *ptr;                 /**< Aligned pointer */
00034     bool first;
00035 } emac_memory_t;
00036 
00037 class EmacTestMemoryManager : public EMACMemoryManager {
00038 public:
00039 
00040     /**
00041      * Creates emac test memory manager
00042      */
00043     EmacTestMemoryManager();
00044 
00045     /*
00046      * Gets static instance
00047      */
00048     static EmacTestMemoryManager &get_instance();
00049 
00050     /**
00051      * Allocates memory buffer from the heap
00052      *
00053      * Memory buffer allocated from heap is always contiguous and can be arbitrary size.
00054      *
00055      * @param size     Size of the memory to allocate in bytes
00056      * @param align    Memory alignment requirement in bytes
00057      * @return         Allocated memory buffer, or NULL in case of error
00058      */
00059     virtual emac_mem_buf_t *alloc_heap(uint32_t size, uint32_t align);
00060 
00061     /**
00062      * Allocates memory buffer from the heap
00063      *
00064      * Memory buffer allocated from heap is always contiguous and can be arbitrary size.
00065      *
00066      * @param size        Size of the memory to allocate in bytes
00067      * @param align       Memory alignment requirement in bytes
00068      * @param opt         Options
00069      * @return            Allocated memory buffer, or NULL in case of error
00070      */
00071     emac_mem_buf_t *alloc_heap(uint32_t size, uint32_t align, uint8_t opt);
00072 
00073     /**
00074      * Allocates memory buffer chain from a pool
00075      *
00076      * Memory allocated from pool is contiguous if size is equal or less than
00077      * (aligned) allocation unit, otherwise may be chained. Will typically come from
00078      * fixed-size packet pool memory.
00079      *
00080      * @param  size    Total size of the memory to allocate in bytes
00081      * @param  align   Memory alignment requirement for each buffer in bytes
00082      * @return         Allocated memory buffer chain, or NULL in case of error
00083      */
00084     virtual emac_mem_buf_t *alloc_pool(uint32_t size, uint32_t align);
00085 
00086     /**
00087      * Allocates memory buffer chain from a pool
00088      *
00089      * Memory allocated from pool is contiguous if size is equal or less than
00090      * (aligned) allocation unit, otherwise may be chained. Will typically come from
00091      * fixed-size packet pool memory.
00092      *
00093      * @param size        Total size of the memory to allocate in bytes
00094      * @param align       Memory alignment requirement for each buffer in bytes
00095      * @param opt         Options
00096      * @return            Allocated memory buffer chain, or NULL in case of error
00097      */
00098     emac_mem_buf_t *alloc_pool(uint32_t size, uint32_t align, uint8_t opt);
00099 
00100     /**
00101      * Get memory buffer pool allocation unit
00102      *
00103      * Returns the maximum size of contiguous memory that can be allocated from a pool.
00104      *
00105      * @param align    Memory alignment requirement in bytes
00106      * @return         Contiguous memory size
00107      */
00108     virtual uint32_t get_pool_alloc_unit(uint32_t align) const;
00109 
00110     /**
00111      * Free memory buffer chain
00112      *
00113      * If memory buffer is chained must point to the start of the chain. Frees all buffers
00114      * from the chained list.
00115      *
00116      * @param buf      Memory buffer chain to be freed.
00117      */
00118     virtual void free(emac_mem_buf_t *buf);
00119 
00120     /**
00121      * Return total length of a memory buffer chain
00122      *
00123      * Returns a total length of this buffer and any following buffers in the chain.
00124      *
00125      * @param buf      Memory buffer chain
00126      * @return         Total length in bytes
00127      */
00128     virtual uint32_t get_total_len(const emac_mem_buf_t *buf) const;
00129 
00130     /**
00131      * Copy a memory buffer chain
00132      *
00133      * Copies data from one buffer chain to another. Copy operation does not adjust the lengths
00134      * of the copied-to memory buffer chain, so chain total lengths must be the same.
00135      *
00136      * @param to_buf    Memory buffer chain to copy to
00137      * @param from_buf  Memory buffer chain to copy from
00138      */
00139     virtual void copy(emac_mem_buf_t *to_buf, const emac_mem_buf_t *from_buf);
00140 
00141     /**
00142      * Concatenate two memory buffer chains
00143      *
00144      * Concatenates buffer chain to end of the other buffer chain. Concatenated-to buffer total length
00145      * is adjusted accordingly. cat_buf must point to the start of a the chain. After concatenation
00146      * to_buf's chain now owns those buffers, and they will be freed when the to_buf chain is freed.
00147      *
00148      * @param to_buf   Memory buffer chain to concatenate to
00149      * @param cat_buf  Memory buffer chain to concatenate
00150      */
00151     virtual void cat(emac_mem_buf_t *to_buf, emac_mem_buf_t *cat_buf);
00152 
00153     /**
00154      * Returns the next buffer
00155      *
00156      * Returns the next buffer from the memory buffer chain.
00157      *
00158      * @param buf      Memory buffer
00159      * @return         The next memory buffer, or NULL if last
00160      */
00161     virtual emac_mem_buf_t *get_next(const emac_mem_buf_t *buf) const;
00162 
00163     /**
00164      * Return pointer to the payload of the buffer
00165      *
00166      * @param buf      Memory buffer
00167      * @return         Pointer to the payload
00168      */
00169     virtual void *get_ptr(const emac_mem_buf_t *buf) const;
00170 
00171     /**
00172      * Return payload size of the buffer
00173      *
00174      * @param buf      Memory buffer
00175      * @return         Size in bytes
00176      */
00177     virtual uint32_t get_len(const emac_mem_buf_t *buf) const;
00178 
00179     /**
00180      * Sets the payload size of the buffer
00181      *
00182      * The allocated payload size will not change. It is not permitted
00183      * to change the length of a buffer that is not the first (or only) in a chain.
00184      *
00185      * @param buf      Memory buffer
00186      * @param len      Payload size, must be less or equal allocated size
00187      */
00188     virtual void set_len(emac_mem_buf_t *buf, uint32_t len);
00189 
00190     /**
00191      * Sets memory buffer pool allocation unit
00192      *
00193      * Sets the maximum size of contiguous memory that can be allocated from a pool.
00194      *
00195      * @param alloc_unit   Contiguous memory size
00196      */
00197     virtual void set_alloc_unit(uint32_t alloc_unit);
00198 
00199     /**
00200      * Sets whether memory is available
00201      *
00202      * Can be used to disable memory allocation request from emac.
00203      *
00204      * @param memory    True if memory is available
00205      */
00206     void set_memory_available(bool memory);
00207 
00208     /**
00209      * Gets memory statistics
00210      *
00211      * Gets memory usage statistics
00212      *
00213      * @param buffers   Number of buffers that are reserved
00214      * @param memory    Reserved memory in bytes
00215      */
00216     void get_memory_statistics(int *buffers, int *memory);
00217 
00218 private:
00219     void validate_list() const;
00220     template <typename TYPE> void check_value(TYPE value, const char *fmt, ...) const;
00221     bool validate_ptr(const emac_mem_buf_t *buf) const;
00222     void check_align(uint32_t align) const;
00223     mutable rtos::Mutex m_mem_mutex;
00224     std::list<emac_memory_t *> m_mem_buffers;
00225     unsigned int m_alloc_unit;
00226     bool m_memory_available;
00227 };
00228 
00229 #endif /* EMAC_TEST_MEMORY_MANAGER_H */