Project

General

Profile

Actions

Bug #13142

open

comment for BITX() is misleading

Added by Patrick Mooney almost 2 years ago.

Status:
New
Priority:
Normal
Category:
kernel
Start date:
Due date:
% Done:

0%

Estimated time:
Difficulty:
Bite-size
Tags:
docs
Gerrit CR:

Description

I was reaching for the BITX() macro to simplify some bit manipulation, and went to read its describing comment to understand its usage semantics:

/*
 * Extracts bits between index h (high, inclusive) and l (low, exclusive) from
 * u, which must be an unsigned integer.
 */
#define BITX(u, h, l)   (((u) >> (l)) & ((1LU << ((h) - (l) + 1LU)) - 1LU))

Looking at how this operates, the description of the low bit being exclusive is completely wrong. It is, in fact, inclusive.
We can prove this out with some simple examples:

        uint32_t in;

        in = 0xff;
        printf("%x %x\n", in, BITX(in, 7, 0));
        printf("%x %x\n", in, BITX(in, 8, 1));
        in = in << 1;
        printf("%x %x\n", in, BITX(in, 7, 0));
        printf("%x %x\n", in, BITX(in, 8, 1));

Resulting in:
ff ff
ff 7f
1fe fe
1fe ff

Overall the behavior (but not the comment) makes sense. The Intel manuals use notation like 7:0 to describe the lowest byte in a field, and BITX(field, 7, 0) would yield the desired result. The comment for it should be updated so future readers are not confused about its operation.

No data to display

Actions

Also available in: Atom PDF