Update the developer docs

[josefbacik]

There's some random things that need to be done in this area, writing them down to keep track of them.

• Chris Murphy wants some better disambiguation between chunks, block groups, and stripes.

[cmurf]

josef | that glossary is wrong, there's not a 64kib stripe size

cmurf | "allocated" is a term used in btrfs fi us that is a reference to block groups
cmurf | so maybe allocation is a suitable blury term that could be used for all: block group, chunks, stripes

If that's a bad idea, lemme know.

'Profile' is missing from the glossary. A block group profile determines the kind, number, and location of chunks used to make up that block group. (?)

My eventual goal is using the least amount of jargon and explanation, that is neither perfectly correct nor grossly misleading, so that users can understand btrfs fi us output.

[lorddoskias]

Are you talking about btrfs-dev-docs/chunks.txt. Because in it I believe chunks are well explained and in the "Translating physical to logical addresses" section there is text which treats stripes as this term is indeed overloaded on btrfs, namely :

Btrfs actually uses the word "stripe" for 2 different types of stripe. The first
   is the already introduced physical stripe. The second type stripe is the logical
  stripe. Logical stripe is the granularity at which writes are mapped in btrfs,  
   that's generally io_width which is currently hard-coded at 64k. To calculate    
   the logical stripe the block_group_offset is divided by logical stripe size :   

[lorddoskias]

Ping @cmurf on this, as I'd really like to see some progress on this. I.e does the excerpt I pasted make sense ?

[cmurf]

Are you talking about btrfs-dev-docs/chunks.txt.

I suggest an explicit connection between 'logical space' and block groups, and 'physical space' and chunks.

Is it correct that "chunk" is generic and "chunk stripe" e.g. a 1GiB data block group with raid1 profile has a physical representation of two 1GiB chunk stripes which are mirrors of each other, each on two different devices? That seems consistent with the dump-tree terminology of 'num_stripes' with 'stripe 0' and 'stripe 1'.

Logical stripe is the granularity at which writes are mapped in btrfs, that's generally io_width which is currently hard-coded at 64k.

Should this be 'logical stripe size'? I could see someone get confused between the superblock dev_item.io_width 4096 and stripesize 4096 whereas the chunk tree has io_width 65536.

To calculate the logical stripe the block_group_offset is divided by logical stripe size.

The previous sentence equates 'logical stripe' to 'io_width'. But here the definition makes it a value that varies as every bg offset has a different value.

[lorddoskias]

Is it correct that "chunk" is generic and "chunk stripe" e.g. a 1GiB data block group with raid1 profile has a physical representation of two 1GiB chunk stripes which are mirrors of each other, each on two different devices? That seems consistent with the dump-tree terminology of 'num_stripes' with 'stripe 0' and 'stripe 1'.

Yep, though if I have to be really nitpicky, a 'stripe' in the context of chunk stripe is really a device stripe/device extent since each chunk stripe is represented by the respective DEV_EXTENT in the device tree. And this is what "physical stripe" in the docs refer to.

Logical stripe is the granularity at which writes are mapped in btrfs, that's generally io_width which is currently hard-coded at 64k.

Should this be 'logical stripe size'? I could see someone get confused between the superblock dev_item.io_width 4096 and stripesize 4096 whereas the chunk tree has io_width 65536.

So the stripesize in the superblock I believe is an old artifact as both mkfs and the kernel set it to sectorsize. So it seems that it can just be removed. @josefbacik care to comment about that? Both io_width and io_align are also artifacts of the past which are currently not used but this doesn't mean they can't be repurposed per se. What's the important is really the chunk's tree io_width since it comes from the kernel constant: BTRFS_STRIPE_LEN which is the logical stripe len which is only shown in the chunk tree as you observed. This is referred to as the logical stripe in the documentation.

To calculate the logical stripe the block_group_offset is divided by logical stripe size.

The previous sentence equates 'logical stripe' to 'io_width'. But here the definition makes it a value that varies as every bg offset has a different value.

I just re-read the paragraph and you are right that having io_width/io_align for both the dev_item in the super-block and the chunk tree makes this somewhat confusing. Though looking at the documentation the superblock is never mentioned so at the time of writing it I have definitely been thinking about io_width of the chunk item in the chunk tree. That sentence should have been the logical stripe index.

In the end I think the paragraph should really be rewritten to the following:

Btrfs actually uses the word "stripe" to refer to 2 different things. The first
is the already introduced physical stripe which is represented by a DEV_ITEM in the device tree. 
The second is the logical stripe size. This is the granularity at which writes are mapped in btrfs, 
currently that's hardcoded to 64k and is shown as the value of "io_width" of a CHUNK_ITEM in the chunk tree. 
It can be use to calculate the logical stripe index inside the block group by dividing the 
block_group_offset by logical stripe size : 

[lorddoskias]

Also @kdave how would you feel about removing the io_width/io_align of the dev item when issuing btrfs inspect-internal dump-super as those values currently mean nothing and as Chris mentioned earlier they can be somewhat confusing.