Kev Mann / mbed-dev-OS5_10_4

RTC auf true

features/netsocket/EMACMemoryManager.h@2:7aab896b1a3b, 2019-03-13 (annotated)

Committer:
kevman
Date:
Wed Mar 13 11:03:24 2019 +0000
Revision:
2:7aab896b1a3b
Parent:
0:38ceb79fef03 
2019-03-13

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kevman 0:38ceb79fef03 1 /* Copyright (c) 2017 ARM Limited
kevman 0:38ceb79fef03 2 *
kevman 0:38ceb79fef03 3 * Licensed under the Apache License, Version 2.0 (the "License");
kevman 0:38ceb79fef03 4 * you may not use this file except in compliance with the License.
kevman 0:38ceb79fef03 5 * You may obtain a copy of the License at
kevman 0:38ceb79fef03 6 *
kevman 0:38ceb79fef03 7 * http://www.apache.org/licenses/LICENSE-2.0
kevman 0:38ceb79fef03 8 *
kevman 0:38ceb79fef03 9 * Unless required by applicable law or agreed to in writing, software
kevman 0:38ceb79fef03 10 * distributed under the License is distributed on an "AS IS" BASIS,
kevman 0:38ceb79fef03 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
kevman 0:38ceb79fef03 12 * See the License for the specific language governing permissions and
kevman 0:38ceb79fef03 13 * limitations under the License.
kevman 0:38ceb79fef03 14 */
kevman 0:38ceb79fef03 15
kevman 0:38ceb79fef03 16 #ifndef EMAC_MEMORY_MANAGER_H
kevman 0:38ceb79fef03 17 #define EMAC_MEMORY_MANAGER_H
kevman 0:38ceb79fef03 18
kevman 0:38ceb79fef03 19 /**
kevman 0:38ceb79fef03 20 * Emac interface memory manager
kevman 0:38ceb79fef03 21 *
kevman 0:38ceb79fef03 22 * This interface provides abstraction for memory modules used in different IP stacks (often to accommodate zero
kevman 0:38ceb79fef03 23 * copy). Emac interface is required to accept output packets and provide received data using this stack-
kevman 0:38ceb79fef03 24 * independent API. This header should be implemented for each IP stack, so that we keep emacs module independent.
kevman 0:38ceb79fef03 25 *
kevman 0:38ceb79fef03 26 * Emac memory interface uses memory buffer chains to store data. Data passed in either direction
kevman 0:38ceb79fef03 27 * may be either contiguous (a single-buffer chain), or may consist of multiple buffers.
kevman 0:38ceb79fef03 28 * Chaining of the buffers is made using singly-linked list. The Emac data-passing APIs do not specify
kevman 0:38ceb79fef03 29 * alignment or structure of the chain in either direction.
kevman 0:38ceb79fef03 30 *
kevman 0:38ceb79fef03 31 * Memory buffers can be allocated either from heap or from memory pools. Heap buffers are always contiguous.
kevman 0:38ceb79fef03 32 * Memory pool buffers may be either contiguous or chained depending on allocation size.
kevman 0:38ceb79fef03 33 *
kevman 0:38ceb79fef03 34 * On Emac interface buffer chain ownership is transferred. Emac must free buffer chain that it is given for
kevman 0:38ceb79fef03 35 * link output and the stack must free the buffer chain that it is given for link input.
kevman 0:38ceb79fef03 36 *
kevman 0:38ceb79fef03 37 */
kevman 0:38ceb79fef03 38
kevman 0:38ceb79fef03 39 #include "nsapi.h"
kevman 0:38ceb79fef03 40
kevman 0:38ceb79fef03 41 typedef void emac_mem_buf_t; // Memory buffer
kevman 0:38ceb79fef03 42
kevman 0:38ceb79fef03 43 class EMACMemoryManager {
kevman 0:38ceb79fef03 44 public:
kevman 0:38ceb79fef03 45
kevman 0:38ceb79fef03 46 /**
kevman 0:38ceb79fef03 47 * Allocates memory buffer from the heap
kevman 0:38ceb79fef03 48 *
kevman 0:38ceb79fef03 49 * Memory buffer allocated from heap is always contiguous and can be arbitrary size.
kevman 0:38ceb79fef03 50 *
kevman 0:38ceb79fef03 51 * @param size Size of the memory to allocate in bytes
kevman 0:38ceb79fef03 52 * @param align Memory alignment requirement in bytes
kevman 0:38ceb79fef03 53 * @return Allocated memory buffer, or NULL in case of error
kevman 0:38ceb79fef03 54 */
kevman 0:38ceb79fef03 55 virtual emac_mem_buf_t *alloc_heap(uint32_t size, uint32_t align) = 0;
kevman 0:38ceb79fef03 56
kevman 0:38ceb79fef03 57 /**
kevman 0:38ceb79fef03 58 * Allocates memory buffer chain from a pool
kevman 0:38ceb79fef03 59 *
kevman 0:38ceb79fef03 60 * Memory allocated from pool is contiguous if size is equal or less than
kevman 0:38ceb79fef03 61 * (aligned) allocation unit, otherwise may be chained. Will typically come from
kevman 0:38ceb79fef03 62 * fixed-size packet pool memory.
kevman 0:38ceb79fef03 63 *
kevman 0:38ceb79fef03 64 * @param size Total size of the memory to allocate in bytes
kevman 0:38ceb79fef03 65 * @param align Memory alignment requirement for each buffer in bytes
kevman 0:38ceb79fef03 66 * @return Allocated memory buffer chain, or NULL in case of error
kevman 0:38ceb79fef03 67 */
kevman 0:38ceb79fef03 68 virtual emac_mem_buf_t *alloc_pool(uint32_t size, uint32_t align) = 0;
kevman 0:38ceb79fef03 69
kevman 0:38ceb79fef03 70 /**
kevman 0:38ceb79fef03 71 * Get memory buffer pool allocation unit
kevman 0:38ceb79fef03 72 *
kevman 0:38ceb79fef03 73 * Returns the maximum size of contiguous memory that can be allocated from a pool.
kevman 0:38ceb79fef03 74 *
kevman 0:38ceb79fef03 75 * @param align Memory alignment requirement in bytes
kevman 0:38ceb79fef03 76 * @return Contiguous memory size
kevman 0:38ceb79fef03 77 */
kevman 0:38ceb79fef03 78 virtual uint32_t get_pool_alloc_unit(uint32_t align) const = 0;
kevman 0:38ceb79fef03 79
kevman 0:38ceb79fef03 80 /**
kevman 0:38ceb79fef03 81 * Free memory buffer chain
kevman 0:38ceb79fef03 82 *
kevman 0:38ceb79fef03 83 * If memory buffer is chained must point to the start of the chain. Frees all buffers
kevman 0:38ceb79fef03 84 * from the chained list.
kevman 0:38ceb79fef03 85 *
kevman 0:38ceb79fef03 86 * @param buf Memory buffer chain to be freed.
kevman 0:38ceb79fef03 87 */
kevman 0:38ceb79fef03 88 virtual void free(emac_mem_buf_t *buf) = 0;
kevman 0:38ceb79fef03 89
kevman 0:38ceb79fef03 90 /**
kevman 0:38ceb79fef03 91 * Return total length of a memory buffer chain
kevman 0:38ceb79fef03 92 *
kevman 0:38ceb79fef03 93 * Returns a total length of this buffer and any following buffers in the chain.
kevman 0:38ceb79fef03 94 *
kevman 0:38ceb79fef03 95 * @param buf Memory buffer chain
kevman 0:38ceb79fef03 96 * @return Total length in bytes
kevman 0:38ceb79fef03 97 */
kevman 0:38ceb79fef03 98 virtual uint32_t get_total_len(const emac_mem_buf_t *buf) const = 0;
kevman 0:38ceb79fef03 99
kevman 0:38ceb79fef03 100 /**
kevman 0:38ceb79fef03 101 * Copy a memory buffer chain
kevman 0:38ceb79fef03 102 *
kevman 0:38ceb79fef03 103 * Copies data from one buffer chain to another. Copy operation does not adjust the lengths
kevman 0:38ceb79fef03 104 * of the copied-to memory buffer chain, so chain total lengths must be the same.
kevman 0:38ceb79fef03 105 *
kevman 0:38ceb79fef03 106 * @param to_buf Memory buffer chain to copy to
kevman 0:38ceb79fef03 107 * @param from_buf Memory buffer chain to copy from
kevman 0:38ceb79fef03 108 */
kevman 0:38ceb79fef03 109 virtual void copy(emac_mem_buf_t *to_buf, const emac_mem_buf_t *from_buf) = 0;
kevman 0:38ceb79fef03 110
kevman 0:38ceb79fef03 111 /**
kevman 0:38ceb79fef03 112 * Copy to a memory buffer chain
kevman 0:38ceb79fef03 113 *
kevman 0:38ceb79fef03 114 * Copies data to a buffer chain. Copy operation does not adjust the lengths
kevman 0:38ceb79fef03 115 * of the copied-to memory buffer chain, so chain total length must match the
kevman 0:38ceb79fef03 116 * copied length.
kevman 0:38ceb79fef03 117 *
kevman 0:38ceb79fef03 118 * @param to_buf Memory buffer chain to copy to
kevman 0:38ceb79fef03 119 * @param ptr Pointer to data
kevman 0:38ceb79fef03 120 * @param len Data length
kevman 0:38ceb79fef03 121 */
kevman 0:38ceb79fef03 122 virtual void copy_to_buf(emac_mem_buf_t *to_buf, const void *ptr, uint32_t len);
kevman 0:38ceb79fef03 123
kevman 0:38ceb79fef03 124 /**
kevman 0:38ceb79fef03 125 * Copy from a memory buffer chain
kevman 0:38ceb79fef03 126 *
kevman 0:38ceb79fef03 127 * Copies data from a memory buffer chain.
kevman 0:38ceb79fef03 128 *
kevman 0:38ceb79fef03 129 * @param len Data length
kevman 0:38ceb79fef03 130 * @param ptr Pointer to data
kevman 0:38ceb79fef03 131 * @param from_buf Memory buffer chain to copy from
kevman 0:38ceb79fef03 132 * @return Length of the data that was copied
kevman 0:38ceb79fef03 133 */
kevman 0:38ceb79fef03 134 virtual uint32_t copy_from_buf(void *ptr, uint32_t len, const emac_mem_buf_t *from_buf) const;
kevman 0:38ceb79fef03 135
kevman 0:38ceb79fef03 136 /**
kevman 0:38ceb79fef03 137 * Concatenate two memory buffer chains
kevman 0:38ceb79fef03 138 *
kevman 0:38ceb79fef03 139 * Concatenates buffer chain to end of the other buffer chain. Concatenated-to buffer total length
kevman 0:38ceb79fef03 140 * is adjusted accordingly. cat_buf must point to the start of a the chain. After concatenation
kevman 0:38ceb79fef03 141 * to_buf's chain now owns those buffers, and they will be freed when the to_buf chain is freed.
kevman 0:38ceb79fef03 142 *
kevman 0:38ceb79fef03 143 * @param to_buf Memory buffer chain to concatenate to
kevman 0:38ceb79fef03 144 * @param cat_buf Memory buffer chain to concatenate
kevman 0:38ceb79fef03 145 */
kevman 0:38ceb79fef03 146 virtual void cat(emac_mem_buf_t *to_buf, emac_mem_buf_t *cat_buf) = 0;
kevman 0:38ceb79fef03 147
kevman 0:38ceb79fef03 148 /**
kevman 0:38ceb79fef03 149 * Returns the next buffer
kevman 0:38ceb79fef03 150 *
kevman 0:38ceb79fef03 151 * Returns the next buffer from the memory buffer chain.
kevman 0:38ceb79fef03 152 *
kevman 0:38ceb79fef03 153 * @param buf Memory buffer
kevman 0:38ceb79fef03 154 * @return The next memory buffer, or NULL if last
kevman 0:38ceb79fef03 155 */
kevman 0:38ceb79fef03 156 virtual emac_mem_buf_t *get_next(const emac_mem_buf_t *buf) const = 0;
kevman 0:38ceb79fef03 157
kevman 0:38ceb79fef03 158 /**
kevman 0:38ceb79fef03 159 * Return pointer to the payload of the buffer
kevman 0:38ceb79fef03 160 *
kevman 0:38ceb79fef03 161 * @param buf Memory buffer
kevman 0:38ceb79fef03 162 * @return Pointer to the payload
kevman 0:38ceb79fef03 163 */
kevman 0:38ceb79fef03 164 virtual void *get_ptr(const emac_mem_buf_t *buf) const = 0;
kevman 0:38ceb79fef03 165
kevman 0:38ceb79fef03 166 /**
kevman 0:38ceb79fef03 167 * Return payload size of the buffer
kevman 0:38ceb79fef03 168 *
kevman 0:38ceb79fef03 169 * @param buf Memory buffer
kevman 0:38ceb79fef03 170 * @return Size in bytes
kevman 0:38ceb79fef03 171 */
kevman 0:38ceb79fef03 172 virtual uint32_t get_len(const emac_mem_buf_t *buf) const = 0;
kevman 0:38ceb79fef03 173
kevman 0:38ceb79fef03 174 /**
kevman 0:38ceb79fef03 175 * Sets the payload size of the buffer
kevman 0:38ceb79fef03 176 *
kevman 0:38ceb79fef03 177 * The allocated payload size will not change. It is not permitted
kevman 0:38ceb79fef03 178 * to change the length of a buffer that is not the first (or only) in a chain.
kevman 0:38ceb79fef03 179 *
kevman 0:38ceb79fef03 180 * @param buf Memory buffer
kevman 0:38ceb79fef03 181 * @param len Payload size, must be less or equal allocated size
kevman 0:38ceb79fef03 182 */
kevman 0:38ceb79fef03 183 virtual void set_len(emac_mem_buf_t *buf, uint32_t len) = 0;
kevman 0:38ceb79fef03 184 };
kevman 0:38ceb79fef03 185
kevman 0:38ceb79fef03 186 #endif /* EMAC_MEMORY_MANAGER_H */