Add guide for address discovery

[mutchiko]

[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

[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)

[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

[glpnk]

Sort of ready to review

[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