Documentation. Changed integer types to match block device types.

Added const qualifier whenever possible.  Added
rtems_fsmount_create_mount_point() prototype.

4 files changed, 266 insertions, 79 deletions

diff --git a/cpukit/libblock/include/rtems/ramdisk.h b/cpukit/libblock/include/rtems/ramdisk.h
index 0df21b4ca0..62b1293a8a 100644
--- a/cpukit/libblock/include/rtems/ramdisk.h
+++ b/cpukit/libblock/include/rtems/ramdisk.h
@@ -1,6 +1,7 @@
 /**
- * @file rtems/ramdisk.h
- * RAM disk block device implementation
+ * @file
+ *
+ * RAM disk block device.
  */
 
 /*
@@ -21,33 +22,70 @@
 extern "C" {
 #endif
 
-/* RAM disk configuration table entry */
+/**
+ * @defgroup rtems_ramdisk RAM Disk Device
+ *
+ * @ingroup rtems_blkdev
+ *
+ * @{
+ */
+
+/**
+ * RAM disk configuration table entry.
+ */
 typedef struct rtems_ramdisk_config {
-    int   block_size; /* RAM disk block size */
-    int   block_num;  /* Number of blocks on this RAM disk */
-    void *location;   /* RAM disk permanent location (out of RTEMS controlled
-                         memory), or NULL if RAM disk memory should be
-                         allocated dynamically */
+  /**
+   * RAM disk block size (must be a power of two).
+   */
+  uint32_t block_size;
+
+  /**
+   * Number of blocks on this RAM disk.
+   */
+  rtems_blkdev_bnum block_num;
+
+  /**
+   * RAM disk location or @c NULL if RAM disk memory should be allocated
+   * dynamically.
+   */
+  void *location;
 } rtems_ramdisk_config;
 
-/* If application want to use RAM disk, it should specify configuration of
- * available RAM disks.
- * The following is definitions for RAM disk configuration table
+/**
+ * External reference to the RAM disk configuration table describing each RAM
+ * disk in the system.
+ *
+ * The configuration table is provided by the application.
+ */
+extern rtems_ramdisk_config rtems_ramdisk_configuration [];
+
+/**
+ * External reference the size of the RAM disk configuration table
+ * @ref rtems_ramdisk_configuration.
+ *
+ * The configuration table size is provided by the application.
  */
-extern rtems_ramdisk_config rtems_ramdisk_configuration[];
 extern size_t rtems_ramdisk_configuration_size;
 
-/* ramdisk_initialize --
- *     RAM disk driver initialization entry point.
+/**
+ * RAM disk driver initialization entry point.
  */
-rtems_device_driver
-ramdisk_initialize(
-    rtems_device_major_number major,
-    rtems_device_minor_number minor,
-    void *arg);
+rtems_device_driver ramdisk_initialize(
+ rtems_device_major_number major,
+ rtems_device_minor_number minor,
+ void *arg
+);
 
+/**
+ * RAM disk driver table entry.
+ */
 #define RAMDISK_DRIVER_TABLE_ENTRY \
-    { ramdisk_initialize, RTEMS_GENERIC_BLOCK_DEVICE_DRIVER_ENTRIES }
+  { \
+    .initialization_entry = ramdisk_initialize, \
+    RTEMS_GENERIC_BLOCK_DEVICE_DRIVER_ENTRIES \
+  }
+
+/** @} */
 
 #ifdef __cplusplus
 }
diff --git a/cpukit/libblock/src/ramdisk.c b/cpukit/libblock/src/ramdisk.c
index 05a896016b..0b18ad34f8 100644
--- a/cpukit/libblock/src/ramdisk.c
+++ b/cpukit/libblock/src/ramdisk.c
@@ -1,5 +1,10 @@
-/* ramdisk.c -- RAM disk block device implementation
+/**
+ * @file
  *
+ * RAM disk block device.
+ */
+
+/*
  * Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
  * Author: Victor V. Vengerov <vvv@oktet.ru>
  *
@@ -18,9 +23,9 @@
 #include <string.h>
 #include <inttypes.h>
 
-#include "rtems/blkdev.h"
-#include "rtems/diskdevs.h"
-#include "rtems/ramdisk.h"
+#include <rtems/blkdev.h>
+#include <rtems/diskdevs.h>
+#include <rtems/ramdisk.h>
 
 /**
  * Control tracing. It can be compiled out of the code for small
@@ -30,23 +35,22 @@
 #define RTEMS_RAMDISK_TRACE 0
 #endif
 
-#define RAMDISK_DEVICE_BASE_NAME "/dev/ramdisk"
+#define RAMDISK_DEVICE_BASE_NAME "/dev/rd"
 
 /* Internal RAM disk descriptor */
 struct ramdisk {
-    int           block_size; /* RAM disk block size */
-    int           block_num;  /* Number of blocks on this RAM disk */
-    void         *area;       /* RAM disk memory area */
-    bool          initialized;/* RAM disk is initialized */
-    bool          malloced;   /* != 0, if memory allocated by malloc for this
-                                 RAM disk */
+  uint32_t block_size; /* RAM disk block size */
+  rtems_blkdev_bnum block_num; /* Number of blocks on this RAM disk */
+  void *area; /* RAM disk memory area */
+  bool initialized; /* RAM disk is initialized */
+  bool malloced; /* != 0, if memory allocated by malloc for this RAM disk */
 #if RTEMS_RAMDISK_TRACE
-    int           info_level; /* Trace level */
+  int info_level; /* Trace level */
 #endif
 };
 
 static struct ramdisk *ramdisk;
-static uint32_t        nramdisks;
+static uint32_t nramdisks;
 
 #if RTEMS_RAMDISK_TRACE
 /**
@@ -242,8 +246,8 @@ ramdisk_initialize(
     for (i = 0; i < rtems_ramdisk_configuration_size; i++, c++, r++)
     {
         dev_t dev = rtems_filesystem_make_dev_t(major, i);
-        char name[sizeof(RAMDISK_DEVICE_BASE_NAME "0123456789")];
-        snprintf(name, sizeof(name), RAMDISK_DEVICE_BASE_NAME "%" PRIu32, i);
+        char name [] = RAMDISK_DEVICE_BASE_NAME "a";
+        name [sizeof(RAMDISK_DEVICE_BASE_NAME)] += i;
         r->block_size = c->block_size;
         r->block_num = c->block_num;
         if (c->location == NULL)
diff --git a/cpukit/libmisc/fsmount/fsmount.c b/cpukit/libmisc/fsmount/fsmount.c
index c7e61e27c5..506c44aeb1 100644
--- a/cpukit/libmisc/fsmount/fsmount.c
+++ b/cpukit/libmisc/fsmount/fsmount.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * File system mount functions.
+ */
+
 /*===============================================================*\
 | Project: RTEMS fsmount                                          |
 +-----------------------------------------------------------------+
@@ -38,7 +44,7 @@
 /*=========================================================================*\
 | Function:                                                                 |
 \*-------------------------------------------------------------------------*/
-int rtems_fsmount_create_mountpoint
+int rtems_fsmount_create_mount_point
 (
 /*-------------------------------------------------------------------------*\
 | Purpose:                                                                  |
@@ -113,9 +119,9 @@ int rtems_fsmount
 +---------------------------------------------------------------------------+
 | Input Parameters:                                                         |
 \*-------------------------------------------------------------------------*/
- const fstab_t *fstab_ptr,
- int fstab_count,
- int *fail_idx
+ const rtems_fstab_entry *fstab_ptr,
+ size_t fstab_count,
+ size_t *fail_idx
  )
 /*-------------------------------------------------------------------------*\
 | Return Value:                                                             |
@@ -124,7 +130,7 @@ int rtems_fsmount
 {
   int rc = 0;
   int tmp_rc;
-  int fstab_idx = 0;
+  size_t fstab_idx = 0;
   rtems_filesystem_mount_table_entry_t *tmp_mt_entry;
   bool terminate = false;
 
@@ -138,7 +144,7 @@ int rtems_fsmount
      * create mount point
      */
     if (tmp_rc == 0) {
-      tmp_rc = rtems_fsmount_create_mountpoint(fstab_ptr->mount_point);
+      tmp_rc = rtems_fsmount_create_mount_point(fstab_ptr->mount_point);
       if (tmp_rc != 0) {
 	if (0 != (fstab_ptr->report_reasons & FSMOUNT_MNTPNT_CRTERR)) {
 	  fprintf(stdout,"fsmount: creation of mount point \"%s\" failed: %s\n",
@@ -154,13 +160,13 @@ int rtems_fsmount
     /*
      * mount device to given mount point
      */
-    if (tmp_rc == RTEMS_SUCCESSFUL) {
+    if (tmp_rc == 0) {
       tmp_rc = mount(&tmp_mt_entry,
 		     fstab_ptr->fs_ops,
 		     fstab_ptr->mount_options,
 		     fstab_ptr->dev,
 		     fstab_ptr->mount_point);
-      if (tmp_rc != RTEMS_SUCCESSFUL) {
+      if (tmp_rc != 0) {
 	if (0 != (fstab_ptr->report_reasons & FSMOUNT_MNT_FAILED)) {
 	  fprintf(stdout,"fsmount: mounting of \"%s\" to"
 		 " \"%s\" failed: %s\n",
diff --git a/cpukit/libmisc/fsmount/fsmount.h b/cpukit/libmisc/fsmount/fsmount.h
index 395e35b93f..0841a6fe49 100644
--- a/cpukit/libmisc/fsmount/fsmount.h
+++ b/cpukit/libmisc/fsmount/fsmount.h
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * File system mount functions.
+ */
+
 /*===============================================================*\
 | Project: RTEMS fsmount                                          |
 +-----------------------------------------------------------------+
@@ -33,46 +39,179 @@
 extern "C" {
 #endif
 
-/*
- * bits to define, what errors will cause reporting (via printf) and
- * abort of mount processing
- * Use a combination of these bits
- * for the fields "report_reasons" and "abort_reasons"
+/**
+ * @defgroup rtems_fstab File System Mount Support
+ *
+ * @{
+ */
+
+/**
+ * File system mount report and abort condition flags.
+ *
+ * The flags define, which conditions will cause a report during the mount
+ * process (via printf()) or abort the mount process.
+ *
+ * @see rtems_fstab_entry and rtems_fsmount().
  */
-#define FSMOUNT_MNT_OK        0x0001 /* mounted ok                 */
-#define FSMOUNT_MNTPNT_CRTERR 0x0002 /* cannot create mount point  */
-#define FSMOUNT_MNT_FAILED    0x0004 /* mounting failed            */
+typedef enum {
+  /**
+   * No conditions.
+   */
+  RTEMS_FSTAB_NONE = 0U,
+
+  /**
+   * Complete mount process was successful.
+   */
+  RTEMS_FSTAB_OK = 0x1U,
+
+  /**
+   * Mount point creation failed.
+   */
+  RTEMS_FSTAB_ERROR_MOUNT_POINT = 0x2U,
 
+  /**
+   * File system mount failed.
+   */
+  RTEMS_FSTAB_ERROR_MOUNT = 0x4U,
+
+  /**
+   * Something failed.
+   */
+  RTEMS_FSTAB_ERROR = RTEMS_FSTAB_ERROR_MOUNT_POINT | RTEMS_FSTAB_ERROR_MOUNT,
+
+  /**
+   * Any condition.
+   */
+  RTEMS_FSTAB_ANY = RTEMS_FSTAB_OK | RTEMS_FSTAB_ERROR
+} rtems_fstab_conditions;
+
+/**
+ * File system table entry.
+ */
 typedef struct {
-  char *dev;
-  char *mount_point;
-  rtems_filesystem_operations_table *fs_ops;
+  /**
+   * Device file path.
+   */
+  const char *dev;
+
+  /**
+   * Mount point path.
+   */
+  const char *mount_point;
+
+  /**
+   * File system operations.
+   */
+  const rtems_filesystem_operations_table *fs_ops;
+
+  /**
+   * File system mount options.
+   */
   rtems_filesystem_options_t mount_options;
-  uint16_t   report_reasons;
-  uint16_t   abort_reasons;
-} fstab_t;
-
-
-/*=========================================================================*\
-| Function:                                                                 |
-\*-------------------------------------------------------------------------*/
-int rtems_fsmount
-(
-/*-------------------------------------------------------------------------*\
-| Purpose:                                                                  |
-|  This function will create the mount points listed and mount the file     |
-|   systems listed in the calling parameters                                |
-+---------------------------------------------------------------------------+
-| Input Parameters:                                                         |
-\*-------------------------------------------------------------------------*/
- const fstab_t *fstab_ptr,              /* Ptr to filesystem mount table   */
- int fstab_count,                       /* number of entries in mount table*/
- int *fail_idx                          /* return: index of failed entry   */
- );
-/*-------------------------------------------------------------------------*\
-| Return Value:                                                             |
-|    0, if success, -1 and errno if failed                                  |
-\*=========================================================================*/
+
+  /**
+   * Report @ref rtems_fstab_conditions "condition flags".
+   */
+  uint16_t report_reasons;
+
+  /**
+   * Abort @ref rtems_fstab_conditions "condition flags".
+   */
+  uint16_t abort_reasons;
+} rtems_fstab_entry;
+
+/**
+ * Creates the mount point with path @a mount_point.
+ *
+ * On success, zero is returned.  On error, -1 is returned, and @c errno is set
+ * appropriately.
+ *
+ * @see rtems_fsmount().
+ */
+int rtems_fsmount_create_mount_point( const char *mount_point);
+
+/**
+ * Mounts the file systems listed in the file system mount table @a fstab of
+ * size @a size.
+ *
+ * Each file system will be mounted according to its table entry parameters.
+ * In case of an abort condition the corresponding table index will be reported
+ * in @a abort_index.  The pointer @a abort_index may be @c NULL.  The mount
+ * point paths will be created with rtems_fsmount_create_mount_point() and need
+ * not exist beforehand.
+ *
+ * On success, zero is returned.  On error, -1 is returned, and @c errno is set
+ * appropriately.
+ *
+ * @see rtems_bdpart_register_from_disk().
+ *
+ * The following example code tries to mount a FAT file system within a SD
+ * Card.  Some cards do not have a partition table so at first it tries to find
+ * a file system inside the hole disk.  If this is successful the mount process
+ * will be aborted because the @ref RTEMS_FSTAB_OK condition is true.  If this
+ * did not work it tries to mount the file system inside the first partition.
+ * If this fails the mount process will not be aborted (this is already the
+ * last entry), but the last error status will be returned.
+ *
+ * @code
+ * #include <stdio.h>
+ * #include <string.h>
+ * #include <errno.h>
+ *
+ * #include <rtems.h>
+ * #include <rtems/bdpart.h>
+ * #include <rtems/dosfs.h>
+ * #include <rtems/error.h>
+ * #include <rtems/fsmount.h>
+ *
+ * static const rtems_fstab_entry fstab [] = {
+ *   {
+ *     .dev = "/dev/sd-card-a",
+ *     .mount_point = "/mnt",
+ *     .fs_ops = &msdos_ops,
+ *     .mount_options = RTEMS_FILESYSTEM_READ_WRITE,
+ *     .report_reasons = RTEMS_FSTAB_ANY,
+ *     .abort_reasons = RTEMS_FSTAB_OK
+ *   }, {
+ *     .dev = "/dev/sd-card-a1",
+ *     .mount_point = "/mnt",
+ *     .fs_ops = &msdos_ops,
+ *     .mount_options = RTEMS_FILESYSTEM_READ_WRITE,
+ *     .report_reasons = RTEMS_FSTAB_ANY,
+ *     .abort_reasons = RTEMS_FSTAB_NONE
+ *   }
+ * };
+ *
+ * static void my_mount(void)
+ * {
+ *   rtems_status_code sc = RTEMS_SUCCESSFUL;
+ *   int rv = 0;
+ *   size_t abort_index = 0;
+ *
+ *   sc = rtems_bdpart_register_from_disk("/dev/sd-card-a");
+ *   if (sc != RTEMS_SUCCESSFUL) {
+ *     printf("read partition table failed: %s\n", rtems_status_text(sc));
+ *   }
+ *
+ *   rv = rtems_fsmount(fstab, sizeof(fstab) / sizeof(fstab [0]), &abort_index);
+ *   if (rv != 0) {
+ *     printf("mount failed: %s\n", strerror(errno));
+ *   }
+ *   printf("mount aborted at %zu\n", abort_index);
+ * }
+ * @endcode
+ */
+int rtems_fsmount( const rtems_fstab_entry *fstab, size_t size, size_t *abort_index);
+
+/** @} */
+
+typedef rtems_fstab_entry fstab_t;
+
+#define FSMOUNT_MNT_OK RTEMS_FSTAB_OK
+
+#define FSMOUNT_MNTPNT_CRTERR RTEMS_FSTAB_ERROR_MOUNT_POINT
+
+#define FSMOUNT_MNT_FAILED RTEMS_FSTAB_ERROR_MOUNT
 
 #ifdef __cplusplus
 }