Home
QNX Hypervisor and QNX Hypervisor for Safety
The QNX Hypervisor and QNX Hypervisor for Safety products allow you to run multiple OSs on a target system so you can separate critical and non-critical functions, support a wide variety of applications, and reduce hardware costs.
Virtual Device Developer's API Reference
The Virtual Device Developer's API Reference presents the QNX hypervisor public virtual device (vdev) API. It is intended for use by developers writing virtual devices (vdevs) in a QNX hypervisor system.
gasp.h
Definitions and functions for working in guest address spaces
gram_find_free()
Find a free memory space from a guest system's RAM/ROM regions

QNX Momentics IDE User's Guide
This User's Guide describes version 8.0 of the Integrated Development Environment (IDE) that's part of the QNX Tool Suite.
QNX Software Development Platform
QNX SDP is a cross-compiling and debugging environment, including an IDE and command-line tools, for building binary images and programs for target boards running the QNX OS 8.0.
QNX Software in the Cloud
QNX Software in the Cloud enables developers to use the QNX software in Amazon Web Services (AWS) and Microsoft Azure (Azure).
QNX Toolkit for Visual Studio Code
This User's Guide describes the QNX^® Toolkit for Visual Studio Code. The guide introduces you to the QNX Toolkit by explaining the QNX development environment and how to build, run, and debug your QNX^® Operating System (OS) applications and systems.
QNX Hypervisor and QNX Hypervisor for Safety
The QNX Hypervisor and QNX Hypervisor for Safety products allow you to run multiple OSs on a target system so you can separate critical and non-critical functions, support a wide variety of applications, and reduce hardware costs.
- User's Guide
  This User's Guide explains the QNX hypervisor architecture and provides instructions for installing and running a QNX hypervisor system, changing system components and configuration, and using hypervisor features such as virtual devices (vdevs).
- Virtual Device Developer's Guide
  The Virtual Device Developer's Guide is intended for use by developers writing virtual devices (vdevs) in a QNX hypervisor system.
- Virtual Device Developer's API Reference
  The Virtual Device Developer's API Reference presents the QNX hypervisor public virtual device (vdev) API. It is intended for use by developers writing virtual devices (vdevs) in a QNX hypervisor system.
  - Function Safety
    This section provides an overview of the restrictions that may apply when using the functions in this API.
  - aarch64/vmid.h
    Functions to access a guest's VMID (ARM)
  - abi.h
    Application binary interface (ABI) information
  - cdev.h
    Support routines for virtual character devices
  - firmware.h
    Functions for working with the firmware components of the VM presented to the guest
  - gasp.h
    Definitions and functions for working in guest address spaces
    - Definitions in gasp.h
      Preprocessor macro definitions for the gasp.h header file
    - gasp_find_free()
      Find a free region of a particular space type
    - gasp_find_free_range()
      Find a free region of a particular space type inside a specified address range
    - gasp_get_vaddr()
      Get the virtual address for a guest-physical address mapping
    - gasp_lock()
      Lock access to regions of the specified type
    - gasp_map()
      Map a guest-physical address range into the qvm process address space for virtual hardware access
    - gasp_map_firmware()
      Map a guest-physical address range into the qvm process address space for virtual firmware access
    - gasp_map_flags_t
      Flags for specifying protection bits in mapped address ranges
    - gasp_map_handle_t
      Data type for representing the handle of a guest-physical address mapping
    - gasp_map_host_contig()
      Map a guest-physical address range into the qvm process address space and obtain host-physical address information
    - gasp_region_info()
      Query information about a guest location
    - gasp_region_set()
      Add, modify, or delete address-space regions in the guest system
    - gasp_region_set_soft()
      Add, modify, or delete address-space regions in the guest system
    - gasp_unlock()
      Release access to regions of the specified type
    - gasp_unmap_handle()
      Unmap a qvm process address range that mapped guest-physical addresses
    - gasp_walk_count()
      Get the number of RAM/ROM entries in the guest's address space
    - gasp_walk_count_filtered()
      Get the number of RAM/ROM entries in the guest's address space that can be accessed through a given memory walk filter
    - gasp_walk_filter_t
      Prototype for function that applies a walk filter
    - gasp_walk_flags_t
      Data type for storing flags controlling a memory walk
    - gasp_walk_init()
      Initialize a memory walk state structure
    - gasp_walk_init_filtered()
      Initialize a memory walk filter state structure
    - gasp_walk_next()
      Get information about the next RAM/ROM block of memory
    - gasp_walk_next_filtered()
      Get information about the next RAM/ROM block of memory accessible through the memory walk filter
    - gasp_walk_state_t
      Data type for storing the guest system's walk state
    - gasp_walk_state_filtered_t
      Data type for storing the guest system's walk filter state
    - gram_find_free()
      Find a free memory space from a guest system's RAM/ROM regions
    - gram_find_free_range()
      Find a free memory space within a specified range from a guest system's RAM/ROM regions
    - gram_reserve()
      Mark a RAM/ROM range as being in use
  - guest.h
    Controls for manipulating a guest system
  - hpci.h
    Host PCI interface for vdevs
  - hw_pci.h
    PCI support for vdevs
  - log.h
    Controls for logging messages
  - types.h
    vdev API base types
  - utils.h
    Miscellaneous utility functions
  - vdev-core.h
    Definitions and functions that support vdev control functions and callbacks
  - vio.h
    Definitions and functions for working with VIRTIO vdevs
  - vpci.h
    Controls for virtual PCI (vPCI) devices
  - wdog.h
    Constants, data types, and functions to support virtual watchdog devices
  - x86_64/apic.h
    Definitions for the virtual APIC bus (x86)
Typographical Conventions, Support, and Licensing
This section describes the typographical conventions used throughout the documentation, explains how to obtain technical support, and provides some information about licensing.

gram_find_free()

Find a free memory space from a guest system's RAM/ROM regions

Synopsis:

#include <qvm/gasp.h>

uint64_t gram_find_free(uint64_t size,
                        uint64_t align,
                        gram_hint_flags_t flags)

Arguments:

size: The number of bytes of free space needed.
align: The requested alignment of the space.
flags: A combination of GRAM_HINT_* flags.

Description:

This function finds a free memory space with the given size and alignment from a guest system's RAM or ROM regions. The function calls gram_reserve() on the region it returns, so you don't need to do that.

Returns:

The address of the free space, or QSL_NO_LOCATION if no space is available.

Page updated: March 14, 2026