From patchwork Mon Aug 5 13:29:54 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Julien Grall X-Patchwork-Id: 170547 Delivered-To: patch@linaro.org Received: by 2002:ac9:2daa:0:0:0:0:0 with SMTP id g42csp4163309oce; Mon, 5 Aug 2019 06:31:28 -0700 (PDT) X-Google-Smtp-Source: APXvYqxSY3X/aMLEH8DUhAN+tgtJN51nx5swXMz0pJuQGSmefzBSX7JsIJxXxlNd/BaFsw66dS0U X-Received: by 2002:a05:6638:38a:: with SMTP id y10mr40595377jap.104.1565011888530; Mon, 05 Aug 2019 06:31:28 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1565011888; cv=none; d=google.com; s=arc-20160816; b=c7f18/ZCoC1NLDqtHSgVqN+bSRXyM0EQYMGTfq3bx1XeO9Bt2al0IwF5ukDtWBHVv+ nSgU4IE6Mx+VHPtDdRPaVMeJ0HH9CkH+rfJ1P7L7qElJoJbdvAsXbyWwWlH7ZpIDXOg7 cqLrsEyHqcaHfsMNYFe5RGeSOQD6hGutLJ4B51H8pqPKT2DgWHbiM8jTTQWB1JLRS4tm EcIdjr1pYneymw0Km00BBrjTpaywQg4LGpDOgfIHwqYUS2+Xt9NsL3CVpZbqaW64pMRM sCCQ2VVz08Ccrrum0pSYIP6I955n4z+iq86v/w+H4xRiEorzwxPV00M2OX6LeXpNCbRL NY6g== 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=HHIHjrBGG596JWlofG7YLmVKqgz0smgqBsm5ErrSrPc=; b=VClX3jxpynp+3NIkKrgB0gFojdNyNV4oxkwegusm5zO9uOYNQdo7+s1jdJ6NL2L39W P9XkdlS4BzkdZTJr598DcJnxX365MvD06yEvYW65oD/vwRoLqEoxE7x41HH8wbjfSqyJ 2iEsy21Y8gseV+uu84Gv5AZFsZboxtwT2qKLw5JPMc/hFb80gMUGctPo17/NEqIloahG xgEvsk1WRcdZjKIklbcdaRfiC1Q0SRe+kSZRSr5+qlCU9ycBH+ng3OYnVqZQn0t0fagB y4GuZKy+h3t/cd2qsRqFls7S3JoRBTsYMFuNhdhZJVYhzT3keBrQXEfpfYXyjEs/yCOP 2EDQ== 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 k2si116229436jac.121.2019.08.05.06.31.27 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Mon, 05 Aug 2019 06:31:28 -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 1hud3w-0004sf-RU; Mon, 05 Aug 2019 13:30:08 +0000 Received: from us1-rack-dfw2.inumbo.com ([104.130.134.6]) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1hud3u-0004rC-UB for xen-devel@lists.xenproject.org; Mon, 05 Aug 2019 13:30:06 +0000 X-Inumbo-ID: 231d066c-b785-11e9-8980-bc764e045a96 Received: from foss.arm.com (unknown [217.140.110.172]) by us1-rack-dfw2.inumbo.com (Halon) with ESMTP id 231d066c-b785-11e9-8980-bc764e045a96; Mon, 05 Aug 2019 13:30:05 +0000 (UTC) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id B022D337; Mon, 5 Aug 2019 06:30:05 -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 5BF573F706; Mon, 5 Aug 2019 06:30:04 -0700 (PDT) From: Julien Grall To: xen-devel@lists.xenproject.org Date: Mon, 5 Aug 2019 14:29:54 +0100 Message-Id: <20190805132955.1630-4-julien.grall@arm.com> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20190805132955.1630-1-julien.grall@arm.com> References: <20190805132955.1630-1-julien.grall@arm.com> Subject: [Xen-devel] [PATCH v2 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: Jan Beulich --- Changes in v2: - Follow the style of other comments within the file - Use @return to make return value - Add a sentence regarding the buffer size --- xen/include/public/xen.h | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h index cb2917e74b..742ab71004 100644 --- a/xen/include/public/xen.h +++ b/xen/include/public/xen.h @@ -486,7 +486,29 @@ DEFINE_XEN_GUEST_HANDLE(mmuext_op_t); /* ` } */ /* - * Commands to HYPERVISOR_console_io(). + * ` int + * ` HYPERVISOR_console_io(unsigned int cmd, + * ` unsigned int count, + * ` char buffer[]); + * + * @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. + * * CONSOLEIO_read: Attempts to read up @count characters from Xen console. + * The maximum buffer size (i.e @count) supported is 2GB. + * @return the number of character read on success, otherwise return + * an error code. */ #define CONSOLEIO_write 0 #define CONSOLEIO_read 1