From: Nathan Rutman Date: Wed, 2 Jun 2010 18:49:46 +0000 (-0700) Subject: b=20972 Add doxygen comments to MGS X-Git-Tag: v1_10_0_44~35 X-Git-Url: https://git.whamcloud.com/?a=commitdiff_plain;h=1a1e988a066cdb4e30599722c7a7f6fdebdb9ccb;p=fs%2Flustre-release.git b=20972 Add doxygen comments to MGS i=breitz --- diff --git a/lustre/include/lustre_cfg.h b/lustre/include/lustre_cfg.h index f1b103a..ae956bf 100644 --- a/lustre/include/lustre_cfg.h +++ b/lustre/include/lustre_cfg.h @@ -52,40 +52,40 @@ #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 { diff --git a/lustre/include/obd_class.h b/lustre/include/obd_class.h index 1376b75..0b12032 100644 --- a/lustre/include/obd_class.h +++ b/lustre/include/obd_class.h @@ -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, diff --git a/lustre/llite/llite_lib.c b/lustre/llite/llite_lib.c index 66a57ee..11b1806 100644 --- a/lustre/llite/llite_lib.c +++ b/lustre/llite/llite_lib.c @@ -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" diff --git a/lustre/mgc/mgc_request.c b/lustre/mgc/mgc_request.c index 883b621..7e31ff8 100644 --- a/lustre/mgc/mgc_request.c +++ b/lustre/mgc/mgc_request.c @@ -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; diff --git a/lustre/obdclass/obd_config.c b/lustre/obdclass/obd_config.c index 00e672f..316ec5e 100644 --- a/lustre/obdclass/obd_config.c +++ b/lustre/obdclass/obd_config.c @@ -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] = ""; diff --git a/lustre/obdclass/obd_mount.c b/lustre/obdclass/obd_mount.c index b2acd97..56b2e57 100644 --- a/lustre/obdclass/obd_mount.c +++ b/lustre/obdclass/obd_mount.c @@ -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",