1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3  * padata.h - header for the padata parallelization interface
4  *
5  * Copyright (C) 2008, 2009 secunet Security Networks AG
6  * Copyright (C) 2008, 2009 Steffen Klassert <steffen.klassert@secunet.com>
7  *
8  * Copyright (c) 2020 Oracle and/or its affiliates.
9  * Author: Daniel Jordan <daniel.m.jordan@oracle.com>
10  */
11 
12 #ifndef PADATA_H
13 #define PADATA_H
14 
15 #include <linux/refcount.h>
16 #include <linux/compiler_types.h>
17 #include <linux/workqueue.h>
18 #include <linux/spinlock.h>
19 #include <linux/list.h>
20 #include <linux/kobject.h>
21 
22 #define PADATA_CPU_SERIAL   0x01
23 #define PADATA_CPU_PARALLEL 0x02
24 
25 /**
26  * struct padata_priv - Represents one job
27  *
28  * @list: List entry, to attach to the padata lists.
29  * @pd: Pointer to the internal control structure.
30  * @cb_cpu: Callback cpu for serializatioon.
31  * @seq_nr: Sequence number of the parallelized data object.
32  * @info: Used to pass information from the parallel to the serial function.
33  * @parallel: Parallel execution function.
34  * @serial: Serial complete function.
35  */
36 struct padata_priv {
37 	struct list_head	list;
38 	struct parallel_data	*pd;
39 	int			cb_cpu;
40 	unsigned int		seq_nr;
41 	int			info;
42 	void                    (*parallel)(struct padata_priv *padata);
43 	void                    (*serial)(struct padata_priv *padata);
44 };
45 
46 /**
47  * struct padata_list - one per work type per CPU
48  *
49  * @list: List head.
50  * @lock: List lock.
51  */
52 struct padata_list {
53 	struct list_head        list;
54 	spinlock_t              lock;
55 };
56 
57 /**
58 * struct padata_serial_queue - The percpu padata serial queue
59 *
60 * @serial: List to wait for serialization after reordering.
61 * @work: work struct for serialization.
62 * @pd: Backpointer to the internal control structure.
63 */
64 struct padata_serial_queue {
65        struct padata_list    serial;
66        struct work_struct    work;
67        struct parallel_data *pd;
68 };
69 
70 /**
71  * struct padata_cpumask - The cpumasks for the parallel/serial workers
72  *
73  * @pcpu: cpumask for the parallel workers.
74  * @cbcpu: cpumask for the serial (callback) workers.
75  */
76 struct padata_cpumask {
77 	cpumask_var_t	pcpu;
78 	cpumask_var_t	cbcpu;
79 };
80 
81 /**
82  * struct parallel_data - Internal control structure, covers everything
83  * that depends on the cpumask in use.
84  *
85  * @ps: padata_shell object.
86  * @reorder_list: percpu reorder lists
87  * @squeue: percpu padata queues used for serialuzation.
88  * @refcnt: Number of objects holding a reference on this parallel_data.
89  * @seq_nr: Sequence number of the parallelized data object.
90  * @processed: Number of already processed objects.
91  * @cpu: Next CPU to be processed.
92  * @cpumask: The cpumasks in use for parallel and serial workers.
93  * @reorder_work: work struct for reordering.
94  * @lock: Reorder lock.
95  */
96 struct parallel_data {
97 	struct padata_shell		*ps;
98 	struct padata_list		__percpu *reorder_list;
99 	struct padata_serial_queue	__percpu *squeue;
100 	refcount_t			refcnt;
101 	unsigned int			seq_nr;
102 	unsigned int			processed;
103 	int				cpu;
104 	struct padata_cpumask		cpumask;
105 	struct work_struct		reorder_work;
106 	spinlock_t                      ____cacheline_aligned lock;
107 };
108 
109 /**
110  * struct padata_shell - Wrapper around struct parallel_data, its
111  * purpose is to allow the underlying control structure to be replaced
112  * on the fly using RCU.
113  *
114  * @pinst: padat instance.
115  * @pd: Actual parallel_data structure which may be substituted on the fly.
116  * @opd: Pointer to old pd to be freed by padata_replace.
117  * @list: List entry in padata_instance list.
118  */
119 struct padata_shell {
120 	struct padata_instance		*pinst;
121 	struct parallel_data __rcu	*pd;
122 	struct parallel_data		*opd;
123 	struct list_head		list;
124 };
125 
126 /**
127  * struct padata_mt_job - represents one multithreaded job
128  *
129  * @thread_fn: Called for each chunk of work that a padata thread does.
130  * @fn_arg: The thread function argument.
131  * @start: The start of the job (units are job-specific).
132  * @size: size of this node's work (units are job-specific).
133  * @align: Ranges passed to the thread function fall on this boundary, with the
134  *         possible exceptions of the beginning and end of the job.
135  * @min_chunk: The minimum chunk size in job-specific units.  This allows
136  *             the client to communicate the minimum amount of work that's
137  *             appropriate for one worker thread to do at once.
138  * @max_threads: Max threads to use for the job, actual number may be less
139  *               depending on task size and minimum chunk size.
140  */
141 struct padata_mt_job {
142 	void (*thread_fn)(unsigned long start, unsigned long end, void *arg);
143 	void			*fn_arg;
144 	unsigned long		start;
145 	unsigned long		size;
146 	unsigned long		align;
147 	unsigned long		min_chunk;
148 	int			max_threads;
149 };
150 
151 /**
152  * struct padata_instance - The overall control structure.
153  *
154  * @cpu_online_node: Linkage for CPU online callback.
155  * @cpu_dead_node: Linkage for CPU offline callback.
156  * @parallel_wq: The workqueue used for parallel work.
157  * @serial_wq: The workqueue used for serial work.
158  * @pslist: List of padata_shell objects attached to this instance.
159  * @cpumask: User supplied cpumasks for parallel and serial works.
160  * @kobj: padata instance kernel object.
161  * @lock: padata instance lock.
162  * @flags: padata flags.
163  */
164 struct padata_instance {
165 	struct hlist_node		cpu_online_node;
166 	struct hlist_node		cpu_dead_node;
167 	struct workqueue_struct		*parallel_wq;
168 	struct workqueue_struct		*serial_wq;
169 	struct list_head		pslist;
170 	struct padata_cpumask		cpumask;
171 	struct kobject                   kobj;
172 	struct mutex			 lock;
173 	u8				 flags;
174 #define	PADATA_INIT	1
175 #define	PADATA_RESET	2
176 #define	PADATA_INVALID	4
177 };
178 
179 #ifdef CONFIG_PADATA
180 extern void __init padata_init(void);
181 #else
padata_init(void)182 static inline void __init padata_init(void) {}
183 #endif
184 
185 extern struct padata_instance *padata_alloc(const char *name);
186 extern void padata_free(struct padata_instance *pinst);
187 extern struct padata_shell *padata_alloc_shell(struct padata_instance *pinst);
188 extern void padata_free_shell(struct padata_shell *ps);
189 extern int padata_do_parallel(struct padata_shell *ps,
190 			      struct padata_priv *padata, int *cb_cpu);
191 extern void padata_do_serial(struct padata_priv *padata);
192 extern void __init padata_do_multithreaded(struct padata_mt_job *job);
193 extern int padata_set_cpumask(struct padata_instance *pinst, int cpumask_type,
194 			      cpumask_var_t cpumask);
195 #endif
196