Functions
bool	cm55_controls_snapshot (ipc_controls_state_t *out)
	ให้นิยามเอง ห้ามเรียก — เติมข้อมูลลง snapshot ของ CONTROLS_STATE บนบอร์ดที่ CM55 เป็นเจ้าของบัสของ controls
lv_obj_t *	game_sprite_create (lv_obj_t parent, const lv_image_dsc_t dsc)
	ให้นิยามเอง ห้ามเรียก — สร้าง sprite ชนิดภาพขึ้นจริงให้ widget manager
const lv_image_dsc_t *	game_sprite_lookup (int sprite_id)
	ให้นิยามเอง ห้ามเรียก — แปลง sprite id ของโปรเจกต์ให้เป็น descriptor ที่คอมไพล์ไว้
void	game_sprite_set (lv_obj_t sprite, const lv_image_dsc_t dsc)
	ให้นิยามเอง ห้ามเรียก — สลับภาพบนอ็อบเจ็กต์ sprite ที่มีอยู่แล้ว
void	ipc_ui_ext_clear_all (void)
	ให้นิยามเอง ห้ามเรียก — รีเซ็ตสิ่งที่ opcode ส่วนขยายของตนทิ้งค้างไว้ให้ทำงานอยู่
bool	ipc_ui_ext_dispatch (uint32_t cmd, const uint8_t *data)
	ให้นิยามเอง ห้ามเรียก — dispatch ส่วนขยายของโปรเจกต์สำหรับ opcode ย่าน UI ที่ยังไม่มีตัวจัดการ
uint16_t	ipc_ui_platform_diag (uint32_t *out, uint16_t max_words)
	weak hook ที่ strong definition ของมันส่งมอบมาใน libbento_cm55.a — เป็นตัวเข้าถึงข้อมูลวินิจฉัย (diagnostics) ของจอแสดงผลขนาด 10 เวิร์ดที่รองรับอย่างเป็นทางการ

Detailed Description

dist/ipc_core/overridable.txt ระบุ symbol ไว้ 7 ตัวพอดี archive นิยาม symbol แต่ละตัวเป็น weak (ตรวจยืนยันโดยฝ่าย RED ด้วย nm : เป็น symbol ชนิด W ใน libbento_ipc.a) โปรเจกต์หนึ่งใส่ strong definition มาหนึ่งตัว แล้ว linker จะเลือกใช้ตัวนั้นโดยไม่แจ้งอะไร สิ่งเหล่านี้เป็นสิ่งที่ต้อง นิยามเอง ไม่ใช่สิ่งที่ เรียกใช้ — ทุก "hit" ของชื่อเหล่านี้ในเทมเพลตคือการนิยาม หน้าคู่มืออ้างอิงที่บอกให้ "call this" จึงเป็นสิ่งที่ผิด ตัวอย่างทุกตัวด้านล่างจึงเป็นการนิยามเพื่อเขียนทับด้วย strong definition ของเทมเพลตเอง อ้างอิงด้วยชื่อไฟล์และหมายเลขบรรทัด ไม่มีไฟล์นิยามเหล่านั้นไฟล์ใดมี marker ของ snippet อยู่ จุดต่าง ๆ จึงยกมาเป็นข้อความแทน

variant ที่ใช้ได้: mtb-mpy และ mtb-only (ทั้ง 7 ตัว)

Function Documentation

◆ cm55_controls_snapshot()

bool cm55_controls_snapshot ( ipc_controls_state_t * out )

ให้นิยามเอง ห้ามเรียก — เติมข้อมูลลง snapshot ของ CONTROLS_STATE บนบอร์ดที่ CM55 เป็นเจ้าของบัสของ controls

ข้อกำหนดการเรียกใช้: ประกาศไว้ใน ipc_communication.h (shared include) ไม่ได้ประกาศไว้ใน header ของ archive เอง IPC service ที่อยู่ใน archive เรียกฟังก์ชันนี้เมื่อ CM33_NS ขอ IPC_CMD_CONTROLS_STATE (0xC6) ส่วนค่าปริยายชนิด weak ไม่รายงานอะไรเลย การเขียนทับ (override) ด้วย strong definition จะเติม out จากไบต์ capsense/pot ที่แคชไว้จากการวนอ่านเซนเซอร์ฝั่ง CM55 — คือฟิลด์บน GFX task ที่มีผู้เขียนรายเดียวตามที่หัวข้อ ipc_sensorhub_feed_capsense อธิบายไว้ — และคืนค่า false เมื่อ out เป็น NULL ให้นิยามฟังก์ชันนี้เฉพาะบนบอร์ดที่ CM55 เป็นเจ้าของบัสของ controls เท่านั้น

variant ที่ใช้ได้: mtb-mpy และ mtb-only

ตัวอย่าง — การเขียนทับด้วย strong definition (เทมเพลต): template/proj_cm55/modules/cm55_sensor_poll/cm55_sensor_poll.c:349 — bool cm55_controls_snapshot(ipc_controls_state_t *out) เริ่มด้วยตัวกัน (guard) NULL แล้วคัดลอกค่าที่แคชไว้ s_caps_btn0 / s_caps_btn1 / s_caps_slider / pot ลงใน *out

◆ game_sprite_create()

lv_obj_t * game_sprite_create	(	lv_obj_t *	parent,
		const lv_image_dsc_t *	dsc )

ให้นิยามเอง ห้ามเรียก — สร้าง sprite ชนิดภาพขึ้นจริงให้ widget manager

ข้อกำหนดการเรียกใช้: ui_widget_mgr_create_sprite() ที่อยู่ใน archive เรียกฟังก์ชันนี้เพื่อสร้าง sprite ชนิดภาพขึ้นจริงภายใต้ parent ของ widget manager ส่วนค่าปริยายชนิด weak คืนค่า NULL ซึ่ง manager รายงานออกมาเป็น -2 ("no sprite engine") การเขียนทับด้วย strong definition ต้องสร้างอ็อบเจ็กต์ภาพของ LVGL เป็นลูกของ parent ตั้งแหล่งภาพเป็น dsc แล้วคืนอ็อบเจ็กต์นั้นกลับมา ทำงานใน GFX-task context (IPC switch)

variant ที่ใช้ได้: mtb-mpy และ mtb-only

ตัวอย่าง — การเขียนทับด้วย strong definition (เทมเพลต): template/proj_cm55/modules/game_sprites_mpy/game_sprite_engine.c:16 — lv_image_create(parent) แล้วตามด้วย lv_image_set_src(img, dsc).

◆ game_sprite_lookup()

const lv_image_dsc_t * game_sprite_lookup ( int sprite_id )

ให้นิยามเอง ห้ามเรียก — แปลง sprite id ของโปรเจกต์ให้เป็น descriptor ที่คอมไพล์ไว้

ข้อกำหนดการเรียกใช้: แปลง sprite id ของโปรเจกต์ (BENTO_SPR_*) ให้เป็น descriptor ที่คอมไพล์ไว้ switch ที่อยู่ใน archive เรียกฟังก์ชันนี้ที่ ipc_ui.c:822 ภายใน case IPC_CMD_UI_SPRITE_FRAME: แล้วส่งผลลัพธ์ต่อให้ ui_widget_mgr_set_sprite_image() ต้องคืนค่า NULL สำหรับ id ที่อยู่นอกช่วง การเขียนทับในเทมเพลตตรวจขอบเขตกับ BENTO_SPR_COUNT และมี _Static_assert กำกับว่าขนาดของ registry ตรงกับค่านั้น เทมเพลตประกาศ prototype ไว้เองในไฟล์ (game_sprite_registry.c:17) เพราะไม่มี header ที่ส่งมอบมาตัวใดประกาศไว้

variant ที่ใช้ได้: mtb-mpy และ mtb-only

ตัวอย่าง — การเขียนทับด้วย strong definition (เทมเพลต): template/proj_cm55/modules/game_sprites_mpy/game_sprite_registry.c:52.

◆ game_sprite_set()

void game_sprite_set	(	lv_obj_t *	sprite,
		const lv_image_dsc_t *	dsc )

ให้นิยามเอง ห้ามเรียก — สลับภาพบนอ็อบเจ็กต์ sprite ที่มีอยู่แล้ว

ข้อกำหนดการเรียกใช้: สลับภาพบนอ็อบเจ็กต์ sprite ที่มีอยู่แล้ว โดย ui_widget_mgr_set_sprite_image() ที่อยู่ใน archive เป็นผู้เรียก ต้องเป็น no-op เมื่อ sprite หรือ descriptor เป็น NULL ทำงานใน GFX-task context

variant ที่ใช้ได้: mtb-mpy และ mtb-only

ตัวอย่าง — การเขียนทับด้วย strong definition (เทมเพลต): template/proj_cm55/modules/game_sprites_mpy/game_sprite_engine.c:25 — ตัวกัน NULL แล้วตามด้วย lv_image_set_src(sprite, dsc).

◆ ipc_ui_ext_clear_all()

void ipc_ui_ext_clear_all ( void )

ให้นิยามเอง ห้ามเรียก — รีเซ็ตสิ่งที่ opcode ส่วนขยายของตนทิ้งค้างไว้ให้ทำงานอยู่

ข้อกำหนดการเรียกใช้: เป็นจุดเขียนทับ (override) ของสายส่วนขยาย ถูกเรียกจากส่วนที่จัดการ IPC_CMD_UI_CLEAR_ALL ใน archive เมื่อสคริปต์ MicroPython ตัวใหม่เริ่มทำงาน ไม่ได้ประกาศไว้ใน header ที่ส่งมอบมาตัวใดเลย (bento_secure_undeclared.h: "WEAK. Define your own; yours wins at link time") ให้นิยามฟังก์ชันนี้เพื่อรีเซ็ตสิ่งที่ opcode ส่วนขยายของตนทิ้งค้างไว้ให้ทำงานอยู่ — เทมเพลตใช้มันหยุด marquee ของ DFR0522 และล้าง matrix ให้ว่าง เพื่อไม่ให้ผลลัพธ์ของผู้ใช้คนก่อนทำงานค้างต่อไปใต้โปรแกรมของคนถัดไป ทำงานใน GFX-task context คืนค่า void

variant ที่ใช้ได้: mtb-mpy และ mtb-only

ตัวอย่าง — การเขียนทับด้วย strong definition (เทมเพลต): template/proj_cm55/modules/dfr0522_rgb/dfr0522_ipc.c:37 — void ipc_ui_ext_clear_all(void) { (void)dfr0522_clear(); }.

◆ ipc_ui_ext_dispatch()

bool ipc_ui_ext_dispatch	(	uint32_t	cmd,
		const uint8_t *	data )

ให้นิยามเอง ห้ามเรียก — dispatch ส่วนขยายของโปรเจกต์สำหรับ opcode ย่าน UI ที่ยังไม่มีตัวจัดการ

Project extension dispatch hook for UI-band IPC opcodes not handled by the built-in switch (weak default returns false / no-op). Called from process_ui_command() in GFX-task context, so implementations may touch the display / GFX resources (e.g. the QWA309 DFR0522 RGB matrix on display I2C).

Parameters

cmd	The IPC opcode (IPC_CMD_UI_* range).
data	Pointer to the raw 128-byte IPC payload (ipc_msg_t.data).

Returns: true if the opcode was handled.

ข้อกำหนดการเรียกใช้: "Project extension dispatch hook for UI-band IPC opcodes not handled by the built-in switch (weak default returns false / no-op). Called from \c process_ui_command() in GFX-task context, so implementations may touch the display / GFX resources" (ipc_ui.h) data ชี้ไปที่ IPC payload ดิบขนาด 128 ไบต์ ให้คืนค่า true เมื่อ opcode นั้นถูกจัดการแล้ว โปรเจกต์หนึ่งอาจเขียนทับฟังก์ชันนี้ได้ ครั้งเดียว เมื่อมีหลายคุณสมบัติอาศัย hook เดียวกัน ให้ต่อกันเป็นสายจาก strong definition เพียงตัวเดียว ตามที่เทมเพลตทำ

variant ที่ใช้ได้: mtb-mpy และ mtb-only

ตัวอย่าง — การเขียนทับด้วย strong definition (เทมเพลต): template/proj_cm55/modules/ipc_ui_ext/ipc_ui_ext_chain.c:41 — ลอง dfr0522_ext_dispatch(cmd, data) ก่อน แล้วจึงเป็น handler ของเสียง SFX โดยคืนค่า true ที่รายแรกที่รับงานไป

◆ ipc_ui_platform_diag()

uint16_t ipc_ui_platform_diag	(	uint32_t *	out,
		uint16_t	max_words )

weak hook ที่ strong definition ของมันส่งมอบมาใน libbento_cm55.a — เป็นตัวเข้าถึงข้อมูลวินิจฉัย (diagnostics) ของจอแสดงผลขนาด 10 เวิร์ดที่รองรับอย่างเป็นทางการ

ข้อกำหนดการเรียกใช้: ต้องมี max_words >= 10 (มิฉะนั้นคืนค่า 0) และคืนมา 10 เวิร์ด ได้แก่ สถานะ DC IRQ, จำนวนนับของ DC frame / underflow / bus-error, จำนวนครั้งที่ GPU กู้คืน, ตัวนับ flush start / ready / timeout, ค่าสูงสุดที่ stack ของ GFX task เคยใช้ และเปอร์เซ็นต์เวลาว่าง นี่คือเส้นทางเข้าถึงจากภายนอกที่รองรับอย่างเป็นทางการสำหรับ g_tesaiot_display_diag ของ display controller — ให้อ้างอิงและใช้งานผ่านตัวเข้าถึงนี้ ไม่ใช่ผ่านตัว struct เปิดออกให้ MicroPython ในชื่อ ui._diag() (เฉพาะ mtb-mpy ส่วนโค้ด C บน mtb-only เรียกได้โดยตรง) archive มีเพียง weak stub เท่านั้น ส่วน strong definition ส่งมอบมาภายใน libbento_cm55.a โปรเจกต์ที่ใช้ display controller ที่ส่งมอบมาจึงมีอยู่แล้ว

variant ที่ใช้ได้: mtb-mpy และ mtb-only

ตัวอย่าง — strong definition (อยู่ใน archive): TESAIoT_KIT_PSE84_AI-Micropython-BentoClaw/proj_cm55/modules/lvgl_display/controller/tesaiot_display.c:593-609 (คอมไพล์รวมอยู่ใน libbento_cm55.a ไม่ได้ส่งมอบมาเป็นซอร์ส): ตัวกัน max_words , ฟิลด์ของ g_tesaiot_display_diag 9 ฟิลด์ลงใน out[0..8] , เปอร์เซ็นต์เวลาว่างลงใน out[9] , return 10

Functions