thelilfrog/cpufetch
1
0
Fork 0
mirror of https://github.com/Dr-Noob/cpufetch.git synced 2026-03-24 23:40:39 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Dr-Noob
2020-12-25 15:42:33 +01:00
parent fce0bbf012
commit c7d1165a94
4 changed files with 110 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
README.md
View File

@@ -1,25 +1,16 @@
# cpufetch
Simplistic yet fancy CPU architecture fetching tool
![cpu1](pictures/i9.png)
![cpu1](i9.png)
### Platforms
cpufetch currently supports x86_64 CPUs (both Intel and AMD) and ARM (experimental support)
| Platform | Intel | AMD | ARM | Notes |
|:---------:|:-------------------------:|:------------------------:|:------------------------:|:-----------------:|
| Linux | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | Prefered platform. <br> Experimental ARM support |
| Windows | :heavy_check_mark: | :heavy_check_mark: | :x: | Some information may be missing. <br> Colors will be used if supported |
| Android | :heavy_exclamation_mark: | :heavy_exclamation_mark: | :heavy_check_mark: | Experimental ARM support |
| macOS | :heavy_exclamation_mark: | :heavy_exclamation_mark: | :heavy_exclamation_mark: | Untested |
| Emoji | Meaning |
|:-----------------------:|:-------------:|
|:heavy_check_mark: | Supported |
|:x: | Not Supported |
|:heavy_exclamation_mark: | Unested |
cpufetch currently supports x86 CPUs (both Intel and AMD CPUs)
| Platform | Intel | AMD | Notes |
|:---------:|:-------------------------:|:------------------------:|:-----------------:|
| Linux | :heavy_check_mark: | :heavy_check_mark: | Prefered platform |
| Windows | :heavy_check_mark: | :heavy_check_mark: | Some information may be missing. <br> Colors will be used if supported |
| macOS | :heavy_exclamation_mark: | :heavy_exclamation_mark: | Untested |
### Usage and installation
@@ -31,11 +22,9 @@ If you are in other distro, you can build `cpufetch` from source (see below)
#### Windows
In the [releases](https://github.com/Dr-Noob/cpufetch/releases) section you will find some cpufetch executables compiled for Windows. Just download and run it from Windows CMD.
#### Android
You need to build `cpufetch` from source (see below).
#### Building from source
Just clone the repo and use `make` to compile it
### Building from source
#### Linux and Windows
```
git clone https://github.com/Dr-Noob/cpufetch
cd cpufetch
@@ -43,24 +32,15 @@ make
./cpufetch
```
#### Android
I recommend using `termux` terminal emulator. Once you installed it, run the following commands:
The Makefile is designed to work on both Linux and Windows.
```
pkg install -y git make clang
git clone https://github.com/Dr-Noob/cpufetch
cd cpufetch
make
./cpufetch
```
### Examples
### Example
Here are more examples of how `cpufetch` looks on different CPUs.
![cpu2](pictures/epyc.png)
![cpu2](epyc.png)
![cpu3](pictures/cascade_lake.png)
![cpu3](cascade_lake.png)
### Colors and style
By default, `cpufetch` will print the CPU art with the system colorscheme. However, you can always set a custom color scheme, either
@@ -76,10 +56,10 @@ In the case of setting the colors using RGB, 4 colors must be given in with the
### Implementation
`cpufetch` fetches all of the information using the `CPUID` x86 instruction. There are, however, some cases where the CPU does not support fetching some needed information. In this case, `cpufetch` will use `/sys/devices/system/cpu` in Linux as a fallback. If `cpufetch` is running on Windows and `CPUID` does not give all the data, `cpufetch` won't be able to show it. [I hope this can be fixed in the future](https://github.com/Dr-Noob/cpufetch/issues/30)
See [cpufetch programming documentation](https://github.com/Dr-Noob/cpufetch/blob/master/doc/README.md).
### Bugs or improvements
There are many open issues in github (see [issues](https://github.com/Dr-Noob/cpufetch/issues)). Feel free to open a new one report a issue or propose any improvement in `cpufetch`
### Testers
I would like to thank [Gonzalocl](https://github.com/Gonzalocl) and [OdnetninI](https://github.com/OdnetninI) for their help, running `cpufeth` in many different CPUs they have access to, which makes it easier to debug and check the correctness of `cpufetch`.
I would like to thank [Gonzalocl](https://github.com/Gonzalocl) and [OdnetninI](https://github.com/OdnetninI) for their help, running `cpufetch` in many different CPUs they have access to, which makes it easier to debug and check the correctness of `cpufetch`.

60
doc/DOCUMENTATION_ARM.md
View File

@@ -1,2 +1,60 @@
### 2. Why ARM cpufetch works on Linux based systems?
TODO
CPUID instructions (present in x86 architectures) [[1](#references)] allow user level applications to obtain information about the CPU. In ARM architectures, there are many registers (MIDR [[2](#references)], CCSIDR [[3](#references)]) that provide information about the CPU too. However, those registers can only be read from privilege mode (PL1 or higher). Therefore, any user level tool which can actually read information about the running CPU must use the operating system to do so. cpufetch uses some Linux kernel features (see the remaining sections). Therefore, cpufetch in ARM processors is limited to Linux kernel based systems, such as __GNU/Linux__ and __Android__
### 3. How to get CPU microarchitecture?
__Involved code: [get_midr_from_cpuinfo (udev.c)](https://github.com/Dr-Noob/cpufetch/blob/master/src/arm/udev.c), [midr.c](https://github.com/Dr-Noob/cpufetch/blob/master/src/arm/midr.c)__
Microarchitecture information is acquired from the Main ID Register (MIDR) [[2](#references)]. Currently, cpufetch rebuilds this register using `/proc/cpuinfo` file. While this file does not contain the value of the register per se, it contains the following fields:
- `CPU implementer`,
- `CPU archiecture`
- `CPU variant`
- `CPU part`
- `CPU revision`
The MIDR register can be built with this information. Another posible approach is to read MIDR directly from `/sys/devices/system/cpu/cpu*/regs/identification/midr_el1`
With the MIDR available, the approach is the same as the one used in x86_64 archiectures. cpufetch has a file which acts like a database that tries to match the MIDR register with the specific CPU microarchitecture.
### 4. How to get CPU topology?
__Involved code: [get_ncores_from_cpuinfo (udev.c)](https://github.com/Dr-Noob/cpufetch/blob/master/src/arm/udev.c), [midr.c](https://github.com/Dr-Noob/cpufetch/blob/master/src/arm/midr.c)__
ARM provides a new interesting archiecture feature: big.LITTLE architectures [[4](#references)]. An ARM CPU can be organized like a typycal x86_64 CPU, where all cores share the same microarchitecture. However, ARM big.LITTLE archiecture break this schema. In a big.LITTLE CPU, two or more CPUs microarchitecture live in the same chip.
This means that cpufetch can't just read which microarchitecture is the first core and assume that the rest of them shares the same microarchitecture. To get the CPU topology, cpufetch first reads the number of CPU cores. This can be obtained from `/sys/devices/system/cpu/present`
Then, for each core, cpufetch reads the MIDR and also the frequency (see section 5). Then, cpufetch assumes that two cores are different when their MIDR are different. This idea allows cpufetch do detect big.LITTLE architectures, and to know how many cores of each archiecture the running CPU has.
### 5. How to get the frequency?
Frequency is read directly from `/sys/devices/system/cpu/cpu*/cpufreq/cpuinfo_max_freq`
### 6. How to get system on chip model?
__Involved code: [soc.c](https://github.com/Dr-Noob/cpufetch/blob/master/src/arm/soc.c)__
System on chip (SoC) model is obtained using the same idea as the microarchitecture. First, SoC string is read. Then, the string has to be matched against a database-like function (__parse_soc_from_string__). The SoC string of the running CPU can be obtained using two different approaches:
- Using `/proc/cpuinfo`. This is the first thing to try. Linux kernel usally provides the string under the `Hardware` keyword. However, it may happend that Linux kernel is unable of providing this information, or it may happen that this string is not found in the database-like function.
- Using Android properties: This only works on Android systems. Android properties can be read using `__system_property_get` function. cpufetch tries to read two properties:
- `ro.mediatek.platform`
- `ro.product.board`
If any string is returned, cpufetch tries to find a match in the database (using the same database as in the case of `/proc/cpuinfo`).
The expected strings have to be hardcoded. I found two ways of knowing which string should correspond to which SoC:
- Searching on the internet. Manufacturers __usually__ provide this information. For example, Qualcomm usually publish the chip name along with other characteristics (under the `Part` or `Part number` keyword [[6](#references)]).
- "Hunting" for the strings. For example, finding smartphones with a given SoC and manually reading the `/proc/cpuinfo` or the `build.prop` file. A very good resource to do this is the SpecDevice webpage [[7](#references)]).
### 7. How to get cache size and topology?
ARM archiecture supports reading the cache information via some registers (for example, the CCSIDR register [[3](#references)]). As mentioned earlier, user level applications are not able to read these registers directly. The remaining option is to ask the operating system for this information. However, at the moment, __Linux kernel does not provide cache information__. Therefore, cpufetch does not print any cache information on ARM CPUs at the moment. There is, however, other approaches to be explored:
- Read the registers in kernel mode. This can be accomplished by running a kernel module [[4](#references)]. Unfortunately, running a custom kernel module is tricky, and sometimes imposible to do in a reasonable way (for example, in Android devices). In any case, my decision is to run cpufetch on user level only.
- Hardcode the cache information for each SoC: Sometimes, manufacturers publish technical information about the chips, where cache topology and size are shown. This method is impractical, since this kind of information is very hard (or impossible) to find online, and the number of SoC is huge.
#### References
- [1] [cpufetch x86_64 documentation](https://github.com/Dr-Noob/cpufetch/blob/master/doc/DOCUMENTATION_X86.md)
- [2] [Main ID Register](https://developer.arm.com/documentation/ddi0433/c/system-control/register-descriptions/main-id-register)
- [3] [Cache size ID Register](https://developer.arm.com/documentation/100403/0200/register-descriptions/aarch32-system-registers/ccsidr--cache-size-id-register)
- [4] [How to get the size of the CPU cache in Linux](https://stackoverflow.com/a/63474811/9975463)
- [5] [ARM big.LITTLE](https://en.wikipedia.org/wiki/ARM_big.LITTLE)
- [6] [Snapdragon 855+ Mobile Platform](https://www.qualcomm.com/products/snapdragon-855-plus-mobile-platform)
- [7] [SpecDevice](http://specdevice.com/unmoderated.php)

61
doc/DOCUMENTATION_X86.md
View File

@@ -1,40 +1,38 @@
### 2. Why differences between Intel and AMD?
There are many different CPUID leaves (see [Useful documentation](#useful-documentation)). However, there are cases where a given leaf does the same thing in Intel and AMD, but the majority of them, they don't. For example, leaf 0x4 gives you the caches information, but in
AMD is a reserved (invalid) leaf! In the case of AMD, is more common to fetch information using extended levels than using the standard levels (the other way around with Intel).
There are many different CPUID leaves [[1](#references)]. In some caseses, a given leaf does the same thing in Intel and AMD processors, but the majority of them, they don't. For example, leaf 0x4 gives you the caches information, but in AMD is a reserved (invalid) leaf! In the case of AMD, is more common to fetch information using extended levels than using the standard levels (the other way around with Intel).
### 3. How to get the frequency?
__Involved code: get_frequency_info (cpuid.c)__
__Involved code: [get_frequency_info (cpuid.c)](https://github.com/Dr-Noob/cpufetch/blob/master/src/x86/cpuid.c)__
We use CPUID leaf 0x16.
CPUID leaf 0x16 is used.
If the CPU supports it, we are done. If not:
- Linux: cpufetch will try to obtain this information using `/sys` filesystem in Linux. I think that, in this case, Linux knows the frequency using MSRs, so at the user level you can't know it, but I will look at the kernel source code to check it.
- Windows: We are dead. cpufetch can't fetch CPU frequency. This means that peak performance can't be computed because the frequency is needed to compute it.
If the CPU does not support supports such level:
- Linux: cpufetch will try to obtain this information using `/sys` filesystem in Linux. I think that Linux knows the frequency using model specific registers (MSRs), which you can't read at the user level.
- Windows: cpufetch can't obtain CPU frequency. This means that peak performance can't be computed because the frequency is needed to compute it.
### 4. How to get cache sizes?
__Involved code: get_cache_info (cpuid.c)__
__Involved code: [get_cache_info (cpuid.c)](https://github.com/Dr-Noob/cpufetch/blob/master/src/x86/cpuid.c)__
- Intel: We use CPUID leaf 0x4
- AMD: We use extended CPUID leaf 0x1D
- Intel: CPUID leaf 0x4 is used (using __get_cache_info_general__). If CPU does not support it, cpufetch can't get this information.
- AMD: Extended CPUID leaf 0x1D is used (using __get_cache_info_general__). If CPU does not support this level, cpufetch uses a fallback method, which uses extended leaves 0x5 and 0x6. This fallback method uses __get_cache_info_amd_fallback__.
If CPU does not support it, we are dead: cpufetch can't get this information. If CPU does, we can fetch it, and 0x4 in Intel behaves the same way as 0x1D in AMD.
### 5. How to get CPU microarchitecture?
__Involved code: get_cpu_uarch (cpuid.c), get_uarch_from_cpuid (uarch.c)__
__Involved code: [get_cpu_uarch (cpuid.c)](https://github.com/Dr-Noob/cpufetch/blob/master/src/x86/cpuid.c), [get_uarch_from_cpuid (uarch.c)](https://github.com/Dr-Noob/cpufetch/blob/master/src/x86/uarch.c)__
We use CPUID leaf 0x1. From there, we get:
CPUID leaf 0x1 is used. From there, we get:
- Model
- Extended Model
- Family
- Extended Family
- Stepping
Knowing this information, we can distinguish any CPU microarchitecture. Inside __uarch.c__ there is a function that behaves as it had a database. It will search, for this information, what kind of microarchitecture the current CPU is. I got the data using and adapting the code form Todd Allen's cpuid program (Link 5 in [Useful documentation](#useful-documentation)). From the microarchitecture, we can obtain the manufacturing process (or technology, the size in nm of the transistors).
Knowing this information, we can distinguish any CPU microarchitecture. Inside __uarch.c__ there is a function that behaves as a database or a lookup table. The function of this database is to find a match between the information obtained from 0x1 and what kind of microarchitecture the current CPU is. I got the data using and adapting the code form Todd Allen's cpuid program [[5](#references)]. Knowing the microarchitecture, we can obtain the manufacturing process (or technology, the size in nm of the transistors).
### 6. How to get CPU topology?
__Involved code: cpuid.h, get_topology_info (cpuid.c), apic.c__
__Involved code: [cpuid.h](https://github.com/Dr-Noob/cpufetch/blob/master/src/x86/cpuid.h), [get_topology_info (cpuid.c)](https://github.com/Dr-Noob/cpufetch/blob/master/src/x86/cpuid.c), [apic.c](https://github.com/Dr-Noob/cpufetch/blob/master/src/x86/apic.c)__
cpufetch tries to support the most complex systems, so it supports multi socket CPUs and a detailed SMT (Intel HyperThreading) information. The CPU topology is stored like this:
cpufetch aims to support the most complex systems, so it supports multi socket CPUs and a detailed SMT (Intel HyperThreading) information. The CPU topology is stored in the following struct:
```
struct topology {
@@ -80,8 +78,8 @@ sockets = 1
Now that we know what data are we looking for, let's see how we get it:
- __Intel__: We use the methodology explained in the Intel webpage (Link 2 in [Useful documentation](#useful-documentation)). Here, Intel explains how to do it and also gives an example source code. I used it and modified it to fit cpufetch style. The core of this methodology is the usage of the APIC id, so the code is inside __apic.c__.
- __AMD__: Intel's algorithm using APIC does not work for AMD. To get the same information in AMD, I used the reference from OSdev(Link 3 in [Useful documentation](#useful-documentation)) and also ideas from lscpu(Link 4 in [Useful documentation](#useful-documentation)). This uses:
- __Intel__: The methodology used is explained in the Intel webpage [[2](#references)]. Intel explains how to do it and also gives an example source code. I used it and modified it to fit cpufetch style. The core of this methodology is the usage of the APIC id, so the code is inside __apic.c__.
- __AMD__: Intel's algorithm using APIC does not work for AMD. To get the same information in AMD, I used the reference from OSdev [[3](#references)] and also ideas from lscpu [[4](#references)]. This uses:
- CPUID extended leaf 0x8: Fill `logical_cores`
- CPUID extended leaf 0x1E: Fill `smt_supported`
- CPUID standard leaf 0x1 (APIC): Fill `smt_available`
@@ -97,25 +95,26 @@ Now that we know what data are we looking for, let's see how we get it:
```
### 7. How to get cache topology?
__Involved code: get_cache_topology_amd (cpuid.c), apic.c__
__Involved code: [get_cache_topology_amd (cpuid.c)](https://github.com/Dr-Noob/cpufetch/blob/master/src/x86/cpuid.c), [apic.c](https://github.com/Dr-Noob/cpufetch/blob/master/src/x86/apic.c)__
The topology is reduced to the idea of how many caches we have at a given level. It usually follows the rule of:
The topology of a cache gives us information about how many caches we have at a given level. It usually follows the rule of:
- L1: The same as the number of cores (one L1i and one L1d per core).
- L2: If L2 is the last level cache, one L2. If not, the same as the number of cores (one L2 per core).
- L3: One L3 cache per socket (shared among all cores).
These assumptions are generally (but not always) true. For example, for the AMD Zen generation, or the Intel Xeon Phi KNL. Thus, cpufetch does not assume the topology and tries to fetch it instead.
These assumptions are generally (but not always) true. For example, for the AMD Zen generation, or the Intel Xeon Phi KNL. Thus, cpufetch does not assume the topology, but obtains it instead.
- __Intel__: We can use the methodology explained in the Intel webpage (Link 2 in [Useful documentation](#useful-documentation)) again (it also covers how to get cache topology using APIC id).
- __Intel__: The idea is similar to the mentioned in CPU topology [[2](#references)](it also covers how to get cache topology using APIC id).
- __AMD__: Again, we have to look another path for AMD. This time, the way to do it is easier and (I think) more solid and future proof. We just use extended CPUID leaf 0x1D. If the CPU does not support it, we can still guess the topology of the caches (as mentioned earlier). If it does, CPUID can give us how many cores shares a given level of cache. So, if we have the number of cores, we can guess how many caches are there for any given level (see __get_cache_topology_amd__).
- __AMD__: Again, we have to look another path for AMD. This time, the way to do it is easier and (I think) more solid and future proof. The idea is to use extended CPUID leaf 0x1D. If the CPU does not support it, we can still guess the topology of the caches (as mentioned earlier). If it does, CPUID can give us how many cores shares a given level of cache. So, if we have the number of cores, we can guess how many caches are there for any given level (see __get_cache_topology_amd__).
#### Useful documentation
- Link 1: [sandpile CPUID webpage](https://www.sandpile.org/x86/cpuid.htm)
- Link 2: [CPU topology and cache topology: Intel](https://software.intel.com/content/www/us/en/develop/articles/intel-64-architecture-processor-topology-enumeration.html)
- Link 3: [CPU topology: AMD](https://wiki.osdev.org/Detecting_CPU_Topology_(80x86))
- Link 4: [lscpu](https://github.com/karelzak/util-linux/blob/master/sys-utils/lscpu.c)
- Link 5: [Todd Allen's cpuid](http://www.etallen.com/cpuid.html)
- Link 6: [AMD specific CPUID specification](https://www.amd.com/system/files/TechDocs/25481.pdf)
#### References
- [1] [sandpile CPUID webpage](https://www.sandpile.org/x86/cpuid.htm)
- [2] [CPU topology and cache topology: Intel](https://software.intel.com/content/www/us/en/develop/articles/intel-64-architecture-processor-topology-enumeration.html)
- [3] [CPU topology: AMD](https://wiki.osdev.org/Detecting_CPU_Topology_(80x86))
- [4] [lscpu](https://github.com/karelzak/util-linux/blob/master/sys-utils/lscpu.c)
- [5] [Todd Allen's cpuid](http://www.etallen.com/cpuid.html)
- [6] [AMD specific CPUID specification](https://www.amd.com/system/files/TechDocs/25481.pdf)
- [7] [Intel vs AMD CPU Architectural Differences: Chips and Chiplets](https://c.mi.com/thread-2585048-1-0.html)
In addition to all these resources, I found very interesting to search in the Linux kernel source code (for example, the directory `arch/x86/kernel/cpu/`), because sometetimes you can find ideas that cannot be found anywhere else!
In addition to all these resources, I found very interesting to search in the Linux kernel source code (for example, the directory [`arch/x86/kernel/cpu/`](https://elixir.bootlin.com/linux/latest/source/arch/x86/kernel/cpu)), because sometetimes you can find ideas that cannot be found anywhere else!

12
doc/README.md
View File

@@ -1,8 +1,8 @@
# cpufetch programming documentation (v0.88)
# cpufetch programming documentation (v0.94)
This documentation explains how cpufetch works internally and all the design decisions I made. The intention of this documentation is to be useful for me in the future, for everyone interested in the project, and for anyone who is trying to obtain any specific information from the CPU. In this way, this can be used as a manual or a page which collects interesting material in this area.
### 1. Basics
cpufetch works for __x86_64__ CPUs (Intel and AMD) and experimental support for __ARM__. Other kinds of x86_64 CPU are not supported (I don't think supporting other CPUs may pay off). Depending on the architecture, cpufetch choose certain files to be compiled. A summarized tree of the source code of cpufetch is shown below.
cpufetch works for __x86_64__ (Intel and AMD) and __ARM__ CPUs. However, cpufetch is expected to work better on x86_64, because the codebase is older and has been tested much more than the ARM version. Other kinds of x86_64 CPU are not supported (I don't think supporting other CPUs may pay off). Depending on the architecture, cpufetch choose certain files to be compiled. A summarized tree of the source code of cpufetch is shown below.
```
cpufetch/
@@ -30,9 +30,9 @@ Source code is divided in three directories:
##### 1.1 Basics (x86_64)
In x86, __cpufetch works using the CPUID instruction__. It is called directly using assembly (see `src/x86/cpuid_asm.c`). To understand how CPUID works you may have a look at the [Useful documentation](https://github.com/Dr-Noob/cpufetch/blob/master/DOCUMENTATION_x86.md#useful-documentation) section (more precisely, Link 1).
In x86, __cpufetch works using the CPUID instruction__. It is called directly using assembly (see `src/x86/cpuid_asm.c`). To understand how CPUID works, see [DOCUMENTATION_X86.md](https://github.com/Dr-Noob/cpufetch/blob/master/doc/DOCUMENTATION_X86.md).
At the beginning of execution, cpufetch needs to know the max standard CPUID level and max CPUID extended level supported in the running CPU. We also need to know if the x86 CPU is Intel or AMD because some fetching depends on it. This information will be stored in:
At the beginning of execution, cpufetch needs to know the max standard CPUID level and max CPUID extended level supported in the running CPU. We also need to know if the x86 CPU is Intel or AMD because sometimes, the way to obtain the information depends on the manufacturer. This information will be stored in:
```
struct cpuInfo {
@@ -44,10 +44,10 @@ struct cpuInfo {
};
```
To use any CPUID leaf, we always need to check that it is supported in the current CPU. cpufetch will always check if the leaf is supported in the current CPU, and will use a different workaround if the CPU is Intel or AMD, which leads us to the following section.
To use any CPUID leaf, cpufetch always need to check that it is supported in the current CPU.
##### 1.2 Basics (ARM)
In ARM, __cpufetch works using the MIDR register and Linux filesystem__. MIDR (Main ID Register) is fetched from `/proc/cpuinfo`. It allows the detection of the microarchitecture of the cores. Furthermore, Linux filesystem `/sys/devices/system/cpu/` is used to fetch the number of cores, and other information. This is the main reason to explain __why `cpufetch` only works on Linux kernel based systems.__
In ARM, __cpufetch works using the MIDR register and Linux filesystem__. MIDR (Main ID Register) is read from `/proc/cpuinfo`. It allows the detection of the microarchitecture of the cores. Furthermore, Linux filesystem `/sys/devices/system/cpu/` is used to fetch the number of cores, and other information. This is the main reason to explain __why `cpufetch` only works on Linux kernel based systems.__
##### 1.3 Documentation organization
The rest of the documentation is divided into x86 and ARM architectures, since each one need different implementations: