# Customize
Source: [https://docs.qualcomm.com/doc/80-70015-10/topic/18-customize.html](https://docs.qualcomm.com/doc/80-70015-10/topic/18-customize.html)
Customization is a process that includes fine-tuning various aspects of the system,
which can significantly affect the overall performance and power of the system.
The CPU scheduler, CPU frequency governor, DVFS governor, perflock, and memory can be
fine-tuned. It is recommended to undertake any tuning only after gaining a thorough
understanding through extensive performance and power analysis.
Caution:
Any customization
can impact the power and performance of the device. Therefore, it is crucial to verify
the impact across all the relevant use cases before performing any customization.
## Customize CPU scheduler
Source: [https://docs.qualcomm.com/doc/80-70015-10/topic/18-customize.html](https://docs.qualcomm.com/doc/80-70015-10/topic/18-customize.html)
You can customize features of the CPU scheduler, such as PELT and UCLAMP schedulers.
For more information, see [CPU scheduler](https://docs.qualcomm.com/doc/80-70015-10/topic/2-performance-features.html#cpu-scheduler).
### PELT half-life at runtime
The PELT half-life is the time that it takes for the PELT signal to reach a 50% load,
starting from zero. By default, the kernel value is set to 32 milliseconds,
indicating that it takes 32 milliseconds for the scheduler to recognize the task
load as 50%.
Choosing a lower value results in a faster PELT ramp-up time, which can speed up the
time needed for the signal to stabilize and accurately represent the task demands.
However, this choice also correspondingly reduces the decay time.
The PELT multiplier is configured through the following kernel command-line argument
in the source code at:
layers/meta-qcom-hwe/conf/machine/include/qcom-<target>.inc
kernel.sched_pelt_multiplier=[1, 2, 4] Default value: 1 (half life 32msec), 2 (half life 16msec), 4 (half life 8msec)]Copy to clipboard
For more information, see [sched/pelt: Change PELT halflife at runtime](https://lwn.net/Articles/906375/).
### UCLAMP
UCLAMP is a scheduler feature that allows user space to manage the task performance
requirements.
It is a hinting mechanism that helps the scheduler understand the performance demands
and limitations of tasks, as a result, it assists the scheduler in making informed
decisions.
When the `schedutil` CPU frequency governor is used, UCLAMP determines
the CPU frequency selection. The UCLAMP value ranges from 0 to 1024.
The following parameters can be customized for UCLAMP:
- `sched_util_clamp_min`: This parameter sets the minimum
acceptable performance level for individual tasks and task groups, ensuring that
tasks receive sufficient resources to operate effectively, even during periods
of low demand.
Any requested `uclamp.min` value for a task
cannot exceed `sched_util_clamp_min`.
- For the scheduler, it acts as a lower bound on the PELT signal, which
tracks task usage.
- For the CPU frequency, it instructs the governor to select a frequency
that can meet the performance requirements of the task, thus ensuring
responsiveness and efficiency.
The Qualcomm-tuned value is 1024. To set this parameter, run the
following command on the device:
echo 1024 > /proc/sys/kernel/sched_util_clamp_minCopy to clipboard
- `sched_util_clamp_max`: This parameter sets the maximum
acceptable performance level for individual tasks and task groups. It ensures
that tasks do not consume excessive resources, preventing resource contention
and system instability.
Any requested `uclamp.max` value for a
task cannot exceed `sched_util_clamp_max`.
- For the scheduler, it acts as a ceiling on the PELT signal, which tracks
the task usage.
- For the CPU frequency, if the task demands exceed the available
frequency, the governor may adjust the frequency to prevent excessive
power consumption.
The Qualcomm-tuned value is 1024. To set this parameter, run the
following command on the device:
echo 1024 > /proc/sys/kernel/sched_util_clamp_maxCopy to clipboard
- `sched_util_clamp_min_rt_default`: By default, the RT tasks
always run at the highest frequency and highest CPU capacity. This parameter
allows you to change the default behavior of an RT task when UCLAMP is being
used.
It enables tuning the best value for an RT task, offering good
performance without pushing it to the maximum performance point. This
behavior addresses the system requirement without burning power and running
at the maximum performance point all the time. The Qualcomm-tuned value is
128.
To set this parameter, run the following command on the
device:
echo 128 > /proc/sys/kernel/sched_util_clamp_min_rt_defaultCopy to clipboard
For more information, see [https://docs.kernel.org/scheduler/sched-util-clamp.html](https://docs.kernel.org/scheduler/sched-util-clamp.html).
## Customize CPU frequency governor
Source: [https://docs.qualcomm.com/doc/80-70015-10/topic/18-customize.html](https://docs.qualcomm.com/doc/80-70015-10/topic/18-customize.html)
You can configure a CPU frequency governor using the
`scaling_governor` node to enhance CPU performance.
Note: The commands specified in the following table should be run
on the device.
Note: The commands containing `policy7` are not
supported on QCS9075.
Table : Commands to customize the CPU frequency governor
| Command | Purpose |
| --- | --- |
| echo performance > /sys/devices/system/cpu/cpufreq/policy0/scaling_governorCopy to clipboard
echo performance > /sys/devices/system/cpu/cpufreq/policy4/scaling_governorCopy to clipboard
echo performance > /sys/devices/system/cpu/cpufreq/policy7/scaling_governorCopy to clipboard | Sets the CPU governor to enhance the system performance. |
| cat /sys/devices/system/cpu/cpufreq/policy0/scaling_governorCopy to clipboard
cat /sys/devices/system/cpu/cpufreq/policy4/scaling_governorCopy to clipboard
cat /sys/devices/system/cpu/cpufreq/policy7/scaling_governorCopy to clipboard | Verifies the CPU frequency governor. |
| echo schedutil > /sys/devices/system/cpu/cpufreq/policy0/scaling_governorCopy to clipboard
echo schedutil > /sys/devices/system/cpu/cpufreq/policy4/scaling_governorCopy to clipboard
echo schedutil > /sys/devices/system/cpu/cpufreq/policy7/scaling_governorCopy to clipboard | Sets the CPU frequency governor to
`schedutil`. |
| echo 1000 > /sys/devices/system/cpu/cpufreq/policyX/schedutil/rate_limit_usCopy to clipboard | Customizes `rate_limit_us`.
The value of `X` in `policyX`
corresponds to clusters 0, 4, and 7.
This is a `schedutil` governor parameter. It contains
the value in microseconds. The governor waits for
`rate_limit_us` time to re-evaluate the load
again after it has evaluated the load previously. The Qualcomm-tuned
value is 1000. |
## Customize DVFS governor
Source: [https://docs.qualcomm.com/doc/80-70015-10/topic/18-customize.html](https://docs.qualcomm.com/doc/80-70015-10/topic/18-customize.html)
You can customize the static map DVFS governor and BWMON governor using DTSI files
according to your power and performance requirements.
### Customize static map DVFS governor
You can customize the mapping between the CPU frequency and the L3/DDR frequency
according to the power and performance requirements from the
arch/arm64/boot/dts/qcom/<target>.dtsi file in the
source code.
In the DTSI file, for each CPU node, there is an entry with
`operating-points-v2 = <&cpux_opp_table>`, where
`cpux_opp_table` holds the static mapping between the CPU
frequency, and the L3 and the DDR frequencies.
For example, the following entry indicates that the CPU 0 frequency operates at
300 MHz:
cpu0_opp_300mhz: opp-300000000 {
opp-hz = /bits/ 64 <300000000>;
pp-peak-kBps = <800000 9600000>;
};
Copy to clipboard
When CPU 0 operates at 300 MHz, it performs the following actions:
- Votes L3 to 9600000, which is 9600000/w (where w = 32) = 300,000, which
corresponds to 300 MHz
- Votes DDR to 800000, which is 800000/w (where w = 4) = 200,00, which
corresponds to 200 MHz
In this example, `w` represents the number of bytes you can write in a
single cycle.
- For L3, this value is 32, which means one transaction per cycle at 32 bytes per
transaction.
- For dual-channel DDR, this value is 4. Each channel can perform two transactions
per cycle (because it is the DDR memory), and each transaction is of 2 bytes.
For more information, see [Generic OPP (Operating Performance Points)
Bindings](https://www.kernel.org/doc/Documentation/devicetree/bindings/opp/opp.txt).
The values in these tables for DDR are specified per channel. This implies that the
mapping is between the CPU frequency and the bandwidth of each memory controller
channel.
Caution:
If you change the DTSI files, the power
and performance of the device are impacted. Ensure that you verify the impact
across all the relevant use cases before changing any nodes.
### Customize BWMON governor
You can customize `bwmon_opp_table` for LLCC and DDR voting according
to the power and performance requirements from the
arch/arm64/boot/dts/qcom/<target>.dtsi file in the
source code.
The following code samples contain the DDR and LLCC frequency levels, and each level
translates to LLCC and DDR voting based on the traffic.
The following DTSI entry votes to DDR based on the CPU traffic between LLCC to DDR,
which corresponds to 200 MHz. In this example, 800000/w (where w = 4) equals 200000:
llcc_bwmon_opp_table: opp-table {
compatible = "operating-points-v2";
opp-0 { opp-peak-kBps = <800000>; };
Copy to clipboard
The following DTSI entry votes to LLCC based on the CPU traffic between CPU and LLCC,
which corresponds to 150 MHz. In this example, 2400000/w (where w = 16) equals
150000:
cpu_bwmon_opp_table: opp-table {
compatible = "operating-points-v2";
opp-0 {
opp-peak-kBps = <2400000>;
};
Copy to clipboard
In these examples, 'w' represents the number of bytes that you can write in a single
cycle.
- For DDR, this value is 4. Each channel can perform two transactions per cycle
(DDR memory), and each transaction is of 2 bytes.
- For LLCC, this value is 16.
## Customize perflock
Source: [https://docs.qualcomm.com/doc/80-70015-10/topic/18-customize.html](https://docs.qualcomm.com/doc/80-70015-10/topic/18-customize.html)
You can use perflock APIs, run a use case using different tuning parameters, and
debug the perflock issues.
### Perflock APIs
To use the perflock APIs from the user space source code, do the following:
1. Include a dynamic linking header in the source file: `#include
`.
2. Load `library(libqti-perfd-client.so)` using
`dlopen`.
3. Load the perf\_lock\_acq() and
perf\_lock\_rel() symbols using
`dlsym`.
4. Declare an integer variable to store the returns of
perf\_lock\_acq().
5. Define `perf_lock_opts` with the required resource opcode and
value pairs.
6. Acquire a lock with the specified optimizations using
perf\_lock\_acq().
7. Release the lock using perf\_lock\_rel().
8. Unload the library using `dlclose` on cleanup.
The following sample code shows the usage of perflock APIs and illustrates how to set
the minimum frequency of the Silver core to 1.9 GHz:
#include
#include
#include
#include
#include
#define PATH_MAX 92
static void *qcopt_handle;
static int (*perf_lock_acq)(int handle, int duration, int list[], int numArgs);
static int (*perf_lock_rel)(int handle);
static int perf_lock_handle;
char opt_lib_path[PATH_MAX] = "/usr/lib/libqti-perfd-client.so";
int main()
{
if ((qcopt_handle = dlopen(opt_lib_path, RTLD_NOW)) == NULL)
{
printf("dlopen failed with error: NULL\n");
} else {
printf("call perflock \n");
perf_lock_acq = (int (*)(int, int, int *, int))dlsym(qcopt_handle, "perf_lock_acq");
if(!perf_lock_acq)
printf("Unable to get perf_lock_rel function handle.\n");
perf_lock_rel = (int (*)(int))dlsym(qcopt_handle, "perf_lock_rel");
}
int perf_lock_opts[2] = {0x44008100,1958400};
perf_lock_handle = perf_lock_acq(perf_lock_handle, 0, perf_lock_opts, 2);
printf("perflock acquired %d\n", perf_lock_handle);
//Code section requiring perflock
perf_lock_rel(perf_lock_handle);
printf("releasing perflock\n");
dlclose(qcopt_handle);
return 0;
}Copy to clipboard
### Perflock native test
The perflock native test is a tool designed to evaluate the effectiveness of specific
combinations of perflock opcodes.
This tool is available at /usr/bin/ on the device.
You can run this utility as a use case to experiment with different tuning parameters
for ``. When the required performance
improvements are confirmed, the perflock code can be integrated into your Qualcomm
Linux software.
The following code shows the syntax:
perflock_native_test --acq Copy to clipboard
The following are some examples of how to use the tool:
Note: The following example commands should be run on the device.
- To acquire a perflock for the Silver cluster with minimum frequency set
to 1958400 KHz for 30 seconds, run the following command:
perflock_native_test --acq 0 30000 0x44008100,1958400Copy to clipboard
- To verify the minimum frequency of the Silver cluster, run the following
command:
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_min_freqCopy to clipboard
- To verify the perflock logging from `syslog`, run the
following
command:
cat /var/log/syslogCopy to clipboard
The following are the
logs:
perflock_native_test: ANDR-PERFLOCK-TESTERANDR-PERFLOCK-TESTER: initialize() 60: NRP: lib name libqti-perfd-client.so
perflock_native_test: ANDR-PERFLOCK-TESTERANDR-PERFLOCK-TESTER: main() 502: NRP: resource_list[0] = 44008100 //silver core min frequency opcode
perflock_native_test: ANDR-PERFLOCK-TESTERANDR-PERFLOCK-TESTER: main() 502: NRP: resource_list[1] = 7a6 // silver core min freq in hexCopy to clipboard
### Debug perflock
The following are some examples of logging mechanisms to debug the perflock
issues:
Note: The following example commands should be run on the
device.
- To verify if the PerfHAL service is available, run the following
command:
ls /usr/bin | grep perf Copy to clipboard
- To verify the running status of the PerfHAL service, run the following
command:
systemctl status perf-halCopy to clipboard
- To enable perflock logs and traces in /var/log/syslog, run
the following commands:
echo debug.trace.perf=1 >> /etc/build.propCopy to clipboard
echo vendor.debug.trace.perf=1 >> /etc/build.propCopy to clipboard
rebootCopy to clipboard
## Customize memory
Source: [https://docs.qualcomm.com/doc/80-70015-10/topic/18-customize.html](https://docs.qualcomm.com/doc/80-70015-10/topic/18-customize.html)
You can manage virtual memory using Kswapd, regulate system memory using watermark,
and define memory regions for specific subsystems through memory carveouts.
### Kswapd
Kswapd is a kernel thread that manages the virtual memory. When the system is low on
free memory, Kswapd is activated to reclaim memory by identifying less frequently
used pages from the file cache and moving them to the swap space (ZRAM).
Kswapd does the following:
- Monitors the memory usage of the system
- Performs swapping activities in the background to maintain an optimal level of
free memory
Figure : CPU usage vs. performance using Kswapd
### Watermark
A watermark is a threshold or limit set on memory parameters that helps regulate the
allocation and usage of system memory.
Table : Watermark parameters
| Parameter | Description |
| --- | --- |
| `/proc/sys/vm/min_free_kbytes` |
- This parameter determines the minimum amount of free memory
that the system must maintain across all zones.
- It ensures that a certain reserve of memory remains
available for critical operations, such as handling atomic
allocations, which cannot wait for memory reclamation.
- The number of reserved free pages in each zone is
proportional to its size.
|
| `/proc/sys/vm/watermark_scale_factor` |
- This factor controls the aggressiveness of Kswapd.
- It defines the amount of memory left in a system before
Kswapd is woken up, and the amount of free memory required
before Kswapd goes back to sleep.
- The unit is in fractions of 10,000.
- The default value of 10 means that the distance between the
watermarks is 0.1% of the available memory in the node or
system. The maximum value is 1000, or 10% of memory.
|
| `/proc/sys/vm/watermark_boost_factor` |
- This factor is used to optimize memory fragmentation by
temporarily providing a high-watermark for the memory
management area, which allows Kswapd to reclaim more memory.
- The unit is in fractions of 10,000.
- The default value of 15,000 means that up to 150% of the
high watermark is reclaimed in the event of a pageblock
being mixed due to fragmentation.
- The number of fragmentation events that have occurred in the
recent past determine the level of reclaim. A boost factor
of 0 disables the feature.
|
For more information, see [Documentation for /proc/sys/vm/](https://www.kernel.org/doc/Documentation/admin-guide/sysctl/vm.rst).
### Memory carveout
Memory carveouts refer to specific memory regions that the kernel cannot address,
known as no-map regions. Specific subsystems such as modem, camera, aDSP, cDSP, and
TrustZone use these regions exclusively and hence those are inaccessible to the
Linux kernel.
These carveouts are defined in the source code at
arch/arm64/boot/dts/qcom/<target>.dtsi.
They fall under the `reserved-memory` node and can be configured.
The following code shows the no-map regions for the cDSP, camera, modem, and
TrustZone subsystems:
reserved-memory {
cdsp_secure_heap_mem: cdsp-secure-heap@81800000 {
reg = <0x0 0x81800000 0x0 0x1e00000>;
no-map;
};
camera_mem: camera@84300000 {
reg = <0x0 0x84300000 0x0 0x500000>;
no-map;
};
adsp_mem: adsp@86100000 {
reg = <0x0 0x86100000 0x0 0x2800000>;
no-map;
};
cdsp_mem: cdsp@88900000 {
reg = <0x0 0x88900000 0x0 0x1e00000>;
no-map;
};
mpss_mem: mpss@8b800000 {
reg = <0x0 0x8b800000 0x0 0xf600000>;
no-map;
};
tz_stat_mem: tz-stat@c0000000 {
reg = <0x0 0xc0000000 0x0 0x100000>;
no-map;
};
tags_mem: tags@c0100000 {
reg = <0x0 0xc0100000 0x0 0x1200000>;
no-map;
};
Copy to clipboard
You can adjust the reserved memory carveout regions based on your product
requirements. This adjustment can include removing a modem carveout region or
reducing the size of TrustZone application memory carveout regions.
For example, the following code snippet shows how to disable the modem memory
carveout for memory optimization:
reserved-memory { mpss_mem: mpss@8b800000 {
reg = <0x0 0x8b800000 0x0 0xf600000>;
no-map;
status = "disabled";
};
Copy to clipboard
In this code:
- `0x8b800000` is the base address of the modem region.
- `0xf600000` is the size of the modem region, which is
246 MB.
- Add `status= disabled` to make this region available to the Linux
kernel.
The following example snippets show how to reduce the memory carveout size of the
TrustZone trusted applications from 28 MB (`0x1c00000`) to 20 MB
(`0x1400000`):
| Before:
reserved memory {
trusted_apps_mem: trusted_apps@c1800000 {
reg = <0x0 0xc1800000 0x0 0x1c00000>;
no-map;
};
Copy to clipboard | After:
reserved memory {
trusted_apps_mem: trusted_apps@c1800000 {
reg = <0x0 0xc1800000 0x0 0x1400000>;
no-map;
};
Copy to clipboard |
| --- | --- |
Last Published: Oct 14, 2024
[Previous Topic
Configure](https://docs.qualcomm.com/bundle/publicresource/80-70015-10/topics/14-configure.md) [Next Topic
Troubleshooting](https://docs.qualcomm.com/bundle/publicresource/80-70015-10/topics/24-debug.md)