From patchwork Wed Nov 13 11:59:50 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Alex_Benn=C3=A9e?= X-Patchwork-Id: 179296 Delivered-To: patch@linaro.org Received: by 2002:a92:38d5:0:0:0:0:0 with SMTP id g82csp9496773ilf; Wed, 13 Nov 2019 04:04:15 -0800 (PST) X-Google-Smtp-Source: APXvYqwnW++tAtlPry+SlZlCOx5UbxMPlcsy0es3RfVopIO8AMFQCS/J2lRqIj5AXQSulmzJ/qAU X-Received: by 2002:a17:906:52c3:: with SMTP id w3mr2434808ejn.122.1573646655256; Wed, 13 Nov 2019 04:04:15 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1573646655; cv=none; d=google.com; s=arc-20160816; b=jRpAWrJbJB61sDR/UL9cmqFc6T5raic7djlzeOd9VqHDxbOAsGl5GNKLFDzz6BJ/78 eGMrdbt4seylxVZMZgEG/HDxaRB47Yn9/occQu1JT6U/9QJEasCKoN9vr9QnrAauIkGi e4rbT64eaqsFx58hfxwP/R2KD8qTs0D0isNIPGx5ZuIgj2rCB9ypB8u5G4U8jmi/6bMn yElEuxpvE3hLQeDg1ePQV1BdyQufdCVU8uGkXh6toYxRIOnTDNzkhiB1TNHlE4bxdwL+ 8kNH23R2XznUr14efi81tvQyuTw1tp++kCvwxl9IJNQaZ3u060A3nyuenu4Cphyu8IbS elWw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=LLUdVSuPei6RAwTaPKVy6/3rq24iATJe7bkWNsh6uTU=; b=oUyHnVY1YwKvNGheZ3us5eb3CnXJNCeehwG82bmdJvqEUy4xeSGb54uSGhyZ/ECRPD g5h4f2gXi2p8aG+tv+oYjGSVyubdDaGpA8njyKt0aJxb4nxgcRsDR74EQowjMsk/oFie ELRfAjXMDIpuW9y1Axt5T7towtRXkobMFq89ZVqKq6WW0AJ+iVwVcFcOVru7HGmX3DEU wfpZKrPgKnLuOjr6HThNsgGrpMU0bwaAbeZ2A53Ru5+Wp4/kvDiTO9pfcvQIT2HOvKfU gPXM1xOq8LzFd46c/f3YDsSc7iXXQKxaJcaejQOSLioi/7AlYpaRD6czF9uCCBiIyvnI 2ZIg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="pCNQqF9/"; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id v2si1218099ede.61.2019.11.13.04.04.15 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 13 Nov 2019 04:04:15 -0800 (PST) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="pCNQqF9/"; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1]:43404 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iUrNe-0000WV-7F for patch@linaro.org; Wed, 13 Nov 2019 07:04:14 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:33071) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iUrJY-00050U-9c for qemu-devel@nongnu.org; Wed, 13 Nov 2019 07:00:01 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iUrJX-0004E6-6b for qemu-devel@nongnu.org; Wed, 13 Nov 2019 07:00:00 -0500 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:35838) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iUrJX-0004De-0p for qemu-devel@nongnu.org; Wed, 13 Nov 2019 06:59:59 -0500 Received: by mail-wr1-x444.google.com with SMTP id s5so2061926wrw.2 for ; Wed, 13 Nov 2019 03:59:58 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=LLUdVSuPei6RAwTaPKVy6/3rq24iATJe7bkWNsh6uTU=; b=pCNQqF9/m0xFj0siyxMAgjxY47lz1d85wHe2FmDsJVgAWI6UEEaXZNn3dO6xloLRCA kEa8kLgYK0IepcSqjDfAK7XJ/4LQE74Yu4ro53r5zN5snIscTk8D4U0QFuRw+B2iQee/ MYM9A2vq295bQCvo+Cn5drsOYw9cLdCKvui9tlws63DKkyphv7drWEkifzMjvVQUXsEM Y+vKIWjBNQIDGxl5VDRgiivsgfpLjaLG3rFkcW/CWJg/c613PZqcu34KgUEApYuRnbaD v0tj8+MNK4UpWfdbf1lAZlnnqMc9ticIKHUwmCNIVTqK2zd6+BrH7600TVoediHOHWUv qEAw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=LLUdVSuPei6RAwTaPKVy6/3rq24iATJe7bkWNsh6uTU=; b=bZkQAiIpJQGxAIKYgA45trqfR/cWtu4M29daNplitkr9+0gMYdIoBKkrqqDzfkXvUf j+6WbgVS6U4ZxufTR+O+7BBG0KlRlvEvP23Dp2fVuiR6Pe6QGJgtsvgtUgiF6ojjrhjn dvW8pun8wZzTiRQeJ8TBxVV+etj5Qkjlmn3v0CX3LqFj/Nq9sI1mzOHyUWLYSjme1KwI +AJY5KnOLCpnP2W7AB250U2erkoE7HsNrCR6MijP2CzkFAVn4c7eJWi76BkRXbnAQUpp oJ0YRadzX+PuKturYn/x2i+N9VuGY3VLfJn7EKfGIa9dFGHqfAKyMuW5V+BqeSNYjEiN qvnA== X-Gm-Message-State: APjAAAUIgfSkf6fnj8OTCRtVhZUFWefy1SxGjB916Qxju2RjbKjmV0eU bXiJhJ2KpieqklthOvcZhQdsNw== X-Received: by 2002:a5d:48c8:: with SMTP id p8mr2617842wrs.318.1573646397870; Wed, 13 Nov 2019 03:59:57 -0800 (PST) Received: from zen.linaroharston ([51.148.130.216]) by smtp.gmail.com with ESMTPSA id 200sm2432008wme.32.2019.11.13.03.59.52 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 13 Nov 2019 03:59:56 -0800 (PST) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 6D0EB1FF90; Wed, 13 Nov 2019 11:59:52 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Subject: [PATCH v1 3/5] docs/devel: update tcg-plugins.rst with API versioning details Date: Wed, 13 Nov 2019 11:59:50 +0000 Message-Id: <20191113115952.775-4-alex.bennee@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20191113115952.775-1-alex.bennee@linaro.org> References: <20191113115952.775-1-alex.bennee@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::444 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: fam@euphon.net, berrange@redhat.com, stefanb@linux.vnet.ibm.com, =?utf-8?q?Alex_Benn=C3=A9e?= , richard.henderson@linaro.org, f4bug@amsat.org, cota@braap.org, stefanha@redhat.com, marcandre.lureau@redhat.com, pbonzini@redhat.com, aurelien@aurel32.net Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" While we are at it fix up the quoted code sections with the inline :: approach. Signed-off-by: Alex Bennée --- v2 - fix grammar - mention we also will fail to load outside the range - clean-up code sections --- docs/devel/tcg-plugins.rst | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) -- 2.20.1 Reviewed-by: Robert Foley diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst index b18fb6729e3..718eef00f22 100644 --- a/docs/devel/tcg-plugins.rst +++ b/docs/devel/tcg-plugins.rst @@ -25,6 +25,23 @@ process. However the project reserves the right to change or break the API should it need to do so. The best way to avoid this is to submit your plugin upstream so they can be updated if/when the API changes. +API versioning +-------------- + +All plugins need to declare a symbol which exports the plugin API +version they were built against. This can be done simply by:: + + QEMU_PLUGIN_EXPORT int qemu_plugin_version = QEMU_PLUGIN_VERSION; + +The core code will refuse to load a plugin that doesn't export a +`qemu_plugin_version` symbol or if plugin version is outside of QEMU's +supported range of API versions. + +Additionally the `qemu_info_t` structure which is passed to the +`qemu_plugin_install` method of a plugin will detail the minimum and +current API versions supported by QEMU. The API version will be +incremented if new APIs are added. The minimum API version will be +incremented if existing APIs are changed or removed. Exposure of QEMU internals -------------------------- @@ -40,16 +57,14 @@ instructions and events are opaque to the plugins themselves. Usage ===== -The QEMU binary needs to be compiled for plugin support: +The QEMU binary needs to be compiled for plugin support:: -:: - configure --enable-plugins + configure --enable-plugins Once built a program can be run with multiple plugins loaded each with -their own arguments: +their own arguments:: -:: - $QEMU $OTHER_QEMU_ARGS \ + $QEMU $OTHER_QEMU_ARGS \ -plugin tests/plugin/libhowvec.so,arg=inline,arg=hint \ -plugin tests/plugin/libhotblocks.so