Whamcloud - gitweb
b=20972 Add doxygen comments to MGS
authorNathan Rutman <nathan.rutman@sun.com>
Wed, 2 Jun 2010 18:49:46 +0000 (11:49 -0700)
committerRobert Read <robert.read@oracle.com>
Thu, 3 Jun 2010 16:47:18 +0000 (09:47 -0700)
i=breitz

lustre/include/lustre_cfg.h
lustre/include/obd_class.h
lustre/llite/llite_lib.c
lustre/mgc/mgc_request.c
lustre/obdclass/obd_config.c
lustre/obdclass/obd_mount.c

index f1b103a..ae956bf 100644 (file)
 #define LCFG_HDR_SIZE(count) \
     cfs_size_round(offsetof (struct lustre_cfg, lcfg_buflens[(count)]))
 
-/* If the LCFG_REQUIRED bit is set in a configuration command,
+/** If the LCFG_REQUIRED bit is set in a configuration command,
  * then the client is required to understand this parameter
  * in order to mount the filesystem. If it does not understand
  * a REQUIRED command the client mount will fail. */
 #define LCFG_REQUIRED         0x0001000
 
 enum lcfg_command_type {
-        LCFG_ATTACH             = 0x00cf001,
-        LCFG_DETACH             = 0x00cf002,
-        LCFG_SETUP              = 0x00cf003,
-        LCFG_CLEANUP            = 0x00cf004,
-        LCFG_ADD_UUID           = 0x00cf005,
-        LCFG_DEL_UUID           = 0x00cf006,
-        LCFG_MOUNTOPT           = 0x00cf007,
-        LCFG_DEL_MOUNTOPT       = 0x00cf008,
-        LCFG_SET_TIMEOUT        = 0x00cf009,
-        LCFG_SET_UPCALL         = 0x00cf00a,
-        LCFG_ADD_CONN           = 0x00cf00b,
-        LCFG_DEL_CONN           = 0x00cf00c,
-        LCFG_LOV_ADD_OBD        = 0x00cf00d,
-        LCFG_LOV_DEL_OBD        = 0x00cf00e,
-        LCFG_PARAM              = 0x00cf00f,
-        LCFG_MARKER             = 0x00cf010,
-        LCFG_LOG_START          = 0x00ce011,
-        LCFG_LOG_END            = 0x00ce012,
-        LCFG_LOV_ADD_INA        = 0x00ce013,
-        LCFG_ADD_MDC            = 0x00cf014,
-        LCFG_DEL_MDC            = 0x00cf015,
-        LCFG_SPTLRPC_CONF       = 0x00ce016,
-        LCFG_POOL_NEW           = 0x00ce020,
-        LCFG_POOL_ADD           = 0x00ce021,
-        LCFG_POOL_REM           = 0x00ce022,
-        LCFG_POOL_DEL           = 0x00ce023,
-        LCFG_SET_LDLM_TIMEOUT   = 0x00ce030,
+        LCFG_ATTACH             = 0x00cf001, /**< create a new obd instance */
+        LCFG_DETACH             = 0x00cf002, /**< destroy obd instance */
+        LCFG_SETUP              = 0x00cf003, /**< call type-specific setup */
+        LCFG_CLEANUP            = 0x00cf004, /**< call type-specific cleanup */
+        LCFG_ADD_UUID           = 0x00cf005, /**< add a nid to a niduuid */
+        LCFG_DEL_UUID           = 0x00cf006, /**< remove a nid from a niduuid */
+        LCFG_MOUNTOPT           = 0x00cf007, /**< create a profile (mdc, osc) */
+        LCFG_DEL_MOUNTOPT       = 0x00cf008, /**< destroy a profile */
+        LCFG_SET_TIMEOUT        = 0x00cf009, /**< set obd_timeout */
+        LCFG_SET_UPCALL         = 0x00cf00a, /**< deprecated */
+        LCFG_ADD_CONN           = 0x00cf00b, /**< add a failover niduuid to an obd */
+        LCFG_DEL_CONN           = 0x00cf00c, /**< remove a failover niduuid */
+        LCFG_LOV_ADD_OBD        = 0x00cf00d, /**< add an osc to a lov */
+        LCFG_LOV_DEL_OBD        = 0x00cf00e, /**< remove an osc from a lov */
+        LCFG_PARAM              = 0x00cf00f, /**< set a proc parameter */
+        LCFG_MARKER             = 0x00cf010, /**< metadata about next cfg rec */
+        LCFG_LOG_START          = 0x00ce011, /**< mgc only, process a cfg log */
+        LCFG_LOG_END            = 0x00ce012, /**< stop processing updates */
+        LCFG_LOV_ADD_INA        = 0x00ce013, /**< like LOV_ADD_OBD, inactive */
+        LCFG_ADD_MDC            = 0x00cf014, /**< add an mdc to a lmv */
+        LCFG_DEL_MDC            = 0x00cf015, /**< remove an mdc from a lmv */
+        LCFG_SPTLRPC_CONF       = 0x00ce016, /**< security */
+        LCFG_POOL_NEW           = 0x00ce020, /**< create an ost pool name */
+        LCFG_POOL_ADD           = 0x00ce021, /**< add an ost to a pool */
+        LCFG_POOL_REM           = 0x00ce022, /**< remove an ost from a pool */
+        LCFG_POOL_DEL           = 0x00ce023, /**< destroy an ost pool name */
+        LCFG_SET_LDLM_TIMEOUT   = 0x00ce030, /**< set ldlm_timeout */
 };
 
 struct lustre_cfg_bufs {
index 1376b75..0b12032 100644 (file)
@@ -901,6 +901,11 @@ static inline struct obd_uuid *obd_get_uuid(struct obd_export *exp)
         RETURN(uuid);
 }
 
+/** Create a new /a exp on device /a obd for the uuid /a cluuid
+ * @param exp New export handle
+ * @param d Connect data, supported flags are set, flags also understood
+ *    by obd are returned.
+ */
 static inline int obd_connect(const struct lu_env *env,
                               struct obd_export **exp,struct obd_device *obd,
                               struct obd_uuid *cluuid,
index 66a57ee..11b1806 100644 (file)
@@ -844,6 +844,7 @@ int ll_fill_super(struct super_block *sb)
                 GOTO(out_free, err);
         }
 
+        /* Profile set with LCFG_MOUNTOPT so we can find our mdc and osc obds */
         lprof = class_get_profile(profilenm);
         if (lprof == NULL) {
                 LCONSOLE_ERROR_MSG(0x156, "The client profile '%s' could not be"
index 883b621..7e31ff8 100644 (file)
@@ -261,8 +261,8 @@ struct config_llog_data *do_config_log_add(struct obd_device *obd,
         RETURN(cld);
 }
 
-/**
- * Add this log to our list of active logs.
+/** Add this log to the list of active logs watched by an MGC.
+ * Active means we're watching for updates.
  * We have one active log per "mount" - client instance or servername.
  * Each instance may be at a different point in the log.
  */
@@ -313,7 +313,8 @@ static int config_log_add(struct obd_device *obd, char *logname,
 
 CFS_DECLARE_MUTEX(llog_process_lock);
 
-/* Stop watching for updates on this log. */
+/** Stop watching for updates on this log.
+ */
 static int config_log_end(char *logname, struct config_llog_instance *cfg)
 {
         struct config_llog_data *cld, *cld_sptlrpc = NULL;
@@ -1242,8 +1243,10 @@ out:
         RETURN(rc);
 }
 
-/* Get a config log from the MGS and process it.
-   This func is called for both clients and servers. */
+/** Get a config log from the MGS and process it.
+ * This func is called for both clients and servers.
+ * Copy the log locally before parsing it if appropriate (non-MGS server)
+ */
 int mgc_process_log(struct obd_device *mgc,
                     struct config_llog_data *cld)
 {
@@ -1371,6 +1374,10 @@ out_pop:
         RETURN(rc);
 }
 
+/** Called from lustre_process_log.
+ * LCFG_LOG_START gets the config log from the MGS, processes it to start
+ * any services, and adds it to the list logs to watch (follow).
+ */
 static int mgc_process_config(struct obd_device *obd, obd_count len, void *buf)
 {
         struct lustre_cfg *lcfg = buf;
@@ -1380,7 +1387,7 @@ static int mgc_process_config(struct obd_device *obd, obd_count len, void *buf)
 
         switch(cmd = lcfg->lcfg_command) {
         case LCFG_LOV_ADD_OBD: {
-                /* Add any new target, not just osts */
+                /* Overloading this cfg command: register a new target */
                 struct mgs_target_info *mti;
 
                 if (LUSTRE_CFG_BUFLEN(lcfg, 1) !=
@@ -1394,8 +1401,7 @@ static int mgc_process_config(struct obd_device *obd, obd_count len, void *buf)
                 break;
         }
         case LCFG_LOV_DEL_OBD:
-                /* Remove target from the fs? */
-                /* FIXME */
+                /* Unregister has no meaning at the moment. */
                 CERROR("lov_del_obd unimplemented\n");
                 rc = -ENOSYS;
                 break;
index 00e672f..316ec5e 100644 (file)
@@ -201,8 +201,8 @@ EXPORT_SYMBOL(class_parse_nid);
 /********************** class fns **********************/
 
 /**
- * Create a new device and set the type, name and uuid.  If successful, the new
- * device can be accessed by either name or uuid.
+ * Create a new obd device and set the type, name and uuid.  If successful,
+ * the new device can be accessed by either name or uuid.
  */
 int class_attach(struct lustre_cfg *lcfg)
 {
@@ -313,6 +313,9 @@ int class_attach(struct lustre_cfg *lcfg)
         return rc;
 }
 
+/** Create hashes, self-export, and call type-specific setup.
+ * Setup is effectively the "start this obd" call.
+ */
 int class_setup(struct obd_device *obd, struct lustre_cfg *lcfg)
 {
         int err = 0;
@@ -425,6 +428,9 @@ err_hash:
         return err;
 }
 
+/** We have finished using this obd and are ready to destroy it.
+ * There can be no more references to this obd.
+ */
 int class_detach(struct obd_device *obd, struct lustre_cfg *lcfg)
 {
         ENTRY;
@@ -454,6 +460,10 @@ int class_detach(struct obd_device *obd, struct lustre_cfg *lcfg)
         RETURN(0);
 }
 
+/** Start shutting down the obd.  There may be in-progess ops when
+ * this is called.  We tell them to start shutting down with a call
+ * to class_disconnect_exports().
+ */
 int class_cleanup(struct obd_device *obd, struct lustre_cfg *lcfg)
 {
         int err = 0;
@@ -599,6 +609,9 @@ void class_decref(struct obd_device *obd, const char *scope, const void *source)
         }
 }
 
+/** Add a failover nid location.
+ * Client obd types contact server obd types using this nid list.
+ */
 int class_add_conn(struct obd_device *obd, struct lustre_cfg *lcfg)
 {
         struct obd_import *imp;
@@ -630,6 +643,8 @@ int class_add_conn(struct obd_device *obd, struct lustre_cfg *lcfg)
         RETURN(rc);
 }
 
+/** Remove a failover nid location.
+ */
 int class_del_conn(struct obd_device *obd, struct lustre_cfg *lcfg)
 {
         struct obd_import *imp;
@@ -675,6 +690,10 @@ struct lustre_profile *class_get_profile(const char * prof)
         RETURN(NULL);
 }
 
+/** Create a named "profile".
+ * This defines the mdc and osc names to use for a client.
+ * This also is used to define the lov to be used by a mdt.
+ */
 int class_add_profile(int proflen, char *prof, int osclen, char *osc,
                       int mdclen, char *mdc)
 {
@@ -791,6 +810,10 @@ void lustre_register_client_process_config(int (*cpc)(struct lustre_cfg *lcfg))
 }
 EXPORT_SYMBOL(lustre_register_client_process_config);
 
+/** Process configuration commands given in lustre_cfg form.
+ * These may come from direct calls (e.g. class_manual_cleanup)
+ * or processing the config llog, or ioctl from lctl.
+ */
 int class_process_config(struct lustre_cfg *lcfg)
 {
         struct obd_device *obd;
@@ -1059,6 +1082,11 @@ extern int lustre_check_exclusion(struct super_block *sb, char *svname);
 #define lustre_check_exclusion(a,b)  0
 #endif
 
+/** Parse a configuration llog, doing various manipulations on them
+ * for various reasons, (modifications for compatibility, skip obsolete
+ * records, change uuids, etc), then class_process_config() resulting
+ * net records.
+ */
 static int class_config_llog_handler(struct llog_handle * handle,
                                      struct llog_rec_hdr *rec, void *data)
 {
@@ -1371,7 +1399,9 @@ parse_out:
 
 }
 
-/* Cleanup and detach */
+/** Call class_cleanup and class_detach.
+ * "Manual" only in the sense that we're faking lcfg commands.
+ */
 int class_manual_cleanup(struct obd_device *obd)
 {
         char                    flags[3] = "";
index b2acd97..56b2e57 100644 (file)
@@ -377,11 +377,18 @@ out:
 
 /**************** config llog ********************/
 
-/* Get a config log from the MGS and process it.
-   This func is called for both clients and servers.
-   Continue to process new statements appended to the logs
-   (whenever the config lock is revoked) until lustre_end_log
-   is called. */
+/** Get a config log from the MGS and process it.
+ * This func is called for both clients and servers.
+ * Continue to process new statements appended to the logs
+ * (whenever the config lock is revoked) until lustre_end_log
+ * is called.
+ * @param sb The superblock is used by the MGC to write to the local copy of
+ *   the config log
+ * @param logname The name of the llog to replicate from the MGS
+ * @param cfg Since the same mgc may be used to follow multiple config logs
+ *   (e.g. ost1, ost2, client), the config_llog_instance keeps the state for
+ *   this log, and is added to the mgc's list of logs to follow.
+ */
 int lustre_process_log(struct super_block *sb, char *logname,
                      struct config_llog_instance *cfg)
 {
@@ -451,6 +458,9 @@ int lustre_end_log(struct super_block *sb, char *logname,
 
 /**************** obd start *******************/
 
+/** lustre_cfg_bufs are a holdover from 1.4; we can still set these up from
+ * lctl (and do for echo cli/srv.
+ */
 int do_lcfg(char *cfgname, lnet_nid_t nid, int cmd,
             char *s1, char *s2, char *s3, char *s4)
 {
@@ -478,6 +488,9 @@ int do_lcfg(char *cfgname, lnet_nid_t nid, int cmd,
         return(rc);
 }
 
+/** Call class_attach and class_setup.  These methods in turn call
+ * obd type-specific methods.
+ */
 static int lustre_start_simple(char *obdname, char *type, char *uuid,
                                char *s1, char *s2)
 {
@@ -1058,7 +1071,8 @@ out:
         RETURN(rc);
 }
 
-/* Start targets */
+/** Start server targets: MDTs and OSTs
+ */
 static int server_start_targets(struct super_block *sb, struct vfsmount *mnt)
 {
         struct obd_device *obd;
@@ -1110,8 +1124,8 @@ static int server_start_targets(struct super_block *sb, struct vfsmount *mnt)
                 cfs_mutex_up(&server_start_lock);
         }
 
-        /* Set the mgc fs to our server disk.  This allows the MGC
-           to read and write configs locally. */
+        /* Set the mgc fs to our server disk.  This allows the MGC to
+         * read and write configs locally, in case it can't talk to the MGS. */
         rc = server_mgc_set_fs(lsi->lsi_mgc, sb);
         if (rc)
                 RETURN(rc);
@@ -1271,7 +1285,11 @@ static int lustre_put_lsi(struct super_block *sb)
 
 /*************** server mount ******************/
 
-/* Kernel mount using mount options in MOUNT_DATA_FILE */
+/** Kernel mount using mount options in MOUNT_DATA_FILE.
+ * Since this file lives on the disk, we pre-mount using a common
+ * type, read the file, then re-mount using the type specified in the
+ * file.
+ */
 static struct vfsmount *server_kernel_mount(struct super_block *sb)
 {
         struct lvfs_run_ctxt mount_ctxt;
@@ -1376,7 +1394,7 @@ out_free:
         RETURN(ERR_PTR(rc));
 }
 
-/* Wait here forever until the mount refcount is 0 before completing umount,
+/** Wait here forever until the mount refcount is 0 before completing umount,
  * else we risk dereferencing a null pointer.
  * LNET may take e.g. 165s before killing zombies.
  */
@@ -1414,6 +1432,8 @@ static void server_wait_finished(struct vfsmount *mnt)
        }
 }
 
+/** Start the shutdown of servers at umount.
+ */
 static void server_put_super(struct super_block *sb)
 {
         struct lustre_sb_info *lsi = s2lsi(sb);
@@ -1505,6 +1525,8 @@ static void server_put_super(struct super_block *sb)
         EXIT;
 }
 
+/** Called only for 'umount -f'
+ */
 #ifdef HAVE_UMOUNTBEGIN_VFSMOUNT
 static void server_umount_begin(struct vfsmount *vfsmnt, int flags)
 {
@@ -1567,6 +1589,9 @@ static int server_statfs (struct dentry *dentry, cfs_kstatfs_t *buf)
         RETURN(0);
 }
 
+/** The operations we support directly on the superblock:
+ * mount, umount, and df.
+ */
 static struct super_operations server_ops =
 {
         .put_super      = server_put_super,
@@ -1612,6 +1637,11 @@ static int server_fill_super_common(struct super_block *sb)
         RETURN(0);
 }
 
+/** Fill in the superblock info for a Lustre server.
+ * Mount the device with the correct options.
+ * Read the on-disk config file.
+ * Start the services.
+ */
 static int server_fill_super(struct super_block *sb)
 {
         struct lustre_sb_info *lsi = s2lsi(sb);
@@ -1652,6 +1682,7 @@ static int server_fill_super(struct super_block *sb)
                         GOTO(out_mnt, rc);
         }
 
+        /* Start MGC before servers */
         rc = lustre_start_mgc(sb);
         if (rc)
                 GOTO(out_mnt, rc);
@@ -1883,7 +1914,10 @@ static int lmd_parse_mgssec(struct lustre_mount_data *lmd, char *ptr)
         return 0;
 }
 
-/* mount -v -t lustre uml1:uml2:/lustre-client /mnt/lustre */
+/** Parse mount line options
+ * e.g. mount -v -t lustre -o abort_recov uml1:uml2:/lustre-client /mnt/lustre
+ * dev is passed as device=uml1:/lustre by mount.lustre
+ */
 static int lmd_parse(char *options, struct lustre_mount_data *lmd)
 {
         char *s1, *s2, *devname = NULL;
@@ -2025,7 +2059,11 @@ invalid:
 }
 
 
-/* Common mount */
+/** This is the entry point for the mount call into Lustre.
+ * This is called when a server or client is mounted,
+ * and this is where we start setting things up.
+ * @param data Mount options (e.g. -o flock,abort_recov)
+ */
 int lustre_fill_super(struct super_block *sb, void *data, int silent)
 {
         struct lustre_mount_data *lmd;
@@ -2136,6 +2174,8 @@ void lustre_kill_super(struct super_block *sb)
         kill_anon_super(sb);
 }
 
+/** Register the "lustre" fs type
+ */
 struct file_system_type lustre_fs_type = {
         .owner        = THIS_MODULE,
         .name         = "lustre",