Getting the build ID from an ELF image (elf_id.h)

The API is defined in the header file sysroot-*-kos/include/kos/elf_id.h from the KasperskyOS SDK.

The API lets you get the build ID from an ELF image. The build ID is required for the sampling-based profiling mechanism to work. It is also preferable that the build ID is available to the kernel GDB server that uses this ID to tell the GDB debugger where to search for debug symbols. (The kernel GDB server uses the name of the executable file as an alternative to the build ID.)

A build ID may be absent from the ELF image. The linker adds the build ID to the ELF image only if the compiler was called with the -Wl,--build-id parameter.

Information about API functions is provided in the table below.

Using the API

To get the build ID and its size from an ELF image, call the KosElfGetBuildId() function. This data must be passed to the kernel so that it is available to the sampling-based profiling mechanism and to the GDB server of the kernel. The build ID and its size are passed to the kernel when calling the KosTaskInitFromSeg(), KosTaskInitFromSegEx() or KosTaskLoadSegments() function from the API task.h. These functions use the segs parameter to receive the array of VmSeg structures that describe loadable ELF image segments. The type of VmSeg structures is defined in the header file sysroot-*-kos/include/coresrv/vmm/vmm_types.h from the KasperskyOS SDK. These structures contain the buildId and buildIdSize fields. For each loadable ELF image segment (including the .symtab symbol table and the .strtab string table), you must define the build ID and its size (the same values for all segments). At the same time, you can use the KnElfCreateVmSegEx() function from the API elf_api.h that automatically fills the buildId and buildIdSize fields in the array of VmSeg structures (if the build ID is available in the ELF image) and passes the address of this array via the output parameter segs. In other words, when using the KnElfCreateVmSegEx() function, the KosElfGetBuildId() function is not necessary.

In addition, the buildId and buildIdSize fields of the VmSeg structure are automatically filled by the KnVmSegInitFromBuf() function from the API vmm_api.h, which receives the build ID and its size via the input parameters buildId and buildIdSize, respectively. The build ID and its size are written to the VmSeg structure that is defined via the output parameter seg so that it can then be passed to the kernel by calling the KosTaskInitFromSeg(), KosTaskInitFromSegEx() or KosTaskLoadSegments() function.

The KosTaskInit(), KosTaskInitEx(), and KosTaskLaunch() functions from the task.h API pass the build ID and its size to the kernel if the build ID is available in the ELF image.

Information about API functions

elf_id.h functions

Function

Information about the function

KosElfGetBuildId()

Purpose

Gets the build ID from an ELF image.

Parameters

  • [in] elf – pointer to the buffer containing the ELF image.
  • [in] elfSize – size (in bytes) of the ELF image.
  • [in] buildIdMaxSize – size (in bytes) of the buffer used to store the build ID.
  • [out] buildId – pointer to the buffer used to store the build ID.
  • [out] buildIdSize – pointer to the build ID size (in bytes).

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

If the build ID is absent from the ELF image, the function returns rcResourceNotFound.

Page top