1 /*- 2 * SPDX-License-Identifier: BSD-2-Clause 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$ 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_ */ 124