.. _ram_allocation_cc23xx:

RAM
===

There is |RAM_SIZE_LOW| of RAM available in the |DEVICE_LOW| and 
|RAM_SIZE_LOW_PLUS| in the |DEVICE_LOW_PLUS|. The various sections of RAM and 
their associated linker files are as follows.

-  **CSTACK**: This the system callstack used by the C main function and HWIs.
   
.. 
   Commented block at end of file:
   See :ref:`sec-memory-management-system-stack` for more information

-  **RAM Reset Vector Table**: This table holds entries for all supported
   reset vectors. It is initialized from the flash reset vector table at boot
   time and is used to plug interrupt table entries at runtime.

For projects where the stack project builds a **library**:

-  **Application and Stack statically allocated data**: This includes any
   initialized and uninitialized variables used by the application or stack.
   (.data,.bss)

RAM Usage
^^^^^^^^^

Like most of the embedded processors, the RAM of the |DEVICE| is used
to store dynamic data (such as the global variables, the threads'
stacks, and the system's heap). Developers can split the usage of the available 
RAM according to their needs.

When building the program, the linker will raise an error if the RAM
size required by the user exceeds the RAM size specified in the linker command
file. In the linker command file, the device's RAM size is defined by the
symbol ``RAM_SIZE``. Executing a project built with the ``RAM_SIZE`` value
set to a larger value than the RAM actually available on the device 
may lead to unexpected behaviors.

.. note::

    For the |DEVICE|, the linker is NOT configured to auto-size the heap
    as it is the case on other SimpleLink devices. Optimal RAM usage is
    achieved by allocating all the unused RAM as heap.

Heap and Stack sizing
^^^^^^^^^^^^^^^^^^^^^

The following steps show how to maximize the heap memory (in order to use all the RAM available on
the device and have an optimal RAM usage):

 * Build the project and go to ``.map`` file
 * Check Unused SRAM section at the top of the ``.map`` file

     .. figure:: resources/check_ram_usage_map_file.png 
        :align: center

 * In the ``FREERTOS`` section of the ``.syscfg`` file, go to the ``Stack and Heap sizing`` section. 
 * Increase the ``Heap size`` value based on the amount of SRAM left unused previously. 
   Due to memory alignment constraint you will likely not be able to allocate all the available RAM.

     .. figure:: resources/change_heap_size_freertos_sysconfig.png
        :align: center

The ROV can be leveraged when running the program with the debugger attached to observe the heap used after
device boots, this will indicate the real amount of memory the application has left to run.
(Further instruction can be found in the ROV section in :ref:`sec-debugging`)

See :ref:`development-and-debugging-check-system-flash-and-ram-usage-with-map-file` for
the procedure to check the size of the configured protocol stack.

.. warning::

    The out-of-the-box projects are configured to leave only a few bytes of RAM
    non-allocated. This can be misleading when looking at the available RAM
    in the out-of-the-box projects. 

    On the unmodified projects, the heap size can be reduced without altering
    the functioning of the project.

.. Only applicable to IAR
.. 
    .. _sec-memory-management-system-stack:
    
    System Stack
    ------------
    
    As described in |FreeRTOS TASK|, each task has its own runtime
    stack for context switching. Another runtime stack is used by the RTOS for
    main(), HWIs, and SWIs. This system stack is allocated in the
    application linker file to be placed at the end of the RAM of the
    application.
    
    For IAR, this RTOS system stack is defined by the CSTACK symbol in the ``.icf`` file:
    
    .. code-block:: c
    
    	////////////////////////////////////////////////////////////////////////////////
    	// Stack
    	define symbol STACK_SIZE            = 0x400;
    	define symbol STACK_START           = RAM_END + 1;
    	define symbol STACK_END             = STACK_START - STACK_SIZE;
    	//
    	define symbol STACK_TOP             = RAM_END + 1;
    	export symbol STACK_TOP;
    
    .. code-block:: c
    
      ////////////////////////////////////////////////////////////////////////////////
      // Memory Placement
      ////////////////////////////////////////////////////////////////////////////////
    
      //...
    
    	// Runtime Stack
    	define block CSTACK with alignment = 8, size = STACK_SIZE { section .stack };
    
      //...
    
    	define block END_OF_RAM with fixed order {
                                            block HEAP_END,
                                            block CSTACK
                                          };
    
      place at end of RAM { block END_OF_RAM };
    
    In IAR, to change the size of the CSTACK, adjust the STACK_SIZE symbol value in
    the linker configuration file (.icf file) of the application.
    
    For CCS the RTOS system stack is defined by the ``Program.stack`` parameter in
    the RTOS configuration file (the ``.cfg`` file):
    
    .. code-block:: js
    
      /* ================ Program configuration ================ */
    
      // ...
      Program.stack = 1024;
    
    and placed by the linker in the RAM space of the application (``.cmd`` file):
    
    .. code-block:: none
    
    	/* Create global constant that points to top of stack */
    	/* CCS: Change stack size under Project Properties */
    	__STACK_TOP = __stack + __STACK_SIZE;
