RTEMS: cpukit/include/rtems/rtl/rtl-allocator.h File Reference

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions
rtl-allocator.h File Reference
API » RTEMS Runtime Link Editor

RTEMS Run-Time Linker Allocator. More...

`#include <stdbool.h>`
`#include "rtl-indirect-ptr.h"`

Go to the source code of this file.

## Data Structures
struct | rtems_rtl_alloc_data

## Macros
#define | RTEMS_RTL_ALLOC_TAGS ((size_t) (RTEMS_RTL_ALLOC_READ_EXEC + 1))

## Typedefs
typedef enum rtems_rtl_alloc_tags | rtems_rtl_alloc_tag
typedef enum rtems_rtl_alloc_cmd | rtems_rtl_alloc_cmd
typedef void(* | rtems_rtl_allocator) (rtems_rtl_alloc_cmd cmd, rtems_rtl_alloc_tag tag, void **address, size_t size)
typedef struct rtems_rtl_alloc_data | rtems_rtl_alloc_data

## Enumerations
enum | rtems_rtl_alloc_tags { RTEMS_RTL_ALLOC_OBJECT , RTEMS_RTL_ALLOC_SYMBOL , RTEMS_RTL_ALLOC_EXTERNAL , RTEMS_RTL_ALLOC_READ , RTEMS_RTL_ALLOC_READ_WRITE , RTEMS_RTL_ALLOC_READ_EXEC }
enum | rtems_rtl_alloc_cmd { RTEMS_RTL_ALLOC_NEW , RTEMS_RTL_ALLOC_DEL , RTEMS_RTL_ALLOC_LOCK , RTEMS_RTL_ALLOC_UNLOCK , RTEMS_RTL_ALLOC_WR_ENABLE , RTEMS_RTL_ALLOC_WR_DISABLE }

## Functions
void | rtems_rtl_alloc_initialise (rtems_rtl_alloc_data *data)
void * | rtems_rtl_alloc_new (rtems_rtl_alloc_tag tag, size_t size, bool zero)
void | rtems_rtl_alloc_del (rtems_rtl_alloc_tag tag, void *address)
void | rtems_rtl_alloc_lock (void)
void | rtems_rtl_alloc_unlock (void)
void | rtems_rtl_alloc_wr_enable (rtems_rtl_alloc_tag tag, void *address)
void | rtems_rtl_alloc_wr_disable (rtems_rtl_alloc_tag tag, void *address)
rtems_rtl_allocator | rtems_rtl_alloc_hook (rtems_rtl_allocator handler)
void | rtems_rtl_alloc_indirect_new (rtems_rtl_alloc_tag tag, rtems_rtl_ptr *handle, size_t size)
void | rtems_rtl_alloc_indirect_del (rtems_rtl_alloc_tag tag, rtems_rtl_ptr *handle)
rtems_rtl_alloc_tag | rtems_rtl_alloc_text_tag (void)
rtems_rtl_alloc_tag | rtems_rtl_alloc_const_tag (void)
rtems_rtl_alloc_tag | rtems_rtl_alloc_eh_tag (void)
rtems_rtl_alloc_tag | rtems_rtl_alloc_data_tag (void)
rtems_rtl_alloc_tag | rtems_rtl_alloc_bss_tag (void)
bool | rtems_rtl_alloc_module_new (void **text_base, size_t text_size, void **const_base, size_t const_size, void **eh_base, size_t eh_size, void **data_base, size_t data_size, void **bss_base, size_t bss_size)
void | rtems_rtl_alloc_module_del (void **text_base, void **const_base, void **eh_base, void **data_base, void **bss_base)

## Detailed Description

RTEMS Run-Time Linker Allocator.

## Macro Definition Documentation

## ◆ RTEMS_RTL_ALLOC_TAGS

#define RTEMS_RTL_ALLOC_TAGS ((size_t) (RTEMS_RTL_ALLOC_READ_EXEC + 1))

The number of tags.

## Typedef Documentation

## ◆ rtems_rtl_alloc_cmd

typedef enum rtems_rtl_alloc_cmd rtems_rtl_alloc_cmd

The allocator command type.

## ◆ rtems_rtl_alloc_tag

typedef enum rtems_rtl_alloc_tags rtems_rtl_alloc_tag

The allocator tag type.

## ◆ rtems_rtl_allocator

typedef void(* rtems_rtl_allocator) (rtems_rtl_alloc_cmd cmd, rtems_rtl_alloc_tag tag, void **address, size_t size)

Allocator handler handles all RTL allocations. It can be hooked and overridded for customised allocation schemes or memory maps.

Parameters

  allocation | The request command.
  tag | The type of allocation request.
  address | Pointer to the memory address. If an allocation the value is unspecific on entry and the allocated address or NULL on exit. The NULL value means the allocation failed. If a delete or free request the memory address is the block to free. A free request of NULL is silently ignored.
  size | The size of the allocation if an allocation request and not used if deleting or freeing a previous allocation.

## Enumeration Type Documentation

## ◆ rtems_rtl_alloc_cmd

enum rtems_rtl_alloc_cmd

Define the allocation command the loader requires.

Enumerator
RTEMS_RTL_ALLOC_NEW | Allocate new memory.
RTEMS_RTL_ALLOC_DEL | Delete allocated memory.
RTEMS_RTL_ALLOC_LOCK | Lock the allocator.
RTEMS_RTL_ALLOC_UNLOCK | Unlock the allocator.
RTEMS_RTL_ALLOC_WR_ENABLE | Enable writes to the memory.
RTEMS_RTL_ALLOC_WR_DISABLE | Disable writes to the memory.

## ◆ rtems_rtl_alloc_tags

enum rtems_rtl_alloc_tags

Define the types of allocation the loader requires.

Note
  It is best to use the object tag for general memory allocation and to leave the tags with specific access properties to the module data

Enumerator
RTEMS_RTL_ALLOC_OBJECT | A generic memory object.
RTEMS_RTL_ALLOC_SYMBOL | Memory used for symbols.
RTEMS_RTL_ALLOC_EXTERNAL | Memory used for external symbols.
RTEMS_RTL_ALLOC_READ | The memory is read only.
RTEMS_RTL_ALLOC_READ_WRITE | The memory is read and write.
RTEMS_RTL_ALLOC_READ_EXEC | The memory is read and executable.

## Function Documentation

## ◆ rtems_rtl_alloc_bss_tag()

rtems_rtl_alloc_tag rtems_rtl_alloc_bss_tag | ( | void |  | ) |

Return the default tag for bss sections.

Returns
  The bss tag.

## ◆ rtems_rtl_alloc_const_tag()

rtems_rtl_alloc_tag rtems_rtl_alloc_const_tag | ( | void |  | ) |

Return the default tag for const sections.

Returns
  The const tag.

## ◆ rtems_rtl_alloc_data_tag()

rtems_rtl_alloc_tag rtems_rtl_alloc_data_tag | ( | void |  | ) |

Return the default tag for data sections.

Returns
  The data tag.

## ◆ rtems_rtl_alloc_del()

void rtems_rtl_alloc_del | ( | rtems_rtl_alloc_tag | tag,
|  | void * | address
| ) |  |

The Runtime Loader allocator delete deletes allocated memory.

Parameters

  tag | The type of allocation request.
  address | The memory address to delete. A NULL is ignored.

## ◆ rtems_rtl_alloc_eh_tag()

rtems_rtl_alloc_tag rtems_rtl_alloc_eh_tag | ( | void |  | ) |

Return the default tag for exception sections.

Returns
  The eh tag.

## ◆ rtems_rtl_alloc_hook()

rtems_rtl_allocator rtems_rtl_alloc_hook | ( | rtems_rtl_allocator | handler | ) |

Hook the Runtime Loader allocatior. A handler can call the previous handler in the chain to use it for specific tags. The default handler uses the system heap. Do not unhook your handler if memory it allocates has not been returned.

Parameters

  handler | The handler to use as the allocator.

Returns
  rtems_rtl_alloc_handler The previous handler.

## ◆ rtems_rtl_alloc_indirect_del()

void rtems_rtl_alloc_indirect_del | ( | rtems_rtl_alloc_tag | tag,
|  | rtems_rtl_ptr * | handle
| ) |  |

Free memory from an indirect handle.

Parameters

  tag | The type of allocation request.
  handle | The handle to free the memory from.

## ◆ rtems_rtl_alloc_indirect_new()

void rtems_rtl_alloc_indirect_new | ( | rtems_rtl_alloc_tag | tag,
|  | rtems_rtl_ptr * | handle,
|  | size_t | size
| ) |  |

Allocate memory to an indirect handle.

Parameters

  tag | The type of allocation request.
  handle | The handle to allocate the memory to.
  size | The size of the allocation.

## ◆ rtems_rtl_alloc_initialise()

void rtems_rtl_alloc_initialise | ( | rtems_rtl_alloc_data * | data | ) |

Initialise the allocate data.

Parameters

  data | The data to initialise.

## ◆ rtems_rtl_alloc_lock()

void rtems_rtl_alloc_lock | ( | void |  | ) |

The Runtime Loader allocator lock. An allocator that depends on a separate allocation process, for example the heap, may need to be locked during loading of an object file to make sure the locality of the memory. This call be used to lock such an allocator. Allocator calls in this interface are protected by the RTL lock.

## ◆ rtems_rtl_alloc_module_del()

void rtems_rtl_alloc_module_del | ( | void ** | text_base,
|  | void ** | const_base,
|  | void ** | eh_base,
|  | void ** | data_base,
|  | void ** | bss_base
| ) |  |

Free the memory allocated to a module.

Parameters

  text_base | Pointer to the text base pointer.
  const_base | Pointer to the const base pointer.
  eh_base | Pointer to the eh base pointer.
  data_base | Pointer to the data base pointer.
  bss_base | Pointer to the bss base pointer.

## ◆ rtems_rtl_alloc_module_new()

bool rtems_rtl_alloc_module_new | ( | void ** | text_base,
|  | size_t | text_size,
|  | void ** | const_base,
|  | size_t | const_size,
|  | void ** | eh_base,
|  | size_t | eh_size,
|  | void ** | data_base,
|  | size_t | data_size,
|  | void ** | bss_base,
|  | size_t | bss_size
| ) |  |

Allocate the memory for a module given the size of the text, const, data and bss sections. If any part of the allocation fails the no memory is allocated.

Parameters

  text_base | Pointer to the text base pointer.
  text_size | The size of the read/exec section.
  const_base | Pointer to the const base pointer.
  const_size | The size of the read only section.
  eh_base | Pointer to the eh base pointer.
  eh_size | The size of the eh section.
  data_base | Pointer to the data base pointer.
  data_size | The size of the read/write secton.
  bss_base | Pointer to the bss base pointer.
  bss_size | The size of the read/write.

Return values

  true | The memory has been allocated.
  false | The allocation of memory has failed.

## ◆ rtems_rtl_alloc_new()

void * rtems_rtl_alloc_new | ( | rtems_rtl_alloc_tag | tag,
|  | size_t | size,
|  | bool | zero
| ) |  |

The Runtime Loader allocator new allocates new memory and optionally clear the memory if requested.

Parameters

  tag | The type of allocation request.
  size | The size of the allocation.
  zero | If true the memory is cleared.

Returns
  void* The memory address or NULL is not memory available.

## ◆ rtems_rtl_alloc_text_tag()

rtems_rtl_alloc_tag rtems_rtl_alloc_text_tag | ( | void |  | ) |

Return the default tag for text sections.

Returns
  The text tag.

## ◆ rtems_rtl_alloc_unlock()

void rtems_rtl_alloc_unlock | ( | void |  | ) |

The Runtime Loader allocator unlock. An allocator that depends on a separate allocation process, for example the heap, may need to be locked during loading of an object file to make sure the locality of the memory. This call can be used to unlock such an allocator. Allocator calls in this interface are protected by the RTL lock.

## ◆ rtems_rtl_alloc_wr_disable()

void rtems_rtl_alloc_wr_disable | ( | rtems_rtl_alloc_tag | tag,
|  | void * | address
| ) |  |

The Runtime Loader allocator disable write on a bloc of allocated memory.

Parameters

  tag | The type of allocation request. Must match the address.
  address | The memory address to write disable. A NULL is ignored.

## ◆ rtems_rtl_alloc_wr_enable()

void rtems_rtl_alloc_wr_enable | ( | rtems_rtl_alloc_tag | tag,
|  | void * | address
| ) |  |

The Runtime Loader allocator enable write on a bloc of allocated memory.

Parameters

  tag | The type of allocation request. Must match the address.
  address | The memory address to write enable. A NULL is ignored.