disp_memfuncs_t

Table of memory management functions

Synopsis:

#include <vmem.h>

typedef struct disp_memfuncs {
    int  (*init) (…);
    void (*fini) (…);
    void (*module_info) (…);
    int  (*reset) (…);
    int  (*alloc_surface) (…);
    int  (*alloc_layer_surface) (…);
    int  (*free_surface) (…);
    int  (*mem_avail) (…);
    int (*query_apertures) (…);
    int (*query_surface) (…);
    int (*get_alloc_info) (…);
    int (*get_alloc_layer_info) (…);

} disp_memfuncs_t;

Description:

The disp_memfuncs_t structure is a table that your driver uses to define the memory management functions that it provides to the graphics framework. Your driver's devg_get_memfuncs() entry point must fill in this structure.

init()

The graphics framework calls this function to initialize the memory manager. The prototype is:

int (*init) (disp_adapter_t *adapter,
             char *optstring)

The graphics framework calls this function before any of the other functions in the disp_memfuncs_t structure. For more information on where this function fits into the general flow, see “Calling sequence” in the Writing a Graphics Driver chapter.

fini()

The graphics framework calls this function to shut down the memory management module, freeing any resources that it allocated. The prototype is:

int (*fini) (disp_adapter_t *adapter)

For more information on where this function fits into the general flow, see “Calling sequence” in the Writing a Graphics Driver chapter.

module_info()

The prototype is:

int (*module_info) (disp_adapter_t *adapter,
                    disp_module_info_t *info)

This function must fill in the disp_module_info_t structure pointed to by module_info.

reset()

The graphics framework calls this function to reset the memory management module to its initial state. The prototype is:

int (*reset) (
        disp_adapter_t *adapter,
        disp_surface_t *surf )

alloc_surface()

The graphics framework calls this function to allocate video memory to contain a 2D surface. The prototype is:

disp_surface_t * (*alloc_surface) (
                     disp_adapter_t *adapter,
                     int width,
                     int height,
                     unsigned format,
                     unsigned flags,
                     unsigned hint_flags)

The size of the surface is width pixels by height scanlines. This function must allocate a disp_surface_t structure and initialize it to describe the allocated surface memory. Set the structure's adapter member to point to the driver's disp_adapter_t structure.

The function must return a pointer to the allocated disp_surface_t and must ensure that the memory it allocates conforms to the surface properties requested by the flags parameter. This implies that when the function returns, any flags set in flags are also set in the flags member of the returned surface.

The hint_flags member can be:

• DISP_VMEM_HINT_USAGE_CPU — allocate the surface to optimize CPU access speed
• DISP_VMEM_HINT_USAGE_2D — allocate the surface to optimize 2D rendering
• DISP_VMEM_HINT_USAGE_3D — allocate the surface to optimize 3D rendering

alloc_layer_surface()

The graphics framework calls this function to allocate a surface whose contents can be displayed on the given layers. The prototype is:

disp_surface_t * (*alloc_layer_surface) (
        disp_adapter_t *adp,
        int dispno[],
        int layer_idx[],
        int nlayers,
        unsigned format,
        int surface_index,
        int width,
        int height,
        unsigned sflags,
        unsigned hint_flags );

The size of the buffer to be allocated is specified in pixels, by the width and height arguments. This function must allocate a disp_surface_t structure and initialize it to describe the allocated memory surface. Set the structure's adapter member to point to the driver's disp_adapter_t structure.

In the case of planar YUV data, the width and height argument would be the same, regardless of whether a Y, a U, or a V plane were being allocated for a given image. It is up to the driver to know how big the actual buffer size which needs to be allocated, should be.

The function must return a pointer to the allocated disp_surface_t and must ensure that the memory it allocates conforms to the surface properties requested by the sflags parameter. This implies that when the function returns, any flags set in sflags are also set in the flags member of the returned surface.

The sflags argument is one of the surface flags as defined in the disp_surface_t section. However, the following flags have no meaning here:

• DISP_SURFACE_DISPLAYABLE
• DISP_SURFACE_SCALER_DISPLAYABLE

The format and surface_idx arguments s the data format of the surface. Some layer formats split the image components across multiple buffers. A planar YUV surface, for example, requires three buffers to store a valid image. The surface_idx argument specifies whether a Y, U, or V buffer gets allocated.

The format argument specifies the data format of the memory to be allocated. See Pixel formats for layers in the Writing a Graphics Driver chapter for a list of formats.

The dispno[] and layer_index[] arguments are arrays of size nlayers, which specify a list of display-layer pairs on which the allocated memory must be displayable.

This function should return a pointer to a structure describing the allocated memory surface, or NULL to indicate failure.

The hint_flags argument can be one of:

• DISP_VMEM_HINT_USAGE_CPU — allocate the surface to optimize CPU access speed
• DISP_VMEM_HINT_USAGE_2D — allocate the surface to optimize 2D rendering
• DISP_VMEM_HINT_USAGE_3D — allocate the surface to optimize 3D rendering

free_surface()

The graphics framework calls this function to free the video memory associated with the disp_surface_t structure that surf points to, as well as freeing the structure itself. The prototype is:

int (*free_surface) (disp_adapter_t *adapter,
                     disp_surface_t *surface)

mem_avail()

The graphics framework calls this function to determine how much memory is available. The prototype is:

int (*mem_avail) (disp_adapter_t *adapter,
                  unsigned sflags)

This function returns the amount of video memory available, in bytes. However, the memory that's reported as being available must conform to the surface properties specified by sflags.

query_apertures()

The graphics framework calls this function to get information about a device's memory-mapped apertures. The prototype is:

int (*query_apertures) (disp_adapter_t *adapter,
    disp_aperture_t *apertures);

Typically a device has one or more memory-mapped apertures, through which registers and video memory may be accessed. Any such apertures that need to be accessed by the driver when rendering, should be declared by this function.

This function should fill in an array of disp_aperture_t structures, with information describing each of the physical memory apertures that need to be exported to the client. No more than DISP_MAX_APERTURES array entries should be filled in.

The following fields should be set for each aperture being declared:

• base — physical memory base address of the apterture
• size — size (in bytes) of the memory aperture
• flags — the following flags are defined:

  DISP_APER_NOCACHE

  Indicates that when the aperture is mapped on the client side, it should not be mapped cacheable.

  DISP_APER_LAZYWRITE

  Indicates that the aperture can be written to in a lazy fashion, in other words, it supports write gathering mechanisms which may delay writes to the aperture or deliver them out-or-order. Such write-gathering mechanisms are commonly used to improve performance when rendering to framebuffers on graphics devices using the CPU.

This function should return the number of apertures that were declared.

query_surface()

The graphics framework calls this function to query a surface that was allocated by the driver. The prototype is:

int (*query_surface) (disp_adapter_t *adapter,
        disp_surface_t *surf,
        disp_surface_info_t *info );

The memory for each allocated surface must reside within one of the memory apertures that was declared by query_apertures. This function fills in a disp_surface_info_t. The driver should set the following fields:

aperture_index

The index of the aperture within which the surface memory resides. This index corresponds to the index into the array of disp_aperture_t that was passed to query_apertures.

offset

The byte offset into the aperture of the first byte of the surface's memory.

get_alloc_info()

The graphics framework calls this function to render to memory that wasn't allocated by the graphics driver. The prototype is:

int (*get_alloc_info) (disp_adapter_t *adapter,
    int width,
    int height,
    unsigned format,
    unsigned sflags,
    unsigned hint_flags,
    disp_alloc_info_t *info);

Sometimes it is desirable or necessary to be able to render to memory that was not allocated by your graphics drivers. This function operates just like the alloc_surface entry point, with the exception that no memory is allocated. The actual allocation of memory takes place external to the driver.

This function fills in a structure of type disp_alloc_info_t, in accordance with the allocation requirements. The following fields must be set by the driver:

start_align

Byte alignment of the start of the memory surface.

end_align

Byte alignment of the end of the memory surface. The allocator may need to include padding at the end of the allocation to satisfy this requirement.

min_stride

Minimum stride of the allocated surface.

max_stride

Maximum stride of the allocated surface.

stride_gran

The stride of the allocated surface must be a multiple of this value.

map_flags

In the event that the surface memory is allocated using the mmap() call, this field specifies the mapping flags that will be passed to mmap(), e.g. MAP_PHYS.

prot_flags

In the event that the surface memory is allocated using the mmap() call, this field specifies the protection flags that will be passed to mmap(). The following values may be set:

• DISP_PROT_READ
• DISP_PROT_WRITE
• DISP_PROT_NOCACHE

surface_flags

Specifies the flags that should be set in the flags field of the disp_surface_t associated with the allocated surface. Keep in mind that your driver will be expected to render to the allocated surface, and set the flags accordingly.

get_alloc_layer_info()

The graphics framework calls this function to render to a surface that wasn't allocated by the graphics driver, and whose contents can be displayed on the given layers.

The prototype is:

int (*get_alloc_layer_info) (disp_adapter_t *adp,
    int dispno[],
    int layer_idx[],
    int nlayers,
    unsigned format,
    int surface_index,
    int width,
    int height,
    unsigned sflags,
    unsigned hint_flags,
    disp_alloc_info_t *info );

This function has the same relationship to alloc_layer_surface() as get_alloc_info() has to alloc_surface(). That is, it operates just like the alloc_surcace_layer() entry point, but no memory is allocated. The actual allocation of the memory takes place external to the driver. However, if memory capable of displaying on one of the device's layers can't be allocated externally to the driver, this function will always return NULL.

The function fills in a structure of type disp_alloc_info_t, setting the same fields as get_alloc_info().

Classification:

Neutrino

See also:

devg_get_memfuncs(), disp_adapter_t, disp_mode_info_t, disp_surface_t