fpsci
1概述
PSCI 规范关注的是安全世界和正常世界之间进行电源管理的接口。
PSCI具有以下预期用途：
- 提供一个通用接口，监管软件可以使用该接口在以下情况下管理电源：
- 核心空闲管理。（core idle management）
- 动态添加和移除系统中的核心，通常称为热插拔。 （hotplug）
- 辅助核心引导。（Secibdary core boot）
- 在不同核心之间移动可信操作系统上下文。 (trusted)
- 系统关机和重启。(system shutdown and reset)
- 提供一个接口，监管软件可以与固件表（FDT和ACPI）描述一起使用，以支持电源管理代码的通用化。
2驱动功能
组成由以下所示
.
├── fpsci.c
└── fpsci.h
本驱动为开发者提供了特性：
- PSCI接口初始化以及function id 检查
- 查看PSCI 版本信息功能
- CPU_SUSPEND接口支持
- CPU hotplug 接口支持
- CPU Affinity power state 查看接口支持
- 冷启动接口支持
3数据结构
4错误码定义
#define FPSCI_SUCCESS 0
#define FPSCI_NOT_SUPPORTED -1
#define FPSCI_INVALID_PARAMS -2
#define FPSCI_DENIED -3
#define FPSCI_ALREADY_ON -4
#define FPSCI_ON_PENDING -5
#define FPSCI_INTERNAL_FAILURE -6
#define FPSCI_NOT_PRESENT -7
#define FPSCI_DISABLED -8
#define FPSCI_INVALID_ADDRESS -9
5应用示例
/example/arch/armv8/fpsci --- 展示接口特性以及cpu hotplug 特性
6API使用步骤
-
初始化PSCI模块，并且确定当前soc下支持哪些psci的functions
-
初始化之后以下接口可以被正常使用：
FPsciVersion
FPsciCpuSuspend
FPsciCpuOn
FPsciAffinityInfo
FPsciSystemReset
FPsciFeatureCheck
FPsciCpuOff
-
hotplug 功能示例
/* 需要power down 的核心,假设次核心ID为1，主动调用以下接口实现CPU_OFF */
FPsciCpuOff() ;
/* Never get here */
/* 准备唤醒核心ID为1的CPU */
unsigned long cpu_affinity ;
GetCpuAffinity(1,&cpu_affinity) ;
/* 其中0x80100000为核心1需要执行的地址 */
FPsciCpuOn(cpu_affinity,0x80100000,0) ;
7API介绍
1. FPsciInit
介绍
初始化 PSCI 驱动的接口函数。
参数
无
返回
- int: 返回值表示初始化结果，0 表示初始化成功，其他值表示初始化失败。
功能描述
- 调用 FSmccInit 函数对 SMCC 接口进行初始化。
- 调用 FPsciVersion 函数获取 PSCI 的版本信息，并打印主版本号和次版本号。
- 调用 FPsciCheckFeatures 函数检查 PSCI 支持的接口是否可用。
2. FPsciSystemReset
void FPsciSystemReset(u32 reset_type)
介绍
重置系统的接口函数。
参数
- u32 reset_type: 系统重置的类型（冷启动/热启动）。使用FPSCI_SYSTEM_RESET_TYPE_COLD 、FPSCI_SYSTEM_RESET_TYPE_WARM
返回
无
功能描述
- 该函数用于重置系统。通过 reset_type 参数指定重置的类型。
- 在调用此函数之前，请确保 PSCI 驱动已经初始化。
- 函数内部通过调用 f_psci_invoke 函数实现 PSCI 接口的调用，并传递相应的参数。
- 使用 FASSERT 宏来检查相关条件是否满足，例如检查 fpsci_support_bit_flg 和 f_psci_invoke 是否已经初始化。
注意：
- 调用该函数将会重置整个系统，请谨慎使用。该接口是否有效也与固件有关
3. FPsciVersion
介绍
获取 PSCI 实现的版本信息的接口函数。
返回
- int: PSCI 实现的版本信息。配合FPSCI_MAJOR_VERSION与 FPSCI_MINOR_VERSION 可以解析出版本号
功能描述
- 该函数用于获取 PSCI 实现的版本信息，该信息从 PSCI VERSION 接口中获取。
- 在调用此函数之前，请确保 PSCI 驱动已经初始化。
- 函数内部通过调用 f_psci_invoke 函数实现 PSCI 接口的调用，并传递相应的参数。
- 使用 FASSERT 宏来检查相关条件是否满足，例如检查 f_psci_invoke 是否已经初始化。
- 函数返回 PSCI 实现的版本信息，该信息存储在 f_psci_invoke 的返回值 res.a0 中。
4. FPsciCpuSuspend
int FPsciCpuSuspend(u32 power_state, unsigned long entry_point_address, unsigned long context_id)
介绍
暂停特定 CPU 的执行的接口函数。
参数
- u32 power_state: 要进入的电源状态。
- unsigned long entry_point_address: 在唤醒时要执行的地址。
- unsigned long context_id: 上下文特定的标识符。
返回
- int: 操作的状态代码，根据 PSCI 规范定义。
功能描述
- 该函数用于暂停特定 CPU 的执行，并返回指示操作是否成功的状态代码。
- 函数参数 power_state 指定要进入的电源状态，entry_point_address 指定唤醒时要执行的地址，context_id 为上下文特定的标识符。
- 在调用此函数之前，请确保 PSCI 驱动已经初始化。
- 函数内部通过调用 f_psci_invoke 函数实现 PSCI 接口的调用，并传递相应的参数。
- 使用 FASSERT 宏来检查相关条件是否满足，例如检查 f_psci_invoke 是否已经初始化。
- 函数返回操作的状态代码，该代码存储在 f_psci_invoke 的返回值 res.a0 中，状态代码的含义由 PSCI 规范定义。
5. FPsciCpuOn
int FPsciCpuOn(unsigned long target_cpu, unsigned long entry_point_address, unsigned long context_id)
介绍
启动特定 CPU 的接口函数。
参数
- unsigned long target_cpu: 要启动的目标 CPU。
- unsigned long entry_point_address: 在唤醒时要执行的地址。
- unsigned long context_id: 上下文特定的标识符。
返回
- int: 操作的状态代码，根据 PSCI 规范定义。
功能描述
- 该函数用于启动特定 CPU，并返回指示操作是否成功的状态代码。
- 函数参数 target_cpu 指定要启动的目标 CPU，entry_point_address 指定唤醒时要执行的地址，context_id 为上下文特定的标识符。
- 根据目标 CPU 的位宽，选择相应的 PSCI_CPU_ON 接口 ID。
- 在调用此函数之前，请确保 PSCI 驱动已经初始化。
- 函数内部通过调用 f_psci_invoke 函数实现 PSCI 接口的调用，并传递相应的参数。
- 使用 FASSERT 宏来检查相关条件是否满足，例如检查 f_psci_invoke 是否已经初始化。
- 函数返回操作的状态代码，该代码存储在 f_psci_invoke 的返回值 res.a0 中，状态代码的含义由 PSCI 规范定义。
6. FPsciAffinityInfo
int FPsciAffinityInfo(unsigned long target_affinity, u32 lowest_affinity_level)
介绍
获取特定关联级别的电源状态的接口函数。
参数
- unsigned long target_affinity: 目标关联级别。
- u32 lowest_affinity_level: 最低关联级别。
返回
- int: 指定关联级别的电源状态，根据 PSCI 规范定义。
功能描述
- 该函数用于获取特定关联级别的电源状态，并返回该电源状态的代码。
- 函数参数 target_affinity 指定要获取电源状态的关联级别，lowest_affinity_level 指定最低关联级别。
- 根据目标关联级别的位宽，选择相应的 PSCI_AFFINITY_INFO 接口 ID。
- 在调用此函数之前，请确保 PSCI 驱动已经初始化。
- 函数内部通过调用 f_psci_invoke 函数实现 PSCI 接口的调用，并传递相应的参数。
- 使用 FASSERT 宏来检查相关条件是否满足，例如检查 f_psci_invoke 是否已经初始化。
- 函数返回指定关联级别的电源状态代码，该代码存储在 f_psci_invoke 的返回值 res.a0 中，电源状态的含义由 PSCI 规范定义。
7. FPsciFeatures
int FPsciFeatures(u32 psci_fid)
介绍
检查是否支持某个 PSCI 功能的接口函数。
参数
- u32 psci_fid: 要检查的 PSCI 功能的功能 ID。
返回
功能描述
- 该函数用于检查是否支持指定的 PSCI 功能。
- 在调用此函数之前，请确保 PSCI 驱动已经初始化。
- 使用 FASSERT 宏来检查 f_psci_invoke 是否已经初始化。
- 函数内部通过调用 f_psci_invoke 函数实现 PSCI 接口的调用，并传递相应的参数。
- 函数返回值为1表示支持指定的 PSCI 功能，返回值为0表示不支持。
8. FPsciCpuOff
介绍
这是 PSCI CPU_Off 接口的包装函数，用于关闭当前 CPU。
返回
- int: 返回 'FSmcccRes' 结构体的 'a0' 字段，表示调用的结果。返回值为 0 (PSCI_SUCCESS) 表示成功，其他任何值表示发生了错误。
功能描述
- 该函数用于关闭当前 CPU，即将当前 CPU 关机。
- 在调用此函数之前，请确保 PSCI 驱动已经初始化。
- 使用 FASSERT 宏来检查 f_psci_invoke 是否已经初始化。
- 函数内部通过调用 f_psci_invoke 函数实现 PSCI 接口的调用，并传递相应的参数。
- 函数返回值为 'a0' 字段，表示 PSCI 调用的结果。返回值为 0 表示成功，其他任何值表示发生了错误。
注意事项：
- 被 CPU_OFF 关闭的核心只能通过 CPU_ON 命令重新启动。
10. FPsciCpuMaskOn
int FPsciCpuMaskOn(s32 cpu_id_mask, uintptr bootaddr)
介绍
此函数用于根据 CPU ID 掩码将指定的 CPU 打开并进入指定的入口地址。
参数
- s32 cpu_id_mask: CPU ID 掩码，用于指定要打开的 CPU。
- uintptr bootaddr: 要执行的入口地址。
返回
- int: 函数执行的结果代码。返回值为 FPSCI_SUCCESS 表示成功，其他值表示错误。
功能描述
- 通过调用
GetCpuAffinityByMask 函数获取与 CPU ID 掩码对应的 CPU 所属的集群。
- 如果获取集群失败，则返回
FPSCI_INVALID_PARAMS 错误。
- 否则，调用
FPsciCpuOn 函数将指定的集群打开，并进入指定的入口地址。
- 函数返回
FPsciCpuOn 函数的执行结果。
注意事项：
- 在调用此函数之前，请确保 PSCI 驱动已经初始化。
- 请确保
GetCpuAffinityByMask 函数已经正确实现，并能根据 CPU ID 掩码获取正确的 CPU 所属的集群信息。
