Linux SID 開發指南

1 前言

1.1 編寫目的

介紹Linux 內核中基于Sunxi 硬件平臺的SID 模塊驅動的詳細設計，為軟件編碼和維護提供基 礎。

1.2 適用范圍

內核版本Linux-5.4, Linux-4.9 的平臺。

1.3 相關人員

SID 驅動、Efuse 驅動、Sysinfo 驅動的維護、應用開發人員等。

1.4 術語、定義、縮略語

2 模塊描述

2.1 模塊功能

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

2.1.1 Chip ID 功能

對于全志的SoC 來說，ChipID 用于該SoC 的唯一標識，如A83 的ChipID 標識其在所有A83 中的唯一（目前僅保證同一型號SoC 中的ChipID 唯一）。ChipID 由4 個word（16 個byte）組成，共128bit，通常放在Efuse（見2.1.3 節）的起始4 個word。具體ChipID 的bit 含義，請參考生產制造部為每顆SoC 定義的《ChipID 燒碼規則》。

2.1.2 SoC Version 功能

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

Version，表示改版編號。

說明：這兩個信息所在的寄存器不一定都在SID 模塊內部，且各平臺位置不一，但軟件上為了統一管理，都歸屬為SID 模塊。

BSP 會返回這兩個信息的組合值，由應用去判斷和做出相應的處理。

2.1.3 Efuse 功能

對軟件來說，Efuse 中提供了一個可編程的永久存儲空間，特點是每一位只能寫一次（從0到1）。 Efuse 接口方式，Efuse 容量大于512bit 采用SRAM 方式。帶有SRAM 的硬件結構示意圖如下：

2.1.4 一些狀態位

Secure Enable標明當前系統的Security 屬性是否打開，即是否運行了SecureBoot 和SecureOS。 芯片SecureEnable 狀態位保存在SID 模塊的0xa0 寄存器。

2.2 模塊位置

SID 是一個比較獨立的模塊，在Linux 內核中沒有依賴其他子系統，在Sunxi 平臺默認是ko 方式，存放在drivers/soc/sunxi 目錄中。 SID 為其他模塊提供API 的調用方式。關系如下圖：

1）TV、Thermal、GMAC 的校準參數保存在SID 中； 2）Nand、SMP、VE 需要讀取SoC Version； 3）CE 和HDMI 會用到SID 中的一些Key； 4）Sysinfo 比較特殊，為了方便用戶空間獲取、調試SID 信息，專門設計的一個字符型設 備驅動。

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

SID 模塊在Device tree 中通常會用到兩個模塊的配置信息：sunxi-sid 以sun50iw10p1為例，需要在sun50iw10p1.dtsi 中添加節點：

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 下增加子節點secure_status, chipid, rotpk。就可以用key_info 來訪問。

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

key_info

console:/ # 00000400

2.4 模塊源碼結構

SID 驅動的源代碼目錄下：

linux-4.9，linux-5.4

./drivers/soc/sunxi/

└── sunxi-sid.c // 實現了SID對外的所有API接口

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

2.5 內核配置

此配置項一般默認開，不需要重新配置 在longan 環境中在根目錄執行./build.sh menconfig進入配置主界面，配置路徑如下：

System Type

└─>ARM system type

└─>Allwinner Ltd. SUNXI family

版

配置界面圖示：

SID 驅動本身沒有注冊為單獨的模塊，需要通過注冊sysinfo 字符驅動（實現代碼見drivers/char/sunxi-sysinfo/）來提供sysfs 節點。 在longan 環境中在根目錄執行./build.sh menconfig進入配置主界面，配置路徑如下

Device Drivers

└─>Character devices

└─>sunxi system info driver

配置界面圖示：

3 模塊設計

3.1 結構框圖

SID 驅動內部的功能劃分如下圖所示：

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

3.2 關鍵數據定義

3.2.1 常量及宏定義

3.2.1.1 key 的名稱定義

在獲取Key 的時候，調用者需要知道Key 的名稱，以此作為索引的依據。Key 名稱詳見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 都能訪問，一般可以訪問的已經在dts 定義。

3.2.2 關鍵數據結構

3.2.2.1 soc_ver_map

用于管理多個SoC 的Version 信息，方便用查表的方式實現SoC Version API。其中有兩個分量：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];

};

對于一個SoC 定義一個soc_ver_map 結構數組，使用id 和不同Version 在rev[] 中查找對應的組合值。

3.2.2.2 soc_ver_reg

SoC Version、BondingID、SecureEnable 的存儲位置因SoC 而異，所以定義了一個結構來記錄這類信息的位置，包括屬于那個模塊（基地址）、偏移、掩碼、位移等。定義見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;

};

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

3.2.3 全局變量

定義幾個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 模塊流程設計

3.3.1 SoC 信息讀取流程

本節中，這里把SoC Ver、ChipID、SecureEnable 信息統稱為“SoC 信息”，因為他們的讀取過程非常相似。都是遵循以下流程：

3.3.2 Efuse Key 讀取流程

在讀取Efuse 中Key 的時候，需要判斷是否存在、以及訪問權限，過程有點復雜，用以下流程圖進行簡單說明。

4 接口設計

4.1 接口函數

4.1.1 s32 sunxi_get_platform(s8 *buf, s32 size)

? 作用：獲取SoC 平臺的名稱，實際上是一個BSP 研發代號，如sun8iw11。 ? 參數： ? buf: 用于保存平臺名稱的緩沖區 ? size:buf 的大小 ? 返回： ? 返回buf 中平臺名稱的實際拷貝長度（如果size 小于名稱長度，返回size）。

4.1.2 int sunxi_get_soc_chipid(u8 *chipid)

? 作用：獲取SoC 的ChipID（從Efuse 中讀到的原始內容，包括數據內容和順序）。 ? 參數： ? chipid：用于保存ChipID 的緩沖區 ? 返回： ? 會返回0，無實際意義

4.1.3 int sunxi_get_serial(u8 *serial)

? 作用：獲取SoC 的序列號（由ChipID 加工而來，格式定義見《chipid 接口的實現方案》。 ? 參數： ? serial：用于保存序列號的緩沖區 ? 返回： ? 會返回0，無實際意義

4.1.4 sunxi_get_soc_chipid_str(char *serial)

? 作用：獲取SoC 的ChipID 的第一個字節，要求轉換為字符串格式。 ? 參數： ? serial：用于打印ChipID 第一個字節的緩沖區 ? 返回： ? 只會返回8（4 個字節的十六進制打印長度），無實際意義

4.1.5 int sunxi_get_soc_ft_zone_str(char *serial)

? 作用：獲取FZ ZONE 的最后一個字節，要求轉換為字符串格式。 ? 參數： ? serial：用于打印ChipID 第一個字節的緩沖區 ? 返回： ? 只會返回8（4 個字節的十六進制打印長度），無實際意義

4.1.6 int sunxi_get_soc_rotpk_status_str(char *status)

? 作用：獲取rotpk 的狀態，是否燒碼 ? 參數： ? status：用于記錄是否燒碼的緩沖區；0，未燒；1，已燒 ? 返回： ? %d 的長度，無實際意義

4.1.7 int sunxi_soc_is_secure(void)

? 作用：獲取整個系統的Secure 狀態，即安全系統是否啟用。 ? 參數： ? 無 ? 返回： ? 0，未啟用安全系統；1，啟用

4.1.8 unsigned int sunxi_get_soc_bin(void)

? 作用：用于芯片分bin，部分SoC 平臺才支持。 ? 參數： ? 無 ? 返回： ? 0: fail ? 1: normal ? 2: faster ? 3: fastest

4.1.9 unsigned int sunxi_get_soc_ver(void)

? 作用：獲取SoC 的版本信息。 ? 參數： ? 無 ? 返回： ? 返回一個十六進制的編號，需要調用者去判斷版本號然后做出相應的處理。詳情參看dts， sid 節點。

4.1.10 s32 sunxi_efuse_readn(void key_name, void buf, u32

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

4.2 內部函數

4.2.1 static s32 sid_get_base(struct device_node **pnode,

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

4.2.2 static void sid_put_base(struct device_node *pnode,

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

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

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

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

5 可測試性

/sys/class/sunxi_info/sys_info 此節點文件可以打印出一些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 此節點用于獲取指定名稱的Key 信息。方法是先寫入一個Key 名稱，然后就可以讀取到Key 的內容。執行效果如下：

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

6 其他說明

當啟用安全系統后，Non-Secure 空間將無法訪問大部分的Efuse 信息，這個時候需要通過SMC 指令來讀取這些Key 信息。此時不能再使用普通的寄存器讀接口readl()，而是調用的SMC 接口：

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

int sunxi_smc_readl(phys_addr_t addr)

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