/Documentation/arm/msm/emulate_domain_manager.txt

  1Copyright (c) 2009, Code Aurora Forum. All rights reserved.
  2
  3Redistribution and use in source form and compiled forms (SGML, HTML, PDF,
  4PostScript, RTF and so forth) with or without modification, are permitted
  5provided that the following conditions are met:
  6
  7Redistributions in source form must retain the above copyright notice, this
  8list of conditions and the following disclaimer as the first lines of this
  9file unmodified.
 10
 11Redistributions in compiled form (transformed to other DTDs, converted to
 12PDF, PostScript, RTF and other formats) must reproduce the above copyright
 13notice, this list of conditions and the following disclaimer in the
 14documentation and/or other materials provided with the distribution.
 15
 16THIS DOCUMENTATION IS PROVIDED BY THE CODE AURORA FORUM "AS IS"
 17AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 18IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 19AND NON-INFRINGEMENT ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD
 20DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 21SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 22PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 23OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 24WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 25OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
 26ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 27
 28
 29Introduction
 30============
 31
 328x50 chipset requires the ability to disable HW domain manager function.
 33
 34The ARM MMU architecture has a feature known as domain manager mode.
 35Briefly each page table, section, or supersection is assigned a domain.
 36Each domain can be globally configured to NoAccess, Client, or Manager
 37mode.  These global configurations allow the access permissions of the
 38entire domain to be changed simultaneously.
 39
 40The domain manger emulation is required to fix a HW problem on the 8x50
 41chipset.  The problem is simple to repair except when domain manager mode
 42is enabled.  The emulation allows the problem to be completely resolved.
 43
 44
 45Hardware description
 46====================
 47
 48When domain manager mode is enabled on a specific domain, the MMU
 49hardware ignores the access permission bits and the execute never bit.  All
 50accesses, to memory in the domain, are granted full read, write,
 51execute permissions.
 52
 53The mode of each domain is controlled by a field in the cp15 dacr register.
 54Each domain can be globally configured to NoAccess, Client, or Manager mode.
 55
 56See: ARMv7 Architecture Reference Manual
 57
 58
 59Software description
 60====================
 61
 62In order to disable domain manager mode the equivalent HW functionality must
 63be emulated in SW.  Any attempts to enable domain manager mode, must be
 64intercepted.
 65
 66Because domain manager mode is not enabled, permissions for the
 67associated domain will remain restricted.  Permission faults will be generated.
 68The permission faults will be intercepted.  The faulted pages/sections will
 69be modified to grant full access and execute permissions.
 70
 71The modified page tables must be restored when exiting domain manager mode.
 72
 73
 74Design
 75======
 76
 77Design Goals:
 78
 79Disable Domain Manager Mode
 80Exact SW emulation of Domain Manager Mode
 81Minimal Kernel changes
 82Minimal Security Risk
 83
 84Design Decisions:
 85
 86Detect kernel page table modifications on restore
 87Direct ARMv7 HW MMU table manipulation
 88Restore emulation modified MMU entries on context switch
 89No need to restore MMU entries for MMU entry copy operations
 90Invalidate TLB entries on modification
 91Store Domain Manager bits in memory
 928 entry MMU entry cache
 93Use spin_lock_irqsave to protect domain manipulation
 94Assume no split MMU table
 95
 96Design Discussion:
 97
 98Detect kernel page table modifications on restore -
 99When restoring original page/section permission faults, the submitted design
100verifies the MMU entry has not been modified.  The kernel modifies MMU
101entries for the following purposes : create a memory mapping, release a
102memory mapping, add permissions during a permission fault, and map a page
103during a translation fault.  The submitted design works with the listed
104scenarios.  The translation fault and permission faults simply do not happen on
105relevant entries (valid entries with full access permissions).  The alternative
106would be to hook every MMU table modification.  The alternative greatly
107increases complexity and code maintenance issues.
108
109Direct ARMv7 HW MMU table manipulation -
110The natural choice would be to use the kernel provided mechanism to manipulate
111MMU page table entries.  The ARM MMU interface is described in pgtable.h.
112This interface is complicated by the Linux implementation.  The level 1 pgd
113entries are treated and manipulated as entry pairs.  The level 2 entries are
114shadowed and cloned.  The compromise was chosen to actually use the ARMv7 HW
115registers to walk and modify the MMU table entries.  The choice limits the
116usage of this implementation to ARMv7 and similar ARM MMU architectures.  Since
117this implementation is targeted at fixing an issue in 8x50 ARMv7, the choice is
118logical.  The HW manipulation is in distinct low level functions.  These could
119easily be replaced or generalized to support other architectures as necessary.
120
121Restore emulation modified MMU entries on context switch -
122This additional hook was added to minimize performance impact.  By guaranteeing
123the ASID will not change during the emulation, the emulation may invalidate each
124entry by MVA & ASID.  Only the affected page table entries will be removed from
125the TLB cache.  The performance cost of the invalidate on context switch is near
126zero.  Typically on context switch the domain mode would also change, forcing a
127complete restore of all modified MMU entries.  The alternative would be to
128invalidate the entire TLB every time a table entry is restored.
129
130No need to restore MMU entries for copy operations -
131Operations which copy MMU entries are relatively rare in the kernel.  Because
132we modify the level 2 pte entries directly in hardware, the Linux shadow copies
133are left untouched.  The kernel treats the shadow copies as the primary pte
134entry.  Any pte copy operations would be unaffected by the HW modification.
135On translation section fault, pgd entries are copied from the kernel master
136page table to the current thread page table.  Since we restore MMU entries on
137context switch, we guarantee the master table will not contain modifications,
138while faulting on a process local entry.  Other read, modify write operations
139occur during permission fault handling.  Since we open permission on modified
140entries, these do not need to be restored, because we guarantee these
141permission fault operations will not happen.
142
143Invalidate TLB entries on modification -
144No real choice here.  This is more of a design requirement.  On permission
145fault, the MMU entry with restricted permissions will be in the TLB.  To open
146access permissions, the TLB entry must be invalidated.  Otherwise the access
147will permission fault again.  Upon restoring original MMU entries, the TLB
148must be invalidated to restrict memory access.
149
150Store Domain Manager bits in memory -
151There was only one alternative here.  2.6.29 kernel only uses 3 of 16
152possible domains.  Additional bits in dacr could be used to store the
153manager bits.  This would allow faster access to the manager bits.
154Overall this would reduce any performance impact.  The performance
155needs did not seem to justify the added weirdness.
156
1578 entry MMU entry cache-
158The size of the modified MMU entry cache is somewhat arbitrary.  The thought
159process is that typically, a thread is using two pointers to perform a copy
160operation.  In this case only 2 entries would be required.  One could imagine
161a more complicated operation, a masked copy for instance, which would require
162more pointers.  8 pointer seemed to be large enough to minimize risk of
163permission fault thrashing.  The disadvantage of a larger cache would simply
164be a longer list of entries to restore.
165
166Use spin_lock_irqsave to protect domain manipulation -
167The obvious choice.
168
169Assume no split MMU table -
170This same assumption is documented in cpu_v7_switch_mm.
171
172
173Power Management
174================
175
176Not affected.
177
178
179SMP/multi-core
180==============
181
182SMP/multicore not supported.  This is intended as a 8x50 workaround.
183
184
185Security
186========
187
188MMU page/section permissions must be manipulated correctly to emulate domain
189manager mode.  If page permission are left in full access mode, any process
190can read associated memory.
191
192
193Performance
194===========
195
196Performance should be impacted only minimally.  When emulating domain manager
197mode, there is overhead added to MMU table/context switches, set_domain()
198calls, data aborts, and prefetch aborts.
199
200Normally the kernel operates with domain != DOMAIN_MANAGER.  In this case the
201overhead is minimal.  An additional check is required to see if domain manager
202mode is on.  This minimal code is added to each of emulation entry points :
203set, data abort, prefetch abort, and MMU table/context switch.
204
205Initial accesses to a MMU protected page/section will generate a permission
206fault. The page will be manipulated to grant full access permissions and
207the access will be retried.  This will typically require 2-3 page table
208walks.
209
210On a context switch, all modified MMU entries will be restored.  On thread
211resume, additional accesses will be treated as initial accesses.
212
213
214Interface
215=========
216
217The emulation does not have clients.  It is hooked to the kernel through a
218small list of functions.
219
220void emulate_domain_manager_set(u32 domain);
221int emulate_domain_manager_data_abort(u32 dfsr, u32 dfar);
222int emulate_domain_manager_prefetch_abort(u32 ifsr, u32 ifar);
223void emulate_domain_manager_switch_mm(
224	unsigned long pgd_phys,
225	struct mm_struct *mm,
226	void (*switch_mm)(unsigned long pgd_phys, struct mm_struct *));
227
228emulate_domain_manager_set() is the set_domain handler.  This replaces the
229direct manipulation of CP15 dacr with a function call.  This allows emulation
230to prevent setting dacr manager bits.  It also allows emulation to restore
231page/section permissions when domain manger is disabled.
232
233emulate_domain_manager_data_abort() handles data aborts caused by domain
234not being set in HW, and handles section/page manipulation.
235
236emulate_domain_manager_prefetch_abort() is the similar prefetch abort handler.
237
238emulate_domain_manager_switch_mm() handles MMU table and context switches.
239This notifies the emulation that the MMU context is changing.  Allowing the
240emulation to restore page table entry permission before switching contexts.
241
242
243Config options
244==============
245
246This option is enable/disable by the EMULATE_DOMAIN_MANAGER_V7 option.
247
248
249Dependencies
250============
251
252Implementation is for ARMv7, MMU, and !SMP.  Targets solving issue for 8x50
253chipset.
254
255
256User space utilities
257====================
258
259None
260
261
262Other
263=====
264
265Code is implemented in kernel/arch/arm/mm.
266
267
268arch/arm/mm/emulate_domain_manager.c contains comments.  No additional public
269documentation available or planned.
270
271
272Known issues
273============
274
275No intent to support SMP or non ARMv7 architectures
276
277
278To do
279=====
280
281None
282