From patchwork Fri Jan 15 13:22:53 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ian Campbell X-Patchwork-Id: 8040371 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 07AA3BEEE5 for ; Fri, 15 Jan 2016 13:25:41 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 2545620458 for ; Fri, 15 Jan 2016 13:25:40 +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 4438520459 for ; Fri, 15 Jan 2016 13:25:39 +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 1aK4Lj-00044M-8G; Fri, 15 Jan 2016 13:23:31 +0000 Received: from mail6.bemta4.messagelabs.com ([85.158.143.247]) by lists.xen.org with esmtp (Exim 4.72) (envelope-from ) id 1aK4Lf-0003pF-QG for xen-devel@lists.xen.org; Fri, 15 Jan 2016 13:23:27 +0000 Received: from [85.158.143.35] by server-1.bemta-4.messagelabs.com id BB/65-09708-FC2F8965; Fri, 15 Jan 2016 13:23:27 +0000 X-Env-Sender: prvs=815b692d9=Ian.Campbell@citrix.com X-Msg-Ref: server-11.tower-21.messagelabs.com!1452864205!10294560!1 X-Originating-IP: [66.165.176.89] X-SpamReason: No, hits=0.0 required=7.0 tests=sa_preprocessor: VHJ1c3RlZCBJUDogNjYuMTY1LjE3Ni44OSA9PiAyMDMwMDc=\n, received_headers: No Received headers X-StarScan-Received: X-StarScan-Version: 7.35.1; banners=-,-,- X-VirusChecked: Checked Received: (qmail 14145 invoked from network); 15 Jan 2016 13:23:27 -0000 Received: from smtp.citrix.com (HELO SMTP.CITRIX.COM) (66.165.176.89) by server-11.tower-21.messagelabs.com with RC4-SHA encrypted SMTP; 15 Jan 2016 13:23:27 -0000 X-IronPort-AV: E=Sophos;i="5.22,299,1449532800"; d="scan'208";a="325395782" From: Ian Campbell To: , , Date: Fri, 15 Jan 2016 13:22:53 +0000 Message-ID: <1452864188-2417-15-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: MIA1 Cc: Ian Campbell Subject: [Xen-devel] [PATCH XEN v8 14/29] tools/libs/foreignmemory: Mention restrictions on fork in docs. 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=-2.8 required=5.0 tests=BAYES_00, RCVD_IN_BRBL_LASTEXT, 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 Signed-off-by: Ian Campbell Acked-by: Wei Liu --- v6: Also discuss recovering the memory. v7: Further clarifications regarding forking based on ML discussions. (Dropped Wei's ack) --- .../libs/foreignmemory/include/xenforeignmemory.h | 33 +++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/tools/libs/foreignmemory/include/xenforeignmemory.h b/tools/libs/foreignmemory/include/xenforeignmemory.h index 04ff548..a6d1bdb 100644 --- a/tools/libs/foreignmemory/include/xenforeignmemory.h +++ b/tools/libs/foreignmemory/include/xenforeignmemory.h @@ -32,13 +32,44 @@ typedef struct xentoollog_logger xentoollog_logger; typedef struct xenforeignmemory_handle xenforeignmemory_handle; /* - * Return a handle onto the hypercall driver. Logs errors. + * Return a handle onto the foreign memory mapping driver. Logs errors. + * + * Note: After fork(2) a child process must not use any opened + * foreignmemory 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 + * foreignmemory. + * + * Calling exec(2) in a child will safely (and reliably) reclaim any + * resources which were allocated via a xenforeignmemory_handle in the + * parent. + * + * A child which does not call exec(2) may safely call + * xenforeignmemory_close() on a xenforeignmemory_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 xenforeignmemory_close() is the only safe operation on a + * xenforeignmemory_handle which has been inherited. */ xenforeignmemory_handle *xenforeignmemory_open(xentoollog_logger *logger, unsigned open_flags); /* * Close a handle previously allocated with xenforeignmemory_open(). + * + * Under normal circumstances (i.e. not in the child after a fork) + * xenforeignmemory_unmap() should be used on all mappings allocated + * by xenforeignmemory_map() 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 + * xenforeignmemory_handle in a child after a + * fork. xenforeignmemory_unmap() must not be called under such + * circumstances. */ int xenforeignmemory_close(xenforeignmemory_handle *fmem);