การอัปเดตเฟิร์มแวร์

Functions
void	fw_hash_compute_at_boot (void)
	คำนวณและแคช digest อัตลักษณ์แบบ SHA-256 ไว้ (ราว 80 ms หนึ่งครั้ง) เป็น idempotent
const char *	fw_hash_hex (void)
	digest 64 อักขระที่แคชไว้ ไม่เป็น NULL เสมอ — ได้ "unknown" ก่อนการคำนวณ ห้าม free ค่านี้
void	fw_hash_prefix8 (char *out9)
	เขียน hex 8 อักขระแรก + NUL ลงใน out9 (ต้องมีอย่างน้อย 9 ไบต์) ไม่มีผู้เรียกที่ใดเลย
void	fw_hash_get_diagnostics (fw_hash_diag_t *out)
	เติม snapshot ข้อมูลวินิจฉัยของ hash ที่ผู้เรียกเป็นเจ้าของ สำหรับบล็อก _diag ของ bento.fw.query
void	bento_fw_handle_query (const char *json, const jsmntok_t *toks, int n_toks)
	handler ของ bento.fw.query: เป็น probe อ่านอย่างเดียวที่ต้นทุนต่ำสำหรับ metadata เรียกจาก dispatcher เท่านั้น
void	bento_fw_handle_update_begin (const char *json, const jsmntok_t *toks, int n_toks)
	handler ของ bento.fw.update.begin: เปิดคำถามยืนยัน Y/N บนจอ LCD และเลื่อน ack ไปจนกว่าจะมีการตัดสินใจ
void	bento_fw_emit_boot_complete (void)
	ส่ง bento.fw.update.complete หนึ่งครั้งต่อการบูตหนึ่งรอบ ตอนเปลี่ยนสถานะเป็น CONNECTED ครั้งแรก
void	bento_fw_on_user_decision (int approve)
	ส่งผลการตัดสินใจ Y/N จากจอ LCD ของ CM55 สำหรับคำถามยืนยันปัจจุบัน เป็น no-op เมื่อไม่มีคำถามค้างอยู่

Detailed Description

8 ฟังก์ชัน: hash ของเฟิร์มแวร์ (fw_hash_*) และกระบวนการอัปเดต (bento_fw_*) คอมไพล์เฉพาะเมื่อ ENABLE_PAGE_BENTO_BUDDY=1 (ค่าตั้งต้นคือ 0, proj_cm33_ns/Makefile:64, :305) ให้ build ใหม่หลังจาก make getlibs — ดู Flag gate (อ่านก่อน)

การประกาศ: fw_hash.h และ bento_fw.h (ซึ่งประกาศ jsmntok_t ล่วงหน้าไว้เอง จึงไม่ต้องใช้ vendor/jsmn.h) ส่วนการนำไปสร้างจริงใน fw_hash.c / bento_fw.c ถูกเก็บไว้ใน libbento_secure.a การแฟลชทุกครั้งที่สั่งมาจากฝั่ง desktop ต้องผ่านคำถามยืนยัน Y/N บนจอ LCD ของอุปกรณ์ ซึ่งแสดงอักขระ hex 8 ตัวแรกของ SHA-256 ปลายทาง ไม่มีทางลัดข้าม และไม่มีการตอบ yes ให้เองเมื่อหมดเวลา

variant ที่ใช้ได้

mtb-mpy และ mtb-only

Function Documentation

fw_hash_compute_at_boot()

void fw_hash_compute_at_boot

(

void

)

คำนวณและแคช digest อัตลักษณ์แบบ SHA-256 ไว้ (ราว 80 ms หนึ่งครั้ง) เป็น idempotent

ข้อกำหนดการเรียกใช้

คำนวณ SHA-256 ของสตริงอัตลักษณ์ที่กำหนดค่าได้แน่นอนจาก build แล้วแคช digest ในรูป hex ไว้ (ราว 80 ms หนึ่งครั้ง) เป็น idempotent (เรียกซ้ำแล้วผลเหมือนเดิม) — การเรียกครั้งที่สองเป็น no-op ถอยไปใช้ค่า sentinel "unknown" เมื่อไม่มี mbedtls หรือไม่มี symbol ของ linker ให้ใช้ ในเฟิร์มแวร์ที่ส่งมอบจริงฟังก์ชันนี้ถูกเรียกจากการนำ BLE ขึ้นแบบ lazy ไม่ใช่จาก main() call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ ble_nus_lazy.c:193 (fw_hash_compute_at_boot(); คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

fw_hash_hex()

const char * fw_hash_hex

(

void

)

digest 64 อักขระที่แคชไว้ ไม่เป็น NULL เสมอ — ได้ "unknown" ก่อนการคำนวณ ห้าม free ค่านี้

ข้อกำหนดการเรียกใช้

พอยน์เตอร์ไปยัง digest ตัวพิมพ์เล็ก 64 อักขระที่แคชไว้ + NUL ไม่เป็น NULL เสมอ — ได้ "unknown" ก่อนที่ fw_hash_compute_at_boot() จะทำงาน ห้าม free ค่านี้ call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ bento_fw.c:217 และ :378 (fw_hash_hex(), ในฐานะอาร์กิวเมนต์ s ของคำตอบต่อคำขอ คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

fw_hash_prefix8()

void fw_hash_prefix8

(

char *

out9

)

เขียน hex 8 อักขระแรก + NUL ลงใน out9 (ต้องมีอย่างน้อย 9 ไบต์) ไม่มีผู้เรียกที่ใดเลย

ข้อกำหนดการเรียกใช้

เขียน hex 8 อักขระแรก + NUL ลงใน out9 ซึ่ง ต้องมีอย่างน้อย 9 ไบต์ (ชื่อพารามิเตอร์คือข้อกำหนดนั้นเอง) ก่อนที่ digest จะถูกคำนวณ ค่านำหน้าที่ได้คือค่านำหน้าของ "unknown" ไม่มีผู้เรียกที่ใดเลย

variant ที่ใช้ได้

mtb-mpy และ mtb-only

ตัวอย่าง (เขียนขึ้นเอง — ไม่มี call site ในของที่ส่งมอบจริง)

__attribute__((used))
static void bento_ex_fw_hash_prefix8(void)
{
    fw_hash_compute_at_boot();         /* idempotent — cache the digest    */
 
    char prefix[9];                    /* contract: >= 9 bytes             */
    fw_hash_prefix8(prefix);
 
    /* prefix now holds e.g. "3fa9c21b" — show it on the physical-ack
     * prompt so the operator can match it against the desktop's hash. */
    (void)prefix;
}

fw_hash_get_diagnostics()

void fw_hash_get_diagnostics

(

fw_hash_diag_t *

out

)

เติม snapshot ข้อมูลวินิจฉัยของ hash ที่ผู้เรียกเป็นเจ้าของ สำหรับบล็อก _diag ของ bento.fw.query

ข้อกำหนดการเรียกใช้

เติม snapshot ที่ผู้เรียกเป็นเจ้าของ ซึ่งถูกเติมค่าใหม่ทุกครั้งที่ fw_hash_compute_at_boot() ทำงาน ค่านี้ถูกส่งออกไปในบล็อก _diag ของคำตอบ bento.fw.query เพื่อให้ฝั่ง desktop ตรวจได้ว่า digest คงที่ข้ามการบูตหลายรอบ call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ bento_fw.c:188 (fw_hash_get_diagnostics(&hd); คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

bento_fw_handle_query()

void bento_fw_handle_query	(	const char *	json,
		const jsmntok_t *	toks,
		int	n_toks )

handler ของ bento.fw.query: เป็น probe อ่านอย่างเดียวที่ต้นทุนต่ำสำหรับ metadata เรียกจาก dispatcher เท่านั้น

ข้อกำหนดการเรียกใช้

handler ของ bento.fw.query: เป็น probe อ่านอย่างเดียวที่ต้นทุนต่ำสำหรับ metadata ส่ง ack แบบ JSON (เวอร์ชัน, hash, _diag) ออกไปบน link ของ NUS เรียกจาก dispatcher เท่านั้น call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_commands.c:1844 (bento_fw_handle_query(json, toks, n_toks); return; คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

bento_fw_handle_update_begin()

void bento_fw_handle_update_begin	(	const char *	json,
		const jsmntok_t *	toks,
		int	n_toks )

handler ของ bento.fw.update.begin: เปิดคำถามยืนยัน Y/N บนจอ LCD และเลื่อน ack ไปจนกว่าจะมีการตัดสินใจ

ข้อกำหนดการเรียกใช้

handler ของ bento.fw.update.begin: เปิดคำถามยืนยัน Y/N บนจอ LCD แล้วส่ง ack สุดท้ายออกไป — การอนุมัติให้ ok:true พร้อมกับหยุด stream ของเซนเซอร์ไว้ (sensor_stream_stop_all()) การปฏิเสธหรือการหมดเวลาให้ค่าความผิดพลาด และถ้ามี stream ทำงานอยู่จะตอบ busy คำถามยืนยันที่ซ้ำกันถูกจำกัดอัตราไว้ภายใน 5 s เรียกจาก dispatcher เท่านั้น call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_commands.c:1847 (bento_fw_handle_update_begin(json, toks, n_toks); return; คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

bento_fw_emit_boot_complete()

void bento_fw_emit_boot_complete

(

void

)

ส่ง bento.fw.update.complete หนึ่งครั้งต่อการบูตหนึ่งรอบ ตอนเปลี่ยนสถานะเป็น CONNECTED ครั้งแรก

ข้อกำหนดการเรียกใช้

ส่ง bento.fw.update.complete หนึ่งครั้งต่อการบูตหนึ่งรอบ ตอนเปลี่ยนสถานะเป็น CONNECTED ครั้งแรกหลังบูต ฝั่ง desktop เทียบ hash กับแคชของตนเพื่อตัดสินว่าเป็นการอัปเดตที่ลงเครื่องแล้ว หรือเป็นเพียงการบูตใหม่ (ข้อมูลการผูกอุปกรณ์ (bonding) อยู่ใน RAM เท่านั้น ทุกการบูตใหม่จึงบังคับให้จับคู่กันใหม่) เป็น idempotent ภายในการบูตหนึ่งรอบ call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ ble_nus_lazy.c:92 (bento_fw_emit_boot_complete(); คอมเมนต์ที่ :89 ระบุ "...is idempotent" คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

bento_fw_on_user_decision()

void bento_fw_on_user_decision

(

int

approve

)

ส่งผลการตัดสินใจ Y/N จากจอ LCD ของ CM55 สำหรับคำถามยืนยันปัจจุบัน เป็น no-op เมื่อไม่มีคำถามค้างอยู่

ข้อกำหนดการเรียกใช้

ถูกเรียกเมื่อจอ LCD ของ CM55 คืนผลการตัดสินใจ Y/N ของคำถามยืนยันปัจจุบัน: ค่าที่ไม่ใช่ศูนย์คือให้ดำเนินการต่อ ศูนย์คือปฏิเสธ เป็น no-op เมื่อไม่มีคำถามยืนยันค้างอยู่ ack ที่ส่งไปยังฝั่ง desktop ถูกเลื่อนมาถึงจุดนี้ (bento_fw.c:328) call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ ipc_bento_buddy_bridge.c:156 (bento_fw_on_user_decision(msg->value != 0 ? 1 : 0); คือการแตะจาก CM55 ที่มาถึงทาง IPC คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้

mtb-mpy และ mtb-only