Linux UWB Stack实现——MCPS调度接口（数据结构）

MCPS（MAC Common Part Sublayer，媒介访问控制（Medium Access Control）公共部分子层）调度接口，文件：include\net\mcps802154_schedule.h。

MCPS访问方法

// MCPS 802154 访问方法
enum mcps802154_access_method {
	MCPS802154_ACCESS_METHOD_NOTHING,
	MCPS802154_ACCESS_METHOD_IMMEDIATE_RX, //立即接收访问方法
	MCPS802154_ACCESS_METHOD_IMMEDIATE_TX, //立即发送访问方法
	MCPS802154_ACCESS_METHOD_MULTI,  //多帧访问方法
	MCPS802154_ACCESS_METHOD_VENDOR, //供应商操作方法
};

mcps802154_access_vendor_ops

该结构体定义了一些函数指针，用于实现供应商特定的访问协议的回调函数，在访问方法为MCPS802154_ACCESS_METHOD_VENDOR时使用。
每个回调函数都可以返回0以继续访问，返回1以停止访问，或者返回错误。

• 如果访问被停止，则使用mcps802154_access.timestamp_dtu和mcps802154_access.duration_dtu来计算下一次访问，除非duration为0，当在该情况下，将从驱动程序请求当前日期。
• 在发生错误的情况下，设备将转换到broken状态。
• 如果回调函数缺失，将视为错误，但&mcps802154_access_vendor_ops.handle与.schedule_change缺失除外，被忽略。

struct mcps802154_access_vendor_ops {
	/*
	 * 匿名结构体，需要在所有访问操作之前声明，与mcps802154_access_ops之中情况相似，均为access_done函数指针
	 */
	struct {
		void (*access_done)(struct mcps802154_access *access);
	};

	int (*handle)(struct mcps802154_access *access);

	int (*rx_frame)(struct mcps802154_access *access);

	int (*rx_timeout)(struct mcps802154_access *access);

	int (*rx_error)(struct mcps802154_access *access,
			enum mcps802154_rx_error_type error);

	int (*tx_done)(struct mcps802154_access *access);

	int (*broken)(struct mcps802154_access *access);

	int (*schedule_change)(struct mcps802154_access *access);
};

• 匿名结构成员->access_done，该结构有一个匿名结构成员，在所有操作访问之前都需要声明。该成员定义了一个名为access_done的函数指针。无论访问操作是否成功，都会在访问操作完成后调用此函数。即，对于所有MCPS访问，都需要为访问操作设定一个访问完成回调函数。
  其他函数指针：
• handle，一旦访问开始即调用，为NULL时，忽略；
• rx_frame，当接收到帧时进行回调。为NULL时，报错。
• rx_timeout，当接收超时时回调，为NULL时，报错。
• rx_error，当接收错误时回调，为NULL时，报错。
• tx_done，当发送完成之后调用。
• broken，当发生不可修复的错误时调用，若为NULL，报错。
• schedule_change，当调度改变时调用，为NULL时，忽略。

mcps802154域

struct mcps802154_region {
	/**
	 * @ops: 域回调函数
	 */
	const struct mcps802154_region_ops *ops;
};

struct mcps802154_region，用于表示一个开放域实例。域处理程序（region handlers）可以在它的后面添加私有数据（private data）。
当前的mcps802154域仅定义了一个指向域回调函数操作的指针。
通过域的定义，不同的域处理程序可以实现在同一统一接口下，实现不同区域处理程序，并且各自管理自己的数据。

struct mcps802154_region_ops {
	/**
	 * @owner: 指向拥有此域的模块的指针，大多数情况下为THIS_MODULE。
	 */
	struct module *owner;
	/**
	 * @name: 域名称
	 */
	const char *name;
	/**
	 * @registered_entry: Entry in list of registered regions.
	 */
	struct list_head registered_entry;
	/**
	 * @open: 打开域的一个实例，返回一个新的域实例。若发生错误返回NULL。
	 */
	struct mcps802154_region *(*open)(struct mcps802154_llhw *llhw);
	/**
	 * @close: Close a region instance.
	 */
	void (*close)(struct mcps802154_region *region);
	/**
	 * @set_parameters: Set region parameters, may be NULL.
	 */
	int (*set_parameters)(struct mcps802154_region *region,
			      const struct nlattr *attrs,
			      struct netlink_ext_ack *extack);
	/**
	 * @call: Call region procedure, may be NULL.
	 */
	int (*call)(struct mcps802154_region *region, u32 call_id,
		    const struct nlattr *attrs, const struct genl_info *info);
	/**
	 * @get_access: Get access for a given region at the given timestamp.
	 * Access is valid until &mcps802154_access_ops.access_done() callback
	 * is called. Return NULL if access is not possible.
	 */
	struct mcps802154_access *(*get_access)(
		struct mcps802154_region *region, u32 next_timestamp_dtu,
		int next_in_region_dtu, int region_duration_dtu);
};

通过定义struct mcps802154_region_ops结构体类型，定义域对应的回调函数，该结构体类型包含以下成员：

1. owner：指向拥有此域的模块的指针，通常为THIS_MODULE。
2. name：域的名称，为const char类型指针。
3. registered_entry：已注册域列表入口。
4. open：打开该域的一个实例，返回一个新的域实例，如果出现错误，则返回NULL。
5. close：关闭域实例。
6. set_parameters：设置域参数，可能为NULL。
7. call：调用域过程，可能为NULL。
8. get_access：获取给定时间戳下给定域的访问权限。访问直到mcps802154_access_ops.access_done()调用之前都是有效的。如果访问不可行，返回NULL。

调度相关定义

调度更新

当调度更新时，上下文环境有效。

struct mcps802154_schedule_update {
	/**
	 * @expected_start_timestamp_dtu: 基于当前访问日期，以及新调度安排在已有调度计划之后，得到的期望开始时间戳。
	 */
	u32 expected_start_timestamp_dtu;
	/**
	 * @start_timestamp_dtu: 调度开始日期，对于无限调度可能会太远
	 */
	u32 start_timestamp_dtu;
	/**
	 * @duration_dtu: 调度持续时间，无限调度时为0。当调度为空时，也为0。
	 */
	int duration_dtu;
	/**
	 * @n_regions: 调度中域的数量
	 */
	size_t n_regions;
};

调度器

一个开放的调度器实例。调度器可以在此结构之后附加私有数据。

struct mcps802154_scheduler {
	/**
	 * @ops: 调度器回调函数指针
	 */
	const struct mcps802154_scheduler_ops *ops;
};

调度器操作（回调）

调度器回调函数。调度器向MCPS提供一个调度计划（schedule），并在特定帧接收或调度不再有效时更新该调度。

struct mcps802154_scheduler_ops {
	struct module *owner;
	const char *name;
	struct list_head registered_entry;
	/**
	 * @open: 为设备附加一个调度器
	 */
	struct mcps802154_scheduler *(*open)(struct mcps802154_llhw *llhw);
	/**
	 * @close: 实现与调度器分离并关闭调度器
	 */
	void (*close)(struct mcps802154_scheduler *scheduler);
	/**
	 * @set_parameters: Configure the scheduler.
	 */
	int (*set_parameters)(struct mcps802154_scheduler *scheduler,
			      const struct nlattr *attrs,
			      struct netlink_ext_ack *extack);
	/**
	 * @set_region_parameters: Configure the region inside the scheduler.
	 */
	int (*set_region_parameters)(struct mcps802154_scheduler *scheduler,
				     u32 region_id, const char *region_name,
				     const struct nlattr *attrs,
				     struct netlink_ext_ack *extack);
	/**
	 * @call: 调用调度器的特定处理流程的函数指针。
	 */
	int (*call)(struct mcps802154_scheduler *scheduler, u32 call_id,
		    const struct nlattr *attrs, const struct genl_info *info);
	/**
	 * @call_region: Call region specific procedure.
	 */
	int (*call_region)(struct mcps802154_scheduler *scheduler,
			   u32 region_id, const char *region_name, u32 call_id,
			   const struct nlattr *attrs,
			   const struct genl_info *info);
	/**
	 * @update_schedule: 该函数指针完成schedule初始化以及更新.
	 */
	int (*update_schedule)(
		struct mcps802154_scheduler *scheduler,
		const struct mcps802154_schedule_update *schedule_update,
		u32 next_timestamp_dtu);
	/**
	 * @ranging_setup: 调用配置测距，为临时接口。
	 */
	int (*ranging_setup)(
		struct mcps802154_scheduler *scheduler,
		const struct mcps802154_nl_ranging_request *requests,
		unsigned int n_requests);
};

调度器回调函数结构体struct mcps802154_scheduler_ops，包括以下成员：

1. owner：指向拥有这个调度器的模块的指针。
2. name：调度器的名称。
3. registered_entry：注册的调度器列表入口。
4. open：为设备附加一个调度器，通过open函数指针，底层设备返回指向调度器的指针。
5. close：将调度器分离并关闭调度器。
6. set_parameters：配置调度器的函数指针。
7. set_region_parameters：配置调度器内部区域的函数指针。
8. call：调用调度器的特定处理流程的函数指针。
9. call_region：调用特定域的过程的函数指针。
10. update_schedule: 该函数指针完成schedule初始化以及更新。
11. ranging_setup: 调用配置测距，为临时接口。

此外，结构体成员中还包括一些参数，例如attrs和extack用于确定调度器的参数设置等。

补充知识

Linux内核模块——THIS_MODULE

THIS_MODULE 是一个宏，它用于在 Linux 内核模块中获取对当前模块的引用。定义在linux/module.h头文件中，用于获取当前正在执行的模块的指针。

#define THIS_MODULE (&__this_module)

__this_module是一个全局变量，其类型是struct module，表示当前模块的信息。

THIS_MODULE 可以用于获取模块的一些重要信息，例如模块的名称、模块的版本、模块的作者和许可证等。通过THIS_MODULE宏，可以获取执行代码的模块指针，进而可以获取或修改模块的各种功能属性。

在 Linux 内核模块编程中，THIS_MODULE 经常与其他内核函数和宏一起使用，例如 module_init() 和 module_exit() 函数。