hidlmapper

Documentation

Overview

Package hidlmapper implements the HIDL IMapper@3.0 client for triggering host GPU readback on goldfish/ranchu emulator buffers via hwbinder.

The ranchu mapper's lock() internally calls rcReadColorBuffer to transfer pixel data from the host GPU into the goldfish address space memory. When a buffer is mmap'd (via /dev/goldfish_address_space), calling lock() populates the shared memory visible to all processes that have mmap'd the same region. The actual pointer returned by lock() is only valid in the mapper's process, but the underlying data is in shared device memory accessible through our mmap.

IMapper@3.0 is a standalone interface (no parent inheritance) with transaction codes starting at FIRST_CALL_TRANSACTION (1):

1: createDescriptor
2: importBuffer
3: freeBuffer
4: validateBufferSize
5: getTransportSize
6: lock
7: lockYCbCr
8: unlock
9: isSupported

Index

• type Mapper
  • func New(ctx context.Context, transport binder.Transport) (_ *Mapper, _err error)
  • func (m *Mapper) FreeBuffer(ctx context.Context, buffer uint64) (_err error)
  • func (m *Mapper) ImportBuffer(ctx context.Context, fds []int32, ints []int32) (_ uint64, _err error)
  • func (m *Mapper) Lock(ctx context.Context, buffer uint64, width int32, height int32) (_err error)
  • func (m *Mapper) LockYCbCr(ctx context.Context, buffer uint64, width int32, height int32) (_err error)
  • func (m *Mapper) Unlock(ctx context.Context, buffer uint64) (_err error)

Types

type Mapper

type Mapper struct {
	// contains filtered or unexported fields
}

Mapper is a HIDL IMapper@3.0 client connected via hwbinder.

func New

func New(
	ctx context.Context,
	transport binder.Transport,
) (_ *Mapper, _err error)

New looks up the IMapper@3.0 service via hwservicemanager and returns a connected Mapper client.

func (*Mapper) FreeBuffer

func (m *Mapper) FreeBuffer(
	ctx context.Context,
	buffer uint64,
) (_err error)

FreeBuffer releases a previously imported buffer.

Wire format (request):

interface token
uint64 buffer (opaque token, inline)

Wire format (response):

int32 error

func (*Mapper) ImportBuffer

func (m *Mapper) ImportBuffer(
	ctx context.Context,
	fds []int32,
	ints []int32,
) (_ uint64, _err error)

ImportBuffer imports a raw gralloc buffer handle into the mapper. Returns an opaque buffer token for use with Lock/Unlock/FreeBuffer.

Wire format (request):

interface token
hidl_handle: top-level buffer object (16 bytes)
  -> child: native_handle_t data
  -> binder_fd_array_object for FDs

Wire format (response):

int32 error (0 = NONE)
padding (4 bytes)
uint64 buffer (opaque token)

func (*Mapper) Lock

func (m *Mapper) Lock(
	ctx context.Context,
	buffer uint64,
	width int32,
	height int32,
) (_err error)

Lock triggers a CPU read lock on the buffer. On goldfish/ranchu emulators, this causes the mapper to call rcReadColorBuffer, transferring pixel data from the host GPU into the shared goldfish address space memory. The returned data pointer is only valid in the mapper's process, but the pixel data is now available in any mmap of the same goldfish region.

Wire format (request):

interface token
uint64 buffer (opaque token, inline)
uint64 cpuUsage (inline)
Rect accessRegion: int32 left, top, width, height (inline)
hidl_handle acquireFence (null = no fence)

Wire format (response):

int32 error
padding (4 bytes)
uint64 data pointer (ignored -- only valid in mapper's process)
int32 bytesPerPixel
int32 bytesPerStride

func (*Mapper) LockYCbCr

func (m *Mapper) LockYCbCr(
	ctx context.Context,
	buffer uint64,
	width int32,
	height int32,
) (_err error)

LockYCbCr triggers a CPU read lock for a YCbCr buffer. Like Lock, this causes the mapper to fetch pixel data from the host GPU into shared memory. The returned YCbCr layout pointers are only valid in the mapper's process.

Wire format (request): same as Lock.

Wire format (response):

int32 error
padding (4 bytes)
YCbCrLayout: y(8) + cb(8) + cr(8) + yStride(4) + cStride(4) + chromaStep(4) + pad(4)

func (*Mapper) Unlock

func (m *Mapper) Unlock(
	ctx context.Context,
	buffer uint64,
) (_err error)

Unlock unlocks a previously locked buffer.

Wire format (request):

interface token
uint64 buffer (opaque token, inline)

Wire format (response):

int32 error
hidl_handle releaseFence (ignored)