a little more lock documentation

Author: Robert Morris

fs.c

@@ -154,6 +154,15 @@ bfree(int dev, uint b)
 // Many internal file system functions expect the caller to
 // have locked the inodes involved; this lets callers create
 // multi-step atomic operations.
+//
+// The icache.lock spin-lock defends ip->ref, ip->dev, and ip->inum.
+// Since ip->ref indicates whether an icache entry is free, the
+// icache.lock defends icache allocation. icache.lock also defends
+// all fields of an unallocated icache entry, during allocation.
+//
+// An ip->lock sleep-lock defends all ip-> fields other than ref,
+// dev, and inum.  One must hold ip->lock in order to
+// read or write that inode's ip->valid, ip->size, ip->type, &c.
 
 struct {
   struct spinlock lock;
@@ -205,6 +214,7 @@ ialloc(uint dev, short type)
 }
 
 // Copy a modified in-memory inode to disk.
+// Caller must hold ip->lock.
 void
 iupdate(struct inode *ip)
 {
@@ -421,6 +431,7 @@ itrunc(struct inode *ip)
 }
 
 // Copy stat information from inode.
+// Caller must hold ip->lock.
 void
 stati(struct inode *ip, struct stat *st)
 {
@@ -433,6 +444,7 @@ stati(struct inode *ip, struct stat *st)
 
 //PAGEBREAK!
 // Read data from inode.
+// Caller must hold ip->lock.
 int
 readi(struct inode *ip, char *dst, uint off, uint n)
 {
@@ -461,6 +473,7 @@ readi(struct inode *ip, char *dst, uint off, uint n)
 
 // PAGEBREAK!
 // Write data to inode.
+// Caller must hold ip->lock.
 int
 writei(struct inode *ip, char *src, uint off, uint n)
 {