]>
Commit | Line | Data |
---|---|---|
2d815d95 AZ |
1 | .\" |
2 | .\" The contents of this file are subject to the terms of the Common Development | |
3 | .\" and Distribution License (the "License"). You may not use this file except | |
4 | .\" in compliance with the License. You can obtain a copy of the license at | |
1d3ba0bf | 5 | .\" usr/src/OPENSOLARIS.LICENSE or https://opensource.org/licenses/CDDL-1.0. |
2d815d95 AZ |
6 | .\" |
7 | .\" See the License for the specific language governing permissions and | |
8 | .\" limitations under the License. When distributing Covered Code, include this | |
9 | .\" CDDL HEADER in each file and include the License file at | |
10 | .\" usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this | |
11 | .\" CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your | |
12 | .\" own identifying information: | |
13 | .\" Portions Copyright [yyyy] [name of copyright owner] | |
30607d9b TF |
14 | .\" |
15 | .\" Copyright 2013 Turbo Fredriksson <turbo@bayour.com>. All rights reserved. | |
16 | .\" | |
2d815d95 | 17 | .Dd August 24, 2020 |
2badb345 | 18 | .Dt SPL 4 |
2d815d95 AZ |
19 | .Os |
20 | . | |
21 | .Sh NAME | |
2badb345 | 22 | .Nm spl |
2d815d95 AZ |
23 | .Nd parameters of the SPL kernel module |
24 | . | |
25 | .Sh DESCRIPTION | |
26 | .Bl -tag -width Ds | |
27 | .It Sy spl_kmem_cache_kmem_threads Ns = Ns Sy 4 Pq uint | |
28 | The number of threads created for the spl_kmem_cache task queue. | |
29 | This task queue is responsible for allocating new slabs | |
30 | for use by the kmem caches. | |
d297a5a3 BB |
31 | For the majority of systems and workloads only a small number of threads are |
32 | required. | |
2d815d95 | 33 | . |
2d815d95 AZ |
34 | .It Sy spl_kmem_cache_obj_per_slab Ns = Ns Sy 8 Pq uint |
35 | The preferred number of objects per slab in the cache. | |
36 | In general, a larger value will increase the caches memory footprint | |
37 | while decreasing the time required to perform an allocation. | |
38 | Conversely, a smaller value will minimize the footprint | |
39 | and improve cache reclaim time but individual allocations may take longer. | |
40 | . | |
41 | .It Sy spl_kmem_cache_max_size Ns = Ns Sy 32 Po 64-bit Pc or Sy 4 Po 32-bit Pc Pq uint | |
42 | The maximum size of a kmem cache slab in MiB. | |
43 | This effectively limits the maximum cache object size to | |
44 | .Sy spl_kmem_cache_max_size Ns / Ns Sy spl_kmem_cache_obj_per_slab . | |
45 | .Pp | |
46 | Caches may not be created with | |
b1c3ae48 | 47 | object sized larger than this limit. |
2d815d95 AZ |
48 | . |
49 | .It Sy spl_kmem_cache_slab_limit Ns = Ns Sy 16384 Pq uint | |
b1c3ae48 | 50 | For small objects the Linux slab allocator should be used to make the most |
2d815d95 AZ |
51 | efficient use of the memory. |
52 | However, large objects are not supported by | |
53 | the Linux slab and therefore the SPL implementation is preferred. | |
54 | This value is used to determine the cutoff between a small and large object. | |
55 | .Pp | |
56 | Objects of size | |
57 | .Sy spl_kmem_cache_slab_limit | |
58 | or smaller will be allocated using the Linux slab allocator, | |
59 | large objects use the SPL allocator. | |
60 | A cutoff of 16K was determined to be optimal for architectures using 4K pages. | |
61 | . | |
62 | .It Sy spl_kmem_alloc_warn Ns = Ns Sy 32768 Pq uint | |
63 | As a general rule | |
64 | .Fn kmem_alloc | |
65 | allocations should be small, | |
66 | preferably just a few pages, since they must by physically contiguous. | |
67 | Therefore, a rate limited warning will be printed to the console for any | |
68 | .Fn kmem_alloc | |
c3eabc75 | 69 | which exceeds a reasonable threshold. |
2d815d95 | 70 | .Pp |
c3eabc75 | 71 | The default warning threshold is set to eight pages but capped at 32K to |
2d815d95 AZ |
72 | accommodate systems using large pages. |
73 | This value was selected to be small enough to ensure | |
74 | the largest allocations are quickly noticed and fixed. | |
c3eabc75 | 75 | But large enough to avoid logging any warnings when a allocation size is |
2d815d95 AZ |
76 | larger than optimal but not a serious concern. |
77 | Since this value is tunable, developers are encouraged to set it lower | |
78 | when testing so any new largish allocations are quickly caught. | |
79 | These warnings may be disabled by setting the threshold to zero. | |
80 | . | |
81 | .It Sy spl_kmem_alloc_max Ns = Ns Sy KMALLOC_MAX_SIZE Ns / Ns Sy 4 Pq uint | |
82 | Large | |
83 | .Fn kmem_alloc | |
84 | allocations will fail if they exceed | |
85 | .Sy KMALLOC_MAX_SIZE . | |
c3eabc75 BB |
86 | Allocations which are marginally smaller than this limit may succeed but |
87 | should still be avoided due to the expense of locating a contiguous range | |
2d815d95 AZ |
88 | of free pages. |
89 | Therefore, a maximum kmem size with reasonable safely margin of 4x is set. | |
90 | .Fn kmem_alloc | |
91 | allocations larger than this maximum will quickly fail. | |
92 | .Fn vmem_alloc | |
93 | allocations less than or equal to this value will use | |
94 | .Fn kmalloc , | |
95 | but shift to | |
96 | .Fn vmalloc | |
97 | when exceeding this value. | |
98 | . | |
99 | .It Sy spl_kmem_cache_magazine_size Ns = Ns Sy 0 Pq uint | |
1a204968 | 100 | Cache magazines are an optimization designed to minimize the cost of |
2d815d95 AZ |
101 | allocating memory. |
102 | They do this by keeping a per-cpu cache of recently | |
103 | freed objects, which can then be reallocated without taking a lock. | |
104 | This can improve performance on highly contended caches. | |
105 | However, because objects in magazines will prevent otherwise empty slabs | |
106 | from being immediately released this may not be ideal for low memory machines. | |
107 | .Pp | |
108 | For this reason, | |
109 | .Sy spl_kmem_cache_magazine_size | |
110 | can be used to set a maximum magazine size. | |
111 | When this value is set to 0 the magazine size will | |
112 | be automatically determined based on the object size. | |
113 | Otherwise magazines will be limited to 2-256 objects per magazine (i.e per cpu). | |
114 | Magazines may never be entirely disabled in this implementation. | |
115 | . | |
116 | .It Sy spl_hostid Ns = Ns Sy 0 Pq ulong | |
b1c3ae48 BB |
117 | The system hostid, when set this can be used to uniquely identify a system. |
118 | By default this value is set to zero which indicates the hostid is disabled. | |
119 | It can be explicitly enabled by placing a unique non-zero value in | |
2d815d95 AZ |
120 | .Pa /etc/hostid . |
121 | . | |
122 | .It Sy spl_hostid_path Ns = Ns Pa /etc/hostid Pq charp | |
123 | The expected path to locate the system hostid when specified. | |
124 | This value may be overridden for non-standard configurations. | |
125 | . | |
126 | .It Sy spl_panic_halt Ns = Ns Sy 0 Pq uint | |
127 | Cause a kernel panic on assertion failures. | |
128 | When not enabled, the thread is halted to facilitate further debugging. | |
129 | .Pp | |
8fc53372 | 130 | Set to a non-zero value to enable. |
2d815d95 AZ |
131 | . |
132 | .It Sy spl_taskq_kick Ns = Ns Sy 0 Pq uint | |
133 | Kick stuck taskq to spawn threads. | |
134 | When writing a non-zero value to it, it will scan all the taskqs. | |
135 | If any of them have a pending task more than 5 seconds old, | |
136 | it will kick it to spawn more threads. | |
137 | This can be used if you find a rare | |
8f3b403a | 138 | deadlock occurs because one or more taskqs didn't spawn a thread when it should. |
2d815d95 AZ |
139 | . |
140 | .It Sy spl_taskq_thread_bind Ns = Ns Sy 0 Pq int | |
141 | Bind taskq threads to specific CPUs. | |
142 | When enabled all taskq threads will be distributed evenly | |
143 | across the available CPUs. | |
144 | By default, this behavior is disabled to allow the Linux scheduler | |
145 | the maximum flexibility to determine where a thread should run. | |
146 | . | |
147 | .It Sy spl_taskq_thread_dynamic Ns = Ns Sy 1 Pq int | |
148 | Allow dynamic taskqs. | |
149 | When enabled taskqs which set the | |
150 | .Sy TASKQ_DYNAMIC | |
151 | flag will by default create only a single thread. | |
152 | New threads will be created on demand up to a maximum allowed number | |
153 | to facilitate the completion of outstanding tasks. | |
154 | Threads which are no longer needed will be promptly destroyed. | |
155 | By default this behavior is enabled but it can be disabled to | |
f7a973d9 | 156 | aid performance analysis or troubleshooting. |
2d815d95 AZ |
157 | . |
158 | .It Sy spl_taskq_thread_priority Ns = Ns Sy 1 Pq int | |
62aa81a5 | 159 | Allow newly created taskq threads to set a non-default scheduler priority. |
2d815d95 AZ |
160 | When enabled, the priority specified when a taskq is created will be applied |
161 | to all threads created by that taskq. | |
162 | When disabled all threads will use the default Linux kernel thread priority. | |
163 | By default, this behavior is enabled. | |
164 | . | |
165 | .It Sy spl_taskq_thread_sequential Ns = Ns Sy 4 Pq int | |
f7a973d9 | 166 | The number of items a taskq worker thread must handle without interruption |
2d815d95 AZ |
167 | before requesting a new worker thread be spawned. |
168 | This is used to control | |
f7a973d9 BB |
169 | how quickly taskqs ramp up the number of threads processing the queue. |
170 | Because Linux thread creation and destruction are relatively inexpensive a | |
2d815d95 | 171 | small default value has been selected. |
b46be903 DS |
172 | This means that normally threads will be created aggressively which is |
173 | desirable. | |
2d815d95 | 174 | Increasing this value will |
f7a973d9 BB |
175 | result in a slower thread creation rate which may be preferable for some |
176 | configurations. | |
2d815d95 AZ |
177 | . |
178 | .It Sy spl_max_show_tasks Ns = Ns Sy 512 Pq uint | |
49349255 | 179 | The maximum number of tasks per pending list in each taskq shown in |
2d815d95 AZ |
180 | .Pa /proc/spl/taskq{,-all} . |
181 | Write | |
182 | .Sy 0 | |
183 | to turn off the limit. | |
184 | The proc file will walk the lists with lock held, | |
185 | reading it could cause a lock-up if the list grow too large | |
186 | without limiting the output. | |
187 | "(truncated)" will be shown if the list is larger than the limit. | |
35a6247c | 188 | . |
e0bd8118 AM |
189 | .It Sy spl_taskq_thread_timeout_ms Ns = Ns Sy 5000 Pq uint |
190 | Minimum idle threads exit interval for dynamic taskqs. | |
191 | Smaller values allow idle threads exit more often and potentially be | |
192 | respawned again on demand, causing more churn. | |
2d815d95 | 193 | .El |