tcm.rst

  1==================================================
  2ARM TCM (Tightly-Coupled Memory) handling in Linux
  3==================================================
  4
  5Written by Linus Walleij <linus.walleij@stericsson.com>
  6
  7Some ARM SoCs have a so-called TCM (Tightly-Coupled Memory).
  8This is usually just a few (4-64) KiB of RAM inside the ARM
  9processor.
 10
 11Due to being embedded inside the CPU, the TCM has a
 12Harvard-architecture, so there is an ITCM (instruction TCM)
 13and a DTCM (data TCM). The DTCM can not contain any
 14instructions, but the ITCM can actually contain data.
 15The size of DTCM or ITCM is minimum 4KiB so the typical
 16minimum configuration is 4KiB ITCM and 4KiB DTCM.
 17
 18ARM CPUs have special registers to read out status, physical
 19location and size of TCM memories. arch/arm/include/asm/cputype.h
 20defines a CPUID_TCM register that you can read out from the
 21system control coprocessor. Documentation from ARM can be found
 22at http://infocenter.arm.com, search for "TCM Status Register"
 23to see documents for all CPUs. Reading this register you can
 24determine if ITCM (bits 1-0) and/or DTCM (bit 17-16) is present
 25in the machine.
 26
 27There is further a TCM region register (search for "TCM Region
 28Registers" at the ARM site) that can report and modify the location
 29size of TCM memories at runtime. This is used to read out and modify
 30TCM location and size. Notice that this is not a MMU table: you
 31actually move the physical location of the TCM around. At the
 32place you put it, it will mask any underlying RAM from the
 33CPU so it is usually wise not to overlap any physical RAM with
 34the TCM.
 35
 36The TCM memory can then be remapped to another address again using
 37the MMU, but notice that the TCM is often used in situations where
 38the MMU is turned off. To avoid confusion the current Linux
 39implementation will map the TCM 1 to 1 from physical to virtual
 40memory in the location specified by the kernel. Currently Linux
 41will map ITCM to 0xfffe0000 and on, and DTCM to 0xfffe8000 and
 42on, supporting a maximum of 32KiB of ITCM and 32KiB of DTCM.
 43
 44Newer versions of the region registers also support dividing these
 45TCMs in two separate banks, so for example an 8KiB ITCM is divided
 46into two 4KiB banks with its own control registers. The idea is to
 47be able to lock and hide one of the banks for use by the secure
 48world (TrustZone).
 49
 50TCM is used for a few things:
 51
 52- FIQ and other interrupt handlers that need deterministic
 53  timing and cannot wait for cache misses.
 54
 55- Idle loops where all external RAM is set to self-refresh
 56  retention mode, so only on-chip RAM is accessible by
 57  the CPU and then we hang inside ITCM waiting for an
 58  interrupt.
 59
 60- Other operations which implies shutting off or reconfiguring
 61  the external RAM controller.
 62
 63There is an interface for using TCM on the ARM architecture
 64in <asm/tcm.h>. Using this interface it is possible to:
 65
 66- Define the physical address and size of ITCM and DTCM.
 67
 68- Tag functions to be compiled into ITCM.
 69
 70- Tag data and constants to be allocated to DTCM and ITCM.
 71
 72- Have the remaining TCM RAM added to a special
 73  allocation pool with gen_pool_create() and gen_pool_add()
 74  and provide tcm_alloc() and tcm_free() for this
 75  memory. Such a heap is great for things like saving
 76  device state when shutting off device power domains.
 77
 78A machine that has TCM memory shall select HAVE_TCM from
 79arch/arm/Kconfig for itself. Code that needs to use TCM shall
 80#include <asm/tcm.h>
 81
 82Functions to go into itcm can be tagged like this:
 83int __tcmfunc foo(int bar);
 84
 85Since these are marked to become long_calls and you may want
 86to have functions called locally inside the TCM without
 87wasting space, there is also the __tcmlocalfunc prefix that
 88will make the call relative.
 89
 90Variables to go into dtcm can be tagged like this::
 91
 92  int __tcmdata foo;
 93
 94Constants can be tagged like this::
 95
 96  int __tcmconst foo;
 97
 98To put assembler into TCM just use::
 99
100  .section ".tcm.text" or .section ".tcm.data"
101
102respectively.
103
104Example code::
105
106  #include <asm/tcm.h>
107
108  /* Uninitialized data */
109  static u32 __tcmdata tcmvar;
110  /* Initialized data */
111  static u32 __tcmdata tcmassigned = 0x2BADBABEU;
112  /* Constant */
113  static const u32 __tcmconst tcmconst = 0xCAFEBABEU;
114
115  static void __tcmlocalfunc tcm_to_tcm(void)
116  {
117	int i;
118	for (i = 0; i < 100; i++)
119		tcmvar ++;
120  }
121
122  static void __tcmfunc hello_tcm(void)
123  {
124	/* Some abstract code that runs in ITCM */
125	int i;
126	for (i = 0; i < 100; i++) {
127		tcmvar ++;
128	}
129	tcm_to_tcm();
130  }
131
132  static void __init test_tcm(void)
133  {
134	u32 *tcmem;
135	int i;
136
137	hello_tcm();
138	printk("Hello TCM executed from ITCM RAM\n");
139
140	printk("TCM variable from testrun: %u @ %p\n", tcmvar, &tcmvar);
141	tcmvar = 0xDEADBEEFU;
142	printk("TCM variable: 0x%x @ %p\n", tcmvar, &tcmvar);
143
144	printk("TCM assigned variable: 0x%x @ %p\n", tcmassigned, &tcmassigned);
145
146	printk("TCM constant: 0x%x @ %p\n", tcmconst, &tcmconst);
147
148	/* Allocate some TCM memory from the pool */
149	tcmem = tcm_alloc(20);
150	if (tcmem) {
151		printk("TCM Allocated 20 bytes of TCM @ %p\n", tcmem);
152		tcmem[0] = 0xDEADBEEFU;
153		tcmem[1] = 0x2BADBABEU;
154		tcmem[2] = 0xCAFEBABEU;
155		tcmem[3] = 0xDEADBEEFU;
156		tcmem[4] = 0x2BADBABEU;
157		for (i = 0; i < 5; i++)
158			printk("TCM tcmem[%d] = %08x\n", i, tcmem[i]);
159		tcm_free(tcmem, 20);
160	}
161  }