1 /***********************license start***************
2 * Copyright (c) 2003-2008 Cavium Networks (support@cavium.com). All rights
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are
10 * * Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above
14 * copyright notice, this list of conditions and the following
15 * disclaimer in the documentation and/or other materials provided
16 * with the distribution.
18 * * Neither the name of Cavium Networks nor the names of
19 * its contributors may be used to endorse or promote products
20 * derived from this software without specific prior written
23 * TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS"
24 * AND WITH ALL FAULTS AND CAVIUM NETWORKS MAKES NO PROMISES, REPRESENTATIONS
25 * OR WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH
26 * RESPECT TO THE SOFTWARE, INCLUDING ITS CONDITION, ITS CONFORMITY TO ANY
27 * REPRESENTATION OR DESCRIPTION, OR THE EXISTENCE OF ANY LATENT OR PATENT
28 * DEFECTS, AND CAVIUM SPECIFICALLY DISCLAIMS ALL IMPLIED (IF ANY) WARRANTIES
29 * OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR A PARTICULAR
30 * PURPOSE, LACK OF VIRUSES, ACCURACY OR COMPLETENESS, QUIET ENJOYMENT, QUIET
31 * POSSESSION OR CORRESPONDENCE TO DESCRIPTION. THE ENTIRE RISK ARISING OUT
32 * OF USE OR PERFORMANCE OF THE SOFTWARE LIES WITH YOU.
35 * For any questions regarding licensing please contact marketing@caviumnetworks.com
37 ***********************license end**************************************/
45 * Simple allocate only memory allocator. Used to allocate memory at application
48 * <hr>$Revision: 41586 $<hr>
52 #ifndef __CVMX_BOOTMEM_H__
53 #define __CVMX_BOOTMEM_H__
59 #define CVMX_BOOTMEM_NAME_LEN 128 /* Must be multiple of 8, changing breaks ABI */
60 #define CVMX_BOOTMEM_NUM_NAMED_BLOCKS 64 /* Can change without breaking ABI */
61 #define CVMX_BOOTMEM_ALIGNMENT_SIZE (16ull) /* minimum alignment of bootmem alloced blocks */
63 /* Flags for cvmx_bootmem_phy_mem* functions */
64 #define CVMX_BOOTMEM_FLAG_END_ALLOC (1 << 0) /* Allocate from end of block instead of beginning */
65 #define CVMX_BOOTMEM_FLAG_NO_LOCKING (1 << 1) /* Don't do any locking. */
68 /* First bytes of each free physical block of memory contain this structure,
69 * which is used to maintain the free memory list. Since the bootloader is
70 * only 32 bits, there is a union providing 64 and 32 bit versions. The
71 * application init code converts addresses to 64 bit addresses before the
76 /* Note: these are referenced from assembly routines in the bootloader, so this structure
77 ** should not be changed without changing those routines as well. */
78 uint64_t next_block_addr;
81 } cvmx_bootmem_block_header_t;
84 /* Structure for named memory blocks
85 ** Number of descriptors
86 ** available can be changed without affecting compatiblity,
87 ** but name length changes require a bump in the bootmem
89 ** Note: This structure must be naturally 64 bit aligned, as a single
90 ** memory image will be used by both 32 and 64 bit programs.
94 uint64_t base_addr; /**< Base address of named block */
95 uint64_t size; /**< Size actually allocated for named block (may differ from requested) */
96 char name[CVMX_BOOTMEM_NAME_LEN]; /**< name of named block */
97 } cvmx_bootmem_named_block_desc_t;
101 /* Current descriptor versions */
102 #define CVMX_BOOTMEM_DESC_MAJ_VER 3 /* CVMX bootmem descriptor major version */
103 #define CVMX_BOOTMEM_DESC_MIN_VER 0 /* CVMX bootmem descriptor minor version */
105 /* First three members of cvmx_bootmem_desc_t are left in original
106 ** positions for backwards compatibility.
110 uint32_t lock; /**< spinlock to control access to list */
111 uint32_t flags; /**< flags for indicating various conditions */
114 uint32_t major_version; /**< incremented changed when incompatible changes made */
115 uint32_t minor_version; /**< incremented changed when compatible changes made, reset to zero when major incremented */
116 uint64_t app_data_addr;
117 uint64_t app_data_size;
119 uint32_t named_block_num_blocks; /**< number of elements in named blocks array */
120 uint32_t named_block_name_len; /**< length of name array in bootmem blocks */
121 uint64_t named_block_array_addr; /**< address of named memory block descriptors */
123 } cvmx_bootmem_desc_t;
127 * Initialize the boot alloc memory structures. This is
128 * normally called inside of cvmx_user_app_init()
130 * @param mem_desc_ptr Address of the free memory list
133 extern int cvmx_bootmem_init(void *mem_desc_ptr);
137 * Allocate a block of memory from the free list that was passed
138 * to the application by the bootloader.
139 * This is an allocate-only algorithm, so freeing memory is not possible.
141 * @param size Size in bytes of block to allocate
142 * @param alignment Alignment required - must be power of 2
144 * @return pointer to block of memory, NULL on error
146 extern void *cvmx_bootmem_alloc(uint64_t size, uint64_t alignment);
149 * Allocate a block of memory from the free list that was
150 * passed to the application by the bootloader at a specific
151 * address. This is an allocate-only algorithm, so
152 * freeing memory is not possible. Allocation will fail if
153 * memory cannot be allocated at the specified address.
155 * @param size Size in bytes of block to allocate
156 * @param address Physical address to allocate memory at. If this memory is not
157 * available, the allocation fails.
158 * @param alignment Alignment required - must be power of 2
159 * @return pointer to block of memory, NULL on error
161 extern void *cvmx_bootmem_alloc_address(uint64_t size, uint64_t address, uint64_t alignment);
166 * Allocate a block of memory from the free list that was
167 * passed to the application by the bootloader within a specified
168 * address range. This is an allocate-only algorithm, so
169 * freeing memory is not possible. Allocation will fail if
170 * memory cannot be allocated in the requested range.
172 * @param size Size in bytes of block to allocate
173 * @param min_addr defines the minimum address of the range
174 * @param max_addr defines the maximum address of the range
175 * @param alignment Alignment required - must be power of 2
176 * @return pointer to block of memory, NULL on error
178 extern void *cvmx_bootmem_alloc_range(uint64_t size, uint64_t alignment, uint64_t min_addr, uint64_t max_addr);
182 * Allocate a block of memory from the free list that was passed
183 * to the application by the bootloader, and assign it a name in the
184 * global named block table. (part of the cvmx_bootmem_descriptor_t structure)
185 * Named blocks can later be freed.
187 * @param size Size in bytes of block to allocate
188 * @param alignment Alignment required - must be power of 2
189 * @param name name of block - must be less than CVMX_BOOTMEM_NAME_LEN bytes
191 * @return pointer to block of memory, NULL on error
193 extern void *cvmx_bootmem_alloc_named(uint64_t size, uint64_t alignment, char *name);
198 * Allocate a block of memory from the free list that was passed
199 * to the application by the bootloader, and assign it a name in the
200 * global named block table. (part of the cvmx_bootmem_descriptor_t structure)
201 * Named blocks can later be freed.
203 * @param size Size in bytes of block to allocate
204 * @param address Physical address to allocate memory at. If this memory is not
205 * available, the allocation fails.
206 * @param name name of block - must be less than CVMX_BOOTMEM_NAME_LEN bytes
208 * @return pointer to block of memory, NULL on error
210 extern void *cvmx_bootmem_alloc_named_address(uint64_t size, uint64_t address, char *name);
215 * Allocate a block of memory from a specific range of the free list that was passed
216 * to the application by the bootloader, and assign it a name in the
217 * global named block table. (part of the cvmx_bootmem_descriptor_t structure)
218 * Named blocks can later be freed.
219 * If request cannot be satisfied within the address range specified, NULL is returned
221 * @param size Size in bytes of block to allocate
222 * @param min_addr minimum address of range
223 * @param max_addr maximum address of range
224 * @param align Alignment of memory to be allocated. (must be a power of 2)
225 * @param name name of block - must be less than CVMX_BOOTMEM_NAME_LEN bytes
227 * @return pointer to block of memory, NULL on error
229 extern void *cvmx_bootmem_alloc_named_range(uint64_t size, uint64_t min_addr, uint64_t max_addr, uint64_t align, char *name);
232 * Frees a previously allocated named bootmem block.
234 * @param name name of block to free
236 * @return 0 on failure,
239 extern int cvmx_bootmem_free_named(char *name);
243 * Finds a named bootmem block by name.
245 * @param name name of block to free
247 * @return pointer to named block descriptor on success
250 cvmx_bootmem_named_block_desc_t * cvmx_bootmem_find_named_block(char *name);
255 * Returns the size of available memory in bytes, only
256 * counting blocks that are at least as big as the minimum block
259 * @param min_block_size
260 * Minimum block size to count in total.
262 * @return Number of bytes available for allocation that meet the block size requirement
264 uint64_t cvmx_bootmem_available_mem(uint64_t min_block_size);
269 * Prints out the list of named blocks that have been allocated
270 * along with their addresses and sizes.
271 * This is primarily used for debugging purposes
273 void cvmx_bootmem_print_named(void);
277 * Allocates a block of physical memory from the free list, at (optional) requested address and alignment.
279 * @param req_size size of region to allocate. All requests are rounded up to be a multiple CVMX_BOOTMEM_ALIGNMENT_SIZE bytes size
281 * Minimum address that block can occupy.
283 * Specifies the maximum address_min (inclusive) that the allocation can use.
284 * @param alignment Requested alignment of the block. If this alignment cannot be met, the allocation fails.
285 * This must be a power of 2.
286 * (Note: Alignment of CVMX_BOOTMEM_ALIGNMENT_SIZE bytes is required, and internally enforced. Requested alignments of
287 * less than CVMX_BOOTMEM_ALIGNMENT_SIZE are set to CVMX_BOOTMEM_ALIGNMENT_SIZE.)
288 * @param flags Flags to control options for the allocation.
290 * @return physical address of block allocated, or -1 on failure
292 int64_t cvmx_bootmem_phy_alloc(uint64_t req_size, uint64_t address_min, uint64_t address_max, uint64_t alignment, uint32_t flags);
297 * Allocates a named block of physical memory from the free list, at (optional) requested address and alignment.
299 * @param size size of region to allocate. All requests are rounded up to be a multiple CVMX_BOOTMEM_ALIGNMENT_SIZE bytes size
301 * Minimum address that block can occupy.
303 * Specifies the maximum address_min (inclusive) that the allocation can use.
304 * @param alignment Requested alignment of the block. If this alignment cannot be met, the allocation fails.
305 * This must be a power of 2.
306 * (Note: Alignment of CVMX_BOOTMEM_ALIGNMENT_SIZE bytes is required, and internally enforced. Requested alignments of
307 * less than CVMX_BOOTMEM_ALIGNMENT_SIZE are set to CVMX_BOOTMEM_ALIGNMENT_SIZE.)
308 * @param name name to assign to named block
309 * @param flags Flags to control options for the allocation.
311 * @return physical address of block allocated, or -1 on failure
313 int64_t cvmx_bootmem_phy_named_block_alloc(uint64_t size, uint64_t min_addr, uint64_t max_addr, uint64_t alignment, char *name, uint32_t flags);
317 * Finds a named memory block by name.
318 * Also used for finding an unused entry in the named block table.
320 * @param name Name of memory block to find.
321 * If NULL pointer given, then finds unused descriptor, if available.
322 * @param flags Flags to control options for the allocation.
324 * @return Pointer to memory block descriptor, NULL if not found.
325 * If NULL returned when name parameter is NULL, then no memory
326 * block descriptors are available.
328 cvmx_bootmem_named_block_desc_t * cvmx_bootmem_phy_named_block_find(char *name, uint32_t flags);
332 * Returns the size of available memory in bytes, only
333 * counting blocks that are at least as big as the minimum block
336 * @param min_block_size
337 * Minimum block size to count in total.
339 * @return Number of bytes available for allocation that meet the block size requirement
341 uint64_t cvmx_bootmem_phy_available_mem(uint64_t min_block_size);
344 * Frees a named block.
346 * @param name name of block to free
347 * @param flags flags for passing options
349 * @return 0 on failure
352 int cvmx_bootmem_phy_named_block_free(char *name, uint32_t flags);
355 * Frees a block to the bootmem allocator list. This must
356 * be used with care, as the size provided must match the size
357 * of the block that was allocated, or the list will become
360 * IMPORTANT: This is only intended to be used as part of named block
361 * frees and initial population of the free memory list.
364 * @param phy_addr physical address of block
365 * @param size size of block in bytes.
366 * @param flags flags for passing options
368 * @return 1 on success,
371 int __cvmx_bootmem_phy_free(uint64_t phy_addr, uint64_t size, uint32_t flags);
375 * Prints the list of currently allocated named blocks
378 void cvmx_bootmem_phy_named_block_print(void);
382 * Prints the list of available memory.
385 void cvmx_bootmem_phy_list_print(void);
390 * This function initializes the free memory list used by cvmx_bootmem.
391 * This must be called before any allocations can be done.
393 * @param mem_size Total memory available, in bytes
394 * @param low_reserved_bytes
395 * Number of bytes to reserve (leave out of free list) at address 0x0.
397 * Buffer for the bootmem descriptor. This must be a 32 bit addressable
400 * @return 1 on success
403 int64_t cvmx_bootmem_phy_mem_list_init(uint64_t mem_size, uint32_t low_reserved_bytes, cvmx_bootmem_desc_t *desc_buffer);
406 * Locks the bootmem allocator. This is useful in certain situations
407 * where multiple allocations must be made without being interrupted.
408 * This should be used with the CVMX_BOOTMEM_FLAG_NO_LOCKING flag.
411 void cvmx_bootmem_lock(void);
414 * Unlocks the bootmem allocator. This is useful in certain situations
415 * where multiple allocations must be made without being interrupted.
416 * This should be used with the CVMX_BOOTMEM_FLAG_NO_LOCKING flag.
419 void cvmx_bootmem_unlock(void);
422 * Internal use function to get the current descriptor pointer */
423 void *__cvmx_bootmem_internal_get_desc_ptr(void);
429 #endif /* __CVMX_BOOTMEM_H__ */