sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget$/translations/zh_CN/dev-tools/kfencemodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget$/translations/zh_TW/dev-tools/kfencemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget$/translations/it_IT/dev-tools/kfencemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget$/translations/ja_JP/dev-tools/kfencemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget$/translations/ko_KR/dev-tools/kfencemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget$/translations/sp_SP/dev-tools/kfencemodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhh>/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence.rsthKubh)}(hCopyright (C) 2020, Google LLC.h]hCopyright (C) 2020, Google LLC.}hhsbah}(h]h ]h"]h$]h&]hhuh1hhhhhhhhKubhsection)}(hhh](htitle)}(hKernel Electric-Fence (KFENCE)h]hKernel Electric-Fence (KFENCE)}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hKernel Electric-Fence (KFENCE) is a low-overhead sampling-based memory safety error detector. KFENCE detects heap out-of-bounds access, use-after-free, and invalid-free errors.h]hKernel Electric-Fence (KFENCE) is a low-overhead sampling-based memory safety error detector. KFENCE detects heap out-of-bounds access, use-after-free, and invalid-free errors.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXKFENCE is designed to be enabled in production kernels, and has near zero performance overhead. Compared to KASAN, KFENCE trades performance for precision. The main motivation behind KFENCE's design, is that with enough total uptime KFENCE will detect bugs in code paths not typically exercised by non-production test workloads. One way to quickly achieve a large enough total uptime is when the tool is deployed across a large fleet of machines.h]hXKFENCE is designed to be enabled in production kernels, and has near zero performance overhead. Compared to KASAN, KFENCE trades performance for precision. The main motivation behind KFENCE’s design, is that with enough total uptime KFENCE will detect bugs in code paths not typically exercised by non-production test workloads. One way to quickly achieve a large enough total uptime is when the tool is deployed across a large fleet of machines.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hhh](h)}(hUsageh]hUsage}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(h-To enable KFENCE, configure the kernel with::h]h,To enable KFENCE, configure the kernel with:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh literal_block)}(hCONFIG_KFENCE=yh]hCONFIG_KFENCE=y}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhhhhubh)}(hTo build a kernel with KFENCE support, but disabled by default (to enable, set ``kfence.sample_interval`` to non-zero value), configure the kernel with::h](hOTo build a kernel with KFENCE support, but disabled by default (to enable, set }(hj$hhhNhNubhliteral)}(h``kfence.sample_interval``h]hkfence.sample_interval}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1j,hj$ubh/ to non-zero value), configure the kernel with:}(hj$hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubj)}(h/CONFIG_KFENCE=y CONFIG_KFENCE_SAMPLE_INTERVAL=0h]h/CONFIG_KFENCE=y CONFIG_KFENCE_SAMPLE_INTERVAL=0}hjFsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhhhhubh)}(hKFENCE provides several other configuration options to customize behaviour (see the respective help text in ``lib/Kconfig.kfence`` for more info).h](hlKFENCE provides several other configuration options to customize behaviour (see the respective help text in }(hjThhhNhNubj-)}(h``lib/Kconfig.kfence``h]hlib/Kconfig.kfence}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjTubh for more info).}(hjThhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hTuning performanceh]hTuning performance}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjthhhhhK#ubh)}(hXThe most important parameter is KFENCE's sample interval, which can be set via the kernel boot parameter ``kfence.sample_interval`` in milliseconds. The sample interval determines the frequency with which heap allocations will be guarded by KFENCE. The default is configurable via the Kconfig option ``CONFIG_KFENCE_SAMPLE_INTERVAL``. Setting ``kfence.sample_interval=0`` disables KFENCE.h](hkThe most important parameter is KFENCE’s sample interval, which can be set via the kernel boot parameter }(hjhhhNhNubj-)}(h``kfence.sample_interval``h]hkfence.sample_interval}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubh in milliseconds. The sample interval determines the frequency with which heap allocations will be guarded by KFENCE. The default is configurable via the Kconfig option }(hjhhhNhNubj-)}(h!``CONFIG_KFENCE_SAMPLE_INTERVAL``h]hCONFIG_KFENCE_SAMPLE_INTERVAL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubh . Setting }(hjhhhNhNubj-)}(h``kfence.sample_interval=0``h]hkfence.sample_interval=0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubh disables KFENCE.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK%hjthhubh)}(hX The sample interval controls a timer that sets up KFENCE allocations. By default, to keep the real sample interval predictable, the normal timer also causes CPU wake-ups when the system is completely idle. This may be undesirable on power-constrained systems. The boot parameter ``kfence.deferrable=1`` instead switches to a "deferrable" timer which does not force CPU wake-ups on idle systems, at the risk of unpredictable sample intervals. The default is configurable via the Kconfig option ``CONFIG_KFENCE_DEFERRABLE``.h](hXThe sample interval controls a timer that sets up KFENCE allocations. By default, to keep the real sample interval predictable, the normal timer also causes CPU wake-ups when the system is completely idle. This may be undesirable on power-constrained systems. The boot parameter }(hjhhhNhNubj-)}(h``kfence.deferrable=1``h]hkfence.deferrable=1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubh instead switches to a “deferrable” timer which does not force CPU wake-ups on idle systems, at the risk of unpredictable sample intervals. The default is configurable via the Kconfig option }(hjhhhNhNubj-)}(h``CONFIG_KFENCE_DEFERRABLE``h]hCONFIG_KFENCE_DEFERRABLE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK,hjthhubhwarning)}(hThe KUnit test suite is very likely to fail when using a deferrable timer since it currently causes very unpredictable sample intervals.h]h)}(hThe KUnit test suite is very likely to fail when using a deferrable timer since it currently causes very unpredictable sample intervals.h]hThe KUnit test suite is very likely to fail when using a deferrable timer since it currently causes very unpredictable sample intervals.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK5hjubah}(h]h ]h"]h$]h&]uh1jhjthhhhhNubh)}(hXBy default KFENCE will only sample 1 heap allocation within each sample interval. *Burst mode* allows to sample successive heap allocations, where the kernel boot parameter ``kfence.burst`` can be set to a non-zero value which denotes the *additional* successive allocations within a sample interval; setting ``kfence.burst=N`` means that ``1 + N`` successive allocations are attempted through KFENCE for each sample interval.h](hRBy default KFENCE will only sample 1 heap allocation within each sample interval. }(hjhhhNhNubhemphasis)}(h *Burst mode*h]h Burst mode}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhO allows to sample successive heap allocations, where the kernel boot parameter }(hjhhhNhNubj-)}(h``kfence.burst``h]h kfence.burst}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubh2 can be set to a non-zero value which denotes the }(hjhhhNhNubj)}(h *additional*h]h additional}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh: successive allocations within a sample interval; setting }(hjhhhNhNubj-)}(h``kfence.burst=N``h]hkfence.burst=N}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubh means that }(hjhhhNhNubj-)}(h ``1 + N``h]h1 + N}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubhN successive allocations are attempted through KFENCE for each sample interval.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK8hjthhubh)}(hXThe KFENCE memory pool is of fixed size, and if the pool is exhausted, no further KFENCE allocations occur. With ``CONFIG_KFENCE_NUM_OBJECTS`` (default 255), the number of available guarded objects can be controlled. Each object requires 2 pages, one for the object itself and the other one used as a guard page; object pages are interleaved with guard pages, and every object page is therefore surrounded by two guard pages.h](hqThe KFENCE memory pool is of fixed size, and if the pool is exhausted, no further KFENCE allocations occur. With }(hjhhhNhNubj-)}(h``CONFIG_KFENCE_NUM_OBJECTS``h]hCONFIG_KFENCE_NUM_OBJECTS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubhX (default 255), the number of available guarded objects can be controlled. Each object requires 2 pages, one for the object itself and the other one used as a guard page; object pages are interleaved with guard pages, and every object page is therefore surrounded by two guard pages.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK?hjthhubh)}(hIThe total memory dedicated to the KFENCE memory pool can be computed as::h]hHThe total memory dedicated to the KFENCE memory pool can be computed as:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKFhjthhubj)}(h ( #objects + 1 ) * 2 * PAGE_SIZEh]h ( #objects + 1 ) * 2 * PAGE_SIZE}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKHhjthhubh)}(hsUsing the default config, and assuming a page size of 4 KiB, results in dedicating 2 MiB to the KFENCE memory pool.h]hsUsing the default config, and assuming a page size of 4 KiB, results in dedicating 2 MiB to the KFENCE memory pool.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKJhjthhubh)}(hNote: On architectures that support huge pages, KFENCE will ensure that the pool is using pages of size ``PAGE_SIZE``. This will result in additional page tables being allocated.h](hhNote: On architectures that support huge pages, KFENCE will ensure that the pool is using pages of size }(hjhhhNhNubj-)}(h ``PAGE_SIZE``h]h PAGE_SIZE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubh=. This will result in additional page tables being allocated.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKMhjthhubeh}(h]tuning-performanceah ]h"]tuning performanceah$]h&]uh1hhhhhhhhK#ubh)}(hhh](h)}(h Error reportsh]h Error reports}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKRubh)}(h0A typical out-of-bounds access looks like this::h]h/A typical out-of-bounds access looks like this:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKThjhhubj)}(hXp================================================================== BUG: KFENCE: out-of-bounds read in test_out_of_bounds_read+0xa6/0x234 Out-of-bounds read at 0xffff8c3f2e291fff (1B left of kfence-#72): test_out_of_bounds_read+0xa6/0x234 kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 kfence-#72: 0xffff8c3f2e292000-0xffff8c3f2e29201f, size=32, cache=kmalloc-32 allocated by task 484 on cpu 0 at 32.919330s: test_alloc+0xfe/0x738 test_out_of_bounds_read+0x9b/0x234 kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 CPU: 0 PID: 484 Comm: kunit_try_catch Not tainted 5.13.0-rc3+ #7 Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014 ==================================================================h]hXp================================================================== BUG: KFENCE: out-of-bounds read in test_out_of_bounds_read+0xa6/0x234 Out-of-bounds read at 0xffff8c3f2e291fff (1B left of kfence-#72): test_out_of_bounds_read+0xa6/0x234 kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 kfence-#72: 0xffff8c3f2e292000-0xffff8c3f2e29201f, size=32, cache=kmalloc-32 allocated by task 484 on cpu 0 at 32.919330s: test_alloc+0xfe/0x738 test_out_of_bounds_read+0x9b/0x234 kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 CPU: 0 PID: 484 Comm: kunit_try_catch Not tainted 5.13.0-rc3+ #7 Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014 ==================================================================}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKVhjhhubh)}(hXThe header of the report provides a short summary of the function involved in the access. It is followed by more detailed information about the access and its origin. Note that, real kernel addresses are only shown when using the kernel command line option ``no_hash_pointers``.h](hXThe header of the report provides a short summary of the function involved in the access. It is followed by more detailed information about the access and its origin. Note that, real kernel addresses are only shown when using the kernel command line option }(hjhhhNhNubj-)}(h``no_hash_pointers``h]hno_hash_pointers}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKnhjhhubh)}(h)Use-after-free accesses are reported as::h]h(Use-after-free accesses are reported as:}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKshjhhubj)}(hXG================================================================== BUG: KFENCE: use-after-free read in test_use_after_free_read+0xb3/0x143 Use-after-free read at 0xffff8c3f2e2a0000 (in kfence-#79): test_use_after_free_read+0xb3/0x143 kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 kfence-#79: 0xffff8c3f2e2a0000-0xffff8c3f2e2a001f, size=32, cache=kmalloc-32 allocated by task 488 on cpu 2 at 33.871326s: test_alloc+0xfe/0x738 test_use_after_free_read+0x76/0x143 kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 freed by task 488 on cpu 2 at 33.871358s: test_use_after_free_read+0xa8/0x143 kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 CPU: 2 PID: 488 Comm: kunit_try_catch Tainted: G B 5.13.0-rc3+ #7 Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014 ==================================================================h]hXG================================================================== BUG: KFENCE: use-after-free read in test_use_after_free_read+0xb3/0x143 Use-after-free read at 0xffff8c3f2e2a0000 (in kfence-#79): test_use_after_free_read+0xb3/0x143 kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 kfence-#79: 0xffff8c3f2e2a0000-0xffff8c3f2e2a001f, size=32, cache=kmalloc-32 allocated by task 488 on cpu 2 at 33.871326s: test_alloc+0xfe/0x738 test_use_after_free_read+0x76/0x143 kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 freed by task 488 on cpu 2 at 33.871358s: test_use_after_free_read+0xa8/0x143 kunit_try_run_case+0x61/0xa0 kunit_generic_run_threadfn_adapter+0x16/0x30 kthread+0x176/0x1b0 ret_from_fork+0x22/0x30 CPU: 2 PID: 488 Comm: kunit_try_catch Tainted: G B 5.13.0-rc3+ #7 Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014 ==================================================================}hjLsbah}(h]h ]h"]h$]h&]hhuh1jhhhKuhjhhubh)}(hsize** e.g. for kmalloc caches) ``gfp_t flags`` GFP flags **Return** * NULL - must proceed with allocating as usual, * non-NULL - pointer to a KFENCE object. **Description** kfence_alloc() should be inserted into the heap allocation fast path, allowing it to transparently return KFENCE-allocated objects with a low probability using a static branch (the probability is controlled by the kfence.sample_interval boot parameter).h](h)}(h**Parameters**h]ju)}(hj h]h Parameters}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKkhj ubj)}(hhh](j)}(hD``struct kmem_cache *s`` struct kmem_cache with object requirements h](j)}(h``struct kmem_cache *s``h]j-)}(hj h]hstruct kmem_cache *s}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j,hj ubah}(h]h ]h"]h$]h&]uh1jhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhhj ubj)}(hhh]h)}(h*struct kmem_cache with object requirementsh]h*struct kmem_cache with object requirements}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hKhhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj hKhhj ubj)}(hl``size_t size`` exact size of the object to allocate (can be less than **s->size** e.g. for kmalloc caches) h](j)}(h``size_t size``h]j-)}(hj h]h size_t size}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j,hj ubah}(h]h ]h"]h$]h&]uh1jhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKjhj ubj)}(hhh]h)}(h[exact size of the object to allocate (can be less than **s->size** e.g. for kmalloc caches)h](h7exact size of the object to allocate (can be less than }(hj hhhNhNubju)}(h **s->size**h]hs->size}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubh e.g. for kmalloc caches)}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKihj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj hKjhj ubj)}(h``gfp_t flags`` GFP flags h](j)}(h``gfp_t flags``h]j-)}(hj3 h]h gfp_t flags}(hj5 hhhNhNubah}(h]h ]h"]h$]h&]uh1j,hj1 ubah}(h]h ]h"]h$]h&]uh1jhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKkhj- ubj)}(hhh]h)}(h GFP flagsh]h GFP flags}(hjL hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjH hKkhjI ubah}(h]h ]h"]h$]h&]uh1jhj- ubeh}(h]h ]h"]h$]h&]uh1jhjH hKkhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubh)}(h **Return**h]ju)}(hjn h]hReturn}(hjp hhhNhNubah}(h]h ]h"]h$]h&]uh1jthjl ubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKmhj ubj)}(hhh](j )}(h1NULL - must proceed with allocating as usual,h]h)}(hj h]h1NULL - must proceed with allocating as usual,}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKmhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(h'non-NULL - pointer to a KFENCE object. h]h)}(h&non-NULL - pointer to a KFENCE object.h]h&non-NULL - pointer to a KFENCE object.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKnhj ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]jhjiuh1jhj hKmhj ubh)}(h**Description**h]ju)}(hj h]h Description}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKphj ubh)}(hkfence_alloc() should be inserted into the heap allocation fast path, allowing it to transparently return KFENCE-allocated objects with a low probability using a static branch (the probability is controlled by the kfence.sample_interval boot parameter).h]hkfence_alloc() should be inserted into the heap allocation fast path, allowing it to transparently return KFENCE-allocated objects with a low probability using a static branch (the probability is controlled by the kfence.sample_interval boot parameter).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKqhj ubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhj9hhhNhNubjY)}(hhh]h}(h]h ]h"]h$]h&]entries](jekfence_ksize (C function)c.kfence_ksizehNtauh1jXhj9hhhNhNubjj)}(hhh](jo)}(h&size_t kfence_ksize (const void *addr)h]ju)}(h%size_t kfence_ksize(const void *addr)h](h)}(hhh]j)}(hsize_th]hsize_t}(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&] refdomainj_reftypej reftargetj modnameN classnameNjj)}j]j)}j kfence_ksizesbc.kfence_ksizeasbuh1hhj hhhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKubj)}(h h]h }(hj* hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj hhhj) hKubj)}(h kfence_ksizeh]j)}(hj& h]h kfence_ksize}(hj< hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj8 ubah}(h]h ](jjeh"]h$]h&]hhuh1jhj hhhj) hKubj)}(h(const void *addr)h]j)}(hconst void *addrh](j)}(hjh]hconst}(hjW hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjS ubj)}(h h]h }(hjd hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjS ubj{)}(hvoidh]hvoid}(hjr hhhNhNubah}(h]h ]jah"]h$]h&]uh1jzhjS ubj)}(h h]h }(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjS ubj)}(hjih]h*}(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjS ubj)}(haddrh]haddr}(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjS ubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjO ubah}(h]h ]h"]h$]h&]hhuh1jhj hhhj) hKubeh}(h]h ]h"]h$]h&]hhj4uh1jtj5j6hj hhhj) hKubah}(h]j ah ](j:j;eh"]h$]h&]j?j@)jAhuh1jnhj) hKhj hhubjC)}(hhh]h)}(h9get actual amount of memory allocated for a KFENCE objecth]h9get actual amount of memory allocated for a KFENCE object}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhj hhubah}(h]h ]h"]h$]h&]uh1jBhj hhhj) hKubeh}(h]h ](j_functioneh"]h$]h&]jdj_jej jfj jgjhjiuh1jihhhj9hNhNubjk)}(hX**Parameters** ``const void *addr`` pointer to a heap object **Return** * 0 - not a KFENCE object, must call __ksize() instead, * non-0 - this many bytes can be accessed without causing a memory error. **Description** kfence_ksize() returns the number of bytes requested for a KFENCE object at allocation time. This number may be less than the object size of the corresponding struct kmem_cache.h](h)}(h**Parameters**h]ju)}(hj h]h Parameters}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhj ubj)}(hhh]j)}(h.``const void *addr`` pointer to a heap object h](j)}(h``const void *addr``h]j-)}(hj h]hconst void *addr}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j,hj ubah}(h]h ]h"]h$]h&]uh1jhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhj ubj)}(hhh]h)}(hpointer to a heap objecth]hpointer to a heap object}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj hKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubh)}(h **Return**h]ju)}(hjA h]hReturn}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj? ubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhj ubj)}(hhh](j )}(h90 - not a KFENCE object, must call __ksize() instead,h]h)}(hj\ h]h90 - not a KFENCE object, must call __ksize() instead,}(hj^ |hhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjZ ubah}(h]h ]h"]h$]h&]uh1j hjW ubj )}(hHnon-0 - this many bytes can be accessed without causing a memory error. h]h)}(hGnon-0 - this many bytes can be accessed without causing a memory error.h]hGnon-0 - this many bytes can be accessed without causing a memory error.}(hjv hhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjr ubah}(h]h ]h"]h$]h&]uh1j hjW ubeh}(h]h ]h"]h$]h&]jhjiuh1jhjk hKhj ubh)}(h**Description**h]ju)}(hj h]h Description}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhj ubh)}(hkfence_ksize() returns the number of bytes requested for a KFENCE object at allocation time. This number may be less than the object size of the corresponding struct kmem_cache.h]hkfence_ksize() returns the number of bytes requested for a KFENCE object at allocation time. This number may be less than the object size of the corresponding struct kmem_cache.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhj ubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhj9hhhNhNubjY)}(hhh]h}(h]h ]h"]h$]h&]entries](je kfence_object_start (C function)c.kfence_object_starthNtauh1jXhj9hhhNhNubjj)}(hhh](jo)}(h-void * kfence_object_start (const void *addr)h]ju)}(h+void *kfence_object_start(const void *addr)h](j{)}(hvoidh]hvoid}(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jzhj hhhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKubj)}(h h]h }(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj hhhj hKubj)}(hjih]h*}(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj hhhj hKubj)}(hkfence_object_starth]j)}(hkfence_object_starth]hkfence_object_start}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubah}(h]h ](jjeh"]h$]h&]hhuh1jhj hhhj hKubj)}(h(const void *addr)h]j)}(hconst void *addrh](j)}(hjh]hconst}(hj"hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(h h]h }(hj/hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj{)}(hvoidh]hvoid}(hj=hhhNhNubah}(h]h ]jah"]h$]h&]uh1jzhjubj)}(h h]h }(hjKhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(hjih]h*}(hjYhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(haddrh]haddr}(hjfhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubah}(h]h ]h"]h$]h&]hhuh1jhj hhhj hKubeh}(h]h ]h"]h$]h&]hhj4uh1jtj5j6hj hhhj hKubah}(h]j ah ](j:j;eh"]h$]h&]j?j@)jAhuh1jnhj hKhj hhubjC)}(hhh]h)}(h%find the beginning of a KFENCE objecth]h%find the beginning of a KFENCE object}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjhhubah}(h]h ]h"]h$]h&]uh1jBhj hhhj hKubeh}(h]h ](j_functioneh"]h$]h&]jdj_jejjfjjgjhjiuh1jihhhj9hNhNubjk)}(hX**Parameters** ``const void *addr`` address within a KFENCE-allocated object **Return** address of the beginning of the object. **Description** SL[AU]B-allocated objects are laid out within a page one by one, so it is easy to calculate the beginning of an object given a pointer inside it and the object size. The same is not true for KFENCE, which places a single object at either end of the page. This helper function is used to find the beginning of a KFENCE-allocated object.h](h)}(h**Parameters**h]ju)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubj)}(hhh]j)}(h>``const void *addr`` address within a KFENCE-allocated object h](j)}(h``const void *addr``h]j-)}(hjh]hconst void *addr}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubah}(h]h ]h"]h$]h&]uh1jhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubj)}(hhh]h)}(h(address within a KFENCE-allocated objecth]h(address within a KFENCE-allocated object}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjubh)}(h **Return**h]ju)}(hj h]hReturn}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubh)}(h'address of the beginning of the object.h]h'address of the beginning of the object.}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubh)}(h**Description**h]ju)}(hj3h]h Description}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj1ubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubh)}(hXOSL[AU]B-allocated objects are laid out within a page one by one, so it is easy to calculate the beginning of an object given a pointer inside it and the object size. The same is not true for KFENCE, which places a single object at either end of the page. This helper function is used to find the beginning of a KFENCE-allocated object.h]hXOSL[AU]B-allocated objects are laid out within a page one by one, so it is easy to calculate the beginning of an object given a pointer inside it and the object size. The same is not true for KFENCE, which places a single object at either end of the page. This helper function is used to find the beginning of a KFENCE-allocated object.}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhj9hhhNhNubjY)}(hhh]h}(h]h ]h"]h$]h&]entries](je__kfence_free (C function)c.__kfence_freehNtauh1jXhj9hhhNhNubjj)}(hhh](jo)}(hvoid __kfence_free (void *addr)h]ju)}(hvoid __kfence_free(void *addr)h](j{)}(hvoidh]hvoid}(hjxhhhNhNubah}(h]h ]jah"]h$]h&]uh1jzhjthhhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKubj)}(h h]h }(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjthhhjhKubj)}(h __kfence_freeh]j)}(h __kfence_freeh]h __kfence_free}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubah}(h]h ](jjeh"]h$]h&]hhuh1jhjthhhjhKubj)}(h (void *addr)h]j)}(h void *addrh](j{)}(hvoidh]hvoid}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jzhjubj)}(h h]h }(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(hjih]h*}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(haddrh]haddr}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubah}(h]h ]h"]h$]h&]hhuh1jhjthhhjhKubeh}(h]h ]h"]h$]h&]hhj4uh1jtj5j6hjphhhjhKubah}(h]jkah ](j:j;eh"]h$]h&]j?j@)jAhuh1jnhjhKhjmhhubjC)}(hhh]h)}(h+release a KFENCE heap object to KFENCE poolh]h+release a KFENCE heap object to KFENCE pool}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjhhubah}(h]h ]h"]h$]h&]uh1jBhjmhhhjhKubeh}(h]h ](j_functioneh"]h$]h&]jdj_jej jfj jgjhjiuh1jihhhj9hNhNubjk)}(h**Parameters** ``void *addr`` object to be freed **Description** Requires: is_kfence_address(addr) Release a KFENCE object and mark it as freed.h](h)}(h**Parameters**h]ju)}(hj*h]h Parameters}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj(ubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhj$ubj)}(hhh]j)}(h"``void *addr`` object to be freed h](j)}(h``void *addr``h]j-)}(hjIh]h void *addr}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjGubah}(h]h ]h"]h$]h&]uh1jhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjCubj)}(hhh]h)}(hobject to be freedh]hobject to be freed}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj^hKhj_ubah}(h]h ]h"]h$]h&]uh1jhjCubeh}(h]h ]h"]h$]h&]uh1jhj^hKhj@ubah}(h]h ]h"]h$]h&]uh1jhj$ubh)}(h**Description**h]ju)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhj$ubh)}(h!Requires: is_kfence_address(addr)h]h!Requires: is_kfence_address(addr)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhj$ubh)}(h-Release a KFENCE object and mark it as freed.h]h-Release a KFENCE object and mark it as freed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhj$ubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhj9hhhNhNubjY)}(hhh]h}(h]h ]h"]h$]h&]entries](jekfence_free (C function) c.kfence_freehNtauh1jXhj9hhhNhNubjj)}(hhh](jo)}(hbool kfence_free (void *addr)h]ju)}(hbool kfence_free(void *addr)h](j{)}(hj~h]hbool}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jzhjhhhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKubj)}(h h]h }(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjhhhjhKubj)}(h kfence_freeh]j)}(h kfence_freeh]h kfence_free}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubah}(h]h ](jjeh"]h$]h&]hhuh1jhjhhhjhKubj)}(h (void *addr)h]j)}(h void *addrh](j{)}(hvoidh]hvoid}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jzhjubj)}(h h]h }(hj"hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(hjih]h*}(hj0hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(haddrh]haddr}(hj=hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhj ubah}(h]h ]h"]h$]h&]hhuh1jhjhhhjhKubeh}(h]h ]h"]h$]h&]hhj4uh1jtj5j6hjhhhjhKubah}(h]jah ](j:j;eh"]h$]h&]j?j@)jAhuh1jnhjhKhjhhubjC)}(hhh]h)}(h6try to release an arbitrary heap object to KFENCE poolh]h6try to release an arbitrary heap object to KFENCE pool}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjdhhubah}(h]h ]h"]h$]h&]uh1jBhjhhhjhKubeh}(h]h ](j_functioneh"]h$]h&]jdj_jejjfjjgjhjiuh1jihhhj9hNhNubjk)}(hX**Parameters** ``void *addr`` object to be freed **Return** * false - object doesn't belong to KFENCE pool and was ignored, * true - object was released to KFENCE pool. **Description** Release a KFENCE object and mark it as freed. May be called on any object, even non-KFENCE objects, to simplify integration of the hooks into the allocator's free codepath. The allocator must check the return value to determine if it was a KFENCE object or not.h](h)}(h**Parameters**h]ju)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubj)}(hhh]j)}(h"``void *addr`` object to be freed h](j)}(h``void *addr``h]j-)}(hjh]h void *addr}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubah}(h]h ]h"]h$]h&]uh1jhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubj)}(hhh]h)}(hobject to be freedh]hobject to be freed}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjubh)}(h **Return**h]ju)}(hjh]hReturn}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubj)}(hhh](j )}(h=false - object doesn't belong to KFENCE pool and was ignored,h]h)}(hjh]h?false - object doesn’t belong to KFENCE pool and was ignored,}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubah}(h]h ]h"]h$]h&]uh1j hjubj )}(h,true - object was released to KFENCE pool. h]h)}(h+true - object was released to KFENCE pool.h]h+true - object was released to KFENCE pool.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubah}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]jhjiuh1jhj hKhjubh)}(h**Description**h]ju)}(hj5h]h Description}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj3ubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubh)}(hXRelease a KFENCE object and mark it as freed. May be called on any object, even non-KFENCE objects, to simplify integration of the hooks into the allocator's free codepath. The allocator must check the return value to determine if it was a KFENCE object or not.h]hXRelease a KFENCE object and mark it as freed. May be called on any object, even non-KFENCE objects, to simplify integration of the hooks into the allocator’s free codepath. The allocator must check the return value to determine if it was a KFENCE object or not.}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhj9hhhNhNubjY)}(hhh]h}(h]h ]h"]h$]h&]entries](je%kfence_handle_page_fault (C function)c.kfence_handle_page_faulthNtauh1jXhj9hhhNhNubjj)}(hhh](jo)}(hWbool kfence_handle_page_fault (unsigned long addr, bool is_write, struct pt_regs *regs)h]ju)}(hVbool kfence_handle_page_fault(unsigned long addr, bool is_write, struct pt_regs *regs)h](j{)}(hj~h]hbool}(hjzhhhNhNubah}(h]h ]jah"]h$]h&]uh1jzhjvhhhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKubj)}(h h]h }(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjvhhhjhKubj)}(hkfence_handle_page_faulth]j)}(hkfence_handle_page_faulth]hkfence_handle_page_fault}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubah}(h]h ](jjeh"]h$]h&]hhuh1jhjvhhhjhKubj)}(h9(unsigned long addr, bool is_write, struct pt_regs *regs)h](j)}(hunsigned long addrh](j{)}(hunsignedh]hunsigned}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jzhjubj)}(h h]h }(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj{)}(hlongh]hlong}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jzhjubj)}(h h]h }(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(haddrh]haddr}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubj)}(h bool is_writeh](j{)}(hj~h]hbool}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jzhjubj)}(h h]h }(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(his_writeh]his_write}(hj"hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubj)}(hstruct pt_regs *regsh](j)}(hjh]hstruct}(hj;hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj7ubj)}(h h]h }(hjHhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj7ubh)}(hhh]j)}(hpt_regsh]hpt_regs}(hjYhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjVubah}(h]h ]h"]h$]h&] refdomainj_reftypej reftargetj[modnameN classnameNjj)}j]j)}jjsbc.kfence_handle_page_faultasbuh1hhj7ubj)}(h h]h }(hjyhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj7ubj)}(hjih]h*}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj7ubj)}(hregsh]hregs}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj7ubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubeh}(h]h ]h"]h$]h&]hhuh1jhjvhhhjhKubeh}(h]h ]h"]h$]h&]hhj4uh1jtj5j6hjrhhhjhKubah}(h]jmah ](j:j;eh"]h$]h&]j?j@)jAhuh1jnhjhKhjohhubjC)}(hhh]h)}(h,perform page fault handling for KFENCE pagesh]h,perform page fault handling for KFENCE pages}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjhhubah}(h]h ]h"]h$]h&]uh1jBhjohhhjhKubeh}(h]h ](j_functioneh"]h$]h&]jdj_jejjfjjgjhjiuh1jihhhj9hNhNubjk)}(hXL**Parameters** ``unsigned long addr`` faulting address ``bool is_write`` is access a write ``struct pt_regs *regs`` current struct pt_regs (can be NULL, but shows full stack trace) **Return** * false - address outside KFENCE pool, * true - page fault handled by KFENCE, no additional handling required. **Description** A page fault inside KFENCE pool indicates a memory error, such as an out-of-bounds access, a use-after-free or an invalid memory access. In these cases KFENCE prints an error message and marks the offending page as present, so that the kernel can proceed.h](h)}(h**Parameters**h]ju)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubj)}(hhh](j)}(h(``unsigned long addr`` faulting address h](j)}(h``unsigned long addr``h]j-)}(hjh]hunsigned long addr}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjubah}(h]h ]h"]h$]h&]uh1jhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubj)}(hhh]h)}(hfaulting addressh]hfaulting address}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjhKhjubj)}(h$``bool is_write`` is access a write h](j)}(h``bool is_write``h]j-)}(hj8h]h bool is_write}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1j,hj6ubah}(h]h ]h"]h$]h&]uh1jhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhj2ubj)}(hhh]h)}(his access a writeh]his access a write}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjMhKhjNubah}(h]h ]h"]h$]h&]uh1jhj2ubeh}(h]h ]h"]h$]h&]uh1jhjMhKhjubj)}(hZ``struct pt_regs *regs`` current struct pt_regs (can be NULL, but shows full stack trace) h](j)}(h``struct pt_regs *regs``h]j-)}(hjqh]hstruct pt_regs *regs}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1j,hjoubah}(h]h ]h"]h$]h&]uh1jhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjkubj)}(hhh]h)}(h@current struct pt_regs (can be NULL, but shows full stack trace)h]h@current struct pt_regs (can be NULL, but shows full stack trace)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjkubeh}(h]h ]h"]h$]h&]uh1jhjhKhjubeh}(h]h ]h"]h$]h&]uh1jhjubh)}(h **Return**h]ju)}(hjh]hReturn}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubj)}(hhh](j )}(h$false - address outside KFENCE pool,h]h)}(hjh]h$false - address outside KFENCE pool,}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubah}(h]h ]h"]h$]h&]uh1j hjubj )}(hGtrue - page fault handled by KFENCE, no additional handling required. h]h)}(hFtrue - page fault handled by KFENCE, no additional handling required.h]hFtrue - page fault handled by KFENCE, no additional handling required.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubah}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]jhjiuh1jhjhKhjubh)}(h**Description**h]ju)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubh)}(hA page fault inside KFENCE pool indicates a memory error, such as an out-of-bounds access, a use-after-free or an invalid memory access. In these cases KFENCE prints an error message and marks the offending page as present, so that the kernel can proceed.h]hA page fault inside KFENCE pool indicates a memory error, such as an out-of-bounds access, a use-after-free or an invalid memory access. In these cases KFENCE prints an error message and marks the offending page as present, so that the kernel can proceed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhX/var/lib/git/docbuild/linux/Documentation/dev-tools/kfence:312: ./include/linux/kfence.hhKhjubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhj9hhhNhNubeh}(h] interfaceah ]h"] interfaceah$]h&]uh1hhhhhhhhM3ubh)}(hhh](h)}(h Related Toolsh]h Related Tools}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj2hhhhhM@ubh)}(hXIn userspace, a similar approach is taken by `GWP-ASan `_. GWP-ASan also relies on guard pages and a sampling strategy to detect memory unsafety bugs at scale. KFENCE's design is directly influenced by GWP-ASan, and can be seen as its kernel sibling. Another similar but non-sampling approach, that also inspired the name "KFENCE", can be found in the userspace `Electric Fence Malloc Debugger `_.h](h-In userspace, a similar approach is taken by }(hjChhhNhNubh reference)}(h/`GWP-ASan `_h]hGWP-ASan}(hjMhhhNhNubah}(h]h ]h"]h$]h&]nameGWP-ASanrefuri!http://llvm.org/docs/GwpAsan.htmluh1jKhjCubhtarget)}(h$ h]h}(h]gwp-asanah ]h"]gwp-asanah$]h&]refurij^uh1j_ referencedKhjCubhX7. GWP-ASan also relies on guard pages and a sampling strategy to detect memory unsafety bugs at scale. KFENCE’s design is directly influenced by GWP-ASan, and can be seen as its kernel sibling. Another similar but non-sampling approach, that also inspired the name “KFENCE”, can be found in the userspace }(hjChhhNhNubjL)}(hF`Electric Fence Malloc Debugger `_h]hElectric Fence Malloc Debugger}(hjshhhNhNubah}(h]h ]h"]h$]h&]nameElectric Fence Malloc Debuggerj]"https://linux.die.net/man/3/efenceuh1jKhjCubj`)}(h% h]h}(h]electric-fence-malloc-debuggerah ]h"]electric fence malloc debuggerah$]h&]refurijuh1j_jnKhjCubh.}(hjChhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMBhj2hhubh)}(hIn the kernel, several tools exist to debug memory access errors, and in particular KASAN can detect all bug classes that KFENCE can detect. While KASAN is more precise, relying on compiler instrumentation, this comes at a performance cost.h]hIn the kernel, several tools exist to debug memory access errors, and in particular KASAN can detect all bug classes that KFENCE can detect. While KASAN is more precise, relying on compiler instrumentation, this comes at a performance cost.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhj2hhubh)}(hXIt is worth highlighting that KASAN and KFENCE are complementary, with different target environments. For instance, KASAN is the better debugging-aid, where test cases or reproducers exists: due to the lower chance to detect the error, it would require more effort using KFENCE to debug. Deployments at scale that cannot afford to enable KASAN, however, would benefit from using KFENCE to discover bugs due to code paths not exercised by test cases or fuzzers.h]hXIt is worth highlighting that KASAN and KFENCE are complementary, with different target environments. For instance, KASAN is the better debugging-aid, where test cases or reproducers exists: due to the lower chance to detect the error, it would require more effort using KFENCE to debug. Deployments at scale that cannot afford to enable KASAN, however, would benefit from using KFENCE to discover bugs due to code paths not exercised by test cases or fuzzers.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMOhj2hhubeh}(h] related-toolsah ]h"] related toolsah$]h&]uh1hhhhhhhhM@ubeh}(h]kernel-electric-fence-kfenceah ]h"]kernel electric-fence (kfence)ah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jjjwjtjjjjjojlj6j3j/j,jjjjjgjju nametypes}(jjwjjjoj6j/jjjjuh}(jhjthjjtjjjljj3jzj,j9jgjpj\jaj j j j j j jkjpjjjmjrjj2jgjajju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.