Page 1 of 1

AHCI data structures

Posted: Wed Dec 08, 2021 5:34 am
by Bonfra
So I'm rewriting my AHCI driver in a more readable way. This time instead of blindly trusting tutorials/wikis/articles I'd wanted to deeply understand what exactly each piece of code does to abstract it in a more pleasant way. I've been reading the AHCI specs in search of explanations about what each bit in the data structures means but as I stumbled upon the FIS structures I couldn't find any good explanation. The wiki provides a struct to use but it, just like the specs, does not go in deep for each field.

Code: Select all

typedef struct fis_reg_h2d
{
    // DWORD 0
    uint8_t fis_type;   // FIS_TYPE_REG_H2D
 
    uint8_t pmport : 4; // Port multiplier
    uint8_t reserved0 : 3;
    uint8_t c : 1;      // 1: Command, 0: Control
 
    uint8_t command;    // Command register
    uint8_t featurel;   // Feature register, 7:0
 
    // DWORD 1
    uint8_t lba0;       // LBA low register, 7:0
    uint8_t lba1;       // LBA mid register, 15:8
    uint8_t lba2;       // LBA high register, 23:16
    uint8_t device;      // Device register
 
    // DWORD 2
    uint8_t lba3;       // LBA register, 31:24
    uint8_t lba4;       // LBA register, 39:32
    uint8_t lba5;       // LBA register, 47:40
    uint8_t featureh;   // Feature register, 15:8
 
    // DWORD 3
    uint8_t countl;     // Count register, 7:0
    uint8_t counth;     // Count register, 15:8
    uint8_t icc;        // Isochronous command completion
    uint8_t control;    // Control register
 
    // DWORD 4
    uint8_t  reserved1[4];
} __attribute__ ((packed)) fis_reg_h2d_t;
This is the struct I'm presented with. While some fields are self-explanatory to me (like fis_type, lba*, count*) some others have cryptic names and I can't find anywhere what their value means.
For example, in my old code, I used to set some arbitrary values to the fields pmport, c and device without really knowing the meaning.
Do you have some kind of table or know somewhere I can read about these structures?

Re: AHCI data structures

Posted: Wed Dec 08, 2021 1:37 pm
by Octocontrabass
Those aren't explained in the AHCI specification; you need to read the SATA specification. Either buy one of the more recent versions of the spec or download an earlier, free version.

Re: AHCI data structures

Posted: Thu Dec 09, 2021 5:28 am
by Bonfra
Octocontrabass wrote:Those aren't explained in the AHCI specification; you need to read the SATA specification. Either buy one of the more recent versions of the spec or download an earlier, free version.
I managed to get my hands on the data 3.0 specs, it does have a table with all the fields listed but it gives something for granted that I'm not sure about. This is the table:
Image
It does not explain the various fields, it just signals the correspondence with the shadow register block, which isn't explained at all. Well it gives a table for the fields of this block but is just the same of the above one and the fields are not documented.

Re: AHCI data structures

Posted: Thu Dec 09, 2021 2:25 pm
by Octocontrabass
Those aren't explained in the SATA specification; you need to read... whichever version of the ATA command set your drive supports, I guess?

It doesn't help that the version of the SATA spec you're looking at is using register names that correspond to 48-bit LBA commands, even though different commands may use those registers for different purposes. I suggest looking at the same table in the SATA 1.0a specification, which uses legacy names but more clearly defines which registers were extended for 48-bit LBA. Then you can compare against old versions of the ATA specification that still use those names and explain how values map to each register, particularly for 28-bit LBA and for the packet command set. (I think ATA/ATAPI-6 has a pretty good explanation of how 48-bit LBA extends the registers over 28-bit LBA, but ATA/ATAPI-5 was the last version to use the legacy register names...)

Re: AHCI data structures

Posted: Thu Dec 09, 2021 3:12 pm
by Bonfra
I think I found something useful in the wiki ata pio page, where it explains a lot of registers, it flies past the feature register but I think I can leave without it if I know the rest. Can I assume these registers are all the same across all ATA (their meaning is the same also for SATA)?

Re: AHCI data structures

Posted: Thu Dec 09, 2021 5:58 pm
by Octocontrabass
Yep, pretty much. The exact use differs slightly between CHS/LBA28/LBA48, but most commands fit into one of those three categories and you'll probably never use CHS. There are a handful of commands that use those registers for different purposes, but those are explained fairly well in the various ATA and ACS specifications.

(Oh, and the wiki doesn't explain the feature register because most commands don't use it. It was originally meant for write precompensation, which all modern drives handle automatically.)

Re: AHCI data structures

Posted: Fri Dec 10, 2021 12:24 am
by Bonfra
Awesome! Thanks a lot for the help:)