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

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.