1/* 2 * An implementation of HyperV key value pair (KVP) functionality for Linux. 3 * 4 * 5 * Copyright (C) 2010, Novell, Inc. 6 * Author : K. Y. Srinivasan <ksrinivasan@novell.com> 7 * 8 * This program is free software; you can redistribute it and/or modify it 9 * under the terms of the GNU General Public License version 2 as published 10 * by the Free Software Foundation. 11 * 12 * This program is distributed in the hope that it will be useful, but 13 * WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or 15 * NON INFRINGEMENT. See the GNU General Public License for more 16 * details. 17 * 18 * You should have received a copy of the GNU General Public License 19 * along with this program; if not, write to the Free Software 20 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 */ 23#ifndef _KVP_H 24#define _KVP_H_ 25 26/* 27 * Maximum value size - used for both key names and value data, and includes 28 * any applicable NULL terminators. 29 * 30 * Note: This limit is somewhat arbitrary, but falls easily within what is 31 * supported for all native guests (back to Win 2000) and what is reasonable 32 * for the IC KVP exchange functionality. Note that Windows Me/98/95 are 33 * limited to 255 character key names. 34 * 35 * MSDN recommends not storing data values larger than 2048 bytes in the 36 * registry. 37 * 38 * Note: This value is used in defining the KVP exchange message - this value 39 * cannot be modified without affecting the message size and compatibility. 40 */ 41 42/* 43 * bytes, including any null terminators 44 */ 45#define HV_KVP_EXCHANGE_MAX_VALUE_SIZE (2048) 46 47 48/* 49 * Maximum key size - the registry limit for the length of an entry name 50 * is 256 characters, including the null terminator 51 */ 52 53#define HV_KVP_EXCHANGE_MAX_KEY_SIZE (512) 54 55/* 56 * In Linux, we implement the KVP functionality in two components: 57 * 1) The kernel component which is packaged as part of the hv_utils driver 58 * is responsible for communicating with the host and responsible for 59 * implementing the host/guest protocol. 2) A user level daemon that is 60 * responsible for data gathering. 61 * 62 * Host/Guest Protocol: The host iterates over an index and expects the guest 63 * to assign a key name to the index and also return the value corresponding to 64 * the key. The host will have atmost one KVP transaction outstanding at any 65 * given point in time. The host side iteration stops when the guest returns 66 * an error. Microsoft has specified the following mapping of key names to 67 * host specified index: 68 * 69 * Index Key Name 70 * 0 FullyQualifiedDomainName 71 * 1 IntegrationServicesVersion 72 * 2 NetworkAddressIPv4 73 * 3 NetworkAddressIPv6 74 * 4 OSBuildNumber 75 * 5 OSName 76 * 6 OSMajorVersion 77 * 7 OSMinorVersion 78 * 8 OSVersion 79 * 9 ProcessorArchitecture 80 * 81 * The Windows host expects the Key Name and Key Value to be encoded in utf16. 82 * 83 * Guest Kernel/KVP Daemon Protocol: As noted earlier, we implement all of the 84 * data gathering functionality in a user mode daemon. The user level daemon 85 * is also responsible for binding the key name to the index as well. The 86 * kernel and user-level daemon communicate using a connector channel. 87 * 88 * The user mode component first registers with the 89 * the kernel component. Subsequently, the kernel component requests, data 90 * for the specified keys. In response to this message the user mode component 91 * fills in the value corresponding to the specified key. We overload the 92 * sequence field in the cn_msg header to define our KVP message types. 93 * 94 * 95 * The kernel component simply acts as a conduit for communication between the 96 * Windows host and the user-level daemon. The kernel component passes up the 97 * index received from the Host to the user-level daemon. If the index is 98 * valid (supported), the corresponding key as well as its 99 * value (both are strings) is returned. If the index is invalid 100 * (not supported), a NULL key string is returned. 101 */ 102 103/* 104 * 105 * The following definitions are shared with the user-mode component; do not 106 * change any of this without making the corresponding changes in 107 * the KVP user-mode component. 108 */ 109 110#define CN_KVP_VAL 0x1 /* This supports queries from the kernel */ 111#define CN_KVP_USER_VAL 0x2 /* This supports queries from the user */ 112 113enum hv_ku_op { 114 KVP_REGISTER = 0, /* Register the user mode component */ 115 KVP_KERNEL_GET, /* Kernel is requesting the value */ 116 KVP_KERNEL_SET, /* Kernel is providing the value */ 117 KVP_USER_GET, /* User is requesting the value */ 118 KVP_USER_SET /* User is providing the value */ 119}; 120 121struct hv_ku_msg { 122 __u32 kvp_index; /* Key index */ 123 __u8 kvp_key[HV_KVP_EXCHANGE_MAX_KEY_SIZE]; /* Key name */ 124 __u8 kvp_value[HV_KVP_EXCHANGE_MAX_VALUE_SIZE]; /* Key value */ 125}; 126 127 128 129 130#ifdef __KERNEL__ 131 132/* 133 * Registry value types. 134 */ 135 136#define REG_SZ 1 137 138enum hv_kvp_exchg_op { 139 KVP_OP_GET = 0, 140 KVP_OP_SET, 141 KVP_OP_DELETE, 142 KVP_OP_ENUMERATE, 143 KVP_OP_COUNT /* Number of operations, must be last. */ 144}; 145 146enum hv_kvp_exchg_pool { 147 KVP_POOL_EXTERNAL = 0, 148 KVP_POOL_GUEST, 149 KVP_POOL_AUTO, 150 KVP_POOL_AUTO_EXTERNAL, 151 KVP_POOL_AUTO_INTERNAL, 152 KVP_POOL_COUNT /* Number of pools, must be last. */ 153}; 154 155struct hv_kvp_hdr { 156 u8 operation; 157 u8 pool; 158}; 159 160struct hv_kvp_exchg_msg_value { 161 u32 value_type; 162 u32 key_size; 163 u32 value_size; 164 u8 key[HV_KVP_EXCHANGE_MAX_KEY_SIZE]; 165 u8 value[HV_KVP_EXCHANGE_MAX_VALUE_SIZE]; 166}; 167 168struct hv_kvp_msg_enumerate { 169 u32 index; 170 struct hv_kvp_exchg_msg_value data; 171}; 172 173struct hv_kvp_msg { 174 struct hv_kvp_hdr kvp_hdr; 175 struct hv_kvp_msg_enumerate kvp_data; 176}; 177 178int hv_kvp_init(struct hv_util_service *); 179void hv_kvp_deinit(void); 180void hv_kvp_onchannelcallback(void *); 181 182#endif /* __KERNEL__ */ 183#endif /* _KVP_H */ 184 185