AN2345 Freescale Semiconductor / Motorola, AN2345 Datasheet
AN2345
Related parts for AN2345
AN2345 Summary of contents
Page 1
... Freescale Semiconductor, Inc. Application Note AN2345/D Rev. 1, 9/2003 Real-Time Memory Manager for StarCore DSPs by Joe Liccese A common limitation of many general-purpose memory managers is that they cannot run within real-time operating system (RTOS) environments typically used with digital signal processors (DSPs), because of reentrancy issues, lack of mutual exclusion, or their non-determinism. Also, general-purpose memory ...
Page 2
Memory Manager Limitations 1.2 Deterministic Systems Real-time systems are prolific within embedded environments. A real-time system must be deterministic, that is, it must provide a required level of service in a bounded response time. Since most general memory managers require ...
Page 3
Freescale Semiconductor, Inc. VSMM routines execute in a known and deterministic way; that is, each VSMM routine has a known and bounded response time. Details on this response time can be found within the interface control document (ICD) [6] of ...
Page 4
Memory Manager Limitations mutual exclusivity must be ensured. The following operation is atomic because nothing but a reset can stop or interrupt the instruction: move.1 d1, r0 Never assume that a compiler generates atomic code. For example assume ...
Page 5
Freescale Semiconductor, Inc. the same heap simultaneously. For example, if one process attempts to allocate a block of memory and fails to update the global free list pointer before it is preempted by a process with a higher priority, the ...
Page 6
VSMM Basics 2 VSMM Basics This section presents an overview of the VSMM requirements, and architecture. The VSMM allows an application to obtain fixed-size memory blocks from a partition (heap) consisting of a contiguous area of memory. All memory blocks ...
Page 7
Freescale Semiconductor, Inc. Heap Handle 0x10028 BlockSize 2.3 Memory Control Blocks Each heap requires its own 24-byte MCB that contains all required heap information. The MCB is defined by the following code: typedef struct { void void INT32U uliVSMMMemBlkSize; INT32U ...
Page 8
VSMM Basics When a heap is created, an MCB is removed from the free list and updated to reflect the characteristics of the new heap. Each of the heap’s memory blocks is initialized so that it points to the next ...
Page 9
Freescale Semiconductor, Inc. Heap Handle 0x10028 Heap Handle 0x10040 Figure 6. A Heap Created From a Memory Block of Another Heap Heap Handle 0x10028 0x100A0 0x180B0 2048 8 6 (void *)0 Heap Handle 0x10040 0x100A0 0x110B0 2048 8 6 0x10028 ...
Page 10
VSMM Basics 2.4 VSMM Global Objects The VSMM uses two global objects to assist in managing each heap: t_VSMM_MEM t_VSMM_MEM astVSMMMemTbl[VSMM_MAX_MEM_PART]; Variable VSMMMemFreeList VSMMMemTbl The VSMMMemInit routine initializes each MCB within the VSMMMemTbl and sets the global VSMMMemFreeList pointer to ...
Page 11
Freescale Semiconductor, Inc. 2.5 Data Control Block The data control block (DCB 28-byte VSMM object used by the VSMM query routine to store specific information about a heap. The VSMM DCB is defined as follows: typedef struct { ...
Page 12
VSMM Distribution VSMM Object Library VSMM Configuration Source File VSMM Configuration Header File VSMM DSP Setup File VSMM General Header File VSMM Master Include File VSMM Enter Critical Method 2 Source VSMM Exit Critical Method 2 Source VSMM Non-RTOS Example ...
Page 13
Freescale Semiconductor, Inc. parameters passed to a VSMM routine are within allowable range. Setting this global constant to 0 disables this feature, thus reducing the cycle overhead and code footprint of each VSMM routine. • Critical entry and exit routines. ...
Page 14
VSMM Distribution 3.6 VSMM Critical Methods Many VSMM routines have critical sections, in which the program is vulnerable to undesirable interruption or corruption and therefore requires interrupts to be disabled during execution of these sections. The VSMM release provides several ...
Page 15
Freescale Semiconductor, Inc. #if #endif Ensure that the OSEck bspspinlock.h header file is included in your module containing this code snippet. 4 Building Your Application with VSMM This section describes the steps necessary to include the VSMM functionality within your ...
Page 16
Building Your Application with VSMM Your application project must also include the VSMM_cfg.c source file. You are required to add the two assembly files VSMMEnterCritical.asm and VSMMExitCritical.asm if you have elected to use the default non-OSEck RTOS critical method 2 ...
Page 17
Freescale Semiconductor, Inc. 0x500000 0x700000 Figure 10. System Stack and Heap Space After identifying the memory ...
Page 18
Building Your Application with VSMM total heap size (THS) = number of blocks * (ABS + VSMM_MEMBLK_HDR_SIZE) For example, suppose we are creating heaps for an application that requires at most: • four 16 KB blocks or twenty 774 byte ...
Page 19
Freescale Semiconductor, Inc. // Allocate a Memory Block from Heap2 apucBlockPtrArray2[0] = (unsigned char *) VSMMMemAlloc( // Verify allocation was a success if(ucErrCode != VSMM_NO_ERR) { printf("ERROR %d -- Unable to Allocate Block from Heap2\n", asm(" debug"); } Upon successful ...
Page 20
... Motorola MSC8101ADS board and appropriate command converter and inter-connecting cable The following software and tools are required in order to build and run the VSMM RTOS example: • PC running Windows 9x, NT, or Win2000 or Solaris Platform • Metrowerks Codewarrior v2.02 Targeted for Motorola StarCore DSPs • ...
Page 21
Freescale Semiconductor, Inc. The ExampleRTOS2 binary, ExampleRTOS2.eld, was built with the VSMM preprocessor macro defined, so only VSMM is used for all memory allocations within the supplied executable. Download ExampleRTOS2 without requiring a build, as follows: 1. Select Preferences from ...
Page 22
VSMM Benchmarking Manager Another important aspect of the VSMM is the overall memory efficiency. For this portion of our benchmarking, we statically created two heaps of sufficient size to allocate thirty-two 230-byte buffers and four 16 KB buffers. The number ...
Page 23
Freescale Semiconductor, Inc. Dynamic heap creation Dynamic heap destruction Memory allocation Memory free Memory query VSMMMemInit.c VSMMMemCreate.c VSMMMemAllocCreate.c VSMMMemDestroy.c VSMMMemAlloc.c VSMMMemFree.c VSMMMemQuery.c VSMMEnterCritical.asm VSMMExitCritical.asm 6 VSSM Functions This section describes the VSMM functions. 6.1 VSMMMemInit() Syntax void VSMMMemInit(void) Description Initializes ...
Page 24
VSSM Functions uliBlkSize. The size, in bytes, of each memory block within this heap. *pucErr. A pointer to an error message that is set by this function. Return Value Address of a memory control block if the heap is created; ...
Page 25
Freescale Semiconductor, Inc. VSMM_MEM_NO_FREE_BLKS. If there are no more free memory blocks, within this heap, to allocate to the caller. Example Usage apucBlockPtrArray2[ (unsigned char *) VSMMMemAlloc(pstHeap2Ptr, &ucErrCode); 6.5 VSMMMemFree() Syntax INT8U VSMMMemFree (void *pvPBlk) Description Determines heap ...
Page 26
Building VSMM Examples 1–3 7 Building VSMM Examples 1–3 This section describes the Metrorwerks Codewarrior v2.02 project associated with building, downloading, and debugging VSMM examples 1 through 3. To build each example, open the project file entitled VSMMExamplesCR.mcp. If Metrowerks ...
Page 27
Freescale Semiconductor, Inc. Figure 12 shows the three targets within this project, Example1, Example2, and Critical Method 2. Figure 12. VSMM Example Project Target Pane Example1 is built as follows: 1. Select this target from the project target pane. 2. ...
Page 28
VSMM Configuration Source Listing 8 VSMM Configuration Source Listing This section contains the source code for the VSMM configuration source files, which include the header file, VSMM_cfg.h and the ‘C’ source file VSMM_cfg.c. These two files allow customization of VSMM ...
Page 29
Freescale Semiconductor, Inc. /* ************************************************************************** * ************************************************************************** */ #if VSMM_CRITICAL_METHOD == 2 && !OSE_RTOS void VSMM_ENTER_CRITICAL(void); void VSMM_EXIT_CRITICAL(void); #endif #endif // end ifndef vsmm_cfg_h // end vsmm_cfg.h 8.2 Configuration ‘C’ Source File, VSMM_cfg.c /* ************************************************************************** * File : VSMM_CFG.C * ...
Page 30
VSMM Configuration Source Listing /* ************************************************************************** * * * Method 1: Disable/Enable interrupts using simple instructions. After * critical section, interrupts will be enabled even if they were disabled * before entering the critical section Method 2: Disable/Enable ...
Page 31
Freescale Semiconductor, Inc. #if VSMM_CRITICAL_METHOD == 2 #if OSE_RTOS > 0 void VSMM_ENTER_CRITICAL(void) { LOCK_SAVE /* Disable interrupts */ } void VSMM_EXIT_CRITICAL(void) { LOCK_RESTORE /* Restore interrupts back to their prev state */ } #endif // end ose_rtos > 0 ...
Page 32
... MOTOROLA and the Stylized M Logo are registered in the U.S. Patent and Trademark Office. OnCE and digital dna are trademarks of Motorola, Inc. All other product or service names are the property of their respective owners. Motorola, Inc Equal Opportunity/Affirmative Action Employer. © Motorola, Inc. 2003 AN2345/D, Rev. 1 For More Information On This Product, Go to: www.freescale.com ...