diff --git a/mps/code/arena.c b/mps/code/arena.c
index 2d460e06c35..519a85d735b 100644
--- a/mps/code/arena.c
+++ b/mps/code/arena.c
@@ -758,7 +758,7 @@ void ArenaChunkRemoved(Arena arena, Chunk chunk)
* This is a primitive allocator used to allocate pages for the arena
* Land. It is called rarely and can use a simple search. It may not
* use the Land or any pool, because it is used as part of the
- * bootstrap.
+ * bootstrap. See design.mps.bootstrap.land.sol.alloc.
*/
static Res arenaAllocPageInChunk(Addr *baseReturn, Chunk chunk, Pool pool)
@@ -866,7 +866,7 @@ static void arenaExcludePage(Arena arena, Range pageRange)
* The arena's free land can't get memory for its block pool in the
* usual way (via ArenaAlloc), because it is the mechanism behind
* ArenaAlloc! So we extend the block pool via a back door (see
- * arenaExtendCBSBlockPool).
+ * arenaExtendCBSBlockPool). See design.mps.bootstrap.land.sol.pool.
*
* Only fails if it can't get a page for the block pool.
*/
diff --git a/mps/code/poolmfs.c b/mps/code/poolmfs.c
index ed1c0343aba..90232621c25 100644
--- a/mps/code/poolmfs.c
+++ b/mps/code/poolmfs.c
@@ -249,7 +249,8 @@ static Res MFSAlloc(Addr *pReturn, Pool pool, Size size,
if(f == NULL)
{
Addr base;
-
+
+ /* See design.mps.bootstrap.land.sol.pool. */
if (!mfs->extendSelf)
return ResLIMIT;
diff --git a/mps/design/bootstrap.txt b/mps/design/bootstrap.txt
index 7eb79df1475..8615aee0f99 100644
--- a/mps/design/bootstrap.txt
+++ b/mps/design/bootstrap.txt
@@ -67,13 +67,23 @@ Arena's free land
_`.land`: Before the arena can allocate memory, a range of addresses
must be inserted into the arena's free land (so that the free land can
hand out memory from this range). But before addresses can be inserted
-into the arena's free land, the arena must be able to allocate memory
-(to store the nodes in the tree representing those addresses).
+into the arena's free land, the free land's block pool must have
+memory from the arena to store the nodes in the tree representing
+those addresses.
_`.land.sol`: The arena has two "back door" mechanisms and uses them
-in combination. First, there is a mechanism for allocating a block of
-memory directly from a chunk, bypassing the free land; second, the MFS
-pool class has a mechanism for extending it with a block of memory.
+in combination.
+
+_`.land.sol.alloc`: First, there is a mechanism for allocating a
+page of memory directly from a chunk, bypassing the free land.
+
+_`.land.sol.pool`: Second, the free land's block pool has an option to
+prevent it extending itself by allocating memory from the arena.
+Instead, it fails allocations with ``ResLIMIT``. The free land's
+block pool also has a mechanism, ``MFSExtend`` to extend it with a
+block of memory. When the free land fails with ``ResLIMIT`` the arena
+uses `.land.sol.alloc`_ to provide it with memory.
+
Document History
@@ -81,15 +91,19 @@ Document History
- 2015-09-01 GDR_ Initial draft.
+- 2016-02-25 RB_ Improving description of arena free land bootstrap
+ and cross-referencing from source code.
+
.. _GDR: http://www.ravenbrook.com/consultants/gdr/
+.. _RB: http://www.ravenbrook.com/consultants/rb/
Copyright and License
---------------------
-Copyright © 2015 Ravenbrook Limited. All rights reserved.
-. This is an open source license. Contact
-Ravenbrook for commercial licensing options.
+Copyright © 2015-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