blob: a657786a94b1ecd049d06120d6e8c6488d405249 [file] [log] [blame]
#ifndef HW_HYPERV_DYNMEM_PROTO_H
#define HW_HYPERV_DYNMEM_PROTO_H
/*
* Hyper-V Dynamic Memory Protocol definitions
*
* Copyright (C) 2020-2023 Oracle and/or its affiliates.
*
* Based on drivers/hv/hv_balloon.c from Linux kernel:
* Copyright (c) 2012, Microsoft Corporation.
*
* Author: K. Y. Srinivasan <kys@microsoft.com>
*
* This work is licensed under the terms of the GNU GPL, version 2.
* See the COPYING file in the top-level directory.
*/
/*
* Protocol versions. The low word is the minor version, the high word the major
* version.
*
* History:
* Initial version 1.0
* Changed to 0.1 on 2009/03/25
* Changes to 0.2 on 2009/05/14
* Changes to 0.3 on 2009/12/03
* Changed to 1.0 on 2011/04/05
* Changed to 2.0 on 2019/12/10
*/
#define DYNMEM_MAKE_VERSION(Major, Minor) ((uint32_t)(((Major) << 16) | (Minor)))
#define DYNMEM_MAJOR_VERSION(Version) ((uint32_t)(Version) >> 16)
#define DYNMEM_MINOR_VERSION(Version) ((uint32_t)(Version) & 0xff)
enum {
DYNMEM_PROTOCOL_VERSION_1 = DYNMEM_MAKE_VERSION(0, 3),
DYNMEM_PROTOCOL_VERSION_2 = DYNMEM_MAKE_VERSION(1, 0),
DYNMEM_PROTOCOL_VERSION_3 = DYNMEM_MAKE_VERSION(2, 0),
DYNMEM_PROTOCOL_VERSION_WIN7 = DYNMEM_PROTOCOL_VERSION_1,
DYNMEM_PROTOCOL_VERSION_WIN8 = DYNMEM_PROTOCOL_VERSION_2,
DYNMEM_PROTOCOL_VERSION_WIN10 = DYNMEM_PROTOCOL_VERSION_3,
DYNMEM_PROTOCOL_VERSION_CURRENT = DYNMEM_PROTOCOL_VERSION_WIN10
};
/*
* Message Types
*/
enum dm_message_type {
/*
* Version 0.3
*/
DM_ERROR = 0,
DM_VERSION_REQUEST = 1,
DM_VERSION_RESPONSE = 2,
DM_CAPABILITIES_REPORT = 3,
DM_CAPABILITIES_RESPONSE = 4,
DM_STATUS_REPORT = 5,
DM_BALLOON_REQUEST = 6,
DM_BALLOON_RESPONSE = 7,
DM_UNBALLOON_REQUEST = 8,
DM_UNBALLOON_RESPONSE = 9,
DM_MEM_HOT_ADD_REQUEST = 10,
DM_MEM_HOT_ADD_RESPONSE = 11,
DM_VERSION_03_MAX = 11,
/*
* Version 1.0.
*/
DM_INFO_MESSAGE = 12,
DM_VERSION_1_MAX = 12,
/*
* Version 2.0
*/
DM_MEM_HOT_REMOVE_REQUEST = 13,
DM_MEM_HOT_REMOVE_RESPONSE = 14
};
/*
* Structures defining the dynamic memory management
* protocol.
*/
union dm_version {
struct {
uint16_t minor_version;
uint16_t major_version;
};
uint32_t version;
} QEMU_PACKED;
union dm_caps {
struct {
uint64_t balloon:1;
uint64_t hot_add:1;
/*
* To support guests that may have alignment
* limitations on hot-add, the guest can specify
* its alignment requirements; a value of n
* represents an alignment of 2^n in mega bytes.
*/
uint64_t hot_add_alignment:4;
uint64_t hot_remove:1;
uint64_t reservedz:57;
} cap_bits;
uint64_t caps;
} QEMU_PACKED;
union dm_mem_page_range {
struct {
/*
* The PFN number of the first page in the range.
* 40 bits is the architectural limit of a PFN
* number for AMD64.
*/
uint64_t start_page:40;
/*
* The number of pages in the range.
*/
uint64_t page_cnt:24;
} finfo;
uint64_t page_range;
} QEMU_PACKED;
/*
* The header for all dynamic memory messages:
*
* type: Type of the message.
* size: Size of the message in bytes; including the header.
* trans_id: The guest is responsible for manufacturing this ID.
*/
struct dm_header {
uint16_t type;
uint16_t size;
uint32_t trans_id;
} QEMU_PACKED;
/*
* A generic message format for dynamic memory.
* Specific message formats are defined later in the file.
*/
struct dm_message {
struct dm_header hdr;
uint8_t data[]; /* enclosed message */
} QEMU_PACKED;
/*
* Specific message types supporting the dynamic memory protocol.
*/
/*
* Version negotiation message. Sent from the guest to the host.
* The guest is free to try different versions until the host
* accepts the version.
*
* dm_version: The protocol version requested.
* is_last_attempt: If TRUE, this is the last version guest will request.
* reservedz: Reserved field, set to zero.
*/
struct dm_version_request {
struct dm_header hdr;
union dm_version version;
uint32_t is_last_attempt:1;
uint32_t reservedz:31;
} QEMU_PACKED;
/*
* Version response message; Host to Guest and indicates
* if the host has accepted the version sent by the guest.
*
* is_accepted: If TRUE, host has accepted the version and the guest
* should proceed to the next stage of the protocol. FALSE indicates that
* guest should re-try with a different version.
*
* reservedz: Reserved field, set to zero.
*/
struct dm_version_response {
struct dm_header hdr;
uint64_t is_accepted:1;
uint64_t reservedz:63;
} QEMU_PACKED;
/*
* Message reporting capabilities. This is sent from the guest to the
* host.
*/
struct dm_capabilities {
struct dm_header hdr;
union dm_caps caps;
uint64_t min_page_cnt;
uint64_t max_page_number;
} QEMU_PACKED;
/*
* Response to the capabilities message. This is sent from the host to the
* guest. This message notifies if the host has accepted the guest's
* capabilities. If the host has not accepted, the guest must shutdown
* the service.
*
* is_accepted: Indicates if the host has accepted guest's capabilities.
* reservedz: Must be 0.
*/
struct dm_capabilities_resp_msg {
struct dm_header hdr;
uint64_t is_accepted:1;
uint64_t hot_remove:1;
uint64_t suppress_pressure_reports:1;
uint64_t reservedz:61;
} QEMU_PACKED;
/*
* This message is used to report memory pressure from the guest.
* This message is not part of any transaction and there is no
* response to this message.
*
* num_avail: Available memory in pages.
* num_committed: Committed memory in pages.
* page_file_size: The accumulated size of all page files
* in the system in pages.
* zero_free: The number of zero and free pages.
* page_file_writes: The writes to the page file in pages.
* io_diff: An indicator of file cache efficiency or page file activity,
* calculated as File Cache Page Fault Count - Page Read Count.
* This value is in pages.
*
* Some of these metrics are Windows specific and fortunately
* the algorithm on the host side that computes the guest memory
* pressure only uses num_committed value.
*/
struct dm_status {
struct dm_header hdr;
uint64_t num_avail;
uint64_t num_committed;
uint64_t page_file_size;
uint64_t zero_free;
uint32_t page_file_writes;
uint32_t io_diff;
} QEMU_PACKED;
/*
* Message to ask the guest to allocate memory - balloon up message.
* This message is sent from the host to the guest. The guest may not be
* able to allocate as much memory as requested.
*
* num_pages: number of pages to allocate.
*/
struct dm_balloon {
struct dm_header hdr;
uint32_t num_pages;
uint32_t reservedz;
} QEMU_PACKED;
/*
* Balloon response message; this message is sent from the guest
* to the host in response to the balloon message.
*
* reservedz: Reserved; must be set to zero.
* more_pages: If FALSE, this is the last message of the transaction.
* if TRUE there will be at least one more message from the guest.
*
* range_count: The number of ranges in the range array.
*
* range_array: An array of page ranges returned to the host.
*
*/
struct dm_balloon_response {
struct dm_header hdr;
uint32_t reservedz;
uint32_t more_pages:1;
uint32_t range_count:31;
union dm_mem_page_range range_array[];
} QEMU_PACKED;
/*
* Un-balloon message; this message is sent from the host
* to the guest to give guest more memory.
*
* more_pages: If FALSE, this is the last message of the transaction.
* if TRUE there will be at least one more message from the guest.
*
* reservedz: Reserved; must be set to zero.
*
* range_count: The number of ranges in the range array.
*
* range_array: An array of page ranges returned to the host.
*
*/
struct dm_unballoon_request {
struct dm_header hdr;
uint32_t more_pages:1;
uint32_t reservedz:31;
uint32_t range_count;
union dm_mem_page_range range_array[];
} QEMU_PACKED;
/*
* Un-balloon response message; this message is sent from the guest
* to the host in response to an unballoon request.
*
*/
struct dm_unballoon_response {
struct dm_header hdr;
} QEMU_PACKED;
/*
* Hot add request message. Message sent from the host to the guest.
*
* mem_range: Memory range to hot add.
*
*/
struct dm_hot_add {
struct dm_header hdr;
union dm_mem_page_range range;
} QEMU_PACKED;
/*
* Hot add response message.
* This message is sent by the guest to report the status of a hot add request.
* If page_count is less than the requested page count, then the host should
* assume all further hot add requests will fail, since this indicates that
* the guest has hit an upper physical memory barrier.
*
* Hot adds may also fail due to low resources; in this case, the guest must
* not complete this message until the hot add can succeed, and the host must
* not send a new hot add request until the response is sent.
* If VSC fails to hot add memory DYNMEM_NUMBER_OF_UNSUCCESSFUL_HOTADD_ATTEMPTS
* times it fails the request.
*
*
* page_count: number of pages that were successfully hot added.
*
* result: result of the operation 1: success, 0: failure.
*
*/
struct dm_hot_add_response {
struct dm_header hdr;
uint32_t page_count;
uint32_t result;
} QEMU_PACKED;
struct dm_hot_remove {
struct dm_header hdr;
uint32_t virtual_node;
uint32_t page_count;
uint32_t qos_flags;
uint32_t reservedZ;
} QEMU_PACKED;
struct dm_hot_remove_response {
struct dm_header hdr;
uint32_t result;
uint32_t range_count;
uint64_t more_pages:1;
uint64_t reservedz:63;
union dm_mem_page_range range_array[];
} QEMU_PACKED;
#define DM_REMOVE_QOS_LARGE (1 << 0)
#define DM_REMOVE_QOS_LOCAL (1 << 1)
#define DM_REMOVE_QOS_MASK (0x3)
/*
* Types of information sent from host to the guest.
*/
enum dm_info_type {
INFO_TYPE_MAX_PAGE_CNT = 0,
MAX_INFO_TYPE
};
/*
* Header for the information message.
*/
struct dm_info_header {
enum dm_info_type type;
uint32_t data_size;
uint8_t data[];
} QEMU_PACKED;
/*
* This message is sent from the host to the guest to pass
* some relevant information (win8 addition).
*
* reserved: no used.
* info_size: size of the information blob.
* info: information blob.
*/
struct dm_info_msg {
struct dm_header hdr;
uint32_t reserved;
uint32_t info_size;
uint8_t info[];
};
#endif