Platform Porting

The porting files are located in the gui_port folder. Six files need to be modified, with their filenames and functions as follows.

Filename	Description
gui_port_acc.c	Acceleration
gui_port_dc.c	Display Device
gui_port_filesystem.c	Filesystem
gui_port_ftl.c	Flash Translation Layer
gui_port_indev.c	Input Device
gui_port_os.c	Operating System

Currently, porting has been done on FreeRTOS, RT-Thread, and Windows for reference.

Acceleration

• Refer to guidef.h and gui_port_acc.c.

• Define the accelerated drawing interface depending on the platform model, generally hw_acc_blit or sw_acc_blit.

• The structure definition is as follows:

  typedef struct acc_engine
  {
      void (*blit)(draw_img_t *image, gui_dispdev_t *dc, gui_rect_t *rect);
      void (*fb_clear)(uint8_t *addr, gui_color_t color, uint32_t len);
      //todo
      void (*draw_circle)(draw_circle_t *circle, gui_dispdev_t *dc, gui_rect_t *rect);
      void (*blur)(gui_dispdev_t *dc, gui_rect_t *rect, uint8_t blur_degree, void *cache_mem);
  
      void *(* jpeg_load)(void *input, int len, int *w, int *h, int *channel);
      void (* jpeg_free)(void *);
      void *(* idu_load)(void *input);
      void (* idu_free)(void *);
      bool enable_async;
      bool enable_thread_sync;
      void *hw_acc_cache_mem; //for hardware acceleration cache memory
      uint32_t hw_acc_cache_size; //for hardware acceleration cache memory size
  
      // void (*draw_rectangle)(canvas_rectangle_t *r, struct gui_dispdev *dc);
      // void (*draw_arc)(canvas_arc_t *a, struct gui_dispdev *dc);
      // void (*draw_line)(canvas_line_t *l, struct gui_dispdev *dc);
      // void (*draw_polyline)(canvas_polyline_t *p, struct gui_dispdev *dc);
      // void (*draw_path)(draw_path_t *path, struct gui_dispdev *dc);
      // void (*draw_wave)(canvas_wave_t *w, struct gui_dispdev *dc);
      // void (*draw_palette_wheel)(canvas_palette_wheel_t *pw, struct gui_dispdev *dc);
  
      // void (*draw_svg)(void *svg, uint32_t data_length, struct gui_dispdev *dc, int x, int y,
      //                  float scale, float rotate_degree, float rotate_center_x, float rotate_center_y);
      // void (*begin_path)(canvas_path_t *data);
      // void (*move_to)(canvas_path_t *data, float x, float y);
      // void (*bezier_to)(canvas_path_t *data, float c1x, float c1y, float c2x, float c2y, float x,
      //                   float y);
      // void (*LineTo)(canvas_path_t *data, float x, float y);
  
  } acc_engine_t;
  

Display Device

• Refer to guidef.h and gui_port_dc.c.

• Define the screen width and height, framebuffer address and mode, whether the resolution is scaled, and implement the refresh function.

• The structure definition is as follows:

  typedef struct gui_dispdev
  {
      /* width and height */
      uint16_t screen_width;
      uint16_t screen_height;
      uint16_t fb_width;
      uint16_t fb_height;
      uint16_t bit_depth;
      uint16_t driver_ic_scan_line_time_us;
      uint16_t host_write_line_time_us;
      uint16_t target_w;
      uint16_t target_h;
      T_GUI_DC_TYPE type;
      T_GUI_PFB_TYPE pfb_type;
      /* pixel data */
      uint8_t *frame_buf;
      uint8_t *shot_buf;
      uint8_t *disp_buf_1;
      uint8_t *disp_buf_2;
  
      gui_rect_t section;
      uint32_t section_count;
      uint32_t section_total;
      void (*lcd_update)(struct gui_dispdev *dc);
      void (*direct_draw_bitmap_to_lcd)(int16_t x, int16_t y, int16_t width, int16_t height,
                                        const uint8_t *bitmap);
      void (*virtual_lcd_update)(struct gui_dispdev *dc);
      int (*flash_seq_trans_enable)(void);
      int (*flash_seq_trans_disable)(void);
      uint32_t (*get_lcd_us)(void);
      void (*reset_lcd_timer)(void);
      void (*lcd_te_wait)(void);
      void (*lcd_power_on)(void);
      void (*lcd_power_off)(void);
      void (*lcd_draw_sync)(void);
      uint8_t *lcd_gram;
      uint32_t frame_count;
      bool fb_measure_enable;
      bool cache_need_clean;
  } gui_dispdev_t;
  

• A typical gui_dispdev structure initialization example:

  static struct gui_dispdev dc =
  {
  #ifdef USE_DC_PFB
      .fb_height = LCD_SECTION_HEIGHT,
      .fb_width = DRV_LCD_WIDTH,
      .type = DC_RAMLESS,
  #else
      .fb_height = DRV_LCD_HEIGHT,
      .fb_width = DRV_LCD_WIDTH,
      .type = DC_SINGLE,
  #endif
      .section = {0, 0, 0, 0},
      .section_count = 0,
      .screen_width =  DRV_LCD_WIDTH,
      .screen_height = DRV_LCD_HEIGHT,
      .bit_depth = DRV_PIXEL_BITS,
      .lcd_update = port_gui_lcd_update,
  
  };
  

• In DC_SINGLE mode, the framebuffer size is screen_width * screen_height * bit_depth / 8.

• In DC_RAMLESS mode, two partial framebuffers are used, with size fb_width * fb_height * bit_depth / 8, where fb_height is the segmented height.

Supported Interface Types

The following table lists the LCD-related interfaces supported by mainstream chips. If you want to know more information, please click on the specific chip name.

SOC	8080	QSPI	RGB	MIPI	SPI
RTL8762C	Y	NA	NA	NA	Y
RTL8762D	Y	Y	NA	NA	Y
RTL8763E	Y	Y	NA	NA	Y
RTL8772G	Y	Y	Y	NA	Y
RTL8773E	Y	Y	Y	NA	Y

Note

'Y' means the driver is already included in the library. 'NA' means the driver is not yet included in the library.

Verified Screen Drivers

The following table lists the LCD-related driver IC supported by mainstream chips. If you want to know more information, please click on the specific chip name.

SOC	EK9716	ICNA3311	NT35510	NV3047	ST7701S	ST77903	ST7796	OTM8009A	SH8601A	SH8601Z	RM69330	ST7789	NV3041A
RTL8762D	NA	NA	NA	NA	NA	NA	Y	NA	NA	NA	Y	Y	Y
RTL8763E	NA	NA	Y	NA	NA	NA	NA	NA	NA	Y	NA	NA	NA
RTL8772G	Y	Y	Y	Y	Y	Y	Y	NA	NA	NA	NA	NA	NA
RTL8773E	NA	NA	NA	NA	NA	NA	NA	NA	Y	NA	NA	NA	NA

Note

'Y' means the driver is already included in the library. 'NA' means the driver is not yet included in the library.

Filesystem

• Refer to guidef.h and gui_port_filesystem.c

• Define several posix-like interfaces to operate files and directories.

• If not using a filesystem, you can fill in null pointers.

• The structure definition is as follows:

  struct gui_fs
  {
      int (*open)(const char *file, int flags, ...);
      int (*close)(int d);
      int (*read)(int fd, void *buf, size_t len);
      int (*write)(int fd, const void *buf, size_t len);
      int (*lseek)(int fd, int offset, int whence);
      /* directory api*/
      gui_dir_t *(*opendir)(const char *name);
      struct gui_fs_dirent *(*readdir)(gui_dir_t *d);
      int (*closedir)(gui_dir_t *d);
      int (*ioctl)(int fildes, int cmd, ...);
      void (*fstat)(int fildes, gui_fstat_t *buf);
  };
  

Flash Translation Layer

• Refer to guidef.h and gui_port_ftl.c

• Define three interfaces for the Flash Translation Layer: read, write, erase.

• If not using a Flash Translation Layer, you can fill in null pointers.

• The structure definition is as follows:

  struct gui_ftl
  {
      int (*read)(uintptr_t addr, uint8_t *buf, size_t len);
      int (*write)(uintptr_t addr, const uint8_t *buf, size_t len);
      int (*erase)(uintptr_t addr, size_t len);
  };
  

Input Device

• Refer to guidef.h and gui_port_indev.c

• Input devices include touchpads, keyboards, and wheels. The structure for input information is as follows:

  typedef struct gui_indev
  {
      uint16_t tp_witdh;
      uint16_t tp_height;
      uint32_t touch_timeout_ms;
      uint16_t long_button_time_ms;
      uint16_t short_button_time_ms;
      uint16_t kb_long_button_time_ms;
      uint16_t kb_short_button_time_ms;
      uint16_t quick_slide_time_ms;
  
      void (*ext_button_indicate)(void (*callback)(void));
  
      gui_touch_port_data_t *(*tp_get_data)(void);
  
      gui_wheel_port_data_t *(*wheel_get_port_data)(void);
  } gui_indev_t;
  

• If a specific input device is needed, the corresponding data acquisition function needs to be implemented in gui_indev, and the required time thresholds need to be filled in.

Touch Chips

The following table lists the touch-related IC supported by all chips. If you want to know more information, please click on the specific chip name.

SOC	CST816S	CHSC6417	FT3169	GT911	ZT2717	CST816T	GT9147
RTL8762D	Y	NA	NA	NA	NA	NA	NA
RTL8763E	NA	NA	NA	NA	NA	Y	Y
RTL8772G	NA	NA	NA	Y	Y	NA	NA
RTL8773E	Y	NA	NA	Y	NA	NA	NA

Note

'Y' means the driver is already included in the library. 'NA' means the driver is not yet included in the library.

Operating System

• Refer to guidef.h and gui_port_os.c

• Define the interfaces for thread, timer, message queue, and memory management. The structure definition is as follows:

  typedef struct gui_os_api
  {
      char *name;
      void *(*thread_create)(const char *name, void (*entry)(void *param), void *param,
                             uint32_t stack_size, uint8_t priority);
      bool (*thread_delete)(void *handle);
      bool (*thread_suspend)(void *handle);
      bool (*thread_resume)(void *handle);
      bool (*thread_mdelay)(uint32_t ms);
      uint32_t (*thread_ms_get)(void);
      uint32_t (*thread_us_get)(void);
      bool (*mq_create)(void *handle, const char *name, uint32_t msg_size, uint32_t max_msgs);
      bool (*mq_send)(void *handle, void *buffer, uint32_t size, uint32_t timeout);
      bool (*mq_send_urgent)(void *handle, void *buffer, uint32_t size, uint32_t timeout);
      bool (*mq_recv)(void *handle, void *buffer, uint32_t size, uint32_t timeout);
  
      void *(*f_malloc)(uint32_t);
      void *(*f_realloc)(void *ptr, uint32_t);
      void (*f_free)(void *rmem);
  
      void (*gui_sleep_cb)(void);
  
      void *mem_addr;
      uint32_t mem_size;
  
      uint32_t mem_threshold_size;
      void *lower_mem_addr;
      uint32_t lower_mem_size;
  
      log_func_t log;
      void (*gui_tick_hook)(void);
  } gui_os_api_t;
  

Sleep Management

To reduce power consumption and increase the device's usage time, sleep (low power) mode is supported.

In the chip manual, this low power state where peripherals can be turned off is called Deep Low Power State (DLPS). More information about DLPS can be found in the relevant SDK documentation.