Add kernel-doc for several functions relating to take the folio lock.
Unified · Split
| @@ -888,6 +888,18 @@ bool __folio_lock_or_retry(struct folio *folio, struct mm_struct *mm, · 887 unmodified lines | |||
| 888 | void unlock_page(struct page *page); | 888 | void unlock_page(struct page *page); |
| 889 | void folio_unlock(struct folio *folio); | 889 | void folio_unlock(struct folio *folio); |
| 890 | 890 | ||
| 891 | /** | ||
| 892 | * folio_trylock() - Attempt to lock a folio. | ||
| 893 | * @folio: The folio to attempt to lock. | ||
| 894 | * | ||
| 895 | * Sometimes it is undesirable to wait for a folio to be unlocked (eg | ||
| 896 | * when the locks are being taken in the wrong order, or if making | ||
| 897 | * progress through a batch of folios is more important than processing | ||
| 898 | * them in order). Usually folio_lock() is the correct function to call. | ||
| 899 | * | ||
| 900 | * Context: Any context. | ||
| 901 | * Return: Whether the lock was successfully acquired. | ||
| 902 | */ | ||
| 891 | static inline bool folio_trylock(struct folio *folio) | 903 | static inline bool folio_trylock(struct folio *folio) |
| 892 | { | 904 | { |
| 893 | return likely(!test_and_set_bit_lock(PG_locked, folio_flags(folio, 0))); | 905 | return likely(!test_and_set_bit_lock(PG_locked, folio_flags(folio, 0))); |
| @@ -901,6 +913,28 @@ static inline int trylock_page(struct page *page) · 7 unmodified lines | |||
| 901 | return folio_trylock(page_folio(page)); | 913 | return folio_trylock(page_folio(page)); |
| 902 | } | 914 | } |
| 903 | 915 | ||
| 916 | /** | ||
| 917 | * folio_lock() - Lock this folio. | ||
| 918 | * @folio: The folio to lock. | ||
| 919 | * | ||
| 920 | * The folio lock protects against many things, probably more than it | ||
| 921 | * should. It is primarily held while a folio is being brought uptodate, | ||
| 922 | * either from its backing file or from swap. It is also held while a | ||
| 923 | * folio is being truncated from its address_space, so holding the lock | ||
| 924 | * is sufficient to keep folio->mapping stable. | ||
| 925 | * | ||
| 926 | * The folio lock is also held while write() is modifying the page to | ||
| 927 | * provide POSIX atomicity guarantees (as long as the write does not | ||
| 928 | * cross a page boundary). Other modifications to the data in the folio | ||
| 929 | * do not hold the folio lock and can race with writes, eg DMA and stores | ||
| 930 | * to mapped pages. | ||
| 931 | * | ||
| 932 | * Context: May sleep. If you need to acquire the locks of two or | ||
| 933 | * more folios, they must be in order of ascending index, if they are | ||
| 934 | * in the same address_space. If they are in different address_spaces, | ||
| 935 | * acquire the lock of the folio which belongs to the address_space which | ||
| 936 | * has the lowest address in memory first. | ||
| 937 | */ | ||
| 904 | static inline void folio_lock(struct folio *folio) | 938 | static inline void folio_lock(struct folio *folio) |
| 905 | { | 939 | { |
| 906 | might_sleep(); | 940 | might_sleep(); |
| @@ -908,6 +942,17 @@ static inline void folio_lock(struct folio *folio) · 1 unmodified line | |||
| 908 | __folio_lock(folio); | 942 | __folio_lock(folio); |
| 909 | } | 943 | } |
| 910 | 944 | ||
| 945 | /** | ||
| 946 | * lock_page() - Lock the folio containing this page. | ||
| 947 | * @page: The page to lock. | ||
| 948 | * | ||
| 949 | * See folio_lock() for a description of what the lock protects. | ||
| 950 | * This is a legacy function and new code should probably use folio_lock() | ||
| 951 | * instead. | ||
| 952 | * | ||
| 953 | * Context: May sleep. Pages in the same folio share a lock, so do not | ||
| 954 | * attempt to lock two pages which share a folio. | ||
| 955 | */ | ||
| 911 | static inline void lock_page(struct page *page) | 956 | static inline void lock_page(struct page *page) |
| 912 | { | 957 | { |
| 913 | struct folio *folio; | 958 | struct folio *folio; |
| @@ -918,6 +963,16 @@ static inline void lock_page(struct page *page) · 4 unmodified lines | |||
| 918 | __folio_lock(folio); | 963 | __folio_lock(folio); |
| 919 | } | 964 | } |
| 920 | 965 | ||
| 966 | /** | ||
| 967 | * folio_lock_killable() - Lock this folio, interruptible by a fatal signal. | ||
| 968 | * @folio: The folio to lock. | ||
| 969 | * | ||
| 970 | * Attempts to lock the folio, like folio_lock(), except that the sleep | ||
| 971 | * to acquire the lock is interruptible by a fatal signal. | ||
| 972 | * | ||
| 973 | * Context: May sleep; see folio_lock(). | ||
| 974 | * Return: 0 if the lock was acquired; -EINTR if a fatal signal was received. | ||
| 975 | */ | ||
| 921 | static inline int folio_lock_killable(struct folio *folio) | 976 | static inline int folio_lock_killable(struct folio *folio) |
| 922 | { | 977 | { |
| 923 | might_sleep(); | 978 | might_sleep(); |
| @@ -964,8 +1019,8 @@ int folio_wait_bit_killable(struct folio *folio, int bit_nr); · 40 unmodified lines | |||
| 964 | * Wait for a folio to be unlocked. | 1019 | * Wait for a folio to be unlocked. |
| 965 | * | 1020 | * |
| 966 | * This must be called with the caller "holding" the folio, | 1021 | * This must be called with the caller "holding" the folio, |
| 967 | * ie with increased "page->count" so that the folio won't | 1022 | * ie with increased folio reference count so that the folio won't |
| 968 | * go away during the wait.. | 1023 | * go away during the wait. |
| 969 | */ | 1024 | */ |
| 970 | static inline void folio_wait_locked(struct folio *folio) | 1025 | static inline void folio_wait_locked(struct folio *folio) |
| 971 | { | 1026 | { |