From 22df831a5df7d19c1bbe7693e65d5a03e3f6b7f9 Mon Sep 17 00:00:00 2001 From: Alex Zhuravlev Date: Mon, 21 Jul 2014 17:19:57 +0400 Subject: [PATCH] LU-4974 doc: comments to lprocfs_lod.c comments to the functions in lod/lprocfs_lod.c. Signed-off-by: Alex Zhuravlev Change-Id: I8722347aae3262db187b4a6fc30d83d18fee2978 Reviewed-on: http://review.whamcloud.com/11159 Tested-by: Jenkins Reviewed-by: John L. Hammond Reviewed-by: Richard Henwood Reviewed-by: Oleg Drokin --- lustre/lod/lproc_lod.c | 245 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 244 insertions(+), 1 deletion(-) diff --git a/lustre/lod/lproc_lod.c b/lustre/lod/lproc_lod.c index 5250127..fe89355 100644 --- a/lustre/lod/lproc_lod.c +++ b/lustre/lod/lproc_lod.c @@ -41,7 +41,23 @@ #include "lod_internal.h" #include +/* + * Notice, all the functions below (except for lod_procfs_init() and + * lod_procfs_fini()) are not supposed to be used directly. They are + * called by Linux kernel's procfs. + */ + #ifdef LPROCFS + +/** + * Show default stripe size. + * + * \param[in] m seq file + * \param[in] v unused for single entry + * + * \retval 0 on success + * \retval negative error code if failed + */ static int lod_stripesize_seq_show(struct seq_file *m, void *v) { struct obd_device *dev = m->private; @@ -53,6 +69,19 @@ static int lod_stripesize_seq_show(struct seq_file *m, void *v) lod->lod_desc.ld_default_stripe_size); } +/** + * Set default stripe size. + * + * \param[in] file proc file + * \param[in] buffer string containing the maximum number of bytes stored in + * each object before moving to the next object in the + * layout (if any) + * \param[in] count @buffer length + * \param[in] off unused for single entry + * + * \retval @count on success + * \retval negative error code if failed + */ static ssize_t lod_stripesize_seq_write(struct file *file, const char *buffer, size_t count, loff_t *off) @@ -75,6 +104,15 @@ lod_stripesize_seq_write(struct file *file, const char *buffer, } LPROC_SEQ_FOPS(lod_stripesize); +/** + * Show default stripe offset. + * + * \param[in] m seq file + * \param[in] v unused for single entry + * + * \retval 0 on success + * \retval negative error code if failed + */ static int lod_stripeoffset_seq_show(struct seq_file *m, void *v) { struct obd_device *dev = m->private; @@ -86,6 +124,20 @@ static int lod_stripeoffset_seq_show(struct seq_file *m, void *v) lod->lod_desc.ld_default_stripe_offset); } +/** + * Set default stripe offset. + * + * Usually contains -1 allowing Lustre to balance objects among OST + * otherwise may cause severe OST imbalance. + * + * \param[in] file proc file + * \param[in] buffer string describing starting OST index for new files + * \param[in] count @buffer length + * \param[in] off unused for single entry + * + * \retval @count on success + * \retval negative error code if failed + */ static ssize_t lod_stripeoffset_seq_write(struct file *file, const char *buffer, size_t count, loff_t *off) @@ -107,6 +159,15 @@ lod_stripeoffset_seq_write(struct file *file, const char *buffer, } LPROC_SEQ_FOPS(lod_stripeoffset); +/** + * Show default striping pattern (LOV_PATTERN_*). + * + * \param[in] m seq file + * \param[in] v unused for single entry + * + * \retval 0 on success + * \retval negative error code if failed + */ static int lod_stripetype_seq_show(struct seq_file *m, void *v) { struct obd_device *dev = m->private; @@ -117,6 +178,18 @@ static int lod_stripetype_seq_show(struct seq_file *m, void *v) return seq_printf(m, "%u\n", lod->lod_desc.ld_pattern); } +/** + * Set default striping pattern (a number, not a human-readable string). + * + * \param[in] file proc file + * \param[in] buffer string containing the default striping pattern for new + * files. This is an integer LOV_PATTERN_* value + * \param[in] count @buffer length + * \param[in] off unused for single entry + * + * \retval @count on success + * \retval negative error code if failed + */ static ssize_t lod_stripetype_seq_write(struct file *file, const char *buffer, size_t count, loff_t *off) @@ -138,6 +211,15 @@ lod_stripetype_seq_write(struct file *file, const char *buffer, } LPROC_SEQ_FOPS(lod_stripetype); +/** + * Show default number of stripes. + * + * \param[in] m seq file + * \param[in] v unused for single entry + * + * \retval 0 on success, + * \retval negative error code if failed + */ static int lod_stripecount_seq_show(struct seq_file *m, void *v) { struct obd_device *dev = m->private; @@ -149,6 +231,18 @@ static int lod_stripecount_seq_show(struct seq_file *m, void *v) (__s16)(lod->lod_desc.ld_default_stripe_count + 1) - 1); } +/** + * Set default number of stripes. + * + * \param[in] file proc file + * \param[in] buffer string containing the default number of stripes + * for new files + * \param[in] count @buffer length + * \param[in] off unused for single entry + * + * \retval @count on success + * \retval negative error code otherwise + */ static ssize_t lod_stripecount_seq_write(struct file *file, const char *buffer, size_t count, loff_t *off) @@ -170,6 +264,15 @@ lod_stripecount_seq_write(struct file *file, const char *buffer, } LPROC_SEQ_FOPS(lod_stripecount); +/** + * Show number of targets. + * + * \param[in] m seq file + * \param[in] v unused for single entry + * + * \retval 0 on success + * \retval negative error code if failed + */ static int lod_numobd_seq_show(struct seq_file *m, void *v) { struct obd_device *dev = m->private; @@ -181,6 +284,15 @@ static int lod_numobd_seq_show(struct seq_file *m, void *v) } LPROC_SEQ_FOPS_RO(lod_numobd); +/** + * Show number of active targets. + * + * \param[in] m seq file + * \param[in] v unused for single entry + * + * \retval 0 on success + * \retval negative error code if failed + */ static int lod_activeobd_seq_show(struct seq_file *m, void *v) { struct obd_device *dev = m->private; @@ -192,6 +304,15 @@ static int lod_activeobd_seq_show(struct seq_file *m, void *v) } LPROC_SEQ_FOPS_RO(lod_activeobd); +/** + * Show UUID of LOD device. + * + * \param[in] m seq file + * \param[in] v unused for single entry + * + * \retval 0 on success + * \retval negative error code if failed + */ static int lod_desc_uuid_seq_show(struct seq_file *m, void *v) { struct obd_device *dev = m->private; @@ -203,7 +324,20 @@ static int lod_desc_uuid_seq_show(struct seq_file *m, void *v) } LPROC_SEQ_FOPS_RO(lod_desc_uuid); -/* free priority (0-255): how badly user wants to choose empty osts */ +/** + * Show QoS priority parameter. + * + * The printed value is a percentage value (0-100%) indicating the priority + * of free space compared to performance. 0% means select OSTs equally + * regardless of their free space, 100% means select OSTs only by their free + * space even if it results in very imbalanced load on the OSTs. + * + * \param[in] m seq file + * \param[in] v unused for single entry + * + * \retval 0 on success + * \retval negative error code if failed + */ static int lod_qos_priofree_seq_show(struct seq_file *m, void *v) { struct obd_device *dev = m->private; @@ -214,6 +348,22 @@ static int lod_qos_priofree_seq_show(struct seq_file *m, void *v) (lod->lod_qos.lq_prio_free * 100 + 255) >> 8); } +/** + * Set QoS free space priority parameter. + * + * Set the relative priority of free OST space compared to OST load when OSTs + * are space imbalanced. See lod_qos_priofree_seq_show() for description of + * this parameter. See lod_qos_thresholdrr_seq_write() and lq_threshold_rr to + * determine what constitutes "space imbalanced" OSTs. + * + * \param[in] file proc file + * \param[in] buffer string which contains the free space priority (0-100) + * \param[in] count @buffer length + * \param[in] off unused for single entry + * + * \retval @count on success + * \retval negative error code if failed + */ static ssize_t lod_qos_priofree_seq_write(struct file *file, const char __user *buffer, size_t count, loff_t *off) @@ -239,6 +389,15 @@ lod_qos_priofree_seq_write(struct file *file, const char __user *buffer, } LPROC_SEQ_FOPS(lod_qos_priofree); +/** + * Show threshold for "same space on all OSTs" rule. + * + * \param[in] m seq file + * \param[in] v unused for single entry + * + * \retval 0 on success + * \retval negative error code if failed + */ static int lod_qos_thresholdrr_seq_show(struct seq_file *m, void *v) { struct obd_device *dev = m->private; @@ -250,6 +409,23 @@ static int lod_qos_thresholdrr_seq_show(struct seq_file *m, void *v) (lod->lod_qos.lq_threshold_rr * 100 + 255) >> 8); } +/** + * Set threshold for "same space on all OSTs" rule. + * + * This sets the maximum percentage difference of free space between the most + * full and most empty OST in the currently available OSTs. If this percentage + * is exceeded, use the QoS allocator to select OSTs based on their available + * space so that more full OSTs are chosen less often, otherwise use the + * round-robin allocator for efficiency and performance. + + * \param[in] file proc file + * \param[in] buffer string containing percentage difference of free space + * \param[in] count @buffer length + * \param[in] off unused for single entry + * + * \retval @count on success + * \retval negative error code if failed + */ static ssize_t lod_qos_thresholdrr_seq_write(struct file *file, const char *buffer, size_t count, loff_t *off) @@ -275,6 +451,16 @@ lod_qos_thresholdrr_seq_write(struct file *file, const char *buffer, } LPROC_SEQ_FOPS(lod_qos_thresholdrr); +/** + * Show expiration period used to refresh cached statfs data, which + * is used to implement QoS/RR striping allocation algorithm. + * + * \param[in] m seq file + * \param[in] v unused for single entry + * + * \retval 0 on success + * \retval negative error code if failed + */ static int lod_qos_maxage_seq_show(struct seq_file *m, void *v) { struct obd_device *dev = m->private; @@ -285,6 +471,17 @@ static int lod_qos_maxage_seq_show(struct seq_file *m, void *v) return seq_printf(m, "%u Sec\n", lod->lod_desc.ld_qos_maxage); } +/** + * Set expiration period used to refresh cached statfs data. + * + * \param[in] file proc file + * \param[in] buffer string contains maximum age of statfs data in seconds + * \param[in] count @buffer length + * \param[in] off unused for single entry + * + * \retval @count on success + * \retval negative error code if failed + */ static ssize_t lod_qos_maxage_seq_write(struct file *file, const char *buffer, size_t count, loff_t *off) @@ -377,6 +574,15 @@ static void *lod_osts_seq_next(struct seq_file *p, void *v, loff_t *pos) return NULL; } +/** + * Show active/inactive status for OST found by lod_osts_seq_next(). + * + * \param[in] m seq file + * \param[in] v unused for single entry + * + * \retval 0 on success + * \retval negative error code if failed + */ static int lod_osts_seq_show(struct seq_file *p, void *v) { struct obd_device *obd = p->private; @@ -438,6 +644,15 @@ LPROC_SEQ_FOPS_RO_TYPE(lod, dt_kbytesavail); LPROC_SEQ_FOPS_RO_TYPE(lod, dt_filestotal); LPROC_SEQ_FOPS_RO_TYPE(lod, dt_filesfree); +/** + * Show whether special failout mode for testing is enabled or not. + * + * \param[in] m seq file + * \param[in] v unused for single entry + * + * \retval 0 on success + * \retval negative error code if failed + */ static int lod_lmv_failout_seq_show(struct seq_file *m, void *v) { struct obd_device *dev = m->private; @@ -449,6 +664,21 @@ static int lod_lmv_failout_seq_show(struct seq_file *m, void *v) return seq_printf(m, "%d\n", lod->lod_lmv_failout ? 1 : 0); } +/** + * Enable/disable a special failout mode for testing. + * + * This determines whether the LMV will try to continue processing a striped + * directory even if it has a (partly) corrupted entry in the master directory, + * or if it will abort upon finding a corrupted slave directory entry. + * + * \param[in] file proc file + * \param[in] buffer string: 0 or non-zero to disable or enable LMV failout + * \param[in] count @buffer length + * \param[in] off unused for single entry + * + * \retval @count on success + * \retval negative error code if failed + */ static ssize_t lod_lmv_failout_seq_write(struct file *file, const char *buffer, size_t count, loff_t *off) @@ -521,6 +751,14 @@ static const struct file_operations lod_proc_target_fops = { .release = lprocfs_seq_release, }; +/** + * Initialize procfs entries for LOD. + * + * \param[in] lod LOD device + * + * \retval 0 on success + * \retval negative error code if failed + */ int lod_procfs_init(struct lod_device *lod) { struct obd_device *obd = lod2obd(lod); @@ -589,6 +827,11 @@ out: return rc; } +/** + * Cleanup procfs entries registred for LOD. + * + * \param[in] lod LOD device + */ void lod_procfs_fini(struct lod_device *lod) { struct obd_device *obd = lod2obd(lod); -- 1.8.3.1