<p>pespin has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/19443">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">chapters: Introduce vty_sched.adoc chapter<br><br>Documents new features added in libosmocore.git Change-Id<br>If76a4bd2cc7b3c7adf5d84790a944d78be70e10a.<br><br>This file will be imported in user manuals of programs using the<br>mentioned libosmovty features.<br><br>Related: SYS#4986<br>Change-Id: Icd75769ef630c3fa985fc5e2154d5521689cdd3c<br>---<br>A common/chapters/vty_sched.adoc<br>1 file changed, 117 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/43/19443/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/common/chapters/vty_sched.adoc b/common/chapters/vty_sched.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..3824950</span><br><span>--- /dev/null</span><br><span>+++ b/common/chapters/vty_sched.adoc</span><br><span>@@ -0,0 +1,117 @@</span><br><span style="color: hsl(120, 100%, 40%);">+[[vty_sched]]</span><br><span style="color: hsl(120, 100%, 40%);">+== VTY Process and Thread management</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Most Osmocom programs provide, some support to tune some system</span><br><span style="color: hsl(120, 100%, 40%);">+settings related to the running process, its threads, its scheduling policies,</span><br><span style="color: hsl(120, 100%, 40%);">+etc.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+All of these settings can be configured through the VTY, either during startup</span><br><span style="color: hsl(120, 100%, 40%);">+by means of usual config files or through direct human interaction at the telnet</span><br><span style="color: hsl(120, 100%, 40%);">+VTY interface while the process is running.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[vty_sched_policy]]</span><br><span style="color: hsl(120, 100%, 40%);">+=== Scheduling Policy</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The scheduler to use as well as some of its properties (such as realtime</span><br><span style="color: hsl(120, 100%, 40%);">+priority) can be configured at any time for the entire process. This sort of</span><br><span style="color: hsl(120, 100%, 40%);">+functionality is useful in order to increase priority for processes running</span><br><span style="color: hsl(120, 100%, 40%);">+time-constrained procedures, such as those acting on the Um interface, like</span><br><span style="color: hsl(120, 100%, 40%);">+_osmo-trx_ or _osmo-bts_, where use of this feature is highly recommended.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Example: Set process to use RR scheduler</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+sched</span><br><span style="color: hsl(120, 100%, 40%);">+ policy rr 1 <1></span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> Configure process to use _SCHED_RR_ policy with real time priority 1</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[vty_sched_cpu_affinity_mask]]</span><br><span style="color: hsl(120, 100%, 40%);">+=== CPU-Affinity Mask</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Most operating systems allow for some sort of configuration on restricting the</span><br><span style="color: hsl(120, 100%, 40%);">+amount of CPUs a given process or thread can run on. The procedure is sometimes</span><br><span style="color: hsl(120, 100%, 40%);">+called as _cpu-pinning_ since it allows to keep different processes pinned on a</span><br><span style="color: hsl(120, 100%, 40%);">+subset of CPUs to make sure the scheduler won't run two CPU-hungry processes on</span><br><span style="color: hsl(120, 100%, 40%);">+the same CPU.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The set of CPUs where each thread is allowed to run on is expressed by means of</span><br><span style="color: hsl(120, 100%, 40%);">+a bitmask in hexadecimal representation, where the right most bit relates to</span><br><span style="color: hsl(120, 100%, 40%);">+CPU 0, and the Nth most significant bit relates to CPU _N-1_. Setting the bit</span><br><span style="color: hsl(120, 100%, 40%);">+means the process is allowed to run on that CPU, while clearing it means the</span><br><span style="color: hsl(120, 100%, 40%);">+process is forbidden to run on that CPU.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Hence, for instance a cpu-affinity mask of _0x00_ means the thread is not</span><br><span style="color: hsl(120, 100%, 40%);">+allowed on any CPU, which will cause the thread to stall until a new value is</span><br><span style="color: hsl(120, 100%, 40%);">+applied. A mask of _0x01_ means the thread is only allowed to run on the 1st CPU</span><br><span style="color: hsl(120, 100%, 40%);">+(CPU 0). A mask of _0xff00_ means CPUs 8-15 are allowed, while 0-7 are not.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+For single-threaded processes (mot of Osmocom are), it is usually enough to set</span><br><span style="color: hsl(120, 100%, 40%);">+this line in VTY config file as follows:</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+sched</span><br><span style="color: hsl(120, 100%, 40%);">+ cpu-affinity self 0x01 <1></span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> Allow main thread (the one managing the VTY) only on CPU 0</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Or otherwise:</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+sched</span><br><span style="color: hsl(120, 100%, 40%);">+ cpu-affinity all 0x01 <1></span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> Allow all threads only on CPU 0</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+For multi-threaded processes, it may be desired to run some threads on a subset</span><br><span style="color: hsl(120, 100%, 40%);">+of CPUs while another subset may run on another one. In order to identify</span><br><span style="color: hsl(120, 100%, 40%);">+threads, one can either use the TID of the thread (each thread has its own PID</span><br><span style="color: hsl(120, 100%, 40%);">+in Linux), or its specific Thread Name in case it has been set by the</span><br><span style="color: hsl(120, 100%, 40%);">+application.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The related information on all threads available in the process can be listed</span><br><span style="color: hsl(120, 100%, 40%);">+through VTY. This allows identifying quickly the different threads, its current</span><br><span style="color: hsl(120, 100%, 40%);">+cpu-affinity mask, etc.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Example: Get osmo-trx Thread list information from VTY</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+OsmoTRX> show sched threads</span><br><span style="color: hsl(120, 100%, 40%);">+Thread list for PID 338609:</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338609, NAME: 'osmo-trx-uhd', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338610, NAME: 'osmo-trx-uhd', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338611, NAME: 'osmo-trx-uhd', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338629, NAME: 'osmo-trx-uhd', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338630, NAME: 'osmo-trx-uhd', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338631, NAME: 'osmo-trx-uhd', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338634, NAME: 'UHDAsyncEvent', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338635, NAME: 'TxLower', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338636, NAME: 'RxLower', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338637, NAME: 'RxUpper0', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338638, NAME: 'TxUpper0', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338639, NAME: 'RxUpper1', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+ TID: 338640, NAME: 'TxUpper1', cpu-affinity: 0x3</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+At runtime, one can change the cpu-affinity mask for a given thread identifying</span><br><span style="color: hsl(120, 100%, 40%);">+it by either TID or name:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Example: Set CPU-affinity from VTY telnet interface</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+OsmoTRX> cpu-affinity TxLower 0x02 <1></span><br><span style="color: hsl(120, 100%, 40%);">+OsmoTRX> cpu-affinity TxLower 0x03 <2></span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> Allow thread named _TxLower_ (_338635_) only on CPU 1</span><br><span style="color: hsl(120, 100%, 40%);">+<2> Allow with TID _338636_ (_RxLower_) only on CPU 0 and 1</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Since thread names are set dynamically by the process during startup or at a</span><br><span style="color: hsl(120, 100%, 40%);">+later point after creating the thread itself, One may need to specify in the</span><br><span style="color: hsl(120, 100%, 40%);">+config file that the mask must be applied by the thread itself once being</span><br><span style="color: hsl(120, 100%, 40%);">+configured rather than trying to apply it immediately. To specify so, the</span><br><span style="color: hsl(120, 100%, 40%);">+_delay_ keyword is using when configuring in the VTY. If the _delay_ keyword is</span><br><span style="color: hsl(120, 100%, 40%);">+not used, the VTY will reprot and error and fail at startup when trying to apply</span><br><span style="color: hsl(120, 100%, 40%);">+a cpu-affinity mask for a yet-to-be-created thread.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Example: Set CPU-affinity from VTY config file</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+sched</span><br><span style="color: hsl(120, 100%, 40%);">+ cpu-affinity TxLower 0x01 delay <1></span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> Allow thread named _TxLower_ (_338635_) only on CPU 1. It will be applied by the thread itself when created.</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/19443">change 19443</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/19443"/><meta itemprop="name" content="View Change"/></div></div>

<div style="display:none"> Gerrit-Project: osmo-gsm-manuals </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: Icd75769ef630c3fa985fc5e2154d5521689cdd3c </div>
<div style="display:none"> Gerrit-Change-Number: 19443 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: pespin <pespin@sysmocom.de> </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>