From patchwork Fri Jan 15 13:23:04 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ian Campbell X-Patchwork-Id: 8040361 Return-Path: X-Original-To: patchwork-xen-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 6FE44BEEED for ; Fri, 15 Jan 2016 13:25:38 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 5700A20453 for ; Fri, 15 Jan 2016 13:25:37 +0000 (UTC) Received: from lists.xen.org (lists.xenproject.org [50.57.142.19]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 3E2C52035D for ; Fri, 15 Jan 2016 13:25:36 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=lists.xen.org) by lists.xen.org with esmtp (Exim 4.72) (envelope-from ) id 1aK4M3-0004hc-Cf; Fri, 15 Jan 2016 13:23:51 +0000 Received: from mail6.bemta5.messagelabs.com ([195.245.231.135]) by lists.xen.org with esmtp (Exim 4.72) (envelope-from ) id 1aK4Lz-0004YM-O1 for xen-devel@lists.xen.org; Fri, 15 Jan 2016 13:23:47 +0000 Received: from [85.158.139.211] by server-13.bemta-5.messagelabs.com id C9/A2-06091-3E2F8965; Fri, 15 Jan 2016 13:23:47 +0000 X-Env-Sender: prvs=815b692d9=Ian.Campbell@citrix.com X-Msg-Ref: server-12.tower-206.messagelabs.com!1452864204!16117711!7 X-Originating-IP: [66.165.176.63] X-SpamReason: No, hits=0.0 required=7.0 tests=sa_preprocessor: VHJ1c3RlZCBJUDogNjYuMTY1LjE3Ni42MyA9PiAzMDYwNDg=\n, received_headers: No Received headers X-StarScan-Received: X-StarScan-Version: 7.35.1; banners=-,-,- X-VirusChecked: Checked Received: (qmail 31724 invoked from network); 15 Jan 2016 13:23:45 -0000 Received: from smtp02.citrix.com (HELO SMTP02.CITRIX.COM) (66.165.176.63) by server-12.tower-206.messagelabs.com with RC4-SHA encrypted SMTP; 15 Jan 2016 13:23:45 -0000 X-IronPort-AV: E=Sophos;i="5.22,299,1449532800"; d="scan'208";a="331644668" From: Ian Campbell To: , , Date: Fri, 15 Jan 2016 13:23:04 +0000 Message-ID: <1452864188-2417-26-git-send-email-ian.campbell@citrix.com> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1452864188-2417-1-git-send-email-ian.campbell@citrix.com> References: <1452864168.32341.97.camel@citrix.com> <1452864188-2417-1-git-send-email-ian.campbell@citrix.com> MIME-Version: 1.0 X-DLP: MIA2 Cc: Ian Campbell Subject: [Xen-devel] [PATCH XEN v8 25/29] tools/libs/{call, evtchn}: Document requirements around forking. X-BeenThere: xen-devel@lists.xen.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org X-Spam-Status: No, score=-4.2 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Much like for gnttab and foreignmemory xencall hypercall buffers need care. Evtchn is a bit simpler (no magic mappings) but may not work from parent + child simultaneously, document "parent only" since it is consistent with the others. Signed-off-by: Ian Campbell Acked-by: Wei Liu --- v7: New --- tools/libs/call/include/xencall.h | 28 ++++++++++++++++++++++++++++ tools/libs/evtchn/include/xenevtchn.h | 23 +++++++++++++++++++---- 2 files changed, 47 insertions(+), 4 deletions(-) diff --git a/tools/libs/call/include/xencall.h b/tools/libs/call/include/xencall.h index 3f325f0..559624a 100644 --- a/tools/libs/call/include/xencall.h +++ b/tools/libs/call/include/xencall.h @@ -36,11 +36,39 @@ typedef struct xencall_handle xencall_handle; /* * Return a handle onto the hypercall driver. Logs errors. + * * + * Note: After fork(2) a child process must not use any opened + * xencall handle inherited from their parent, nor access any + * hypercall argument buffers associated with that handle. + * + * The child must open a new handle if they want to interact with + * xencall. + * + * Calling exec(2) in a child will safely (and reliably) reclaim any + * resources which were allocated via a xencall_handle in the parent. + * + * A child which does not call exec(2) may safely call xencall_close() + * on a xencall_handle inherited from their parent. This will attempt + * to reclaim any resources associated with that handle. Note that in + * some implementations this reclamation may not be completely + * effective, in this case any affected resources remain allocated. + * + * Calling xencall_close() is the only safe operation on a + * xencall_handle which has been inherited. */ xencall_handle *xencall_open(xentoollog_logger *logger, unsigned open_flags); /* * Close a handle previously allocated with xencall_open(). + * + * Under normal circumstances (i.e. not in the child after a fork) any + * allocated hypercall argument buffers should be freed using the + * appropriate xencall_free_*() prior to closing the handle in order + * to free up resources associated with those mappings. + * + * This is the only function which may be safely called on a + * xencall_handle in a child after a fork. xencall_free_*() must not + * be called under such circumstances. */ int xencall_close(xencall_handle *xcall); diff --git a/tools/libs/evtchn/include/xenevtchn.h b/tools/libs/evtchn/include/xenevtchn.h index 428d54c..4d26161 100644 --- a/tools/libs/evtchn/include/xenevtchn.h +++ b/tools/libs/evtchn/include/xenevtchn.h @@ -45,10 +45,25 @@ typedef struct xentoollog_logger xentoollog_logger; * Return a handle to the event channel driver, or NULL on failure, in * which case errno will be set appropriately. * - * Note: - * After fork a child process must not use any opened evtchn - * handle inherited from their parent. They must open a new handle if - * they want to interact with evtchn. + * Note: After fork(2) a child process must not use any opened evtchn + * handle inherited from their parent, nor access any grant mapped + * areas associated with that handle. + * + * The child must open a new handle if they want to interact with + * evtchn. + * + * Calling exec(2) in a child will safely (and reliably) reclaim any + * allocated resources via a xenevtchn_handle in the parent. + * + * A child which does not call exec(2) may safely call + * xenevtchn_close() on a xenevtchn_handle inherited from their + * parent. This will attempt to reclaim any resources associated with + * that handle. Note that in some implementations this reclamation may + * not be completely effective, in this case any affected resources + * remain allocated. + * + * Calling xenevtchn_close() is the only safe operation on a + * xenevtchn_handle which has been inherited. */ /* Currently no flags are defined */ xenevtchn_handle *xenevtchn_open(xentoollog_logger *logger, unsigned open_flags);