RTEMS: Protected Heap Handler

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Files | Functions
Protected Heap Handler
Internal » SuperCore » Heap Handler

Provides protected heap services. More...

## Files
file | protectedheap.h
| Protected Heap Handler API.
file | pheapallocate.c
| Protected Heap Handler implementation.
file | pheapextend.c
| Protected Heap Handler implementation.
file | pheapfree.c
| Protected Heap Handler implementation.
file | pheapgetblocksize.c
| Protected Heap Handler implementation.
file | pheapgetfreeinfo.c
| Protected Heap Handler implementation.
file | pheapgetinfo.c
| Protected Heap Handler implementation.
file | pheapgetsize.c
| Protected Heap Handler implementation.
file | pheapinit.c
| Protected Heap Handler implementation.
file | pheapiterate.c
| _Heap_Iterate() implementation.
file | pheapresizeblock.c
| Protected Heap Handler implementation.
file | pheapwalk.c
| Protected Heap Handler implementation.

## Functions
RTEMS_INLINE_ROUTINE uintptr_t | _Protected_heap_Initialize (Heap_Control *heap, void *area_begin, uintptr_t area_size, uintptr_t page_size)
| Initializes the protected heap.
bool | _Protected_heap_Extend (Heap_Control *heap, void *area_begin, uintptr_t area_size)
| Extends the protected heap.
void * | _Protected_heap_Allocate_aligned_with_boundary (Heap_Control *heap, uintptr_t size, uintptr_t alignment, uintptr_t boundary)
| Allocates an aligned memory area with boundary constraint for the protected heap.
RTEMS_INLINE_ROUTINE void * | _Protected_heap_Allocate_aligned (Heap_Control *heap, uintptr_t size, uintptr_t alignment)
| Allocates an aligned memory area.
RTEMS_INLINE_ROUTINE void * | _Protected_heap_Allocate (Heap_Control *heap, uintptr_t size)
| Allocates a memory area.
bool | _Protected_heap_Get_block_size (Heap_Control *heap, void *addr, uintptr_t *size)
| Returns the size of the allocatable memory area.
bool | _Protected_heap_Resize_block (Heap_Control *heap, void *addr, uintptr_t size)
| Resizes the block of the allocated memory area.
bool | _Protected_heap_Free (Heap_Control *heap, void *addr)
| Frees the allocated memory area.
bool | _Protected_heap_Walk (Heap_Control *heap, int source, bool dump)
| Verifies the integrity of the heap.
void | _Protected_heap_Iterate (Heap_Control *heap, Heap_Block_visitor visitor, void *visitor_arg)
| Iterates over all blocks of the heap.
bool | _Protected_heap_Get_information (Heap_Control *heap, Heap_Information_block *info)
| Returns information about used and free blocks for the heap.
bool | _Protected_heap_Get_free_information (Heap_Control *heap, Heap_Information *info)
| Returns information about free blocks for the heap.
uintptr_t | _Protected_heap_Get_size (Heap_Control *heap)
| Returns the size of the allocatable area in bytes.

## Detailed Description

Provides protected heap services.

The ScoreAllocatorMutex is used to protect the heap accesses.

## Function Documentation

## ◆ _Protected_heap_Allocate()

RTEMS_INLINE_ROUTINE void * _Protected_heap_Allocate | ( | Heap_Control * | heap,
|  | uintptr_t | size
| ) |  |

Allocates a memory area.

A size value of zero will return a unique address which may be freed with _Heap_Free(). This method first locks the allocator and after the allocation of the memory area, unlocks it again.

Parameters

  [in,out] | heap | The heap to allocate a memory are from.
  | size | The size of the desired memory are in bytes.

Return values

  pointer | The starting address of the allocated memory area.
  NULL | No memory is available of the parameters are inconsistent.

## ◆ _Protected_heap_Allocate_aligned()

RTEMS_INLINE_ROUTINE void * _Protected_heap_Allocate_aligned | ( | Heap_Control * | heap,
|  | uintptr_t | size,
|  | uintptr_t | alignment
| ) |  |

Allocates an aligned memory area.

A size value of zero will return a unique address which may be freed with _Heap_Free(). This method first locks the allocator and after the allocation of the memory area, unlocks it again.

Parameters

  [in,out] | heap | The heap to allocate a memory are from.
  | size | The size of the desired memory are in bytes.
  | alignment | The allocated memory area will begin at an address aligned by this value.

Return values

  pointer | The starting address of the allocated memory area.
  NULL | No memory is available of the parameters are inconsistent.

## ◆ _Protected_heap_Allocate_aligned_with_boundary()

void * _Protected_heap_Allocate_aligned_with_boundary | ( | Heap_Control * | heap,
|  | uintptr_t | size,
|  | uintptr_t | alignment,
|  | uintptr_t | boundary
| ) |  |

Allocates an aligned memory area with boundary constraint for the protected heap.

A size value of zero will return a unique address which may be freed with _Heap_Free(). This method first locks the allocator and after the allocation of the memory area, unlocks it again.

Parameters

  [in,out] | heap | The heap to allocate a memory are from.
  | size | The size of the desired memory are in bytes.
  | alignment | The allocated memory area will begin at an address aligned by this value.
  | boundary | The allocated memory area will fulfill a boundary constraint, if this value is not equal to zero. The boundary value specifies the set of addresses which are aligned by the boundary value. The interior of the allocated memory area will not contain an element of this set. The begin or end address of the area may be a member of the set.

Return values

  pointer | The starting address of the allocated memory area.
  NULL | No memory is available of the parameters are inconsistent.

## ◆ _Protected_heap_Extend()

bool _Protected_heap_Extend | ( | Heap_Control * | heap,
|  | void * | area_begin,
|  | uintptr_t | area_size
| ) |  |

Extends the protected heap.

Parameters

  [in,out] | heap | The heap to extend.
  | area_begin | The starting addres of the area to extend heap with.
  | area_size | The size of the heap area.

Return values

  true | The operation succeeded.
  false | The operation failed.

## ◆ _Protected_heap_Free()

bool _Protected_heap_Free | ( | Heap_Control * | heap,
|  | void * | addr
| ) |  |

Frees the allocated memory area.

Inappropriate values for addr may corrupt the heap. This method first locks the allocator and after the free operation, unlocks it again.

Parameters

  [in,out] | heap | The heap of the allocated memory area.
  | addr | The starting address of the memory area to be freed.

Return values

  true | The allocated memory area was successfully freed.
  false | The method failed.

## ◆ _Protected_heap_Get_block_size()

bool _Protected_heap_Get_block_size | ( | Heap_Control * | heap,
|  | void * | addr,
|  | uintptr_t * | size
| ) |  |

Returns the size of the allocatable memory area.

The size value may be greater than the initially requested size in _Heap_Allocate_aligned_with_boundary().

Inappropriate values for addr will not corrupt the heap, but may yield invalid size values.

This method first locks the allocator and after the operation, unlocks it again.

Parameters

  | heap | The heap to operate upon.
  | addr | The starting address of the allocatable memory area.
  [out] | size | Stores the size of the allocatable memory area after the method call.

Return values

  true | The operation was successful.
  false | The operation was not successful.

## ◆ _Protected_heap_Get_free_information()

bool _Protected_heap_Get_free_information | ( | Heap_Control * | heap,
|  | Heap_Information * | info
| ) |  |

Returns information about free blocks for the heap.

This method first locks the allocator and after the operation, unlocks it again.

Parameters

  | heap | The heap to get the information from.
  [out] | info | Stores the information about free blocks of heap after the method call.

## ◆ _Protected_heap_Get_information()

bool _Protected_heap_Get_information | ( | Heap_Control * | heap,
|  | Heap_Information_block * | info
| ) |  |

Returns information about used and free blocks for the heap.

This method first locks the allocator and after the operation, unlocks it again.

Parameters

  | heap | The heap to get the information from.
  [out] | info | Stores the information of the heap after the method call.

## ◆ _Protected_heap_Get_size()

uintptr_t _Protected_heap_Get_size | ( | Heap_Control * | heap | ) |

Returns the size of the allocatable area in bytes.

This value is an integral multiple of the page size.

Parameters

  heap | The heap to get the allocatable area from.

Returns
  The size of the allocatable area in heap in bytes.

## ◆ _Protected_heap_Initialize()

RTEMS_INLINE_ROUTINE uintptr_t _Protected_heap_Initialize | ( | Heap_Control * | heap,
|  | void * | area_begin,
|  | uintptr_t | area_size,
|  | uintptr_t | page_size
| ) |  |

Initializes the protected heap.

Parameters

  [out] | heap | The heap to initialize.
  | area_begin | The starting address of the heap area.
  | area_size | The size of the heap area.
  | page_size | The page size for the heap.

## ◆ _Protected_heap_Iterate()

void _Protected_heap_Iterate | ( | Heap_Control * | heap,
|  | Heap_Block_visitor | visitor,
|  | void * | visitor_arg
| ) |  |

Iterates over all blocks of the heap.

This method first locks the allocator and after the operation, unlocks it again.

Parameters

  [in,out] | heap | The heap to iterate over.
  | visitor | This will be called for each heap block with the argument visitor_arg.
  [in,out] | visitor_arg | The argument for all calls of visitor.

## ◆ _Protected_heap_Resize_block()

bool _Protected_heap_Resize_block | ( | Heap_Control * | heap,
|  | void * | addr,
|  | uintptr_t | size
| ) |  |

Resizes the block of the allocated memory area.

Inappropriate values for addr may corrupt the heap.

This method first locks the allocator and after the resize, unlocks it again.

Parameters

  [in,out] | heap | The heap to operate upon.
  | addr | The starting address of the allocated memory area to be resized.
  | size | The least possible size for the new memory area. Resize may be impossible and depends on the current heap usage.
  [out] | old_size | Stores the size available for allocation in the current block before the resize after the method call.
  [out] | new_size | Stores the size available for allocation in the resized block after the method call. In the case of an unsuccessful resize, zero is returned in this parameter

Return values

  HEAP_RESIZE_SUCCESSFUL | The resize was successful.
  HEAP_RESIZE_UNSATISFIED | The least possible size size was too big. Resize not possible.
  HEAP_RESIZE_FATAL_ERROR | The block starting at addr is not part of the heap.

## ◆ _Protected_heap_Walk()

bool _Protected_heap_Walk | ( | Heap_Control * | heap,
|  | int | source,
|  | bool | dump
| ) |  |

Verifies the integrity of the heap.

Walks the heap to verify its integrity. This method first locks the allocator and after the operation, unlocks it again, if the thread dispatch is enabled.

Parameters

  heap | The heap whose integrity is to be verified.
  source | If dump is `true`, this is used to mark the output lines.
  dump | Indicates whether diagnostic messages will be printed to standard output.

Return values

  true | No errors occured, the heap´s integrity is not violated.
  false | The heap is corrupt.