From patchwork Fri May 4 18:33:12 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matthew Wilcox X-Patchwork-Id: 10381369 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 4C16860542 for ; Fri, 4 May 2018 18:59:07 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 3BAC82954C for ; Fri, 4 May 2018 18:59:07 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 2FF452957B; Fri, 4 May 2018 18:59:07 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.8 required=2.0 tests=BAYES_00,DKIM_SIGNED, MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE,T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 515C32958C for ; Fri, 4 May 2018 18:59:04 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id CE0656B026F; Fri, 4 May 2018 14:33:27 -0400 (EDT) Delivered-To: linux-mm-outgoing@kvack.org Received: by kanga.kvack.org (Postfix, from userid 40) id C18256B0270; Fri, 4 May 2018 14:33:27 -0400 (EDT) X-Original-To: int-list-linux-mm@kvack.org X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id B2E9D6B0271; Fri, 4 May 2018 14:33:27 -0400 (EDT) X-Original-To: linux-mm@kvack.org X-Delivered-To: linux-mm@kvack.org Received: from mail-pf0-f197.google.com (mail-pf0-f197.google.com [209.85.192.197]) by kanga.kvack.org (Postfix) with ESMTP id 709D66B026F for ; Fri, 4 May 2018 14:33:27 -0400 (EDT) Received: by mail-pf0-f197.google.com with SMTP id x23so10461637pfm.7 for ; Fri, 04 May 2018 11:33:27 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:dkim-signature:from:to:cc:subject:date :message-id:in-reply-to:references; bh=xUddnoWo9Dt+4YVH2Ov/RU04/WjM9VBKiNyZgKw2TKM=; b=CW2S7ga0DuFFouNefw+GQwHgMgdaZ3FDyeKFnNUIf5/SkaziPaD13FdteUrP0hv3zQ JARtWo12UEOePXZ1RqjKpUk/0m/Ecwlh2/pEDV76x0gWINh2nXCx3FP6g3hXvX356JV+ Qlk1kSFO3Uq7RbEAxN11DGxk6PI2eRDbwEbMhoRdCjzrWM46eeH8I06HaDjBiloHZBun N+N5OTCz64MLPF4Tm6aFCQU15B2bVtchL83UbLVNjj6xu5shjC2VkdcdFTG/GIqZHtGG mcH1RnRCsBN2TGyotMo8pDzFWmdybfRcTbIqzj0QXu13ZuinRi6NT9/2NLzW/+yjDkqv PLMQ== X-Gm-Message-State: ALQs6tCK/lM+WKt+4ydI3B5fTFS0QCfZU2YGKXCNCbQHXDWVo7LStLvw TF6I0h+g43/6gDkYtyr2WynnvLn7dvoHpYTBt1ZxYVGUI1J6aGqGpJ71XA8Ypp1hMrarS4vSLRn q8DSK+FqcfHpyWhRuhkzS7k9RhgUeMunhosq91m0FJexfTN5iApzLz4zA+v2BIDuQFQ== X-Received: by 10.98.228.8 with SMTP id r8mr28044452pfh.172.1525458807122; Fri, 04 May 2018 11:33:27 -0700 (PDT) X-Google-Smtp-Source: AB8JxZqtq3XpuI3z2ikQTztbEw+3g6PM5PvRmntfiXHlHIiGwWAolxiy3brCh89rhpZE3Mwhbipw X-Received: by 10.98.228.8 with SMTP id r8mr28044418pfh.172.1525458806189; Fri, 04 May 2018 11:33:26 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1525458806; cv=none; d=google.com; s=arc-20160816; b=h4kMxm7/bEOp9x/ZBVAjM4pVWrcEgqnvTt8nEdsiuM0ZckWI69przmdUFN4HpIfdAy UyWhNRTI661ostQG+R6fvcKjtpfi+o9/fANUW3Ws6YlYMv3PrPZ9UG6nxTNCH6X+0YAp zdUt4JNbFkrJjG8sF2/ZSDgQ6tNjRLwntjybAHw1ZkijM/lbmWjkh0VGdWhGL3Rn9xC2 4ze7MgzoTCPcoGyMjfN08R6OBK9pFIwSXI/rU3ONA8GYdmWYA0HNb7/WXyOi77G1k+81 sAWPAEPfN1tLAMGxkmFuF6xkLByvLb1DO6TnnbjIGefRqcQsjW5wxpNfODSrR8mrJi2R gOSw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature:arc-authentication-results; bh=xUddnoWo9Dt+4YVH2Ov/RU04/WjM9VBKiNyZgKw2TKM=; b=aE7rNgyAYcfCtOYoc1UOf+87/BnMyNhQFATNjn551zZUmMgKOn2HJHO27+y4M8kxpw 1y4odWGwaUy4rMktKp50p18yAi7baysFcQzDJGrkpclPmyNxdxp/44npLYSsGCV2stT/ 6KGi66UoTG86U1E7IbJAn5jqMEP7u5mu/RSvSYV6VKZZj4UM72q1IqLwUXXf4445fVQI CgDI7mkNoxuDsveqMCIuQ9UrH0tPy3F0Sm1+/Zoic8nXFuNhQPAo/kmdEcRV5/e3VL+H aA4OKV4exymPSqSWRiaGsvhECHPHZzYnKZArLk+taqZFe2omouKvpYb8IqUFFFkbcfJA hvwg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@infradead.org header.s=bombadil.20170209 header.b=jqpNjcU5; spf=pass (google.com: best guess record for domain of willy@infradead.org designates 2607:7c80:54:e::133 as permitted sender) smtp.mailfrom=willy@infradead.org Received: from bombadil.infradead.org (bombadil.infradead.org. [2607:7c80:54:e::133]) by mx.google.com with ESMTPS id a13si13600627pfd.338.2018.05.04.11.33.26 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 04 May 2018 11:33:26 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of willy@infradead.org designates 2607:7c80:54:e::133 as permitted sender) client-ip=2607:7c80:54:e::133; Authentication-Results: mx.google.com; dkim=pass header.i=@infradead.org header.s=bombadil.20170209 header.b=jqpNjcU5; spf=pass (google.com: best guess record for domain of willy@infradead.org designates 2607:7c80:54:e::133 as permitted sender) smtp.mailfrom=willy@infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=References:In-Reply-To:Message-Id: Date:Subject:Cc:To:From:Sender:Reply-To:MIME-Version:Content-Type: Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id: List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=xUddnoWo9Dt+4YVH2Ov/RU04/WjM9VBKiNyZgKw2TKM=; b=jqpNjcU5S6LdSFU79cEKEj1TR /GeFjjB7KU4+6PY4f1FaGZdDed8lpzwtsTa1DCRHZ/VYBr7f8O+sm5GeXkV7eiwW3B1jO5AX4H5B+ 3jtVHIoNuufHesnizSGYjb1kBxzhRBjasylPVPEM6vxDOmqu/i8TwFftjYBYjVAVLlGlgX5ycJC45 ZCGHKXXFUbCGIOweCXIJH1LiQC7XEF1pcHNQXHmhPcTgwZ/4ALAe3Ze9enJ1xe9DQj0XBg37VXVxQ VYiPMF00xqSzihfKi4WgTMCHPmF8pn/lAeb+8gArqxyW3YavY4peEV7I2ipD6qfHuEuAHJQlrwjn8 FcjM1w5+g==; Received: from willy by bombadil.infradead.org with local (Exim 4.90_1 #2 (Red Hat Linux)) id 1fEfWH-0003n4-09; Fri, 04 May 2018 18:33:25 +0000 From: Matthew Wilcox To: linux-mm@kvack.org Cc: Matthew Wilcox , Andrew Morton , "Kirill A . Shutemov" , Christoph Lameter , Lai Jiangshan , Pekka Enberg , Vlastimil Babka , Dave Hansen , =?UTF-8?q?J=C3=A9r=C3=B4me=20Glisse?= Subject: [PATCH v5 11/17] mm: Improve struct page documentation Date: Fri, 4 May 2018 11:33:12 -0700 Message-Id: <20180504183318.14415-12-willy@infradead.org> X-Mailer: git-send-email 2.14.3 In-Reply-To: <20180504183318.14415-1-willy@infradead.org> References: <20180504183318.14415-1-willy@infradead.org> X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: X-Virus-Scanned: ClamAV using ClamSMTP From: Matthew Wilcox Rewrite the documentation to describe what you can use in struct page rather than what you can't. Signed-off-by: Matthew Wilcox Reviewed-by: Randy Dunlap Acked-by: Vlastimil Babka --- include/linux/mm_types.h | 40 +++++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/include/linux/mm_types.h b/include/linux/mm_types.h index cf3bbee8c9a1..90a6dbeeef11 100644 --- a/include/linux/mm_types.h +++ b/include/linux/mm_types.h @@ -33,29 +33,27 @@ struct hmm; * it to keep track of whatever it is we are using the page for at the * moment. Note that we have no way to track which tasks are using * a page, though if it is a pagecache page, rmap structures can tell us - * who is mapping it. If you allocate the page using alloc_pages(), you - * can use some of the space in struct page for your own purposes. + * who is mapping it. * - * Pages that were once in the page cache may be found under the RCU lock - * even after they have been recycled to a different purpose. The page - * cache reads and writes some of the fields in struct page to pin the - * page before checking that it's still in the page cache. It is vital - * that all users of struct page: - * 1. Use the first word as PageFlags. - * 2. Clear or preserve bit 0 of page->compound_head. It is used as - * PageTail for compound pages, and the page cache must not see false - * positives. Some users put a pointer here (guaranteed to be at least - * 4-byte aligned), other users avoid using the field altogether. - * 3. page->_refcount must either not be used, or must be used in such a - * way that other CPUs temporarily incrementing and then decrementing the - * refcount does not cause problems. On receiving the page from - * alloc_pages(), the refcount will be positive. - * 4. Either preserve page->_mapcount or restore it to -1 before freeing it. + * If you allocate the page using alloc_pages(), you can use some of the + * space in struct page for your own purposes. The five words in the main + * union are available, except for bit 0 of the first word which must be + * kept clear. Many users use this word to store a pointer to an object + * which is guaranteed to be aligned. If you use the same storage as + * page->mapping, you must restore it to NULL before freeing the page. * - * If you allocate pages of order > 0, you can use the fields in the struct - * page associated with each page, but bear in mind that the pages may have - * been inserted individually into the page cache, so you must use the above - * four fields in a compatible way for each struct page. + * If your page will not be mapped to userspace, you can also use the four + * bytes in the mapcount union, but you must call page_mapcount_reset() + * before freeing it. + * + * If you want to use the refcount field, it must be used in such a way + * that other CPUs temporarily incrementing and then decrementing the + * refcount does not cause problems. On receiving the page from + * alloc_pages(), the refcount will be positive. + * + * If you allocate pages of order > 0, you can use some of the fields + * in each subpage, but you may need to restore some of their values + * afterwards. * * SLUB uses cmpxchg_double() to atomically update its freelist and * counters. That requires that freelist & counters be adjacent and