--- a/persistentstorage/store/USTOR/UT_COLL.CPP	Thu May 27 14:29:47 2010 +0300
+++ b/persistentstorage/store/USTOR/UT_COLL.CPP	Fri Jun 11 15:29:22 2010 +0300
@@ -905,15 +905,41 @@
 	}
 
 void CPermanentStoreCollector::RelocateStreamL(const CPermanentStoreCollector::TEntry& aReloc, TInt aExtent)
-//
-// relocate a stream into [iFree, aExtent)
-//
+/* relocate a stream into [iFree, aExtent)
+
+During compaction the sequence of operations is:
+
+1.  Copy stream S1 content from position A1 to position B1 . The copy never overlaps so the old stream content is still good at this point.
+2.  Optionally rewrite the file header to state that stream S1 is being relocated to B1 (more about the ‘optional below’)
+3.  Overwrite the TOC entry for S1 to state that the content is now at B1
+4.  Carry on with stream S2
+5.  … etc
+
+
+First consider the impact of a mid-write failure in any of these steps (when write caching is disabled):
+1.  If step #1 only partially completes the file is good as the original content is intact and the new content was being written to otherwise free space
+2.  If step #2 only partially completes the header CRC fails and only the TOC reference is considered valid (so the corrupt stream relocation record is ignored). The TOC will be good because it is being overwritten with the same content.
+3.  If step #3 only partially completes the entry for S1 in the TOC is corrupt, BUT the relocation record for S1 in the file header is good and will override the entry in the TOC.
+
+In all cases the file is never broken by a crash in mid-compaction.
+
+Step #2 is optional – there are many cases when step #3 cannot fail ‘halfway through’ because the underlying media makes atomic block/page based updates and the write does not cross any block boundaries. In STORE we assume that blocks cannot be smaller than 512 bytes and any flash based media provides the required behavior. Thus 99% of the step #2 writes are eliminated.
+
+Note that sequencing MATTERS even for just one stream. If the TOC update hits the disk before the content is moved, and then the device fails we will have a broken file: S1 points to B1 which contains garbage.  Equally in the case where step #2 is required (i.e. when step #3 straddles a block boundary and could fail) step 2 has to go before the step 3. Otherwise write #3 could go to disk and fail part way through before write #2 and leave the TOC corrupt with no recovery in the file header.
+
+Consider the case that step 2 was omitted, so the Store relies on step 3 being completed in order to know that S1 is in location B1; and that no flush is done after step 3. In step 4 the stream S2 is moved – at this point the old space for stream S1 at A1 is considered empty – and suppose it gets moved from A2 to B2 where B2 overlaps/overwrites A1. If the writes in step 3 and step 4 are re-ordered and the step 3 write does not happen – then the TOC will claim that S1 is still at A1 but this location in the file has been overwritten with data from S2. A corrupted file.
+
+Based on the knowledge above, it is strongly recommended to set EFileWriteDirectIO bit when opening the file so that the order is maintained when writing to the file.
+
+*/
 	{
 	if (Coord().Accessed())	// must have exclusive access to relocate the stream
 		__LEAVE(KErrInUse);
 //
 	TInt end=RelocateL(aReloc.entry.ref,aReloc.len,aReloc.entry.handle == KHandleTocBase ? EFrameDescriptive16 : EFrameData16, aExtent);
+	//Step 1, 4,....
 	Coord().RelocateL(aReloc.entry.handle, iFree);
+	// Step 2 & 3, 5 & 6,...
 	iCoordGen=Coord().Generation();	// changed by relocation
 	iFree = end;
 	}