Linux SID 開(kāi)發(fā)指南

1 前言

1.1 編寫(xiě)目的

介紹Linux 內(nèi)核中基于Sunxi 硬件平臺(tái)的SID 模塊驅(qū)動(dòng)的詳細(xì)設(shè)計(jì)，為軟件編碼和維護(hù)提供基 礎(chǔ)。

1.2 適用范圍

內(nèi)核版本Linux-5.4, Linux-4.9 的平臺(tái)。

1.3 相關(guān)人員

SID 驅(qū)動(dòng)、Efuse 驅(qū)動(dòng)、Sysinfo 驅(qū)動(dòng)的維護(hù)、應(yīng)用開(kāi)發(fā)人員等。

1.4 術(shù)語(yǔ)、定義、縮略語(yǔ)

2 模塊描述

2.1 模塊功能

SID 提供的功能可以分為四大部分：ChipID、SoC Version、Efuse 功能、一些狀態(tài)位。

2.1.1 Chip ID 功能

對(duì)于全志的SoC 來(lái)說(shuō)，ChipID 用于該SoC 的唯一標(biāo)識(shí)，如A83 的ChipID 標(biāo)識(shí)其在所有A83 中的唯一（目前僅保證同一型號(hào)SoC 中的ChipID 唯一）。ChipID 由4 個(gè)word（16 個(gè)byte）組成，共128bit，通常放在Efuse（見(jiàn)2.1.3 節(jié)）的起始4 個(gè)word。具體ChipID 的bit 含義，請(qǐng)參考生產(chǎn)制造部為每顆SoC 定義的《ChipID 燒碼規(guī)則》。

2.1.2 SoC Version 功能

嚴(yán)格講SoC Version 包含兩部分信息： 1.Bonding ID，表示不同封裝。

Version，表示改版編號(hào)。

說(shuō)明：這兩個(gè)信息所在的寄存器不一定都在SID 模塊內(nèi)部，且各平臺(tái)位置不一，但軟件上為了統(tǒng)一管理，都?xì)w屬為SID 模塊。

BSP 會(huì)返回這兩個(gè)信息的組合值，由應(yīng)用去判斷和做出相應(yīng)的處理。

2.1.3 Efuse 功能

對(duì)軟件來(lái)說(shuō)，Efuse 中提供了一個(gè)可編程的永久存儲(chǔ)空間，特點(diǎn)是每一位只能寫(xiě)一次（從0到1）。 Efuse 接口方式，Efuse 容量大于512bit 采用SRAM 方式。帶有SRAM 的硬件結(jié)構(gòu)示意圖如下：

2.1.4 一些狀態(tài)位

Secure Enable標(biāo)明當(dāng)前系統(tǒng)的Security 屬性是否打開(kāi)，即是否運(yùn)行了SecureBoot 和SecureOS。 芯片SecureEnable 狀態(tài)位保存在SID 模塊的0xa0 寄存器。

2.2 模塊位置

SID 是一個(gè)比較獨(dú)立的模塊，在Linux 內(nèi)核中沒(méi)有依賴(lài)其他子系統(tǒng)，在Sunxi 平臺(tái)默認(rèn)是ko 方式，存放在drivers/soc/sunxi 目錄中。 SID 為其他模塊提供API 的調(diào)用方式。關(guān)系如下圖：

1）TV、Thermal、GMAC 的校準(zhǔn)參數(shù)保存在SID 中； 2）Nand、SMP、VE 需要讀取SoC Version； 3）CE 和HDMI 會(huì)用到SID 中的一些Key； 4）Sysinfo 比較特殊，為了方便用戶(hù)空間獲取、調(diào)試SID 信息，專(zhuān)門(mén)設(shè)計(jì)的一個(gè)字符型設(shè) 備驅(qū)動(dòng)。

2.3 模塊device tree 配置說(shuō)明(適用Linux-5.4)

SID 模塊在Device tree 中通常會(huì)用到兩個(gè)模塊的配置信息：sunxi-sid 以sun50iw10p1為例，需要在sun50iw10p1.dtsi 中添加節(jié)點(diǎn)：

sid@3006000 {

compatible = "allwinner,sun50iw10p1-sid", "allwinner,sunxi-sid";

reg = <0x0 0x03006000 0 0x1000>;

#address-cells = <1>;

#size-cells = <1>;

/* some guys has nothing to do with nvmem */

secure_status {

reg = <0x0 0>;

offset = <0xa0>;

size = <0x4>;

};

chipid {

reg = <0x0 0>;

offset = <0x200>;

size = <0x10>;

};

rotpk {

reg = <0x0 0>;

offset = <0x270>;

size = <0x20>;

};

};

在sid 下增加子節(jié)點(diǎn)secure_status, chipid, rotpk。就可以用key_info 來(lái)訪問(wèn)。

console:/ # echo chipid > /sys/class/sunxi_info/key_info ; cat /sys/class/sunxi_info/

key_info

console:/ # 00000400

2.4 模塊源碼結(jié)構(gòu)

SID 驅(qū)動(dòng)的源代碼目錄下：

linux-4.9，linux-5.4

./drivers/soc/sunxi/

└── sunxi-sid.c // 實(shí)現(xiàn)了SID對(duì)外的所有API接口

對(duì)外提供的接口頭文件：./include/linux/sunxi-sid.h

2.5 內(nèi)核配置

此配置項(xiàng)一般默認(rèn)開(kāi)，不需要重新配置 在longan 環(huán)境中在根目錄執(zhí)行./build.sh menconfig進(jìn)入配置主界面，配置路徑如下：

System Type

└─>ARM system type

└─>Allwinner Ltd. SUNXI family

版

配置界面圖示：

SID 驅(qū)動(dòng)本身沒(méi)有注冊(cè)為單獨(dú)的模塊，需要通過(guò)注冊(cè)sysinfo 字符驅(qū)動(dòng)（實(shí)現(xiàn)代碼見(jiàn)drivers/char/sunxi-sysinfo/）來(lái)提供sysfs 節(jié)點(diǎn)。 在longan 環(huán)境中在根目錄執(zhí)行./build.sh menconfig進(jìn)入配置主界面，配置路徑如下

Device Drivers

└─>Character devices

└─>sunxi system info driver

配置界面圖示：

3 模塊設(shè)計(jì)

3.1 結(jié)構(gòu)框圖

SID 驅(qū)動(dòng)內(nèi)部的功能劃分如下圖所示：

總體上，SID 驅(qū)動(dòng)內(nèi)部可以分為兩大部分： 1.SID Register RW，封裝了對(duì)寄存器按位讀取的接口，以及獲取指定compatible 的模塊基地址等。 2.SID Api，以API 的方式提供一些功能接口：獲取Key、獲取SoC Version、獲取SecureEnable、獲取ChipID 等。

3.2 關(guān)鍵數(shù)據(jù)定義

3.2.1 常量及宏定義

3.2.1.1 key 的名稱(chēng)定義

在獲取Key 的時(shí)候，調(diào)用者需要知道Key 的名稱(chēng)，以此作為索引的依據(jù)。Key 名稱(chēng)詳見(jiàn)sunxisid.h：

1 #define EFUSE_CHIPID_NAME "chipid"

2 #define EFUSE_BROM_CONF_NAME "brom_conf"

3 #define EFUSE_BROM_TRY_NAME "brom_try"

4 #define EFUSE_THM_SENSOR_NAME "thermal_sensor"

5 #define EFUSE_FT_ZONE_NAME "ft_zone"

6 #define EFUSE_TV_OUT_NAME "tvout"

7 #define EFUSE_OEM_NAME "oem"

9 #define EFUSE_WR_PROTECT_NAME "write_protect"

10 #define EFUSE_RD_PROTECT_NAME "read_protect"

11 #define EFUSE_IN_NAME "in"

12 #define EFUSE_ID_NAME "id"

13 #define EFUSE_ROTPK_NAME "rotpk"

14 #define EFUSE_SSK_NAME "ssk"

15 #define EFUSE_RSSK_NAME "rssk"

16 #define EFUSE_HDCP_HASH_NAME "hdcp_hash"

17 #define EFUSE_HDCP_PKF_NAME "hdcp_pkf"

18 #define EFUSE_HDCP_DUK_NAME "hdcp_duk"

19 #define EFUSE_EK_HASH_NAME "ek_hash"

20 #define EFUSE_SN_NAME "sn"

21 #define EFUSE_NV1_NAME "nv1"

22 #define EFUSE_NV2_NAME "nv2"

23 #define EFUSE_BACKUP_KEY_NAME "backup_key"

24 #define EFUSE_RSAKEY_HASH_NAME "rsakey_hash"

25 #define EFUSE_RENEW_NAME "renewability"

26 #define EFUSE_OPT_ID_NAME "operator_id"

27 #define EFUSE_LIFE_CYCLE_NAME "life_cycle"

28 #define EFUSE_JTAG_SECU_NAME "jtag_security"

29 #define EFUSE_JTAG_ATTR_NAME "jtag_attr"

30 #define EFUSE_CHIP_CONF_NAME "chip_config"

31 #define EFUSE_RESERVED_NAME "reserved"

32 #define EFUSE_RESERVED2_NAME "reserved2"

33 /* For KeyLadder */

34 #define EFUSE_KL_SCK0_NAME "keyladder_sck0"

35 #define EFUSE_KL_KEY0_NAME "keyladder_master_key0"

36 #define EFUSE_KL_SCK1_NAME "keyladder_sck1"

37 #define EFUSE_KL_KEY1_NAME "keyladder_master_key1"

sunxi-sid.h 不是所有key 都能訪問(wèn)，一般可以訪問(wèn)的已經(jīng)在dts 定義。

3.2.2 關(guān)鍵數(shù)據(jù)結(jié)構(gòu)

3.2.2.1 soc_ver_map

用于管理多個(gè)SoC 的Version 信息，方便用查表的方式實(shí)現(xiàn)SoC Version API。其中有兩個(gè)分量：id，即BondingID；rev[]，用于保存BondingID 和Version 的各種組合值。定義在sunxi-sid.c 中：

#define SUNXI_VER_MAX_NUM 8

struct soc_ver_map {

u32 id;

u32 rev[SUNXI_VER_MAX_NUM];

};

對(duì)于一個(gè)SoC 定義一個(gè)soc_ver_map 結(jié)構(gòu)數(shù)組，使用id 和不同Version 在rev[] 中查找對(duì)應(yīng)的組合值。

3.2.2.2 soc_ver_reg

SoC Version、BondingID、SecureEnable 的存儲(chǔ)位置因SoC 而異，所以定義了一個(gè)結(jié)構(gòu)來(lái)記錄這類(lèi)信息的位置，包括屬于那個(gè)模塊（基地址）、偏移、掩碼、位移等。定義見(jiàn)sunxisid.c：

#define SUNXI_SOC_ID_INDEX 1

#define SUNXI_SECURITY_ENABLE_INDEX 2

struct soc_ver_reg {

s8 compatile[48];

u32 offset;

u32 mask;

u32 shift;

};

每個(gè)SoC 會(huì)定義一個(gè)soc_ver_reg 數(shù)組，目前各元素的定義如下： 0 - SoC Version 信息在寄存器中的位置。 1 - BondingID 信息在寄存器中的位置。 2 - SecureEnable 信息在寄存器中的位置。

3.2.3 全局變量

定義幾個(gè)static 全局變量，用于保存解析后的ChipID、SoC_Ver 等信息：

static unsigned int sunxi_soc_chipid[4]; static unsigned int sunxi_serial[4]; static int sunxi_soc_secure; static unsigned int sunxi_soc_bin; static unsigned int sunxi_soc_ver;

3.3 模塊流程設(shè)計(jì)

3.3.1 SoC 信息讀取流程

本節(jié)中，這里把SoC Ver、ChipID、SecureEnable 信息統(tǒng)稱(chēng)為“SoC 信息”，因?yàn)樗麄兊淖x取過(guò)程非常相似。都是遵循以下流程：

3.3.2 Efuse Key 讀取流程

在讀取Efuse 中Key 的時(shí)候，需要判斷是否存在、以及訪問(wèn)權(quán)限，過(guò)程有點(diǎn)復(fù)雜，用以下流程圖進(jìn)行簡(jiǎn)單說(shuō)明。

4 接口設(shè)計(jì)

4.1 接口函數(shù)

4.1.1 s32 sunxi_get_platform(s8 *buf, s32 size)

? 作用：獲取SoC 平臺(tái)的名稱(chēng)，實(shí)際上是一個(gè)BSP 研發(fā)代號(hào)，如sun8iw11。 ? 參數(shù)： ? buf: 用于保存平臺(tái)名稱(chēng)的緩沖區(qū) ? size:buf 的大小 ? 返回： ? 返回buf 中平臺(tái)名稱(chēng)的實(shí)際拷貝長(zhǎng)度（如果size 小于名稱(chēng)長(zhǎng)度，返回size）。

4.1.2 int sunxi_get_soc_chipid(u8 *chipid)

? 作用：獲取SoC 的ChipID（從Efuse 中讀到的原始內(nèi)容，包括數(shù)據(jù)內(nèi)容和順序）。 ? 參數(shù)： ? chipid：用于保存ChipID 的緩沖區(qū) ? 返回： ? 會(huì)返回0，無(wú)實(shí)際意義

4.1.3 int sunxi_get_serial(u8 *serial)

? 作用：獲取SoC 的序列號(hào)（由ChipID 加工而來(lái)，格式定義見(jiàn)《chipid 接口的實(shí)現(xiàn)方案》。 ? 參數(shù)： ? serial：用于保存序列號(hào)的緩沖區(qū) ? 返回： ? 會(huì)返回0，無(wú)實(shí)際意義

4.1.4 sunxi_get_soc_chipid_str(char *serial)

? 作用：獲取SoC 的ChipID 的第一個(gè)字節(jié)，要求轉(zhuǎn)換為字符串格式。 ? 參數(shù)： ? serial：用于打印ChipID 第一個(gè)字節(jié)的緩沖區(qū) ? 返回： ? 只會(huì)返回8（4 個(gè)字節(jié)的十六進(jìn)制打印長(zhǎng)度），無(wú)實(shí)際意義

4.1.5 int sunxi_get_soc_ft_zone_str(char *serial)

? 作用：獲取FZ ZONE 的最后一個(gè)字節(jié)，要求轉(zhuǎn)換為字符串格式。 ? 參數(shù)： ? serial：用于打印ChipID 第一個(gè)字節(jié)的緩沖區(qū) ? 返回： ? 只會(huì)返回8（4 個(gè)字節(jié)的十六進(jìn)制打印長(zhǎng)度），無(wú)實(shí)際意義

4.1.6 int sunxi_get_soc_rotpk_status_str(char *status)

? 作用：獲取rotpk 的狀態(tài)，是否燒碼 ? 參數(shù)： ? status：用于記錄是否燒碼的緩沖區(qū)；0，未燒；1，已燒 ? 返回： ? %d 的長(zhǎng)度，無(wú)實(shí)際意義

4.1.7 int sunxi_soc_is_secure(void)

? 作用：獲取整個(gè)系統(tǒng)的Secure 狀態(tài)，即安全系統(tǒng)是否啟用。 ? 參數(shù)： ? 無(wú) ? 返回： ? 0，未啟用安全系統(tǒng)；1，啟用

4.1.8 unsigned int sunxi_get_soc_bin(void)

? 作用：用于芯片分bin，部分SoC 平臺(tái)才支持。 ? 參數(shù)： ? 無(wú) ? 返回： ? 0: fail ? 1: normal ? 2: faster ? 3: fastest

4.1.9 unsigned int sunxi_get_soc_ver(void)

? 作用：獲取SoC 的版本信息。 ? 參數(shù)： ? 無(wú) ? 返回： ? 返回一個(gè)十六進(jìn)制的編號(hào)，需要調(diào)用者去判斷版本號(hào)然后做出相應(yīng)的處理。詳情參看dts， sid 節(jié)點(diǎn)。

4.1.10 s32 sunxi_efuse_readn(void key_name, void buf, u32

n) ? 作用：讀取Efuse 中的一個(gè)key 信息。 ? 參數(shù)： ? key_name - Key 的名稱(chēng)，定義詳見(jiàn)sunxi-sid.h ? buf - 用于保存Key 值的緩沖區(qū) ? size - buf 的大小 ? 返回： ? 0: success ? other: fail 版

4.2 內(nèi)部函數(shù)

4.2.1 static s32 sid_get_base(struct device_node **pnode,

void __iomem **base, s8 *compatible, u32 sec) ? 作用：從DTS 中獲取指定模塊的寄存器基地址。 ? 參數(shù)： ? pnode - 用于保存獲取到的模塊node 信息 ? base - 用于保存獲取到的寄存器基地址 ? compatible - 模塊名稱(chēng)，用于匹配DTS 中的模塊 ? 返回： ? 0: success ? other: fail

4.2.2 static void sid_put_base(struct device_node *pnode,

void __iomem *base, u32 sec) ? 作用：釋放一個(gè)模塊的基地址。 ? 參數(shù)： ? pnode - 保存模塊node 信息 ? base - 該模塊的寄存器基地址 ? 返回： ? 無(wú)

4.2.3 static u32 sid_rd_bits(s8 *name, u32 offset, u32 shift,

u32 mask, u32 sec) ? 作用：從一個(gè)模塊的寄存器中，讀取指定位置的bit 信息。 ? 參數(shù)： ? name - 模塊名稱(chēng)，用于匹配DTS 中的模塊 ? offset - 寄存器相當(dāng)于基地址的偏移 ? shift - 該bit 在寄存器中的位移 ? mask - 該bit 的掩碼值 ? 返回：

? 0,fail ? other，獲取到的實(shí)際bit 信息 版

5 可測(cè)試性

/sys/class/sunxi_info/sys_info 此節(jié)點(diǎn)文件可以打印出一些SoC 信息，包括版本信息、ChipID 等：

# cat /sys/class/sunxi_info/sys_info sunxi_platform : sun50iw10p1 sunxi_secure : secure sunxi_chipid : 00000000000000000000000000000000 sunxi_chiptype : 00000400 sunxi_batchno : 0x1

/sys/class/sunxi_info/key_info 此節(jié)點(diǎn)用于獲取指定名稱(chēng)的Key 信息。方法是先寫(xiě)入一個(gè)Key 名稱(chēng)，然后就可以讀取到Key 的內(nèi)容。執(zhí)行效果如下：

# echo chipid > /sys/class/sunxi_info/key_info ; cat /sys/class/sunxi_info/key_info 0xf1c1b200: 0x00000400 0xf1c1b204: 0x00000000 0xf1c1b208: 0x00000000 0xf1c1b20c: 0x00000000

6 其他說(shuō)明

當(dāng)啟用安全系統(tǒng)后，Non-Secure 空間將無(wú)法訪問(wèn)大部分的Efuse 信息，這個(gè)時(shí)候需要通過(guò)SMC 指令來(lái)讀取這些Key 信息。此時(shí)不能再使用普通的寄存器讀接口readl()，而是調(diào)用的SMC 接口：

目前，sunxi_smc_readl() 的實(shí)現(xiàn)在源代碼sunxi-smc.c，該文件保存在drivers/char/sunxisysinfo。

int sunxi_smc_readl(phys_addr_t addr)

目前，sunxi_smc_readl() 的實(shí)現(xiàn)在源代碼sunxi-smc.c，該文件保存在drivers/char/sunxisysinfo。