ข้อมูลวินิจฉัยและ symbol ที่ไม่มีการประกาศ

Topics
	ข้อสรุปเรื่อง extern ที่เขียนด้วยมือ

Functions
uint32_t	calculate_idle_percentage (void)
	แหล่งค่าเปอร์เซ็นต์เวลาว่างของ GFX — ให้ผูกเข้ากับ LV_SYSMON_GET_IDLE

Variables
TaskHandle_t	rtos_cm55_gfx_task_handle
	handle ของ GFX task ซึ่ง tesaiot_display_init() เป็นเจ้าของ — ห้ามแตะต้องจากภายนอก
volatile tesaiot_display_diag_t	g_tesaiot_display_diag
	struct ข้อมูลวินิจฉัยของจอแสดงผล — ให้ใช้ accessor ipc_ui_platform_diag() ไม่ใช่ตัว struct
cy_stc_scb_i2c_context_t	disp_touch_i2c_controller_context
	context ของบัส I2C ที่จอแสดงผลกับการสัมผัสใช้ร่วมกัน — ผู้ใช้ไลบรารีเป็นผู้เขียน extern เอง; ใช้ timeout ที่มีขอบเขตเท่านั้น

Detailed Description

ส่วนข้อมูลวินิจฉัย (diagnostics) ที่ archive เปิดให้เรียกใช้ และ symbol ที่ export ออกมาโดยมีการประกาศอยู่ที่ฝั่งผู้ใช้ไลบรารีเท่านั้น ได้แก่ struct ข้อมูลวินิจฉัยของจอแสดงผลและวินัยการเข้าถึงผ่าน accessor ของมัน, handle ของ GFX task, context ของบัส I2C ที่จอแสดงผลกับการสัมผัสใช้ร่วมกัน และแหล่งค่าเปอร์เซ็นต์เวลาว่างของ GFX ส่วน bento_secure_undeclared.h ที่ถูกสร้างขึ้นอัตโนมัติ และรูปแบบการเขียน extern ด้วยมือที่มาคู่กัน อธิบายไว้ใน ข้อสรุปเรื่อง extern ที่เขียนด้วยมือ

variant ที่ใช้ได้

mtb-mpy และ mtb-only

Function Documentation

calculate_idle_percentage()

uint32_t calculate_idle_percentage

(

void

)

แหล่งค่าเปอร์เซ็นต์เวลาว่างของ GFX — ให้ผูกเข้ากับ LV_SYSMON_GET_IDLE

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

เป็นแหล่งค่าเปอร์เซ็นต์เวลาว่างของ GFX ที่ archive (.a คือไฟล์ไลบรารีแบบสแตติก) export ออกมา การเรียกจริงมีเพียงจุดเดียว อยู่ในสตริงข้อมูลวินิจฉัย (diagnostics) ของหน้า Edge AI ที่อยู่ใน archive (page_edge_ai.c:1461) การใช้งานเพียงอย่างเดียวในเทมเพลต — และเป็นตัวอย่างต้นแบบที่ควรยึดเมื่อส่งมอบ — คือการผูกไว้ในไฟล์ตั้งค่าของ LVGL ได้แก่ LV_USE_SYSMON 1, extern ที่มี __ASSEMBLER__ เป็นตัวกัน (guard) และ LV_SYSMON_GET_IDLE ที่นิยามให้ชี้มาที่ฟังก์ชันนี้ เพื่อให้ system monitor ของ LVGL เองอ่านค่าตัวเดียวกันกับที่ ipc_ui_platform_diag() รายงานไว้เป็นเวิร์ดที่ 9

variant ที่ใช้ได้

mtb-mpy และ mtb-only

#define LV_USE_SYSMON 1
#if LV_USE_SYSMON
/*Get the idle percentage. E.g. uint32_t my_get_idle(void);*/
#ifndef __ASSEMBLER__
extern uint32_t calculate_idle_percentage(void);
#endif
#define LV_SYSMON_GET_IDLE calculate_idle_percentage

Variable Documentation

rtos_cm55_gfx_task_handle

TaskHandle_t rtos_cm55_gfx_task_handle

extern

handle ของ GFX task ซึ่ง tesaiot_display_init() เป็นเจ้าของ — ห้ามแตะต้องจากภายนอก

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

tesaiot_display_init() เป็นผู้สร้างและเป็นเจ้าของ การอ้างถึงทั้ง 2 จุดอยู่ภายในทั้งคู่ (tesaiot_display.c:190 เรียก xTaskNotifyFromISR จาก ISR ของ DC, และเป็นพารามิเตอร์ขาออกของ xTaskCreate ที่ :212) anti-example: ห้ามใช้มันโดยตรง — ห้าม notify ห้าม suspend และห้าม delete GFX task จากภายนอก tesaiot_display.h ประกาศตัวแปรนี้ไว้แล้ว แม้รายการ undeclared ที่ถูกสร้างขึ้นจะระบุตรงกันข้าม ห้ามเพิ่ม extern ที่เขียนด้วยมือซึ่งขัดกับการประกาศนั้น

variant ที่ใช้ได้

mtb-mpy และ mtb-only

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

/* Hand-written extern (bento_secure_undeclared.h lists the symbol;
 * dist/cm55_core/include/tesaiot_display.h carries the declaration but
 * drags the whole display include chain). Type per tesaiot_display.h: */
extern TaskHandle_t rtos_cm55_gfx_task_handle;
 
__attribute__((used))
static void bento_ex_rtos_cm55_gfx_task_handle(void)
{
    /* WRONG — do not do any of this:
     *
     *   vTaskSuspend(rtos_cm55_gfx_task_handle);   // display freezes
     *   vTaskDelete(rtos_cm55_gfx_task_handle);    // LVGL orphaned
     *   vTaskPrioritySet(rtos_cm55_gfx_task_handle, ...); // starves I2C
     *
     * The handle is owned by tesaiot_display_init(). Right usage of this
     * symbol is: none. */
    (void)rtos_cm55_gfx_task_handle;
}

g_tesaiot_display_diag

volatile tesaiot_display_diag_t g_tesaiot_display_diag

extern

struct ข้อมูลวินิจฉัยของจอแสดงผล — ให้ใช้ accessor ipc_ui_platform_diag() ไม่ใช่ตัว struct

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

มีการอ้างถึง 20 จุด ทั้งหมดอยู่ภายใน tesaiot_display.c การเข้าถึงจากภายนอกที่ตั้งใจไว้คือผ่าน accessor (ฟังก์ชันสำหรับเข้าถึงค่า) ipc_ui_platform_diag(uint32_t *out, uint16_t max_words) (tesaiot_display.c:593; ต้องมี max_words >= 10 และคืนค่า 10) — ให้เขียนเอกสารของ accessor ไม่ใช่ของตัว struct บน mtb-mpy ข้อมูล 10 เวิร์ดชุดเดียวกันนี้อ่านได้ด้วย ui._diag() ส่วนบน mtb-only ให้เรียก accessor จากฝั่ง C tesaiot_display.h ประกาศตัวแปรนี้ไว้แล้ว แม้รายการ undeclared ที่ถูกสร้างขึ้นจะระบุตรงกันข้าม

variant ที่ใช้ได้

mtb-mpy และ mtb-only

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

/* Hand-written extern — no shipped header declares this weak-hook
 * accessor. Signature copied from the strong definition,
 * tesaiot_display.c:593. */
extern uint16_t ipc_ui_platform_diag(uint32_t *out, uint16_t max_words);
 
__attribute__((used))
static void bento_ex_g_tesaiot_display_diag(void)
{
    uint32_t words[10];                 /* contract: max_words >= 10        */
    uint16_t n = ipc_ui_platform_diag(words, 10u);
    if (n != 10u) {
        return;                         /* diag hook absent or buffer small */
    }
 
    uint32_t flush_starts = words[5];   /* incrementing = frames are moving */
    uint32_t gfx_idle_pct = words[9];
    (void)flush_starts;
    (void)gfx_idle_pct;
}

disp_touch_i2c_controller_context

cy_stc_scb_i2c_context_t disp_touch_i2c_controller_context

extern

context ของบัส I2C ที่จอแสดงผลกับการสัมผัสใช้ร่วมกัน — ผู้ใช้ไลบรารีเป็นผู้เขียน extern เอง; ใช้ timeout ที่มีขอบเขตเท่านั้น

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

ไม่มี header ที่ส่งมอบมาตัวใดประกาศตัวแปรนี้ — ผู้ใช้ไลบรารีต้องเขียน extern เอง SCB ถูกเริ่มต้นค่าโดยการเปิดใช้งานจอแสดงผล (tesaiot_display.c:203) ผู้ใช้ไลบรารีห้ามเรียก Cy_SCB_I2C_Init กับตัวมัน ให้จับคู่กับ DISPLAY_I2C_CONTROLLER_HW เป็น base เสมอ ห้ามใช้ SCB ตัวอื่น บัสนี้ใช้ร่วมกัน การเรียก PDL ทุกครั้งจึงต้องใช้ timeout ที่มีขอบเขต (2 ms) ห้ามใช้ 0 หรือรอแบบไม่มีที่สิ้นสุด: ธุรกรรมเหล่านี้รันอยู่ใน GFX task ที่ความสำคัญระดับ MAX-1 และครั้งหนึ่งอุปกรณ์ที่ค้างอยู่ระหว่างการยืดสัญญาณนาฬิกา (clock stretching) เคยทำให้ GFX task จอดค้างอยู่บนบัส และทำให้ CM55 task ที่ความสำคัญต่ำกว่าทุกตัวไม่ได้รันเลย การเริ่มต้นค่าการสัมผัสใหม่หลังจาก master อีกตัว (OPTIGA) ปล่อยบัสแล้ว ต้องเลื่อนไปทำใน GFX task ผ่าน flag touch_needs_reinit ที่ถูกระบายออกใน read callback ของ LVGL

variant ที่ใช้ได้

mtb-mpy และ mtb-only

ตัวอย่าง — ผู้ใช้ไลบรารีจากภายนอกบนบัสที่ใช้ร่วมกัน (เทมเพลต)

/*******************************************************************************
 * I2C shared with display — extern from lv_port_indev / display init
 ******************************************************************************/
extern cy_stc_scb_i2c_context_t disp_touch_i2c_controller_context;
 
#define SENSOR_I2C_HW       DISPLAY_I2C_CONTROLLER_HW
#define SENSOR_I2C_CTX      (&disp_touch_i2c_controller_context)
/* BOUNDED timeout per PDL byte call. This read runs in the GFX task at MAX-1
 * priority: with the old 0 (= block forever), a wedged/clock-stretching 4000T
 * parked the GFX task on the bus and starved every lower-priority CM55 task —
 * the prime suspect for the USB joystick HID stream stall (JOYSTICK_EVIDENCE).
 * 2 ms x ~5 byte-calls caps the worst case at ~10 ms, once, then backoff. */
#define I2C_TIMEOUT_MS      (2U)

ตัวอย่าง — การเริ่มต้นค่าไดรเวอร์การสัมผัส (เทมเพลต)

static void touchpad_init(void)
{
    cy_rslt_t result = CY_RSLT_SUCCESS;
 
#if defined(MTB_CTP_GT911)
    result = mtb_gt911_init(DISPLAY_I2C_CONTROLLER_HW,
                                &disp_touch_i2c_controller_context);
 
#elif defined(MTB_CTP_ILI2511)
    result = mtb_ctp_ili2511_init(&ctp_ili2511_cfg);
#elif defined(MTB_CTP_FT5406)
    result = (cy_rslt_t)mtb_ctp_ft5406_init(&ctp_ft5406_cfg);
#endif

ตัวอย่าง — การเริ่มต้นค่าใหม่แบบเลื่อนเวลาหลัง OPTIGA ปล่อยบัส (เทมเพลต)

    /* ...context: inside the touchpad read callback - GFX task context ... */
    /* Deferred reinit after OPTIGA released I2C bus — runs in GFX task context */
    if (touch_needs_reinit) {
        touch_needs_reinit = false;
#if defined(MTB_CTP_FT5406)
        Cy_SCB_I2C_Disable(DISPLAY_I2C_CONTROLLER_HW,
                           &disp_touch_i2c_controller_context);
        Cy_SCB_I2C_Enable(DISPLAY_I2C_CONTROLLER_HW);
        mtb_ctp_ft5406_init(&ctp_ft5406_cfg);
        touch_i2c_error_count = 0;
#elif defined(MTB_CTP_GT911)
        touchpad_init();
#elif defined(MTB_CTP_ILI2511)
        touchpad_init();
#endif
    }