Signed-of-by: Mike Travis <travis@sgi.com>
---
cpumask.txt | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 73 insertions(+)
--- /dev/null
+++ struct-cpumasks/cpumask.txt
@@ -0,0 +1,73 @@
+
+ CPUMASKS
+ --------
+
+ [PRELIMINARY]
+
+Introduction
+
+Cpumask variables are used to represent (with a single bit) all the
+CPU's in a system. With the prolific increase in the number of CPU's
+in a single system image (SSI), managing this large number of cpus has
+become an ordeal. When the limit of CPU's in a system was small, the
+cpumask could fit within an integer. Even with the increase to 128, a
+bit pattern was well within a managable size. Now with systems available
+with 2048 cores, with hyperthreading, there are 4096 cpu threads. And the
+number of cpus in an SSI is growing, 16,384 is right around the corner.
+Even desktop systems with only 2 or 4 sockets, a new generation of Intel
+processors that have 128 cores per socket will increase the count of CPU
+threads tremendously.
+
+Thus the handling of the cpumask that represents this 4096 limit needs
+512 bytes, putting pressure on the amount of stack space needed to
+accomodate temporary cpumask variables.
+
+The primary goal of the cpumasks API is to accomodate these large number
+of cpus without effecting the compactness of Linux for small, compact
+systems.
+
+
+The Changes
+
+Provide new cpumask interface API. The relevant change is basically
+cpumask_t becomes an opaque object. This should result in the minimum
+amount of modifications while still allowing the inline cpumask functions,
+and the ability to declare static cpumask objects.
+
+
+ /* raw declaration */
+ struct __cpumask_data_s { DECLARE_BITMAP(bits, NR_CPUS); };
+
+ /* cpumask_map_t used for declaring static cpumask maps */
+ typedef struct __cpumask_data_s cpumask_map_t[1];
+
+ /* cpumask_t used for function args and return pointers */
+ typedef struct __cpumask_data_s *cpumask_t;
+ typedef const struct __cpumask_data_s *const_cpumask_t;
+
+ /* cpumask_var_t used for local variable, definition follows */
+ typedef struct __cpumask_data_s cpumask_var_t[1]; /* SMALL NR_CPUS */
+ typedef struct __cpumask_data_s *cpumask_var_t; /* LARGE NR_CPUS */
+
+ /* replaces cpumask_t dst = (cpumask_t)src */
+ void cpus_copy(cpumask_t dst, const cpumask_t src);
+
+This removes the '*' indirection in all references to cpumask_t objects.
+You can change the reference to the cpumask object but to change the
+cpumask object itself you must use the functions that operate on cpumask
+objects (f.e. the cpu_* operators). Functions can return a cpumask_t
+(which is a pointer to the cpumask object) and can only be passed a
+cpumask_t.
+
+All uses of a cpumask_t variable on the stack are changed to be cpumask_var_t
+except for pointers to static (read only) cpumask objects. Allocation of
+local (temp) cpumask objects use the functions available in cpumask_alloc.h.
+(descriptions to be supplied.)
+
+All cpumask operators now operate using nr_cpu_ids instead of NR_CPUS. All
+variants of the cpumask operators which used nr_cpu_ids instead of NR_CPUS
+have been deleted.
+
+All variants of functions which use the (old cpumask_t *) pointer have been
+deleted (f.e. set_cpus_allowed_ptr()).
+
--
--
