From b4a3d0824bfdd4e25dd2983e45c6e4a7506fd9bc Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Thu, 13 Oct 2016 15:06:14 +0100 Subject: [PATCH] Rename the "protection mutator context" module to "mutator context" (this module handles mutator context decoding for both the protection module and the thread module). Rename functions Prot{Can,}StepInstruction to MutatorContext{Can,}StepInstruction so that they follow the naming convention in guide.implc.naming.prefix.program. Move mutator context declarations out of prot.h into new header prmc.h. Correct .assume.null in a couple of places -- it's not safe for MutatorContextStepInstruction to return ResUNIMPL, instead MutatorContextCanStepInstruction should return FALSE. Copied from Perforce Change: 192528 ServerID: perforce.ravenbrook.com --- mps/code/mpm.h | 1 + mps/code/mps.c | 2 +- mps/code/poolabs.c | 4 +- mps/code/prmc.h | 68 +++++++++++++++++++++++++++++ mps/code/prmcan.c | 16 +++---- mps/code/prmcfri3.c | 5 +-- mps/code/prmcfri6.c | 5 +-- mps/code/prmci3.c | 17 ++++---- mps/code/prmci3.h | 2 +- mps/code/prmci6.c | 17 ++++---- mps/code/prmci6.h | 2 +- mps/code/prmcix.h | 2 +- mps/code/prmclii3.c | 5 +-- mps/code/prmclii6.c | 5 +-- mps/code/prmcw3i3.c | 5 +-- mps/code/prmcw3i6.c | 5 +-- mps/code/prmcxc.h | 2 +- mps/code/prmcxci3.c | 5 +-- mps/code/prmcxci6.c | 5 +-- mps/code/prot.h | 9 ---- mps/code/pthrdext.c | 2 - mps/code/thix.c | 2 +- mps/code/thxc.c | 2 +- mps/design/an.txt | 6 +-- mps/design/exec-env.txt | 8 ++-- mps/design/index.txt | 2 +- mps/design/prmc.txt | 37 ++++++++-------- mps/design/prot.txt | 4 +- mps/manual/source/code-index.rst | 1 + mps/manual/source/topic/porting.rst | 12 ++--- 30 files changed, 151 insertions(+), 107 deletions(-) create mode 100644 mps/code/prmc.h diff --git a/mps/code/mpm.h b/mps/code/mpm.h index 5153d381a1c..5ce72628faa 100644 --- a/mps/code/mpm.h +++ b/mps/code/mpm.h @@ -18,6 +18,7 @@ #include "event.h" #include "lock.h" +#include "prmc.h" #include "prot.h" #include "sp.h" #include "th.h" diff --git a/mps/code/mps.c b/mps/code/mps.c index a6d1876c80f..1631f8fc781 100644 --- a/mps/code/mps.c +++ b/mps/code/mps.c @@ -106,7 +106,7 @@ #include "than.c" /* generic threads manager */ #include "vman.c" /* malloc-based pseudo memory mapping */ #include "protan.c" /* generic memory protection */ -#include "prmcan.c" /* generic protection mutator context */ +#include "prmcan.c" /* generic mutator context */ #include "span.c" /* generic stack probe */ #include "ssan.c" /* generic stack scanner */ diff --git a/mps/code/poolabs.c b/mps/code/poolabs.c index 0efc8a36a61..703937ef58a 100644 --- a/mps/code/poolabs.c +++ b/mps/code/poolabs.c @@ -494,7 +494,7 @@ Res PoolSingleAccess(Pool pool, Seg seg, Addr addr, arena = PoolArena(pool); - if(ProtCanStepInstruction(context)) { + if (MutatorContextCanStepInstruction(context)) { Ref ref; Res res; @@ -517,7 +517,7 @@ Res PoolSingleAccess(Pool pool, Seg seg, Addr addr, seg, (Ref *)addr); } } - res = ProtStepInstruction(context); + res = MutatorContextStepInstruction(context); AVER(res == ResOK); /* Update SegSummary according to the possibly changed reference. */ diff --git a/mps/code/prmc.h b/mps/code/prmc.h new file mode 100644 index 00000000000..22247154493 --- /dev/null +++ b/mps/code/prmc.h @@ -0,0 +1,68 @@ +/* prmc.h: MUTATOR CONTEXT INTERFACE + * + * $Id$ + * Copyright (c) 2016 Ravenbrook Limited. See end of file for license. + * + * See for the design of the generic interface including + * the contracts for these functions. + * + * This interface has several different implementations, typically one + * per platform, see for the various implementations. + */ + +#ifndef prmc_h +#define prmc_h + +#include "mpmtypes.h" + + +extern Bool MutatorContextCanStepInstruction(MutatorContext context); +extern Res MutatorContextStepInstruction(MutatorContext context); +extern Addr MutatorContextSP(MutatorContext context); +extern Res MutatorContextScan(ScanState ss, MutatorContext context, + mps_area_scan_t scan, void *closure); + + +#endif /* prmc_h */ + + +/* C. COPYRIGHT AND LICENSE + * + * Copyright (C) 2016 Ravenbrook Limited . + * All rights reserved. This is an open source license. Contact + * Ravenbrook for commercial licensing options. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are + * met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * 3. Redistributions in any form must be accompanied by information on how + * to obtain complete source code for this software and any accompanying + * software that uses this software. The source code must either be + * included in the distribution or be available for no more than the cost + * of distribution plus a nominal fee, and must be freely redistributable + * under reasonable conditions. For an executable file, complete source + * code means the source code for all modules it contains. It does not + * include source code for modules or files that typically accompany the + * major components of the operating system on which the executable file + * runs. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS + * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED + * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR + * PURPOSE, OR NON-INFRINGEMENT, ARE DISCLAIMED. IN NO EVENT SHALL THE + * COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON + * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ diff --git a/mps/code/prmcan.c b/mps/code/prmcan.c index bef53ad272e..7ff88abab40 100644 --- a/mps/code/prmcan.c +++ b/mps/code/prmcan.c @@ -1,4 +1,4 @@ -/* prmcan.c: PROTECTION MUTATOR CONTEXT (ANSI) +/* prmcan.c: MUTATOR CONTEXT (ANSI) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. @@ -7,9 +7,9 @@ * which is implemented in this module including the contracts for the * functions. * - * .purpose: This module implements the part of the protection module - * that implements the MutatorContext type. In this ANSI version - * none of the functions have a useful implementation. + * .purpose: Implement the mutator context module. See . + * In this ANSI version none of the functions have a useful + * implementation. */ #include "mpm.h" @@ -17,9 +17,7 @@ SRCID(prmcan, "$Id$"); -/* ProtCanStepInstruction -- can the current instruction be single-stepped */ - -Bool ProtCanStepInstruction(MutatorContext context) +Bool MutatorContextCanStepInstruction(MutatorContext context) { UNUSED(context); @@ -27,9 +25,7 @@ Bool ProtCanStepInstruction(MutatorContext context) } -/* ProtStepInstruction -- step over instruction by modifying context */ - -Res ProtStepInstruction(MutatorContext context) +Res MutatorContextStepInstruction(MutatorContext context) { UNUSED(context); diff --git a/mps/code/prmcfri3.c b/mps/code/prmcfri3.c index 73aeb4527b6..aeda5f8015f 100644 --- a/mps/code/prmcfri3.c +++ b/mps/code/prmcfri3.c @@ -1,10 +1,9 @@ -/* prmcfri3.c: PROTECTION MUTATOR CONTEXT INTEL 386 (FREEBSD) +/* prmcfri3.c: MUTATOR CONTEXT INTEL 386 (FREEBSD) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. * - * .purpose: This module implements the part of the protection module - * that decodes the MutatorContext. + * .purpose: Implement the mutator context module. See . * * * SOURCES diff --git a/mps/code/prmcfri6.c b/mps/code/prmcfri6.c index 6dee3c232b9..1631c9366af 100644 --- a/mps/code/prmcfri6.c +++ b/mps/code/prmcfri6.c @@ -1,10 +1,9 @@ -/* prmcfri6.c: PROTECTION MUTATOR CONTEXT x64 (FREEBSD) +/* prmcfri6.c: MUTATOR CONTEXT x64 (FREEBSD) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. * - * .purpose: This module implements the part of the protection module - * that decodes the MutatorContext. + * .purpose: Implement the mutator context module. See . * * * ASSUMPTIONS diff --git a/mps/code/prmci3.c b/mps/code/prmci3.c index d82e10f9fb9..26a6b139516 100644 --- a/mps/code/prmci3.c +++ b/mps/code/prmci3.c @@ -1,14 +1,13 @@ -/* prmci3.c: PROTECTION MUTATOR CONTEXT (INTEL 386) +/* prmci3.c: MUTATOR CONTEXT (INTEL 386) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. * - * .design: See for the generic design of the interface + * .design: See for the generic design of the interface * which is implemented in this module, including the contracts for the * functions. * - * .purpose: This module implements the part of the protection module - * that implements the MutatorContext type. + * .purpose: Implement the mutator context module. See . * * .requirements: Current requirements are for limited support only, for * stepping the sorts of instructions that the Dylan compiler might @@ -31,9 +30,9 @@ * * ASSUMPTIONS * - * .assume.null: It's always safe for Prot*StepInstruction to return - * ResUNIMPL. A null implementation of this module would be overly - * conservative but otherwise correct. + * .assume.null: It's always safe for MutatorContextCanStepInstruction + * to return FALSE. A null implementation of this module would be + * overly conservative but otherwise correct. * * .assume.want: The Dylan implementation is likely to access a * weak table vector using either MOV r/m32,r32 or MOV r32,r/m32 @@ -211,7 +210,7 @@ static Bool IsSimpleMov(Size *inslenReturn, } -Bool ProtCanStepInstruction(MutatorContext context) +Bool MutatorContextCanStepInstruction(MutatorContext context) { Size inslen; MRef src; @@ -227,7 +226,7 @@ Bool ProtCanStepInstruction(MutatorContext context) } -Res ProtStepInstruction(MutatorContext context) +Res MutatorContextStepInstruction(MutatorContext context) { Size inslen; MRef src; diff --git a/mps/code/prmci3.h b/mps/code/prmci3.h index 78d5826374e..23f36303a0f 100644 --- a/mps/code/prmci3.h +++ b/mps/code/prmci3.h @@ -1,4 +1,4 @@ -/* prmci3.h: PROTECTION MUTATOR CONTEXT (Intel 386) +/* prmci3.h: MUTATOR CONTEXT (Intel 386) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. diff --git a/mps/code/prmci6.c b/mps/code/prmci6.c index 115e05c576a..7b98b44fc47 100644 --- a/mps/code/prmci6.c +++ b/mps/code/prmci6.c @@ -1,14 +1,13 @@ -/* prmci6.c: PROTECTION MUTATOR CONTEXT (x64) +/* prmci6.c: MUTATOR CONTEXT (x64) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. * - * .design: See for the generic design of the interface + * .design: See for the generic design of the interface * which is implemented in this module, including the contracts for the * functions. * - * .purpose: This module implements the part of the protection module - * that implements the MutatorContext type. + * .purpose: Implement the mutator context module. See . * * * SOURCES @@ -20,9 +19,9 @@ * * ASSUMPTIONS * - * .assume.null: It's always safe for Prot*StepInstruction to return - * ResUNIMPL. A null implementation of this module would be overly - * conservative but otherwise correct. + * .assume.null: It's always safe for MutatorContextCanStepInstruction + * to return FALSE. A null implementation of this module would be + * overly conservative but otherwise correct. * */ @@ -54,7 +53,7 @@ static Bool IsSimpleMov(Size *inslenReturn, } -Bool ProtCanStepInstruction(MutatorContext context) +Bool MutatorContextCanStepInstruction(MutatorContext context) { Size inslen; MRef src; @@ -69,7 +68,7 @@ Bool ProtCanStepInstruction(MutatorContext context) } -Res ProtStepInstruction(MutatorContext context) +Res MutatorContextStepInstruction(MutatorContext context) { Size inslen; MRef src; diff --git a/mps/code/prmci6.h b/mps/code/prmci6.h index a33395f182d..516661592d2 100644 --- a/mps/code/prmci6.h +++ b/mps/code/prmci6.h @@ -1,4 +1,4 @@ -/* prmci6.h: PROTECTION MUTATOR CONTEXT (x64) +/* prmci6.h: MUTATOR CONTEXT (x64) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. diff --git a/mps/code/prmcix.h b/mps/code/prmcix.h index 00975f17fd1..0ac22e2e5d4 100644 --- a/mps/code/prmcix.h +++ b/mps/code/prmcix.h @@ -1,4 +1,4 @@ -/* prmcix.h: PROTECTION MUTATOR CONTEXT (UNIX) +/* prmcix.h: MUTATOR CONTEXT (UNIX) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. diff --git a/mps/code/prmclii3.c b/mps/code/prmclii3.c index 5ad655e53ce..c47d4fee0f0 100644 --- a/mps/code/prmclii3.c +++ b/mps/code/prmclii3.c @@ -1,10 +1,9 @@ -/* prmclii3.c: PROTECTION MUTATOR CONTEXT INTEL 386 (LINUX) +/* prmclii3.c: MUTATOR CONTEXT INTEL 386 (LINUX) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. * - * .purpose: This module implements the part of the protection module - * that decodes the MutatorContext. + * .purpose: Implement the mutator context module. See . * * * SOURCES diff --git a/mps/code/prmclii6.c b/mps/code/prmclii6.c index 0d98a135220..be2cfe0e3be 100644 --- a/mps/code/prmclii6.c +++ b/mps/code/prmclii6.c @@ -1,10 +1,9 @@ -/* prmclii6.c: PROTECTION MUTATOR CONTEXT x64 (LINUX) +/* prmclii6.c: MUTATOR CONTEXT x64 (LINUX) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. * - * .purpose: This module implements the part of the protection module - * that decodes the MutatorContext. + * .purpose: Implement the mutator context module. See . * * * SOURCES diff --git a/mps/code/prmcw3i3.c b/mps/code/prmcw3i3.c index 16b0047f23b..1a53ae4139d 100644 --- a/mps/code/prmcw3i3.c +++ b/mps/code/prmcw3i3.c @@ -1,12 +1,11 @@ -/* prmcw3i3.c: PROTECTION MUTATOR CONTEXT INTEL 386 (Windows) +/* prmcw3i3.c: MUTATOR CONTEXT INTEL 386 (Windows) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. * * PURPOSE * - * .purpose: This module implements the part of the protection module - * that decodes the MutatorContext. + * .purpose: Implement the mutator context module. See . * * SOURCES * diff --git a/mps/code/prmcw3i6.c b/mps/code/prmcw3i6.c index 493e4f19a3a..18f1e728454 100644 --- a/mps/code/prmcw3i6.c +++ b/mps/code/prmcw3i6.c @@ -1,12 +1,11 @@ -/* prmcw3i6.c: PROTECTION MUTATOR CONTEXT INTEL x64 (Windows) +/* prmcw3i6.c: MUTATOR CONTEXT INTEL x64 (Windows) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. * * PURPOSE * - * .purpose: This module implements the part of the protection module - * that decodes the MutatorContext. + * .purpose: Implement the mutator context module. See . * * SOURCES * diff --git a/mps/code/prmcxc.h b/mps/code/prmcxc.h index 4818749c42f..af145a6e603 100644 --- a/mps/code/prmcxc.h +++ b/mps/code/prmcxc.h @@ -1,4 +1,4 @@ -/* prmcxc.h: PROTECTION MUTATOR CONTEXT FOR OS X MACH +/* prmcxc.h: MUTATOR CONTEXT FOR OS X MACH * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. diff --git a/mps/code/prmcxci3.c b/mps/code/prmcxci3.c index 93729ac8fc6..03fe3d836f0 100644 --- a/mps/code/prmcxci3.c +++ b/mps/code/prmcxci3.c @@ -1,10 +1,9 @@ -/* prmcxci3.c: PROTECTION MUTATOR CONTEXT INTEL 386 (MAC OS X) +/* prmcxci3.c: MUTATOR CONTEXT INTEL 386 (MAC OS X) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. * - * .purpose: This module implements the part of the protection module - * that decodes the MutatorContext. + * .purpose: Implement the mutator context module. See . * * * SOURCES diff --git a/mps/code/prmcxci6.c b/mps/code/prmcxci6.c index e27b13d77a7..269deb4b275 100644 --- a/mps/code/prmcxci6.c +++ b/mps/code/prmcxci6.c @@ -1,10 +1,9 @@ -/* prmcxci6.c: PROTECTION MUTATOR CONTEXT x64 (OS X) +/* prmcxci6.c: MUTATOR CONTEXT x64 (OS X) * * $Id$ * Copyright (c) 2001-2016 Ravenbrook Limited. See end of file for license. * - * .purpose: This module implements the part of the protection module - * that decodes the MutatorContext. + * .purpose: Implement the mutator context module. See . * * * SOURCES diff --git a/mps/code/prot.h b/mps/code/prot.h index 2664ae48b92..4a6f6a23aa2 100644 --- a/mps/code/prot.h +++ b/mps/code/prot.h @@ -25,15 +25,6 @@ extern void ProtSet(Addr base, Addr limit, AccessSet mode); extern void ProtSync(Arena arena); -/* Mutator Fault Context */ - -extern Bool ProtCanStepInstruction(MutatorContext context); -extern Res ProtStepInstruction(MutatorContext context); -extern Addr MutatorContextSP(MutatorContext context); -extern Res MutatorContextScan(ScanState ss, MutatorContext context, - mps_area_scan_t scan, void *closure); - - #endif /* prot_h */ diff --git a/mps/code/pthrdext.c b/mps/code/pthrdext.c index 8b1c3c9ebcf..1d4851878e3 100644 --- a/mps/code/pthrdext.c +++ b/mps/code/pthrdext.c @@ -55,8 +55,6 @@ static RingStruct suspendedRing; /* PThreadext suspend ring */ * * See * - * The interface for determining the MFC might be platform specific. - * * Handle PTHREADEXT_SIGSUSPEND in the target thread, to suspend it until * receiving PTHREADEXT_SIGRESUME (resume). Note that this is run with both * PTHREADEXT_SIGSUSPEND and PTHREADEXT_SIGRESUME blocked. Having diff --git a/mps/code/thix.c b/mps/code/thix.c index 8d03779c024..a5207f0f8db 100644 --- a/mps/code/thix.c +++ b/mps/code/thix.c @@ -276,7 +276,7 @@ Res ThreadScan(ScanState ss, Thread thread, Word *stackCold, if(res != ResOK) return res; - /* scan the registers in the mutator fault context */ + /* scan the registers in the mutator context */ res = MutatorContextScan(ss, context, scan_area, closure); if(res != ResOK) return res; diff --git a/mps/code/thxc.c b/mps/code/thxc.c index 7d4ce2bcb1d..bcac8296b50 100644 --- a/mps/code/thxc.c +++ b/mps/code/thxc.c @@ -263,7 +263,7 @@ Res ThreadScan(ScanState ss, Thread thread, Word *stackCold, if(res != ResOK) return res; - /* scan the registers in the mutator fault context */ + /* scan the registers in the mutator context */ res = MutatorContextScan(ss, &context, scan_area, closure); if(res != ResOK) return res; diff --git a/mps/design/an.txt b/mps/design/an.txt index 78ecccfeafb..a6cbdf6d364 100644 --- a/mps/design/an.txt +++ b/mps/design/an.txt @@ -100,7 +100,7 @@ _`.mod`: This section lists the functional modules in the MPS. _`.mod.lock`: Locks. See design.mps.lock_. -_`.mod.prmc`: Protection mutator context. See design.mps.prmc_. +_`.mod.prmc`: Mutator context. See design.mps.prmc_. _`.mod.prot`: Memory protection. See design.mps.prot_. @@ -136,7 +136,7 @@ design.mps.prmc.impl.an.fault_) and requires a single-threaded mutator _`.lim.prot`: Does not support incremental collection (see design.mps.prot.impl.an.sync_) and is not compatible with -implementations of the protection mutator context module that support +implementations of the mutator context module that support single-stepping of accesses (see design.mps.prot.impl.an.sync.issue_). _`.lim.sp`: Only suitable for use with programs that do not handle @@ -176,7 +176,7 @@ Document History Copyright and License --------------------- -Copyright © 2014 Ravenbrook Limited . +Copyright © 2014-2016 Ravenbrook Limited . All rights reserved. This is an open source license. Contact Ravenbrook for commercial licensing options. diff --git a/mps/design/exec-env.txt b/mps/design/exec-env.txt index 71d7287f057..4dac219a8cb 100644 --- a/mps/design/exec-env.txt +++ b/mps/design/exec-env.txt @@ -112,10 +112,10 @@ The core must be freestanding. _`.arch.platform`: The *platform* provides the core with interfaces to features of the operating system and processor (locks, memory -protection, protection mutator context, stack probing, stack and -register scanning, thread management, and virtual memory). The -platform is specialized to a particular environment and so can safely -use whatever features are available in that environment. +protection, mutator context, stack probing, stack and register +scanning, thread management, and virtual memory). The platform is +specialized to a particular environment and so can safely use whatever +features are available in that environment. _`.arch.plinth`: The *plinth* provides the core with interfaces to features of the user environment (time, assertions, and logging). See diff --git a/mps/design/index.txt b/mps/design/index.txt index decfb0fe66d..66530dc7a63 100644 --- a/mps/design/index.txt +++ b/mps/design/index.txt @@ -85,7 +85,7 @@ poolmrg_ Manual Rank Guardian pool class poolmv_ Manual Variable pool class poolmvt_ Manual Variable Temporal pool class poolmvff_ Manual Variable First-Fit pool class -prmc_ Protection mutator context +prmc_ Mutator context prot_ Memory protection protli_ Linux implementation of protection module protocol_ Protocol inheritance diff --git a/mps/design/prmc.txt b/mps/design/prmc.txt index 34632964369..d16bd3faaa5 100644 --- a/mps/design/prmc.txt +++ b/mps/design/prmc.txt @@ -1,7 +1,7 @@ .. mode: -*- rst -*- -Protection mutator context -========================== +Mutator context +=============== :Tag: design.mps.prmc :Author: Gareth Rees @@ -9,31 +9,30 @@ Protection mutator context :Status: complete design :Revision: $Id$ :Copyright: See `Copyright and License`_. -:Index terms: pair: protection mutator context; design +:Index terms: pair: mutator context; design Introduction ------------ -_`.intro`: This is the design of the protection mutator context -module. +_`.intro`: This is the design of the mutator context module. _`.readership`: Any MPS developer; anyone porting the MPS to a new platform. -_`.overview`: The protection mutator context module decodes the -*context* of a mutator thread at the point when it caused a protection -fault, so that access to a protected region of memory can be handled, -or when it was suspended by the thread manager, so that its registers -and control stack can be scanned. +_`.overview`: The mutator context module decodes the *context* of a +mutator thread at the point when it caused a protection fault, so that +access to a protected region of memory can be handled, or when it was +suspended by the thread manager, so that its registers and control +stack can be scanned. _`.def.context`: The *context* of a thread (also called its *continuation*) is an abstract representation of the control state of the thread at a point in time, including enough information to continue the thread from that point. -_`.status`: The protection mutator context module does not currently -present a clean interface to the rest of the MPS: source files are +_`.status`: The mutator context module does not currently present a +clean interface to the rest of the MPS: source files are inconsistently named, and the implementation is (necessarily) mixed up with the implementation of the memory protection module (design.mps.prot_) and the thread manager @@ -64,7 +63,7 @@ weak hash tables. See request.dylan.160044_.) .. _request.dylan.160044: https://info.ravenbrook.com/project/mps/import/2001-11-05/mmprevol/request/dylan/160044/ -_`.req.suspend.scan`: Must capature enough information to ambiguously +_`.req.suspend.scan`: Must capture enough information to ambiguously scan all roots in the context of a thread that has been suspended by the thread manager. (This is necessary for conservative garbage collection to work. See design.mps.thread-manager.if.scan_.) @@ -85,14 +84,14 @@ See design.mps.thread-manager.if.thread_. .. _design.mps.thread-manager.if.thread: thread-manager#if.thread -``Bool ProtCanStepInstruction(MutatorContext context)`` +``Bool MutatorContextCanStepInstruction(MutatorContext context)`` _`.if.canstep`: Examine the context to determine whether the protection module can single-step the instruction which is causing the -fault. Return ``TRUE`` if ``ProtStepInstruction()`` is capable of -single-stepping the instruction, or ``FALSE`` if not. +fault. Return ``TRUE`` if ``MutatorContextStepInstruction()`` is +capable of single-stepping the instruction, or ``FALSE`` if not. -``Bool Res ProtStepInstruction(MutatorContext context)`` +``Bool Res MutatorContextStepInstruction(MutatorContext context)`` _`.if.step`: Single-step the instruction which is causing the fault. Update the mutator context according to the emulation or execution of @@ -101,8 +100,8 @@ instruction which was caused the fault to be re-executed. Return ``ResOK`` if the instruction was single-stepped successfully, or ``ResUNIMPL`` if the instruction cannot be single-stepped. -This function is only called if ``ProtCanStepInstruction(context)`` -returned ``TRUE``. +This function is only called if +``MutatorContextCanStepInstruction(context)`` returned ``TRUE``. ``Res MutatorContextScan(ScanState ss, MutatorContext context, mps_area_scan_t scan, void *closure)`` diff --git a/mps/design/prot.txt b/mps/design/prot.txt index a3ff8e35a38..2190eb1c3c4 100644 --- a/mps/design/prot.txt +++ b/mps/design/prot.txt @@ -153,8 +153,8 @@ Document History - 2013-05-23 GDR_ Converted to reStructuredText. -- 2014-10-23 GDR_ Move protection mutator context interface to - design.mps.prmc_. Bring design up to date. +- 2014-10-23 GDR_ Move mutator context interface to design.mps.prmc_. + Bring design up to date. .. _design.mps.prmc: prmc diff --git a/mps/manual/source/code-index.rst b/mps/manual/source/code-index.rst index 7e85c4c0237..a14aabeb59e 100644 --- a/mps/manual/source/code-index.rst +++ b/mps/manual/source/code-index.rst @@ -163,6 +163,7 @@ lock.h Lock interface. See design.mps.lock_. lockan.c Lock implementation for standard C. lockix.c Lock implementation for POSIX. lockw3.c Lock implementation for Windows. +prmc.h Mutator context interface. See design.mps.prmc_. prmcan.c Mutator context implementation for standard C. prmcfri3.c Mutator context implementation for FreeBSD, IA-32. prmcfri6.c Mutator context implementation for FreeBSD, x86-64. diff --git a/mps/manual/source/topic/porting.rst b/mps/manual/source/topic/porting.rst index c61d710374d..bfe3c1adef3 100644 --- a/mps/manual/source/topic/porting.rst +++ b/mps/manual/source/topic/porting.rst @@ -69,13 +69,13 @@ usable. there is no further need to protect it. This means it can't support incremental collection, and has no control over pause times. -#. The **protection mutator context** module figures out what the - :term:`mutator` was doing when it caused a :term:`protection - fault`, so that access to a protected region of memory can be - handled, or when a thread was suspended, so that its - :term:`registers` and :term:`control stack` can be scanned. +#. The **mutator context** module figures out what the :term:`mutator` + was doing when it caused a :term:`protection fault`, so that access + to a protected region of memory can be handled, or when a thread + was suspended, so that its :term:`registers` and :term:`control + stack` can be scanned. - See :ref:`design-prmc` for the design, and ``prot.h`` for the + See :ref:`design-prmc` for the design, and ``prmc.h`` for the interface. There are implementations on Unix, Windows, and OS X for IA-32 and x86-64.