Drivers

• Introduction

• Directory Structure

• Constraints

  • Available APIs
  • Usage

• Repositories Involved

Introduction

A kernel driver acts as a bridge between software and hardware. It allows accessing hardware resources of the OpenHarmony kernel through file system APIs, providing a mode of communication between the user space and kernel space and between processes. The main kernel drivers include mem, random, video, quickstart, hievent, and tzdriver. The preceding four types of drivers are stored in the kernel/liteos_a/drivers/char directory, and the last two types hievent and tzdriver are stored in the drivers/liteos directory. Each type of driver represents a capability. You can select a driver as required to transmit data. The following figure shows the kernel driver architecture.

Figure 1 Kernel driver architecture

Wherein:

• mem indicates the driver for accessing physical input/output (I/O) devices in user space. It is used together with the mmap function.
• random indicates the driver for devices to obtain random numbers, including true random number generators (TRNGs) and pseudorandom number generators (PRNGs). The device nodes for a TRNG and a PRNG are /dev/random and /dev/urandom, respectively. Comparatively, TRNGs provide a higher randomness.
• video indicates the framebuffer driver framework. You need to initialize APIs, register the framebuffer driver, and operate the framebuffer driver through file system APIs.

Directory Structure

/drivers/liteos
├── hievent         # Driver for event log management
├── include         # Header files exposed externally
├── tzdriver        # Used for switching and communication between the rich execution environment (REE) and trusted execution environment (TEE) and provides device nodes that can be accessed from the application layer.

Constraints

Since the tzdriver implementation is not completely open-source, third-party vendors need to obtain the support for it through cooperation.

The hievent-related capabilities are not supported currently and will be opened in the future. In addition, do not modify APIs and the format of their parameters defined in the hievent folder.

The video-related source code is stored in the video/fb.c and video/fb.h files under the third_party/NuttX directory.

Available APIs

As shown in the preceding kernel driver architecture, a kernel driver can be taken as a special file. You can call standard file system APIs, such as open, close, read, write, and ioctl to perform operations on the driver. The following lists related APIs:

• fb_register

  Function prototype:

  int fb_register(int display, int plane);

  Function description: Loads the framebuffer driver and registers the /dev/fb0 device node. If the operation is successful, 0 is returned. Otherwise, an error code is returned.

  Parameter description

  Parameter	Description
  display	Indicates the display layer number. The value is usually 0. If the hardware supports multiple display layers, this parameter can be set to other values.
  plane	Indicates the color plane. The value is usually 0.

• fb_unregister

  Function prototype:

  int fb_unregister(int display);

  Function description: Uninstalls the framebuffer driver. If the operation is successful, 0 is returned. Otherwise, an error code is returned.

  Parameter description

  Parameter	Description
  display	Indicates the display layer number.

• up_fbinitialize

  Function prototype:

  int up_fbinitialize(int display);

  Function description: Initializes the framebuffer driver. This function needs your implementation by calling fb_register to register a device node for providing the framebuffer hardware driver capability. If the operation is successful, 0 is returned. Otherwise, an error code is returned.

  Parameter description

  Parameter	Description
  display	Indicates the display layer number.

• up_fbuninitialize

  Function prototype:

  void up_fbuninitialize(int display);

  Function description: Uninstalls the framebuffer driver. This function needs your implementation by calling fb_unregister to unregister the device node. No value is returned for this function.

  Parameter description

  Parameter	Description
  display	Indicates the display layer number.

• up_fbgetvplane

  Function prototype:

  struct fb_vtable_s *up_fbgetvplane(int display, int vplane);

  Function description: Obtains a framebuffer driver handle, which needs your implementation. If the operation is successful, a valid pointer is returned. Otherwise, NULL is returned.

  Parameter description

  Parameter	Description
  display	Indicates the display layer number.
  vplane	Indicates the specified color plane.

• pse_ran_dev_register

  Function prototype:

  int pse_ran_dev_register(void);

  Function description: Initializes the PRNG device driver and registers the /dev/random device node. If the operation is successful, 0 is returned. Otherwise, an error code is returned.

  Parameter description: none

• ran_dev_register

  Function prototype:

  int ran_dev_register(void);

  Function description: Initializes the TRNG driver and registers the /dev/urandom device node. If the operation is successful, 0 is returned. Otherwise, an error code is returned.

  Parameter description: none

• mem_dev_register

  Function prototype:

  int mem_dev_register(void);

  Function description: Initializes the mem driver and registers the /dev/mem device node. If the operation is successful, 0 is returned. Otherwise, an error code is returned.

  Parameter description: none

Usage

• The following uses the framebuffer driver as an example:

int up_fbinitialize(int display)
{
    // Provide framebuffer hardware driver capabilities. The specific code logic needs your implementation.
}

void up_fbuninitialize(int display)
{
    // This function is used together with up_fbinitialize. The specific code logic needs your implementation.
}

struct fb_vtable_s *up_fbgetvplane(int display, int vplane)
{
    // Register a hardware driver based on information described by the fb_vtable_s structure. You can use the driver capabilities through the video framework layer. The specific code logic needs your implementation.
}

int FrameBufferFunc(void)
{
    int ret;
    int fd = -1;
    struct hifb_info info;
    char *pShowScreen = NULL;

    ret = fb_register(0, 0); // Register the /dev/fb0 device node. This function will call the preceding functions to enable hardware driver capabilities.
    if (ret != 0) {
        return -1;
    }

    fd = open(file, O_RDWR, 0);  
    if (fd < 0) {
        return -1;
    }
 
    if (ioctl(fd, FBIOGET_SCREENINFO_HIFB, &info) < 0) {
        return -1;
    }
    info.vinfo.xres = 1920;
    info.vinfo.yres = 1080;
    info.oinfo.sarea.w = 1920;
    info.oinfo.sarea.h = 1080;
    info.oinfo.bpp = 16;
    info.activate = 0;
    info.vinfo.fmt = HIFB_FMT_ARGB1555;

    if (ioctl(fd, FBIOPUT_SCREENINFO_HIFB, &info) < 0) {
        return -1;
    }

    if (ioctl(fd, FBIOGET_SCREENINFO_HIFB, &info) < 0) {
        return -1;
    }

    pShowScreen = mmap(HI_NULL, info.oinfo.fblen, PROT_READ | PROT_WRITE, MAP_SHARED, pstInfo->fd, 0);
    if (pShowScreen == -1) {
        return -1;
    }

    // Fill in the memory to which pShowScreen points and display the graphics through the ioctl call.

    munmap(pShowScreen, info.oinfo.fblen); 
  
    close(fd);

    ret = fb_unregister(0);
    if (ret != 0) {
        return -1;
    }
}

Repositories Involved

Kernel subsystem

drivers_liteos

kernel_liteos_a