kernel/linux/Documentation/sched-domains.txt

   1 Each CPU has a "base" scheduling domain (struct sched_domain). These are
   2 accessed via cpu_sched_domain(i) and this_sched_domain() macros. The domain
   3 hierarchy is built from these base domains via the ->parent pointer. ->parent
   4 MUST be NULL terminated, and domain structures should be per-CPU as they
   5 are locklessly updated.
   6
   7 Each scheduling domain spans a number of CPUs (stored in the ->span field).
   8 A domain's span MUST be a superset of it child's span, and a base domain
   9 for CPU i MUST span at least i. The top domain for each CPU will generally
  10 span all CPUs in the system although strictly it doesn't have to, but this
  11 could lead to a case where some CPUs will never be given tasks to run unless
  12 the CPUs allowed mask is explicitly set. A sched domain's span means "balance
  13 process load among these CPUs".
  14
  15 Each scheduling domain must have one or more CPU groups (struct sched_group)
  16 which are organised as a circular one way linked list from the ->groups
  17 pointer. The union of cpumasks of these groups MUST be the same as the
  18 domain's span. The intersection of cpumasks from any two of these groups
  19 MUST be the empty set. The group pointed to by the ->groups pointer MUST
  20 contain the CPU to which the domain belongs. Groups may be shared among
  21 CPUs as they contain read only data after they have been set up.
  22
  23 Balancing within a sched domain occurs between groups. That is, each group
  24 is treated as one entity. The load of a group is defined as the sum of the
  25 load of each of its member CPUs, and only when the load of a group becomes
  26 out of balance are tasks moved between groups.
  27
  28 In kernel/sched.c, rebalance_tick is run periodically on each CPU. This
  29 function takes its CPU's base sched domain and checks to see if has reached
  30 its rebalance interval. If so, then it will run load_balance on that domain.
  31 rebalance_tick then checks the parent sched_domain (if it exists), and the
  32 parent of the parent and so forth.
  33
  34 *** Implementing sched domains ***
  35 The "base" domain will "span" the first level of the hierarchy. In the case
  36 of SMT, you'll span all siblings of the physical CPU, with each group being
  37 a single virtual CPU.
  38
  39 In SMP, the parent of the base domain will span all physical CPUs in the
  40 node. Each group being a single physical CPU. Then with NUMA, the parent
  41 of the SMP domain will span the entire machine, with each group having the
  42 cpumask of a node. Or, you could do multi-level NUMA or Opteron, for example,
  43 might have just one domain covering its one NUMA level.
  44
  45 The implementor should read comments in include/linux/sched.h:
  46 struct sched_domain fields, SD_FLAG_*, SD_*_INIT to get an idea of
  47 the specifics and what to tune.
  48
  49 Implementors should change the line
  50 #undef SCHED_DOMAIN_DEBUG
  51 to
  52 #define SCHED_DOMAIN_DEBUG
  53 in kernel/sched.c as this enables an error checking parse of the sched domains
  54 which should catch most possible errors (described above). It also prints out
  55 the domain structure in a visual format.