From patchwork Fri May 18 19:45:13 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matthew Wilcox X-Patchwork-Id: 10412005 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 9853B6031B for ; Fri, 18 May 2018 19:47:22 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 8858028ABA for ; Fri, 18 May 2018 19:47:22 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 7CED428ABD; Fri, 18 May 2018 19:47:22 +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 EBCDC28ABA for ; Fri, 18 May 2018 19:47:21 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id D16716B067C; Fri, 18 May 2018 15:47:20 -0400 (EDT) Delivered-To: linux-mm-outgoing@kvack.org Received: by kanga.kvack.org (Postfix, from userid 40) id CC58C6B067E; Fri, 18 May 2018 15:47:20 -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 BB4C76B067F; Fri, 18 May 2018 15:47:20 -0400 (EDT) X-Original-To: linux-mm@kvack.org X-Delivered-To: linux-mm@kvack.org Received: from mail-pl0-f69.google.com (mail-pl0-f69.google.com [209.85.160.69]) by kanga.kvack.org (Postfix) with ESMTP id 7BF8A6B067C for ; Fri, 18 May 2018 15:47:20 -0400 (EDT) Received: by mail-pl0-f69.google.com with SMTP id x32-v6so5613053pld.16 for ; Fri, 18 May 2018 12:47:20 -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=xOgwWvox7Sqk27H9ZjTjwwo5jSijyBvf8rXNbBYG0+Q=; b=SxDW0aaIDR0YKH2kad75sXGeTPEmWqd2xS5wcKoLVbwSnI2AQIK8Z9T5+GdyAXW/8w iE7bDdoVGJMmEDbtCKGVcQEg4AwcoNqP7BhM2uPMM2c88/1SpkhumAqNHTMSbCeGpm9x Hf5zjn8hGiBtUngn6u+PDu3ozeQXbMj6KQ2ao2wD8biiqkdVpmQYrFqngeXVJ3oU+6GX 1IdEETZU4u8+yCUxXIcheyMftir162V+5/HAGf9hxObWtC/04YCjer3XaB3FOf7WlMaP mGbfeWYePYtkRyscaZqe+3gPlTkCKo8KlsF9/Ajkezi02hIr1IaZMkDRk5pvHDzJ9fkJ qtRQ== X-Gm-Message-State: ALKqPwe/xcNncVn7PTN/Z6fc+HWJt2Mti9jwRG2AVfQ17XQ6z/c3MQAU EtICiJ0l2SqPuwJHWdaM14N0lURWefSSmBz4740FJ71T5x2+crzZJ4Ek24UcLWjHIsrNEVewD5R FUhUhi/ed42r/3lTPR7DccoJF95tHUVZXfMY3ZvXWsnPTl0ptojeFkIYOxSjWx0x7zA== X-Received: by 2002:a17:902:6a85:: with SMTP id n5-v6mr2896575plk.288.1526672840191; Fri, 18 May 2018 12:47:20 -0700 (PDT) X-Google-Smtp-Source: AB8JxZpKuPOthSx+48MhBIve6oa9cqUUkRUPeLFVYAzIP1e8beb7WAJ4IFJn1znLMr56nGFSmJMo X-Received: by 2002:a17:902:6a85:: with SMTP id n5-v6mr2892293plk.288.1526672724006; Fri, 18 May 2018 12:45:24 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1526672723; cv=none; d=google.com; s=arc-20160816; b=mbah8mO+fSveqCTheqzBNbEQ1klo2EckW51us4DySpRC6hzc9o9Jxy9isQxHaXAxy4 nr/ukQY1pcUaBNxZcN5uKFnfTPAqRidsb0+AywIgEwpW79estYLCm0jWmWeu3YI0ETdZ E8S2oR+iEPCFF5wNO91FOr5p2fBXK5V7iSfKAIoosSjJ2JPwgDkWzs654wStchyBAc4l Eglo2LF0Pis35MN+YkRxiMG8ogvfqqqJ+/Y+6jnzU9RbmcT0a02wZHr1t8qHZPNNZO09 XQpBMTpkF8Mf6iI+auICYGfH81zJuNa+cDysAPkud1tAPLBxAaZLvizdszdXzIlupCrK i/0w== 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=xOgwWvox7Sqk27H9ZjTjwwo5jSijyBvf8rXNbBYG0+Q=; b=S998oki/p3T1726flPnuF88LB9LSI1kAfM5LYrdQQtqXKkO7k3DTkbAz2vz9Tz22zc 9hQ09HwebKTPUNZUQ8Hsx2FAVjoTnNWmliXGBzAWhJUYYbVhAbE87lvr8yC7xjZUrx0G YekrYq7FAssdbD3maZuIeyFpoRX3YGoiXHM3Jm0QghIF8YIs1KnxsocYfhPiARVznsCK +gqJf29ubIzVtFkQvxSaQXSDrAyL2a+c9hkz70n1ZgSIFFX3iK1NXDwDrkNzyUuhz102 AcWNVU3/mHhZkDQOv1n7LS/kGwehEBDb4ovHKwpAk3fhXHkmC97m+jKer1Okkg5VfLxV nRHw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@infradead.org header.s=bombadil.20170209 header.b=Qz0unk1o; 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 s36-v6si7803911pld.114.2018.05.18.12.45.23 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 18 May 2018 12:45:23 -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=Qz0unk1o; 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=xOgwWvox7Sqk27H9ZjTjwwo5jSijyBvf8rXNbBYG0+Q=; b=Qz0unk1ombGtyPXHQLh4udSZj 79qLYmyOR723K3FFS20gj/YAge22ZalI6Y8crQ47cYcMZ7cmjqW+NrU41qJbJ42vwveLMx6PG4kVo 8zooSpuXO597QbDOtregzr8nmm2vX+/InbbcNYwLX7iUb6yMR1a6I6wRy/GVE9OoxXCqRA1N/ys7r gJQG0lTiS2xSDY7VJL4cD+HmfLnUkixjzaptJiZywx70oegHA2/0MBszXHXmIGzhiPJK5T1JYIchr BsueXKfUF38ZpJdym64ZMwIoMBGT7MCo21vNSzQrFLx3qA71yh6J8bcGRlgm+Z3AlYiAg/kNtjFkZ PyK5ps4ng==; Received: from willy by bombadil.infradead.org with local (Exim 4.90_1 #2 (Red Hat Linux)) id 1fJlJb-00011c-G0; Fri, 18 May 2018 19:45:23 +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 v6 11/17] mm: Improve struct page documentation Date: Fri, 18 May 2018 12:45:13 -0700 Message-Id: <20180518194519.3820-12-willy@infradead.org> X-Mailer: git-send-email 2.14.3 In-Reply-To: <20180518194519.3820-1-willy@infradead.org> References: <20180518194519.3820-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