NVMe Linux驱动系列一：host端[multipath.c]＜34＞

nvme_read_ana_log

static int nvme_read_ana_log(struct nvme_ctrl *ctrl)
{
	u32 nr_change_groups = 0;
	int error;

	mutex_lock(&ctrl->ana_lock);
	error = nvme_get_log(ctrl, NVME_NSID_ALL, NVME_LOG_ANA, 0, NVME_CSI_NVM,
			ctrl->ana_log_buf, ctrl->ana_log_size, 0);
	if (error) {
		dev_warn(ctrl->device, "Failed to get ANA log: %d\n", error);
		goto out_unlock;
	}

	error = nvme_parse_ana_log(ctrl, &nr_change_groups,
			nvme_update_ana_state);
	if (error)
		goto out_unlock;

	/*
	 * In theory we should have an ANATT timer per group as they might enter
	 * the change state at different times.  But that is a lot of overhead
	 * just to protect against a target that keeps entering new changes
	 * states while never finishing previous ones.  But we'll still
	 * eventually time out once all groups are in change state, so this
	 * isn't a big deal.
	 *
	 * We also double the ANATT value to provide some slack for transports
	 * or AEN processing overhead.
	 */
	if (nr_change_groups)
		mod_timer(&ctrl->anatt_timer, ctrl->anatt * HZ * 2 + jiffies);
	else
		del_timer_sync(&ctrl->anatt_timer);
out_unlock:
	mutex_unlock(&ctrl->ana_lock);
	return error;
}

这段代码用于从 NVMe 控制器读取 ANA（Asymmetric Namespace Access）日志，然后解析日志并更新与每个组描述符相关联的命名空间的状态。以下是代码的功能解释：

1. u32 nr_change_groups = 0;: 初始化状态为 NVME_ANA_CHANGE 的组的数量计数器为 0。

2. mutex_lock(&ctrl->ana_lock);: 获取 ANA（Asymmetric Namespace Access）锁，以确保在读取和解析 ANA 日志期间不会发生竞争。

3. 使用 nvme_get_log 函数从控制器中读取 ANA 日志。NVME_LOG_ANA 表示日志的类型为 ANA 日志，ctrl->ana_log_buf 是用于存储日志的缓冲区，ctrl->ana_log_size 表示缓冲区的大小。

4. 如果读取日志出错，会发出警告并跳转到 out_unlock 处解锁并返回错误。

5. 使用 nvme_parse_ana_log 函数解析 ANA 日志，同时传递 &nr_change_groups 和 nvme_update_ana_state 作为回调函数。这将对每个组描述符调用 nvme_update_ana_state 函数来更新命名空间的 ANA 状态。

6. 如果解析 ANA 日志出错，会跳转到 out_unlock 处解锁并返回错误。

7. 如果存在状态为 NVME_ANA_CHANGE 的组，计算 ANATT 定时器的超时值，然后使用 mod_timer 设置 ANATT 定时器的超时时间，以便在一定时间内监视组的状态变化。

8. 如果没有状态为 NVME_ANA_CHANGE 的组，删除 ANATT 定时器。

9. mutex_unlock(&ctrl->ana_lock);: 解锁 ANA 锁，表示 ANA 日志的读取和解析完成。

10. 返回错误码，如果成功读取和解析 ANA 日志，则返回 0。

nvme_ana_work

static void nvme_ana_work(struct work_struct *work)
{
	struct nvme_ctrl *ctrl = container_of(work, struct nvme_ctrl, ana_work);

	if (ctrl->state != NVME_CTRL_LIVE)
		return;

	nvme_read_ana_log(ctrl);
}

这段代码定义了一个名为 nvme_ana_work 的工作函数，用于处理与 ANA（Asymmetric Namespace Access）相关的工作。以下是代码的功能解释：

1. struct nvme_ctrl *ctrl = container_of(work, struct nvme_ctrl, ana_work);: 通过工作结构体的成员变量 ana_work 的地址反向计算得到控制器结构体的地址。

2. if (ctrl->state != NVME_CTRL_LIVE): 检查控制器的状态是否为 NVME_CTRL_LIVE，即控制器是否处于“LIVE”状态。如果不是，说明控制器当前不可用，直接返回，不进行 ANA 日志的读取和更新操作。

3. 如果控制器处于 “LIVE” 状态，调用 nvme_read_ana_log 函数来读取和更新 ANA 日志。

这个工作函数的作用是在控制器处于 “LIVE” 状态时，定期（由 ANATT 定时器触发）读取和更新 ANA 日志，以及相应的命名空间状态。这有助于实现 ANA 功能，以确保 I/O 在多路径环境下得到适当的处理。

nvme_mpath_update

void nvme_mpath_update(struct nvme_ctrl *ctrl)
{
	u32 nr_change_groups = 0;

	if (!ctrl->ana_log_buf)
		return;

	mutex_lock(&ctrl->ana_lock);
	nvme_parse_ana_log(ctrl, &nr_change_groups, nvme_update_ana_state);
	mutex_unlock(&ctrl->ana_lock);
}

nvme_mpath_update 函数用于更新 NVMe 多路径（Multipath）相关的信息，特别是关于 Asymmetric Namespace Access (ANA) 的状态。以下是函数的逐步解释：

1. 首先，函数接收一个指向 struct nvme_ctrl 的指针 ctrl，表示 NVMe 控制器。

2. 函数检查 ctrl->ana_log_buf 是否存在。这是一个用于存储 Asymmetric Namespace Access (ANA) 日志信息的缓冲区。如果不存在，函数就直接返回，不执行任何操作。

3. 如果 ctrl->ana_log_buf 存在，函数会获取控制器的 ANA 日志信息，并对每个 ANA 组进行解析，以更新相应的命名空间状态。

4. 函数会通过获取 ctrl 的 ana_lock 互斥量来确保在处理 ANA 日志信息时没有并发问题。

5. 在解析 ANA 日志信息期间，函数调用 nvme_update_ana_state 函数来更新命名空间的 ANA 状态。函数还会计算出 ANA 日志中处于 NVME_ANA_CHANGE 状态的组的数量，以便根据需要启动 ANATT 计时器。

6. 解析完成后，函数释放 ctrl 的 ana_lock 互斥量，以确保其他线程可以访问相应的数据结构。

总之，nvme_mpath_update 函数的主要目的是解析 NVMe 控制器的 ANA 日志，更新相关的命名空间状态，并根据需要启动 ANATT 计时器，以便在一定时间后重新读取 ANA 日志。这些操作都与 NVMe 多路径功能和 Asymmetric Namespace Access 相关。

nvme_anatt_timeout

static void nvme_anatt_timeout(struct timer_list *t)
{
	struct nvme_ctrl *ctrl = from_timer(ctrl, t, anatt_timer);

	dev_info(ctrl->device, "ANATT timeout, resetting controller.\n");
	nvme_reset_ctrl(ctrl);
}

这段代码实现了 ANATT（Asymmetric Namespace Access Timeout）超时处理函数 nvme_anatt_timeout：

1. 首先，函数从计时器结构体中获取指向 struct nvme_ctrl 的指针 ctrl，这是触发计时器超时的 NVMe 控制器。

2. 函数通过 dev_info 函数向内核日志输出一条信息，表示 ANATT 已超时，需要执行控制器复位操作。

3. 最后，函数调用 nvme_reset_ctrl 函数来执行控制器的复位操作，将控制器恢复到初始状态。

在 NVMe 中，ANATT 计时器用于在某些情况下自动读取 ANA 日志，以确保命名空间的状态保持最新。当 ANATT 计时器超时时，表示已经等待了足够长的时间，需要重新读取 ANA 日志并更新相关状态。超时后，通过执行控制器复位操作，可以确保 ANA 日志得到及时的处理和更新。

nvme_mpath_stop

void nvme_mpath_stop(struct nvme_ctrl *ctrl)
{
	if (!nvme_ctrl_use_ana(ctrl))
		return;
	del_timer_sync(&ctrl->anatt_timer);
	cancel_work_sync(&ctrl->ana_work);
}

这段代码实现了 nvme_mpath_stop 函数，用于停止与 NVMe 控制器的多路径管理相关的操作：

1. 函数首先通过调用 nvme_ctrl_use_ana 函数判断是否需要使用 Asymmetric Namespace Access（ANA）特性来进行多路径管理。如果不需要使用 ANA 特性，则函数直接返回，不执行后续操作。

2. 如果需要使用 ANA 特性，则函数调用 del_timer_sync 函数来删除 ANATT 计时器，以停止 ANATT 计时器的定时运行。这将取消 ANA 日志的定时读取。

3. 接下来，函数调用 cancel_work_sync 函数来取消 ANA 相关的工作队列，确保已提交的工作任务得到取消。这可以用于停止 ANA 日志的处理和更新。

综上所述，nvme_mpath_stop 函数用于停止与 NVMe 控制器的多路径管理相关的后台操作，以便在不需要多路径管理时进行清理和关闭。

SUBSYS_ATTR_RW

#define SUBSYS_ATTR_RW(_name, _mode, _show, _store)  \
	struct device_attribute subsys_attr_##_name =	\
		__ATTR(_name, _mode, _show, _store)

这段代码定义了一个宏 SUBSYS_ATTR_RW，用于简化创建设备属性的操作。宏接受四个参数：

1. _name: 属性的名称。
2. _mode: 属性的访问权限模式，通常是 0644 或类似的值。
3. _show: 属性的读取回调函数。
4. _store: 属性的写入回调函数。

宏会使用这些参数来创建一个名为 subsys_attr_##_name 的 device_attribute 结构体，其中 _name 是传入的属性名称。该结构体用于定义设备属性的各种属性，包括名称、访问权限、读取和写入回调函数等。

使用这个宏可以更简洁地定义一组设备属性，并且避免了重复的代码书写。例如，假设你想要为一个子系统定义一个名为 attr1 的可读写属性，你可以这样使用宏：

SUBSYS_ATTR_RW(attr1, 0644, show_attr1, store_attr1);

这将自动创建一个名为 subsys_attr_attr1 的 device_attribute 结构体，然后你可以将其与你的子系统的设备关联，以实现设备属性的读取和写入。

nvme_subsys_iopolicy_show & nvme_subsys_iopolicy_store

static ssize_t nvme_subsys_iopolicy_show(struct device *dev,
		struct device_attribute *attr, char *buf)
{
	struct nvme_subsystem *subsys =
		container_of(dev, struct nvme_subsystem, dev);

	return sysfs_emit(buf, "%s\n",
			  nvme_iopolicy_names[READ_ONCE(subsys->iopolicy)]);
}

static ssize_t nvme_subsys_iopolicy_store(struct device *dev,
		struct device_attribute *attr, const char *buf, size_t count)
{
	struct nvme_subsystem *subsys =
		container_of(dev, struct nvme_subsystem, dev);
	int i;

	for (i = 0; i < ARRAY_SIZE(nvme_iopolicy_names); i++) {
		if (sysfs_streq(buf, nvme_iopolicy_names[i])) {
			WRITE_ONCE(subsys->iopolicy, i);
			return count;
		}
	}

	return -EINVAL;
}
SUBSYS_ATTR_RW(iopolicy, S_IRUGO | S_IWUSR,
		      nvme_subsys_iopolicy_show, nvme_subsys_iopolicy_store);

这段代码定义了一个名为 subsys_attr_iopolicy 的设备属性，用于控制 NVMe 子系统的 I/O 策略。设备属性包括一个读取回调函数 nvme_subsys_iopolicy_show 和一个写入回调函数 nvme_subsys_iopolicy_store。这些回调函数会在读取和写入设备属性时被调用。

读取回调函数 nvme_subsys_iopolicy_show 的目的是将子系统的当前 I/O 策略转换为对应的名称，并将结果写入到提供的缓冲区中。写入回调函数 nvme_subsys_iopolicy_store 的目的是根据传入的属性值，将对应的 I/O 策略名称转换为索引，并将该索引存储在子系统的 iopolicy 字段中。

最后，通过 SUBSYS_ATTR_RW 宏，将这两个回调函数与 subsys_attr_iopolicy 设备属性关联，从而实现了可读写的子系统属性，用于控制 NVMe 子系统的 I/O 策略。

ana_grpid_show & ana_state_show

static ssize_t ana_grpid_show(struct device *dev, struct device_attribute *attr,
		char *buf)
{
	return sysfs_emit(buf, "%d\n", nvme_get_ns_from_dev(dev)->ana_grpid);
}
DEVICE_ATTR_RO(ana_grpid);

static ssize_t ana_state_show(struct device *dev, struct device_attribute *attr,
		char *buf)
{
	struct nvme_ns *ns = nvme_get_ns_from_dev(dev);

	return sysfs_emit(buf, "%s\n", nvme_ana_state_names[ns->ana_state]);
}
DEVICE_ATTR_RO(ana_state);

这段代码定义了两个设备属性：ana_grpid 和 ana_state，用于显示 NVMe 命名空间（namespace）的 ANA（Asymmetric Namespace Access）分组 ID 和状态。

• ana_grpid_show 是一个读取回调函数，当读取 ana_grpid 属性时，它将从设备获取对应的 NVMe 命名空间，并将其 ANA 分组 ID 写入提供的缓冲区中。

• ana_state_show 也是一个读取回调函数，当读取 ana_state 属性时，它将从设备获取对应的 NVMe 命名空间，并将其 ANA 状态转换为状态名称，并将状态名称写入提供的缓冲区中。

通过 DEVICE_ATTR_RO 宏，这两个回调函数与 ana_grpid 和 ana_state 设备属性关联，从而实现了可读的属性，用于显示 NVMe 命名空间的 ANA 分组 ID 和状态。

nvme_lookup_ana_group_desc

static int nvme_lookup_ana_group_desc(struct nvme_ctrl *ctrl,
		struct nvme_ana_group_desc *desc, void *data)
{
	struct nvme_ana_group_desc *dst = data;

	if (desc->grpid != dst->grpid)
		return 0;

	*dst = *desc;
	return -ENXIO; /* just break out of the loop */
}

这段代码定义了一个函数 nvme_lookup_ana_group_desc，用于在 NVMe 控制器的 ANA 日志中查找与给定分组 ID 匹配的 ANA 分组描述。

• 当查找到与给定分组 ID 匹配的分组描述时，该函数将将匹配的分组描述复制到 data 所指向的内存中，并返回 -ENXIO。这个负返回值会在函数 nvme_parse_ana_log 中被检测到，使其停止继续解析 ANA 日志，从而达到提前退出的效果。

这种方式允许在 ANA 日志中仅解析特定分组的信息，而不需要继续解析其他分组。

nvme_mpath_add_disk

void nvme_mpath_add_disk(struct nvme_ns *ns, __le32 anagrpid)
{
	if (nvme_ctrl_use_ana(ns->ctrl)) {
		struct nvme_ana_group_desc desc = {
			.grpid = anagrpid,
			.state = 0,
		};

		mutex_lock(&ns->ctrl->ana_lock);
		ns->ana_grpid = le32_to_cpu(anagrpid);
		nvme_parse_ana_log(ns->ctrl, &desc, nvme_lookup_ana_group_desc);
		mutex_unlock(&ns->ctrl->ana_lock);
		if (desc.state) {
			/* found the group desc: update */
			nvme_update_ns_ana_state(&desc, ns);
		} else {
			/* group desc not found: trigger a re-read */
			set_bit(NVME_NS_ANA_PENDING, &ns->flags);
			queue_work(nvme_wq, &ns->ctrl->ana_work);
		}
	} else {
		ns->ana_state = NVME_ANA_OPTIMIZED;
		nvme_mpath_set_live(ns);
	}

	if (blk_queue_stable_writes(ns->queue) && ns->head->disk)
		blk_queue_flag_set(QUEUE_FLAG_STABLE_WRITES,
				   ns->head->disk->queue);
#ifdef CONFIG_BLK_DEV_ZONED
	if (blk_queue_is_zoned(ns->queue) && ns->head->disk)
		ns->head->disk->nr_zones = ns->disk->nr_zones;
#endif
}

这段代码实现了函数 nvme_mpath_add_disk，用于为 NVMe 命名空间添加多路径支持的磁盘。

函数首先检查是否应该使用 ANA（Asymmetric Namespace Access）机制来处理多路径。如果控制器支持 ANA，它将尝试根据给定的 ANA 分组 ID 查找分组描述。如果找到匹配的分组描述，将更新命名空间的 ANA 状态。如果未找到匹配的分组描述，将设置标志位 NVME_NS_ANA_PENDING，并将 ANA 工作队列添加到工作队列中以重新读取 ANA 信息。

如果控制器不支持 ANA，命名空间的 ANA 状态将设置为 NVME_ANA_OPTIMIZED，并通过调用 nvme_mpath_set_live 来启动多路径支持。

此外，如果命名空间支持稳定写入（stable writes），则会设置队列标志 QUEUE_FLAG_STABLE_WRITES。如果命名空间支持分区（zoned namespaces），则会将命名空间的分区数赋值给对应磁盘的分区数。

总之，这段代码负责初始化命名空间的多路径支持和相关的参数设置。

nvme_mpath_shutdown_disk & nvme_mpath_remove_disk

void nvme_mpath_shutdown_disk(struct nvme_ns_head *head)
{
	if (!head->disk)
		return;
	kblockd_schedule_work(&head->requeue_work);
	if (test_bit(NVME_NSHEAD_DISK_LIVE, &head->flags)) {
		nvme_cdev_del(&head->cdev, &head->cdev_device);
		del_gendisk(head->disk);
	}
}

void nvme_mpath_remove_disk(struct nvme_ns_head *head)
{
	if (!head->disk)
		return;
	/* make sure all pending bios are cleaned up */
	kblockd_schedule_work(&head->requeue_work);
	flush_work(&head->requeue_work);
	put_disk(head->disk);
}

这些代码片段实现了两个函数：nvme_mpath_shutdown_disk 和 nvme_mpath_remove_disk，用于处理多路径命名空间磁盘的关闭和移除操作。

1. nvme_mpath_shutdown_disk 函数：
   这个函数用于关闭多路径命名空间的磁盘。它会安排工作队列以重新排队未处理的 BIO（块输入/输出操作），并删除命名空间的字符设备（cdev）。如果命名空间的磁盘标志 NVME_NSHEAD_DISK_LIVE 被设置，它会从系统中删除该磁盘（使用 del_gendisk 函数）。该函数旨在在关闭系统时执行，以确保资源被正确释放。

2. nvme_mpath_remove_disk 函数：
   这个函数用于移除多路径命名空间的磁盘。它会首先安排工作队列以确保所有挂起的 BIO 被清理。然后，它会等待工作队列中的操作完成，使用 flush_work 函数。最后，它会释放命名空间的磁盘（使用 put_disk 函数），从而完全移除该磁盘对象。这个函数旨在在命名空间被移除时执行，以确保资源的正确释放。

综上所述，这两个函数用于管理多路径命名空间的磁盘关闭和移除操作，确保资源的正确释放和清理。

nvme_mpath_init_ctrl & nvme_mpath_init_identify & nvme_mpath_uninit

void nvme_mpath_init_ctrl(struct nvme_ctrl *ctrl)
{
	mutex_init(&ctrl->ana_lock);
	timer_setup(&ctrl->anatt_timer, nvme_anatt_timeout, 0);
	INIT_WORK(&ctrl->ana_work, nvme_ana_work);
}

int nvme_mpath_init_identify(struct nvme_ctrl *ctrl, struct nvme_id_ctrl *id)
{
	size_t max_transfer_size = ctrl->max_hw_sectors << SECTOR_SHIFT;
	size_t ana_log_size;
	int error = 0;

	/* check if multipath is enabled and we have the capability */
	if (!multipath || !ctrl->subsys ||
	    !(ctrl->subsys->cmic & NVME_CTRL_CMIC_ANA))
		return 0;

	if (!ctrl->max_namespaces ||
	    ctrl->max_namespaces > le32_to_cpu(id->nn)) {
		dev_err(ctrl->device,
			"Invalid MNAN value %u\n", ctrl->max_namespaces);
		return -EINVAL;
	}

	ctrl->anacap = id->anacap;
	ctrl->anatt = id->anatt;
	ctrl->nanagrpid = le32_to_cpu(id->nanagrpid);
	ctrl->anagrpmax = le32_to_cpu(id->anagrpmax);

	ana_log_size = sizeof(struct nvme_ana_rsp_hdr) +
		ctrl->nanagrpid * sizeof(struct nvme_ana_group_desc) +
		ctrl->max_namespaces * sizeof(__le32);
	if (ana_log_size > max_transfer_size) {
		dev_err(ctrl->device,
			"ANA log page size (%zd) larger than MDTS (%zd).\n",
			ana_log_size, max_transfer_size);
		dev_err(ctrl->device, "disabling ANA support.\n");
		goto out_uninit;
	}
	if (ana_log_size > ctrl->ana_log_size) {
		nvme_mpath_stop(ctrl);
		nvme_mpath_uninit(ctrl);
		ctrl->ana_log_buf = kvmalloc(ana_log_size, GFP_KERNEL);
		if (!ctrl->ana_log_buf)
			return -ENOMEM;
	}
	ctrl->ana_log_size = ana_log_size;
	error = nvme_read_ana_log(ctrl);
	if (error)
		goto out_uninit;
	return 0;

out_uninit:
	nvme_mpath_uninit(ctrl);
	return error;
}

void nvme_mpath_uninit(struct nvme_ctrl *ctrl)
{
	kvfree(ctrl->ana_log_buf);
	ctrl->ana_log_buf = NULL;
	ctrl->ana_log_size = 0;
}

这些代码片段展示了初始化和清理多路径支持的函数。

1. nvme_mpath_init_ctrl 函数：
   这个函数初始化与多路径相关的控制结构，包括互斥锁、ANATT（ANA Transition Time）定时器和用于ANA（Asymmetric Namespace Access）工作的工作队列。

2. nvme_mpath_init_identify 函数：
   这个函数在控制器初始化阶段处理多路径支持。它从控制器的NVMe标识信息中提取有关ANA支持的相关信息，如ANACAP（ANA Capabilities）、ANATT（ANA Transition Time）、nanagrpid（Namespace Group Identifier），以及ANAGRPMAX（Maximum Namespace Group ID）等。然后，它计算ANA日志页的大小，并与控制器的最大传输大小（MDTS）进行比较，以确保日志大小不超过最大传输大小。如果满足要求，它会分配ANA日志缓冲区并读取ANA日志页。

3. nvme_mpath_uninit 函数：
   这个函数在清理多路径支持时释放分配的ANA日志缓冲区。它会释放先前在 nvme_mpath_init_identify 中分配的资源，以便控制器可以正确地释放多路径支持相关的资源。

综上所述，这些函数在NVMe控制器的初始化和清理阶段管理多路径支持的资源和状态。