Merge branch 'upstream'

Conflicts:
	cpukit/libblock/include/rtems/bdbuf.h
	cpukit/libblock/src/bdbuf.c

3 files changed, 61 insertions, 7 deletions

diff --git a/cpukit/libblock/include/rtems/bdbuf.h b/cpukit/libblock/include/rtems/bdbuf.h
index cdac89d306..134a0ceff5 100644
--- a/cpukit/libblock/include/rtems/bdbuf.h
+++ b/cpukit/libblock/include/rtems/bdbuf.h
@@ -470,12 +470,16 @@ rtems_bdbuf_init (void);
  * The block number is the linear block number. This is relative to the start
  * of the partition on the media.
  *
+ * Before you can use this function, the rtems_bdbuf_init() routine must be
+ * called at least once to initialize the cache, otherwise a fatal error will
+ * occur.
+ *
  * @param dd [in] The disk device.
  * @param block [in] Linear media block number.
  * @param bd [out] Reference to the buffer descriptor pointer.
  *
  * @retval RTEMS_SUCCESSFUL Successful operation. 
- * @retval RTEMS_INVALID_NUMBER Invalid block size.
+ * @retval RTEMS_INVALID_ID Invalid block number.
  */
 rtems_status_code
 rtems_bdbuf_get (
@@ -499,12 +503,16 @@ rtems_bdbuf_get (
  * buffer is returned. The highest priority waiter will obtain the buffer
  * first.
  *
+ * Before you can use this function, the rtems_bdbuf_init() routine must be
+ * called at least once to initialize the cache, otherwise a fatal error will
+ * occur.
+ *
  * @param dd [in] The disk device.
  * @param block [in] Linear media block number.
  * @param bd [out] Reference to the buffer descriptor pointer.
  *
  * @retval RTEMS_SUCCESSFUL Successful operation. 
- * @retval RTEMS_INVALID_NUMBER Invalid block size.
+ * @retval RTEMS_INVALID_ID Invalid block number.
  * @retval RTEMS_IO_ERROR IO error.
  */
 rtems_status_code
@@ -522,7 +530,13 @@ rtems_bdbuf_read (
  * the cache and modified before this call it will be returned to the modified
  * queue. The buffers is returned to the end of the LRU list.
  *
- * @param bd [in] Reference to the buffer descriptor.
+ * Before you can use this function, the rtems_bdbuf_init() routine must be
+ * called at least once to initialize the cache, otherwise a fatal error will
+ * occur.
+ *
+ * @param bd [in] Reference to the buffer descriptor.  The buffer descriptor
+ * reference must not be @c NULL and must be obtained via rtems_bdbuf_get() or
+ * rtems_bdbuf_read().
  *
  * @retval RTEMS_SUCCESSFUL Successful operation. 
  * @retval RTEMS_INVALID_ADDRESS The reference is NULL.
@@ -540,7 +554,13 @@ rtems_bdbuf_release (rtems_bdbuf_buffer* bd);
  * or a sync call has been made. If the buffer is obtained with a get or read
  * before the hold timer has expired the buffer will be returned to the user.
  *
- * @param bd [in] Reference to the buffer descriptor.
+ * Before you can use this function, the rtems_bdbuf_init() routine must be
+ * called at least once to initialize the cache, otherwise a fatal error will
+ * occur.
+ *
+ * @param bd [in] Reference to the buffer descriptor.  The buffer descriptor
+ * reference must not be @c NULL and must be obtained via rtems_bdbuf_get() or
+ * rtems_bdbuf_read().
  *
  * @retval RTEMS_SUCCESSFUL Successful operation. 
  * @retval RTEMS_INVALID_ADDRESS The reference is NULL.
@@ -556,8 +576,14 @@ rtems_bdbuf_release_modified (rtems_bdbuf_buffer* bd);
  *
  * @note This code does not lock the sync mutex and stop additions to the
  *       modified queue.
-
- * @param bd [in] Reference to the buffer descriptor.
+ *
+ * Before you can use this function, the rtems_bdbuf_init() routine must be
+ * called at least once to initialize the cache, otherwise a fatal error will
+ * occur.
+ *
+ * @param bd [in] Reference to the buffer descriptor.  The buffer descriptor
+ * reference must not be @c NULL and must be obtained via rtems_bdbuf_get() or
+ * rtems_bdbuf_read().
  *
  * @retval RTEMS_SUCCESSFUL Successful operation. 
  * @retval RTEMS_INVALID_ADDRESS The reference is NULL.
@@ -574,6 +600,10 @@ rtems_bdbuf_sync (rtems_bdbuf_buffer* bd);
  * @note Nesting calls to sync multiple devices will be handled sequentially. A
  * nested call will be blocked until the first sync request has complete.
  *
+ * Before you can use this function, the rtems_bdbuf_init() routine must be
+ * called at least once to initialize the cache, otherwise a fatal error will
+ * occur.
+ *
  * @param dd [in] The disk device.
  *
  * @retval RTEMS_SUCCESSFUL Successful operation. 
@@ -585,6 +615,12 @@ rtems_bdbuf_syncdev (const rtems_disk_device *dd);
  * @brief Purges all buffers corresponding to the disk device @a dd.
  *
  * This may result in loss of data.
+ *
+ * Before you can use this function, the rtems_bdbuf_init() routine must be
+ * called at least once to initialize the cache, otherwise a fatal error will
+ * occur.
+ *
+ * @param dd [in] The disk device.
  */
 void
 rtems_bdbuf_purge_dev (const rtems_disk_device *dd);
@@ -595,6 +631,10 @@ rtems_bdbuf_purge_dev (const rtems_disk_device *dd);
  * This will also change the block_to_media_block_shift and bds_per_group
  * fields of the disk device.
  *
+ * Before you can use this function, the rtems_bdbuf_init() routine must be
+ * called at least once to initialize the cache, otherwise a fatal error will
+ * occur.
+ *
  * @param dd [in, out] The disk device.
  * @param dd [in] The new block size.
  *
diff --git a/cpukit/libblock/src/bdbuf.c b/cpukit/libblock/src/bdbuf.c
index f6d9327138..ad1112b517 100644
--- a/cpukit/libblock/src/bdbuf.c
+++ b/cpukit/libblock/src/bdbuf.c
@@ -154,10 +154,17 @@ typedef struct rtems_bdbuf_cache
 #define RTEMS_BLKDEV_FATAL_BDBUF_STATE_10      RTEMS_BLKDEV_FATAL_ERROR(8)
 #define RTEMS_BLKDEV_FATAL_BDBUF_TREE_RM       RTEMS_BLKDEV_FATAL_ERROR(9)
 #define RTEMS_BLKDEV_FATAL_BDBUF_SWAPOUT       RTEMS_BLKDEV_FATAL_ERROR(10)
+
+/*
+ * The lock/unlock fatal errors occur in case the bdbuf is not initialized with
+ * rtems_bdbuf_init().  General system corruption like stack overflow etc. may
+ * also trigger these fatal errors.
+ */
 #define RTEMS_BLKDEV_FATAL_BDBUF_SYNC_LOCK     RTEMS_BLKDEV_FATAL_ERROR(11)
 #define RTEMS_BLKDEV_FATAL_BDBUF_SYNC_UNLOCK   RTEMS_BLKDEV_FATAL_ERROR(12)
 #define RTEMS_BLKDEV_FATAL_BDBUF_CACHE_LOCK    RTEMS_BLKDEV_FATAL_ERROR(13)
 #define RTEMS_BLKDEV_FATAL_BDBUF_CACHE_UNLOCK  RTEMS_BLKDEV_FATAL_ERROR(14)
+
 #define RTEMS_BLKDEV_FATAL_BDBUF_PREEMPT_DIS   RTEMS_BLKDEV_FATAL_ERROR(15)
 #define RTEMS_BLKDEV_FATAL_BDBUF_CACHE_WAIT_2  RTEMS_BLKDEV_FATAL_ERROR(16)
 #define RTEMS_BLKDEV_FATAL_BDBUF_PREEMPT_RST   RTEMS_BLKDEV_FATAL_ERROR(17)
@@ -1744,7 +1751,7 @@ rtems_bdbuf_get_media_block (const rtems_disk_device *dd,
   rtems_blkdev_bnum mb = rtems_bdbuf_media_block (dd, block);
   if (mb >= dd->size)
   {
-    return RTEMS_INVALID_NUMBER;
+    return RTEMS_INVALID_ID;
   }
 
   *media_block_ptr = mb + dd->start;
diff --git a/doc/user/conf.t b/doc/user/conf.t
index d7f68097ee..7e403cab95 100644
--- a/doc/user/conf.t
+++ b/doc/user/conf.t
@@ -2187,6 +2187,7 @@ need to control the size of the workspace very tightly because they just
 want to get the new software to run; later they can tune the workspace size
 as needed.
 
+@findex rtems_resource_unlimited
 When the number of objects is not known ahead of time, RTEMS provides an
 auto-extending mode that can be enabled individually for each object
 type by using the macro @code{rtems_resource_unlimited}. This takes a value
@@ -2204,6 +2205,12 @@ allocation block of objects allocated. Here is an example of using
 #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
 @end example
 
+@findex rtems_resource_is_unlimited
+@findex rtems_resource_maximum_per_allocation
+Object maximum specifications can be evaluated with the
+@code{rtems_resource_is_unlimited} and
+@code{rtems_resource_maximum_per_allocation} macros.
+
 To ease the burden of developers who are porting new software RTEMS also
 provides the following macros:
 @itemize @bullet