The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/sys/pidctrl.h

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    1 /*-
    2  * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
    3  *
    4  * Copyright (c) 2017,  Jeffrey Roberson <jeff@freebsd.org>
    5  * All rights reserved.
    6  *
    7  * Redistribution and use in source and binary forms, with or without
    8  * modification, are permitted provided that the following conditions
    9  * are met:
   10  * 1. Redistributions of source code must retain the above copyright
   11  *    notice unmodified, this list of conditions, and the following
   12  *    disclaimer.
   13  * 2. Redistributions in binary form must reproduce the above copyright
   14  *    notice, this list of conditions and the following disclaimer in the
   15  *    documentation and/or other materials provided with the distribution.
   16  *
   17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
   18  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   19  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
   20  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
   21  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
   22  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
   23  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
   24  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
   26  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   27  *
   28  * $FreeBSD: releng/12.0/sys/sys/pidctrl.h 329882 2018-02-23 22:51:51Z jeff $
   29  */
   30 
   31 #ifndef _SYS_PIDCTRL_H_
   32 #define _SYS_PIDCTRL_H_
   33 
   34 /*
   35  * Proportional Integral Derivative controller.
   36  *
   37  * This controller is intended to replace a multitude of threshold based
   38  * daemon regulation systems.  These systems produce sharp sawtooths of
   39  * activity which can cause latency spikes and other undesireable bursty
   40  * behavior.  The PID controller adapts to changing load conditions and
   41  * adjusts the work done by the daemon to keep a smoother output.
   42  *
   43  * The setpoint can be thought of as a single watermark that the controller
   44  * is always trying to reach.  Compared to a high water/low water type
   45  * algorithm the pid controller is dynamically deciding the low water and
   46  * regulating to the high water.  The setpoint should be high enough that
   47  * the controller and daemon have time to observe the rise in value and
   48  * respond to it, else the resource may be exhausted.  More frequent wakeups
   49  * permit higher setpoints and less underutilized resources.
   50  *
   51  * The controller has been optimised for simplicity of math making it quite
   52  * inexpensive to execute.  There is no floating point and so the gains must
   53  * be the inverse of whole integers.
   54  *
   55  * Failing to measure and tune the gain parameters can result in wild
   56  * oscillations in output.  It is strongly encouraged that controllers are
   57  * tested and tuned under a wide variety of workloads before gain values are
   58  * picked.  Some reasonable defaults are provided below.
   59  */
   60 
   61 struct pidctrl {
   62         /* Saved control variables. */
   63         int     pc_error;               /* Current error. */
   64         int     pc_olderror;            /* Saved error for derivative. */
   65         int     pc_integral;            /* Integral accumulator. */
   66         int     pc_derivative;          /* Change from last error. */
   67         int     pc_input;               /* Last input. */
   68         int     pc_output;              /* Last output. */
   69         int     pc_ticks;               /* Last sampling time. */
   70         /* configuration options, runtime tunable via sysctl */
   71         int     pc_setpoint;            /* Desired level */
   72         int     pc_interval;            /* Update interval in ticks. */
   73         int     pc_bound;               /* Integral wind-up limit. */
   74         int     pc_Kpd;                 /* Proportional gain divisor. */
   75         int     pc_Kid;                 /* Integral gain divisor. */
   76         int     pc_Kdd;                 /* Derivative gain divisor. */
   77 };
   78 
   79 /*
   80  * Reasonable default divisors.
   81  *
   82  * Actual gains are 1/divisor.  Gains interact in complex ways with the
   83  * setpoint and interval.  Measurement under multiple loads should be
   84  * taken to ensure adequate stability and rise time.
   85  */
   86 #define PIDCTRL_KPD     3               /* Default proportional divisor. */
   87 #define PIDCTRL_KID     4               /* Default integral divisor. */
   88 #define PIDCTRL_KDD     8               /* Default derivative divisor. */
   89 #define PIDCTRL_BOUND   4               /* Bound factor, setpoint multiple. */
   90 
   91 struct sysctl_oid_list;
   92 
   93 void    pidctrl_init(struct pidctrl *pc, int interval, int setpoint,
   94             int bound, int Kpd, int Kid, int Kdd);
   95 void    pidctrl_init_sysctl(struct pidctrl *pc, struct sysctl_oid_list *parent);
   96 
   97 /*
   98  * This is the classic PID controller where the interval is clamped to
   99  * [-bound, bound] and the output may be negative.  This should be used
  100  * in continuous control loops that can adjust a process variable in
  101  * either direction.  This is a descrete time controller and should
  102  * only be called once per-interval or the derivative term will be
  103  * inaccurate.
  104  */
  105 int     pidctrl_classic(struct pidctrl *pc, int input);
  106 
  107 /*
  108  * This controler is intended for consumer type daemons that can only
  109  * regulate in a positive direction, that is to say, they can not exert
  110  * positive pressure on the process variable or input.  They can only
  111  * reduce it by doing work.  As such the integral is bound between [0, bound]
  112  * and the output is similarly a positive value reflecting the units of
  113  * work necessary to be completed in the current interval to eliminate error.
  114  *
  115  * It is a descrete time controller but can be invoked more than once in a
  116  * given time interval for ease of client implementation.  This should only
  117  * be done in overload situations or the controller may not produce a stable
  118  * output.  Calling it less frequently when there is no work to be done will
  119  * increase the rise time but should otherwise be harmless.
  120  */
  121 int     pidctrl_daemon(struct pidctrl *pc, int input);
  122 
  123 #endif  /* !_SYS_PIDCTRL_H_ */

Cache object: 07da3bbe7a4b2cc350c48c33196c7060


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.