From patchwork Tue Apr 2 16:42:37 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Julien Grall X-Patchwork-Id: 161641 Delivered-To: patch@linaro.org Received: by 2002:a02:c6d8:0:0:0:0:0 with SMTP id r24csp1963956jan; Tue, 2 Apr 2019 09:44:23 -0700 (PDT) X-Google-Smtp-Source: APXvYqyXygRTln/JDnAn4VF/zbMVUj83/vp3aQgxBQaopxtRvy+pixUx4PuKD+SVPzDnoWJl/Xto X-Received: by 2002:a81:848f:: with SMTP id u137mr25149525ywf.22.1554223463629; Tue, 02 Apr 2019 09:44:23 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1554223463; cv=none; d=google.com; s=arc-20160816; b=W77I8S2yKMZpmU1phBUebpqLzZJvt/IZfWUQNNvYTVhRQ81oMK3A82YUcBnx9FHaYT vXIvmO8QIWEtaF9dWmN08FoTbtUz/dJsm+4tL/mCRIpL/CXBlDVKmQpff2HFU+Datw5M 2LkcyciYDvGaJbC2VxAiyfVEY4GEwRlvqRNg1JR9cBFcOjJZ6VEeE0E6nlue451PU3V2 zMFXipr4q4QOWxwBQtXgI4QwdeBRRpnFQfGD/L8lPHSX+zx2QjGrpxZLmxE2HmUDpMT/ pRaokEuT4MS4HY13iu63Tx5XGgVqMNm2nGOks3B4VXIvihU08aS6d+B681rXLTFo7hsR rTnA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:mime-version:cc :list-subscribe:list-help:list-post:list-unsubscribe:list-id :precedence:subject:references:in-reply-to:message-id:date:to:from; bh=IlRySa64K7Jpz7i+DRcOj4YXDyBEL5zV3DI+V7tCfJU=; b=FDcfX50N9QXXRIHPwqjFrqocxVdIgKrAh/mPbxtOI3ZdRPRlcRDSblym0OUvUtv/n8 Hkqih+D5QAyvBNqSDOZMK7ibacVcdACo0TURCDyDyUCnnY+kotGWtRNHmfk51vIe5j9/ EKzycbErYspvRBJZOZt3luhp50UaviQ3mytyoOU3DLuAdfEGC20KACKZ4LvED2x6f9kG QnZQMs2BLzFLo7FlzQATabZcqO3CQxed9dqmiGKWJs8cs1ZM+i1lDPbVT288eH1eh41Y y6UrafoyUT92OwPHi5sopEqOibBwP9dw0oHPC4+sB5E4msXTqny92DJJjnHeD1b/T+p+ EnWg== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of xen-devel-bounces@lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Return-Path: Received: from lists.xenproject.org (lists.xenproject.org. [192.237.175.120]) by mx.google.com with ESMTPS id n7si8707549ybp.58.2019.04.02.09.44.23 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Tue, 02 Apr 2019 09:44:23 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of xen-devel-bounces@lists.xenproject.org designates 192.237.175.120 as permitted sender) client-ip=192.237.175.120; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of xen-devel-bounces@lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1hBMV2-0005yE-Bm; Tue, 02 Apr 2019 16:43:00 +0000 Received: from all-amaz-eas1.inumbo.com ([34.197.232.57] helo=us1-amaz-eas2.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1hBMV1-0005xu-Cv for xen-devel@lists.xenproject.org; Tue, 02 Apr 2019 16:42:59 +0000 X-Inumbo-ID: 5f1c9570-5566-11e9-9c4a-87eae8392637 Received: from foss.arm.com (unknown [217.140.101.70]) by us1-amaz-eas2.inumbo.com (Halon) with ESMTP id 5f1c9570-5566-11e9-9c4a-87eae8392637; Tue, 02 Apr 2019 16:42:58 +0000 (UTC) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.72.51.249]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 08BF21688; Tue, 2 Apr 2019 09:42:58 -0700 (PDT) Received: from e108454-lin.cambridge.arm.com (e108454-lin.cambridge.arm.com [10.1.196.50]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 3C20A3F721; Tue, 2 Apr 2019 09:42:56 -0700 (PDT) From: Julien Grall To: xen-devel@lists.xenproject.org Date: Tue, 2 Apr 2019 17:42:37 +0100 Message-Id: <20190402164238.1815-4-julien.grall@arm.com> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20190402164238.1815-1-julien.grall@arm.com> References: <20190402164238.1815-1-julien.grall@arm.com> Subject: [Xen-devel] [PATCH 3/4] xen/public: Document HYPERCALL_console_io() X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Stefano Stabellini , Wei Liu , Konrad Rzeszutek Wilk , George Dunlap , Andrew Cooper , Ian Jackson , Tim Deegan , Julien Grall , Jan Beulich MIME-Version: 1.0 Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" Currently, OS developpers will have to look at Xen code in order to know the parameters of an hypercall and how it is meant to work. This is not a trivial task as you may need to have a deep understanding of Xen internal. This patch attempts to document the behavior of HYPERCALL_console_io() to help OS developer. Signed-off-by: Julien Grall Acked-by: Wei Liu --- This is a first attempt to address the lack on documentation for hypercalls. We may want to decide a format to use in every hypercall so it can be readable for the OS developer and easily consummed by documentation tools. --- xen/include/public/xen.h | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h index ccdffc0ad1..7c119c6782 100644 --- a/xen/include/public/xen.h +++ b/xen/include/public/xen.h @@ -97,6 +97,7 @@ DEFINE_XEN_GUEST_HANDLE(xen_ulong_t); #define __HYPERVISOR_set_timer_op 15 #define __HYPERVISOR_event_channel_op_compat 16 /* compat since 0x00030202 */ #define __HYPERVISOR_xen_version 17 +/* HYPERVISOR_console_io(int cmd, int count, XEN_GUEST_HANDLE(char) buffer); */ #define __HYPERVISOR_console_io 18 #define __HYPERVISOR_physdev_op_compat 19 /* compat since 0x00030202 */ #define __HYPERVISOR_grant_table_op 20 @@ -486,7 +487,25 @@ DEFINE_XEN_GUEST_HANDLE(mmuext_op_t); /* ` } */ /* - * Commands to HYPERVISOR_console_io(). + * Commands to HYPERVISOR_console_io() + * + * @cmd: Command (see below) + * @count: Size of the buffer to read/write + * @buffer: Pointer in the guest memory + * + * List of commands: + * + * * CONSOLEIO_write: Write the buffer on Xen console. + * For the hardware domain, all the characters in the buffer will + * be written. Characters will be printed to directly to the + * console. + * For all the other domains, only the printable characters will be + * written. Characters may be buffered until a newline (i.e '\n') is + * found. + * Return 0 on success, otherwise return an error code. + * * CONSOLE_read: Attempts to read up @count characters from Xen console. + * Return the number of character read on success, otherwise return + * an error code. */ #define CONSOLEIO_write 0 #define CONSOLEIO_read 1