Skip to content

Commit

Permalink
Add documentation about Physical vs Usable RAM
Browse files Browse the repository at this point in the history
There has been some confusion about what the difference between physical
and usable RAM is and why `ghw` doesn't report transient metrics like
available/used RAM. This patch adds some documentation explaining both.
  • Loading branch information
jaypipes committed May 10, 2020
1 parent e193f94 commit 211284c
Showing 1 changed file with 67 additions and 0 deletions.
67 changes: 67 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,18 @@ for Linux and Windows. There currently exists partial support for MacOSX.
the structs returned by various library functions should have consistent
attribute and method names.

## Inspecting != Monitoring

`ghw` is a tool for gathering information about your hardware's **capacity**
and **capabilities**.

It is important to point out that `ghw` does **NOT** report information that is
temporary or variable. It is **NOT** a system monitor nor is it an appropriate
tool for gathering data points for metrics that change over time. If you are
looking for a system that tracks usage of CPU, memory, network I/O or disk I/O,
there are plenty of great open source tools that do this! Check out the
[Prometheus project](https://prometheus.io/) for a great example.

## Usage

You can use the functions in `ghw` to determine various hardware-related
Expand Down Expand Up @@ -135,6 +147,61 @@ Example output from my personal workstation:
memory (24GB physical, 24GB usable)
```

#### Physical versus Usable Memory

There has been [some](https://github.com/jaypipes/ghw/pull/171)
[confusion](https://github.com/jaypipes/ghw/issues/183) regarding the
difference between the total physical bytes versus total usable bytes of
memory.

Some of this confusion has been due to a misunderstanding of the term "usable".
As mentioned [above](#inspection!=monitoring), `ghw` does inspection of the
system's capacity.

A host computer has two capacities when it comes to RAM. The first capacity is
the amount of RAM that is contained in all memory banks (DIMMs) that are
attached to the motherboard. `ghw.MemoryInfo.TotalPhysicalBytes` refers to this
first capacity.

There is a (usually small) amount of RAM that is consumed by the bootloader
before the operating system is started (booted). Once the bootloader has booted
the operating system, the amount of RAM that may be used by the operating
system and its applications is fixed. `ghw.MemoryInfo.TotalUsableBytes` refers
to this second capacity.

You can determine the amount of RAM that the bootloader used (that is not made
available to the operating system) by subtracting
`ghw.MemoryInfo.TotalUsableBytes` from `ghw.MemoryInfo.TotalPhysicalBytes`:

```go
package main

import (
"fmt"

"github.com/jaypipes/ghw"
)

func main() {
memory, err := ghw.Memory()
if err != nil {
fmt.Printf("Error getting memory info: %v", err)
}

phys := memory.TotalPhysicalBytes
usable := memory.TotalUsableBytes

fmt.Printf("The bootloader consumes %d bytes of RAM\n", phys - usable)
}
```

Example output from my personal workstation booted into a Windows10 operating
system with a Linux GRUB bootloader:

```
The bootloader consumes 3832720 bytes of RAM
```

### CPU

The `ghw.CPU()` function returns a `ghw.CPUInfo` struct that contains
Expand Down

0 comments on commit 211284c

Please sign in to comment.