; --------------------------------------------------------------------------------
; @Title: Readme for FreeRTOS on ARM/ARM64
; @Description: 
;   This file includes necessary patches for FreeRTOS to support Task aware
;   tracing.
;   
; @Keywords: awareness, RTOS, FreeRTOS
; @Author: AME
; @Copyright: (C) 1989-2022 Lauterbach GmbH, licensed for use with TRACE32(R) only
; --------------------------------------------------------------------------------
; $Id: readme.txt 18850 2022-01-26 18:41:29Z bschroefel $

= Debug =
== Exception Level ==
Per default the awareness assumes FreeRTOS is running in NonSecure EL1 / Supervisor 
mode. If that is not the case, the parameter "/ACCESS" must be used.
Example - FreeRTOS in NonSecure EL1
  TASK.CONFIG ~~/demo/arm/kernel/freertos/freertos.t32
Example - FreeRTOS in EL2 / Hypervisor mode
  TASK.CONFIG ~~/demo/arm/kernel/freertos/freertos.t32 /ACCESS H:
Example - FreeRTOS in EL3 / Monitor mode (64bit cores only)
  TASK.CONFIG ~~/demo/arm/kernel/freertos/freertos.t32 /ACCESS M:

== Stack Evaluation ==
For FreeRTOS-Version>=10 make use of configRECORD_STACK_HIGH_ADDRESS.
<FreeRTOSConfig.h>
#define configCHECK_FOR_STACK_OVERFLOW 2
#define configRECORD_STACK_HIGH_ADDRESS 1
</FreeRTOSConfig.h>

= Task aware Trace =
== CortexA/R without DataTrace ==
Applicable for ARMv8/v9 cores in 64bit mode e.g. Cortex-A53/R82.

The C-MACRO traceTASK_SWITCHED_IN is used to write the pxCurrentTCB pointer 
(address of the current task structure) to the CONTEXTIDR_EL1 register.

<FreeRTOSConfig.h>
#define traceTASK_SWITCHED_IN() \
{ \
  __asm volatile ("msr contextidr_el1,%0" : :"r" (pxCurrentTCB)); \
}
</FreeRTOSConfig.h>

Setting within TRACE32:
  ETM.ContextID 32
  ETM.TraceON
  ETM.ON

= Task aware Trace =
== CortexA/R without DataTrace ==
Applicable for ARMv7, ARMv8, ARMv9 cores in 32bit mode, e.g. CortexA32/R52/A7.

Description: A function T32_Magic_Update is used to write the pxCurrectTCB value to the CONTEXTIDR (C15:0x10d).
The C-MACRO traceTASK_SWITCHED_IN is used to write the pxCurrentTCB pointer 
(address of the current task structure) to the CONTEXTIDR (C15:0x10d) register.

<FreeRTOSConfig.h>
#define traceTASK_SWITCHED_IN() \
{ \
  __asm volatile ("MCR	P15, 0x0,%0,C13,C0,0x1" : :"r" (pxCurrentTCB)); \
}
</FreeRTOSConfig.h>

Setting within TRACE32:
	ETM.ContextID 32
	ETM.TraceON
	ETM.ON