Add power management register defintions and clock control logic for the SAM4L

1 files changed, 101 insertions, 69 deletions

diff --git a/nuttx/mm/README.txt b/nuttx/mm/README.txt
index d2f307849..de15e0a5d 100644
--- a/nuttx/mm/README.txt
+++ b/nuttx/mm/README.txt
@@ -3,78 +3,110 @@ mm/README.txt
 
 This directory contains the NuttX memory management logic.  This include:
 
-1) The standard memory management functions as prototyped in stdlib.h as
-   specified in the  Base definitions volume of IEEE Std 1003.1-2001.  This
-   include the files:
+1) Standard Memory Management Functions:
 
-   o Standard Interfaces: mm_malloc.c, mm_calloc.c, mm_realloc.c,
+     The standard memory management functions as prototyped in stdlib.h as
+     specified in the  Base definitions volume of IEEE Std 1003.1-2001.  This
+     include the files:
+
+     o Standard Interfaces: mm_malloc.c, mm_calloc.c, mm_realloc.c,
        mm_memalign.c, mm_free.c
-   o Less-Standard Interfaces: mm_zalloc.c, mm_mallinfo.c
-   o Internal Implementation: mm_initialize.c mm_sem.c  mm_addfreechunk.c
+     o Less-Standard Interfaces: mm_zalloc.c, mm_mallinfo.c
+     o Internal Implementation: mm_initialize.c mm_sem.c  mm_addfreechunk.c
        mm_size2ndx.c mm_shrinkchunk.c, mm_internal.h
-   o Build and Configuration files: Kconfig, Makefile
+     o Build and Configuration files: Kconfig, Makefile
 
    Memory Models:
 
-   o Small Memory Model.  If the MCU supports only 16-bit data addressing
-     then the small memory model is automatically used.  The maximum size
-     of the heap is then 64K.  The small memory model can also be forced
-     MCUs with wider addressing by defining CONFIG_SMALL_MEMORY in the
-     NuttX configuration file.
-   o Large Memory Model.  Otherwise, the allocator uses a model that
-     supports a heap of up to 4G.
-
-   This implementation uses a variable length allocator with the following
-   properties:
-
-   o Overhead:  Either 8- or 4-bytes per allocation for large and small
-     models, respectively.
-   o Alignment:  All allocations are aligned to 8- or 4-bytes for large
-     and small models, respectively.
-
-2) Granule Allocator.  A non-standard granule allocator is also available
-   in this directory  The granule allocator allocates memory in units
-   of a fixed sized block ("granule").  Allocations may be aligned to a user-
-   provided address boundary.
-
-   The granule allocator interfaces are defined in nuttx/include/nuttx/gran.h.
-   The granule allocator consists of these files in this directory:
-
-     mm_gran.h, mm_granalloc.c, mm_grancritical.c, mm_granfree.c
-     mm_graninit.c
-
-   The granule allocator is not used anywhere within the base NuttX code
-   as of this writing.  The intent of the granule allocator is to provide
-   a tool to support platform-specific management of aligned DMA memory.
-
-   NOTE: Because each granule may be aligned and each allocation is in
-   units of the granule size, selection of the granule size is important:
-   Larger granules will give better performance and less overhead but more
-   losses of memory due to quantization waste.  Additional memory waste
-   can occur from alignment;  Of course, heap alignment should no be
-   used unless (a) you are using the granule allocator to manage DMA memory
-   and (b) your hardware has specific memory alignment requirements.
-
-   The current implementation also restricts the maximum allocation size
-   to 32 granules.  That restriction could be eliminated with some
-   additional coding effort, but currently requires larger granule
-   sizes for larger allocations.
-
-  Geneneral Usage Example.  This is an example using the GCC section
-  attribute to position a DMA heap in memory (logic in the linker script
-  would assign the section .dmaheap to the DMA memory.
- 
-    FAR uint32_t g_dmaheap[DMAHEAP_SIZE] __attribute__((section(.dmaheap)));
- 
-  The heap is created by calling gran_initialize.  Here the granual size
-  is set to 64 bytes and the alignment to 16 bytes:
- 
-    GRAN_HANDLE handle = gran_initialize(g_dmaheap, DMAHEAP_SIZE, 6, 4);
- 
-  Then the GRAN_HANDLE can be used to allocate memory (There is no
-  GRAN_HANDLE if CONFIG_GRAN_SINGLE=y):
- 
-    FAR uint8_t *dma_memory = (FAR uint8_t *)gran_alloc(handle, 47);
- 
-  The actual memory allocates will be 64 byte (wasting 17 bytes) and
-  will be aligned at least to (1 << log2align).
+     o Small Memory Model.  If the MCU supports only 16-bit data addressing
+       then the small memory model is automatically used.  The maximum size
+       of the heap is then 64K.  The small memory model can also be forced
+       MCUs with wider addressing by defining CONFIG_SMALL_MEMORY in the
+       NuttX configuration file.
+     o Large Memory Model.  Otherwise, the allocator uses a model that
+       supports a heap of up to 4G.
+
+     This implementation uses a variable length allocator with the following
+     properties:
+
+     o Overhead:  Either 8- or 4-bytes per allocation for large and small
+       models, respectively.
+     o Alignment:  All allocations are aligned to 8- or 4-bytes for large
+       and small models, respectively.
+
+   Multiple Heaps:
+
+     This allocator can be used to manage multiple heaps (albeit with some
+     non-standard interfaces).  A heap is represented by struct mm_heap_s
+     as defined in the file include/nuttx/mm.h.  To create another heap
+     instance, you would allocate a heap structure, most likely statically
+     in memory:
+
+       include <nuttx/mm.h>
+       static struct mm_heap_s g_myheap;
+
+     Then initialize the heap using:
+
+       mm_initialize(&g_myheap, myheap_start, myheap_size);
+
+     Where mm_initialize() and all related interfaces are prototyped in the
+     header file include/nuttx/mm.h.
+
+     After the new heap instance has been initialized, it can then be used
+     with these almost familiar interfaces: mm_malloc(), mm_realloc(), mm_free(),
+     etc.  These are 'almost familiar' because they are analogous of the
+     standard malloc(), realloc(), free(), etc. except that they expect a
+     reference to the initialized heap structure as the first parameter.
+
+     In fact, the standard malloc(), realloc(), free() use this same mechanism,
+     but with a global heap structure called g_mmheap.
+
+2) Granule Allocator.
+
+     A non-standard granule allocator is also available in this directory  The
+     granule allocator allocates memory in units of a fixed sized block ("granule").
+     Allocations may be aligned to a user-provided address boundary.
+
+     The granule allocator interfaces are defined in nuttx/include/nuttx/gran.h.
+     The granule allocator consists of these files in this directory:
+
+       mm_gran.h, mm_granalloc.c, mm_grancritical.c, mm_granfree.c
+       mm_graninit.c
+
+     The granule allocator is not used anywhere within the base NuttX code
+     as of this writing.  The intent of the granule allocator is to provide
+     a tool to support platform-specific management of aligned DMA memory.
+
+     NOTE: Because each granule may be aligned and each allocation is in
+     units of the granule size, selection of the granule size is important:
+     Larger granules will give better performance and less overhead but more
+     losses of memory due to quantization waste.  Additional memory waste
+     can occur from alignment;  Of course, heap alignment should no be
+     used unless (a) you are using the granule allocator to manage DMA memory
+     and (b) your hardware has specific memory alignment requirements.
+
+     The current implementation also restricts the maximum allocation size
+     to 32 granules.  That restriction could be eliminated with some
+     additional coding effort, but currently requires larger granule
+     sizes for larger allocations.
+
+   General Usage Example.
+
+     This is an example using the GCC section attribute to position a DMA
+     heap in memory (logic in the linker script would assign the section
+     .dmaheap to the DMA memory.
+
+        FAR uint32_t g_dmaheap[DMAHEAP_SIZE] __attribute__((section(.dmaheap)));
+
+     The heap is created by calling gran_initialize.  Here the granule size
+     is set to 64 bytes and the alignment to 16 bytes:
+
+       GRAN_HANDLE handle = gran_initialize(g_dmaheap, DMAHEAP_SIZE, 6, 4);
+
+     Then the GRAN_HANDLE can be used to allocate memory (There is no
+     GRAN_HANDLE if CONFIG_GRAN_SINGLE=y):
+
+       FAR uint8_t *dma_memory = (FAR uint8_t *)gran_alloc(handle, 47);
+
+     The actual memory allocates will be 64 byte (wasting 17 bytes) and
+     will be aligned at least to (1 << log2align).