MBA.h File Reference

Random memory allocation, function prototypes. More...

#include <IPBS/impl/MBA.h.xx-xxx-xxx>

Classes
struct	_MBA_badBlock
	Definition of a bad block of memory. More...
Typedefs
typedef struct _MBA_badBlock	MBA_badBlock
	Typedef for struct _MBA_badBlock.
typedef PART_ID(*	MBA_create_cb )(void *prm)
	Function signature for a user definition initialization routine.
Functions
void *	MBA_align (unsigned int alignment, unsigned int nBytes)
	Allocates nBytes of aligned memory.
void *	MBA_alloc (unsigned int nBytes)
	Allocates nBytes of at least word aligned memory.
int	MBA_free (void *pBlock)
	Frees a piece of memory allocated with either MBA_align() or MBA_alloc().
int	MBA_statsGet (MBA_stats *stats)
	Gets the memory stats for the MBA partition.
int	MBA_initialize (MBA_create_cb create, void *prm)
	One time initialization of the MBA facility.

---

Detailed Description

Random memory allocation, function prototypes.

Author:

JJRussell - russell@slac.stanford.edu

    CVS $Id: MBA.h,v 1.2 2011/03/25 21:15:00 saxton Exp $

SYNOPSIS

This file acts as a front for malloc() and memalign() on host platforms and for memPartAlloc and memPartAlignedAlloc on VxWorks. Application level code should always use the equivalent M routines. On VxWork's platforms, malloc() and memalign(), by default, allocate out of the system partition. Because the VxWork's dynamic loader uses malloc() and because restrictions on the range of branch statements, the system partition must be limited to less than 24Mbytes.

With this in mind, FSW decided on a policy that discourages use of malloc() and memalign() in application code, effectively reserving the system partition for exclusive use by VxWorks itself.

---

Typedef Documentation

MBA_badBlock

Typedef for struct _MBA_badBlock.

A bad block is defined as a starting address and a length, in bytes. Typically one will specify a list of bad blocks. By convention, the list is terminated with a block specified with a beginning address of 0 and a length of 0.

On embedded systems, MBA will remove bad blocks that fall within the range of its pool. This will be done at system initialization time. Unforturnately, there is no easy way to do this if the bad blocks fall within the system partition. It appears the only method here is to rebuild the kernel.

Note:

This should have been an easy job. One would have used the memory mapping registers to remap around the bad blocks. But, alas, the page registers do not work on the RAD750, hence this method.

PART_ID(* MBA_create_cb)(void *prm)

Function signature for a user definition initialization routine.

Returns:

The partition id

Parameters:

prm

Arbitrary user parameter

While this function will get called back on non-VxWorks targets, it has no effect and is there simply for portability.

---

Function Documentation

void * MBA_align	(	unsigned int	alignment,
		unsigned int	nBytes
	)

Allocates nBytes of aligned memory.

Parameters:

	alignment	The alignment factor. This must be a power of 2
	nBytes	The number of bytes to allocate

Returns:

If successful, a pointer to the allocated memory, Else NULL

Warning:

Note that the calling sequence to this routine follows the convention of memalign(), not that of the VxWorks routine memPartAlign().

void * MBA_alloc

(

unsigned int

nBytes

)

Allocates nBytes of at least word aligned memory.

Parameters:

nBytes

The number of bytes to allocate

Returns:

If successful, a pointer to the allocated memory, Else NULL

Referenced by TASK_create(), TASK_cvt(), and WUT_sys_init().

int MBA_free

(

void *

pBlock

)

Frees a piece of memory allocated with either MBA_align() or MBA_alloc().

Parameters:

pBlock

Pointer to the block of memory to be freed.

Return values:

	0,if	successful
	-1,if	error

The return error codes are only supported on VxWorks platforms. On generic platforms, success is always returned. This is because free() does not give any indication of success or failure, whereas the VxWorks memPart routines do.

Referenced by TASK_cvt(), TASK_join(), TASK_rvt(), and WUT_sys_shutdown().

int MBA_initialize	(	MBA_create_cb	create,
		void *	prm
	)

One time initialization of the MBA facility.

Returns:

Status

Parameters:

	create	User callback partition creation meant to usurp the default creation routine in an extreme emergency
	prm	Arbitrary user parameter passed to partition creation routine. If the partition creation routine is specified as NULL, then, if this parameter is treated as a pointer to a list of bad blocks, MBA_badBlock.

This is not meant to be a user callable routine.

Referenced by PBS_initialize2().

int MBA_statsGet

(

MBA_stats *

stats

)

Gets the memory stats for the MBA partition.

Parameters:

stats

Pointer to the statistics block to fill

Return values:

	0,if	successful
	-1,if	error

On generic host platforms, this call is provided only for portability reasons. Such statistics either do not exist or exist, but there is no user level access to them.

Warning:

Because these statistics do not exist, the caller should not depend on the contents of the filled in statistics block. Anything beyond just displaying or reporting the contents is sure to get the caller in trouble. If one is depending on these results, then it is up to the caller to make his code portable across both a VXWORS and a generic platform.