Kenji Arai / mbed-os_TYBLE16

mbed-os5 only for TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

features/netsocket/NetStackMemoryManager.h@1:9db0e321a9f4, 2019-12-31 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 31 06:02:27 2019 +0000
Revision:
1:9db0e321a9f4
Parent:
0:5b88d5760320 
updated based on mbed-os5.15.0

Who changed what in which revision?

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