README.md
1# cpufetch programming documentation (v0.98)
2This documentation explains how cpufetch works internally and all the design decisions I made. This document intends 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 that collects interesting material in this area.
3
4### 1. Basics
5cpufetch works for __x86_64__ (Intel and AMD), __ARM__ and __PowerPC__ 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 and PowerPC versions. Depending on the architecture, cpufetch choose certain files to be compiled. A summarized tree of the source code of cpufetch is shown below.
6
7```
8cpufetch/
9├── doc
10│ ├── DOCUMENTATION_ARM.md
11| ├── DOCUMENTATION_PPC.md
12│ ├── DOCUMENTATION_X86.md
13│ └── README.md
14├── Makefile
15├── README.md
16└── src/
17 ├── arm/
18 │ ├── midr.c
19 │ ├── midr.h
20 │ └── other files ...
21 ├── common/
22 │ └── common files ...
23 ├── ppc/
24 | ├── ppc.c
25 | ├── ppc.h
26 | └── other files ...
27 └── x86/
28 ├── cpuid.c
29 ├── cpuid.h
30 └── other files ...
31```
32
33Source code is divided into four directories:
34
35- `common/`: Source code shared between all architectures
36- `arm/`: ARM source code
37- `ppc/`: PowerPC source code
38- `x86/`: x86 source code
39
40##### 1.1 Basics (x86_64)
41
42In 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).
43
44At 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:
45
46```
47struct cpuInfo {
48 ...
49 VENDOR cpu_vendor;
50 uint32_t maxLevels;
51 uint32_t maxExtendedLevels;
52 ...
53};
54```
55
56To use any CPUID leaf, cpufetch always needs to check that it is supported in the current CPU.
57
58##### 1.2 Basics (ARM)
59In 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` for ARM only works on Linux systems.__
60
61##### 1.3 Basics (PowerPC)
62In PowerPC, __cpufetch works using the PVR register and Linux filesystem__. PVR (Processor Version Register) is read using assembly and it is used to identify the microarchitecture of the CPU. Linux is also used to query the rest of the information, like the CPU topology, frequency, etc. This is the main reason to explain __why `cpufetch` for PowerPC only works on Linux systems.__
63
64##### 1.4 Documentation organization
65The rest of the documentation is divided in specific files for each architecture, since each one needs different implementations:
66
67- [DOCUMENTATION_ARM.md](https://github.com/Dr-Noob/cpufetch/blob/master/doc/DOCUMENTATION_ARM.md)
68- [DOCUMENTATION_PPC.md](https://github.com/Dr-Noob/cpufetch/blob/master/doc/DOCUMENTATION_PPC.md)
69- [DOCUMENTATION_X86.md](https://github.com/Dr-Noob/cpufetch/blob/master/doc/DOCUMENTATION_X86.md)
70