Add guide for address discovery

[mutchiko]

No description provided.

[glpnk]

@teackot what can you say?

[teackot]

The ec_sys module isn't present on all distributions, for example Fedora doesn't ship it. We have a debug mode in our driver, which dumps the EC ram contents in /sys/devices/platform/msi-ec/debug/ec_dump

[glpnk]

Hi, @teackot, can you check this EC dump method on your devices with both generations. It should workon WMI1 devices, because used in DSDT tables. It reads address 0xFC000080

sudo dd if=/dev/mem bs=1 skip=4227860480 count=256 | hexdump -C

Basically I'm interested is it works on wmi2

[teackot]

Hi! Yep it works on my WMI2 Summit E14, gives me a correct EC dump. I'll test in on my P14 a little later

Edit: also works on my P14

[glpnk]

Nice, I'll add this to guide too

[teackot]

I left some suggestions on how to improve the guide

[glpnk]

@teackot I'm thinking about splitting guide into 2 or 3 parts:

• main - Disclaimers, info about known values, other info
• Windows - Disclaimer + Windows guide
• Linux - Disclaimer + debug mode + ec_sys + raw memory read

[teackot]

So the main one will describe the base principle, the danger, info about the dump, and where and what to look for (aka the known values), etc? This does sound like it should be in this guide.

If by splitting you mean to split it into separate files I don't think there is much need, and a single page might be better

I'm thinking of a format like this:

1. Base info (main guide)
2. Table of contents
3. Windows
4. Linux

[glpnk]

Okay, known values I'll keep for contribution guide, for example.

I'm thinking of a format like this:

Base info (main guide)
Table of contents
Windows
Linux

Okay, single file guide sounds good. But what we can add to Table of contents?

Also, can you start new review and add Alerts tags

My own guide making attempt here https://github.com/glpnk/msi-ec/tree/docs/more-docs/docs

[teackot]

We can put the known values into its own section, since it is likely going to be big.

1. Base info
2. Table of contents
3. Windows
4. Linux
5. Known values

All sections after the TOC go into it (win, lin, known)

[teackot]

Alerts

[glpnk]

Main problem of Markdown is indents in lists

Github don't render Alerts as part of lists, but we can add pictures inside Alerts

[teackot]

We can remove the "9. Here you should see a table of all the values your Embedded Chip has in its memory." entry and put the alert it the "reading the table" section.

It can go like this:

## Windows method

### Preparation

1. Install
2. Update
3. MSI apps
4. AMD/Nvidia
5. Test the app
6. Download RWEverything
7. Launch
8. EC page
9. Refrest rate

### Reading the table

Here you will see a table of all the values your Embedded Controller has in its memory.

CAUTION: do not edit

This is how you find the address

This is how you interpret it

Example

...

This way the list won't have anything that breaks the indentation

[glpnk]

Yeah, because we have a second method of reading EC on Win we can split guide to few steps as you said, and apps

UPD: I changed heading levels because heading-3 looks unnoticeable

[mutchiko]

and how do i check if the dump i made doesn't include sensitive info? let's call this method "experimental" until we make sure it works no less than 90% of the time.

[glpnk]

true, only by comparing with reference dump, like matching the location of the ec name

[glpnk]

Actually, chance of getting reading error is higher than accidentally dump some confidential info. And maybe this memory area newer mapped to system RAM

[teackot]

Let's mark it as "Not recommended" and put the warning at the top of this method's section, so it can be the last resort if the two previous methods didn't work for any reason

[mutchiko]

this is outside the scope of this guide, you've already done a good write up on that topic, so lets keep it outside this guide

[teackot]

Right, this is just a guide on how to obtain and interpret the dump

[glpnk]

Guide about naming and wmi versions is short, and some people got confused between BIOS and EC names in the past.
And it will be useful to describe known addresses

[teackot]

Alright, adding it here as a draft wouldn't hurt, we'll see how well it fits here when the guide is near finished

[teackot]

I don't think anyone does. At least, we don't need binaries submitted here, so let's exclude this part

[mutchiko]

this is a solid explanation , but it's better to put it in another documentation

[glpnk]

We probably don't need more then 1 guide now

[teackot]

These should probably be in a separate guide.

Some people have been requesting a guide on adding a config to the code and I think it also doesn't belong in this file.

We can make a file with a "Contribution" guide that:

1. refers people to this guide if they want to contribute by discovering their laptops' configs (this is a separate file because it is big)
2. provides some specific info like FW naming and generations
3. explains how to add a config to the code

[glpnk]

@teackot do you have access to https://github.com/BeardOverflow/msi-ec/graphs/traffic ? Can you make screenshot of Referring sites block? Maybe this will help us focus on the most popular sites that bring people to this project.

At least I think about the Arch Wiki

[teackot]

Here it is

Most visits are from search engines and Phoronix articles

[teackot]

What's left to do here? I think we need to direct people to the issue tracker at the end of the "Windows method" section (like we do in the "Linux method" section) and remove the "Contribution" section (to later move it to a different file as described in this comment), and this PR is good to go

[mutchiko]

@teackot only thing left is is to decide where to put links to the guide, my initial thoughts:
1- in the first/second section of the readme
2- on top of the supported devices list
3- in the issue template

and this is just enough to attract people's attention.

[glpnk]

Now I think that Table of content section looks confusing, we probably need to move 2nd level bullet points to guide.

About contribution section - I think info about generations might be useful, but we can call it like Additional info

[glpnk]

2- on top of the supported devices list

Something like this

3- in the issue template

Above Laptop model probably

[mutchiko]

@glpnk for number 2 lets change the wording to "If your device is not in the list, read this guide to get it supported and add it to the list"

helpful in case people outside github share the link with each other

[glpnk]

I'm not committed this change, so it's just draft

[mutchiko]

Im thinking about adding an explanation about mic/speaker mute LEDs in the Additional Info section;
just to tell people that they exist and how they work on linux, but we don't have a way to trigger them, yet.

[glpnk]

LEDs controlled by kernel triggers, which are controlled by audio card drivers. Bluetooth audio works in userspace, so it can't be used as trigger

[mutchiko]

@teackot the guide is ready, please go ahead and merge it.

[teackot]

Thank you very much for writing this important guide!

[teackot]

And with this, all the open PRs are finally merged