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() 函数。