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