gralloc

Documentation

Overview

Package gralloc provides gralloc buffer allocation and CPU mapping via the Android IAllocator/IMapper HAL services.

Index

• func BytesPerPixel(format gfxCommon.PixelFormat) int
• func CopyToMMIO(dst []byte, src []byte) int
• type Buffer
  • func Allocate(ctx context.Context, sm *servicemanager.ServiceManager, width int32, ...) (*Buffer, error)
  • func ReadGraphicBuffer(p *parcel.Parcel) (*Buffer, error)
  • func (b *Buffer) BufferSize() int
  • func (b *Buffer) Mmap() error
  • func (b *Buffer) Munmap()
  • func (b *Buffer) ReadPixels(ctx context.Context) ([]byte, error)
• type Mapper
  • func GetMapper(ctx context.Context) (Mapper, error)

Functions

func BytesPerPixel

func BytesPerPixel(format gfxCommon.PixelFormat) int

BytesPerPixel returns the bytes per pixel for common formats. Returns 0 for planar formats (YCbCr) where bytes-per-pixel is not a meaningful concept.

func CopyToMMIO

func CopyToMMIO(dst []byte, src []byte) int

CopyToMMIO copies src into a goldfish address space mmap region dst. Like copyFromMMIO, this avoids Go's runtime.memmove which uses AVX2 VMOVDQU instructions that crash on UC (uncacheable) PCI BAR memory. Only min(len(src), len(dst)) bytes are copied; the count is returned.

Types

type Buffer

type Buffer struct {
	Handle common.NativeHandle
	Stride int32
	Width  uint32
	Height uint32
	Format int32
	Usage  uint64

	// MmapData holds a persistent mmap of the dmabuf, set by Mmap().
	// Keeping it mapped avoids mmap/munmap syscalls per frame read.
	MmapData []byte
	// contains filtered or unexported fields
}

Buffer holds a gralloc-allocated buffer with its NativeHandle.

func Allocate

func Allocate(
	ctx context.Context,
	sm *servicemanager.ServiceManager,
	width int32,
	height int32,
	format gfxCommon.PixelFormat,
	usage gfxCommon.BufferUsage,
) (*Buffer, error)

Allocate allocates a gralloc buffer using the best available allocator. The fallback chain is:

1. AIDL IAllocator (android.hardware.graphics.allocator.IAllocator/default)
2. HIDL gralloc 3.0 IAllocator via hwbinder
3. dma-buf heap (/dev/dma_heap/system)
4. memfd (last resort; camera HAL may not accept these)

func ReadGraphicBuffer

func ReadGraphicBuffer(p *parcel.Parcel) (*Buffer, error)

ReadGraphicBuffer reads a flattened GraphicBuffer from a parcel. The wire format follows GraphicBuffer::unflatten():

int32(flattenedSize) + int32(fdCount) + raw[flattenedSize] + fd objects

func (*Buffer) BufferSize

func (b *Buffer) BufferSize() int

BufferSize returns the buffer size in bytes based on dimensions and pixel format.

func (*Buffer) Mmap

func (b *Buffer) Mmap() error

Mmap creates a persistent mmap of this buffer's dmabuf FD. It tries several flag combinations to handle different allocator backends (AIDL gralloc, HIDL gralloc, dma-buf heap, memfd). On kernel 6.6+, DMA-BUF mmap requires a prior SYNC ioctl. The MmapData field can then be read directly. Call Munmap to release.

For goldfish emulator buffers (/dev/goldfish_address_space), the FD requires claiming a shared region via ioctl and mmapping at the buffer's address space offset. ReadPixels() then uses IMapper.lock() via hwbinder to trigger rcReadColorBuffer (host GPU readback) before copying from the mmap'd region.

func (*Buffer) Munmap

func (b *Buffer) Munmap()

Munmap releases the persistent mmap created by Mmap.

func (*Buffer) ReadPixels

func (b *Buffer) ReadPixels(ctx context.Context) ([]byte, error)

ReadPixels returns the buffer pixel data.

For non-goldfish buffers (memfd, dma-buf heap), a copy of MmapData is returned directly.

For goldfish emulator buffers, the pixel data lives in host GPU memory and must be fetched via IMapper.lock() (which triggers rcReadColorBuffer). If the buffer was mmap'd successfully, lock() populates the shared goldfish address space memory visible through our mmap. If mmap failed (common on kernels where goldfish_address_space denies mmap with EPERM), the mapper reads pixel data via pread from the goldfish FD after lock().

If the mapper is not accessible (e.g., hwbinder denied from shell), pread is attempted directly -- on goldfish emulators the camera HAL writes frame data to the shared address space region, which is readable via pread even without an explicit lock cycle.

type Mapper

type Mapper interface {
	LockBuffer(ctx context.Context, b *Buffer) ([]byte, error)
}

Mapper provides CPU access to gralloc buffers via the HIDL IMapper HAL.

func GetMapper

func GetMapper(ctx context.Context) (Mapper, error)

GetMapper returns a Mapper for the current device. The result is cached. Returns an error when no mapper is available.