doc: Clarified text and added reference back to main RBD pages. Added sidebar.

Signed-off-by: John Wilkins <john.wilkins@inktank.com>

diff --git a/doc/config-cluster/rbd-config-ref.rst b/doc/config-cluster/rbd-config-ref.rst
index 409cffbc66f193c38b7677449ebaa5b61db2f807..dde3dedf257a3bdb2be3c2fb28b89d2c270a60b1 100644 (file)
--- a/doc/config-cluster/rbd-config-ref.rst
+++ b/doc/config-cluster/rbd-config-ref.rst
@@ -1,19 +1,23 @@
-===========================
- RBD Cache Config Settings
-===========================
+=======================
+ librbd Cache Settings
+=======================
 
-With the kernel rbd driver, the Linux page cache can be used to
-improve performance. The userspace implementation, librbd, cannot take
-advantage of the page cache, so it includes its own in-memory caching,
-called RBD caching.
+See `Block Device`_ for additional details.
 
-RBD caching behaves just like well-behaved hard disk caching.  When the OS sends
-a barrier or a flush request, all dirty data is written to the OSDs. This means
-that using write-back caching is just as safe as using a well-behaved physical
-hard disk with a VM that properly sends flushes (i.e. Linux kernel >= 2.6.32).
+.. sidebar:: Kernel Caching
 
-The cache is LRU, and in write-back mode it can coalesce contiguous
-requests for better throughput.
+       The kernel driver for Ceph block devices can use the Linux page cache to 
+       improve performance.
+
+The user space implementation of the Ceph block device (i.e., ``librbd``) cannot
+take advantage of the Linux page cache, so it includes its own in-memory
+caching, called "RBD caching." RBD caching behaves just like well-behaved hard
+disk caching.  When the OS sends a barrier or a flush request, all dirty data is
+written to the OSDs. This means that using write-back caching is just as safe as
+using a well-behaved physical hard disk with a VM that properly sends flushes
+(i.e. Linux kernel >= 2.6.32). The cache uses a Least Recently Used (LRU)
+algorithm, and in write-back mode it  can coalesce contiguous requests for
+better throughput.
 
 .. versionadded:: 0.46
 
@@ -82,3 +86,4 @@ section of your configuration file. The settings include:
 :Required: No
 :Default: ``1.0``
 
+.. _Block Device: ../../rbd/rbd/
\ No newline at end of file