Generic bitfield packing and unpacking functions

Hardware bitfield 표현의 문제

Generic bitfield packing and unpacking functions

문제 정의 (Problem statement)

Hardware와 작업할 때는 여러 interface 방식 중 하나를 선택해야 합니다. 정교하게 만든 struct pointer를 hardware device의 memory region에 map하고, bitfield로 선언할 수도 있는 member를 통해 field에 접근할 수 있습니다. 하지만 CPU와 hardware device의 endianness가 다를 수 있어 portability가 떨어집니다.

Hardware 문서의 register definition을 struct bitfield index로 옮길 때도 세심한 주의가 필요합니다. 특히 networking 장비 같은 hardware는 합리적인 word boundary, 때로는 64-bit boundary까지 위반하는 방식으로 register field를 묶습니다. 그러면 struct 안에서 register field의 high와 low 부분을 따로 정의해야 하는 불편이 생깁니다.

Struct field 대신 필요한 bit 수만큼 shift하여 field를 추출하는 방식이 더 견고할 수 있습니다. 그러나 모든 memory access를 byte 단위로 수행하지 않는 한 endianness mismatch를 막지는 못합니다. 많은 bit shift 때문에 code가 복잡해지고 high-level 의도가 묻히기도 쉽습니다.

많은 driver가 bit-shift 방식을 사용한 뒤 custom macro로 복잡함을 줄이려 하지만, 이 macro도 대개 shortcut을 택해 code가 완전히 portable해지는 것을 막습니다.

Packing API가 제공하는 추상화

해결책 (The solution)

이 API는 두 가지 기본 operation을 다룹니다.

• CPU가 사용할 수 있는 숫자를 hardware constraint와 quirk를 적용하여 memory buffer에 packing합니다.
• Hardware constraint와 quirk가 적용된 memory buffer를 CPU가 사용할 수 있는 숫자로 unpacking합니다.

API는 hardware constraint와 quirk, CPU endianness, 그리고 둘 사이에서 생길 수 있는 mismatch를 추상화합니다.

이 API function의 기본 단위는 `u64`입니다. CPU 관점에서 bit 63은 논리적으로 항상 byte 7의 bit offset 7을 뜻합니다. 핵심 질문은 이 bit를 memory의 어느 위치에 놓는가입니다.

다음 예제는 packed `u64` field의 memory layout을 설명합니다. Packed buffer의 byte offset은 항상 암묵적으로 0, 1부터 7까지이며, 그림은 logical byte와 bit가 놓이는 위치를 보여 줍니다.

Quirk가 없는 기본 layout

1. Quirk가 없을 때의 일반적인 layout입니다.

CPU가 사용하는 `u64`의 MSByte인 7은 memory offset 0에 있고 LSByte인 0은 memory offset 7에 있습니다. 이는 bit `i`가 숫자 `2^i`에 대응하는 일반적인 big-endian 형태이며 code comment에서는 logical notation이라고도 부릅니다.

QUIRK_MSB_ON_THE_RIGHT layout

2. `QUIRK_MSB_ON_THE_RIGHT`를 설정한 layout입니다.

`QUIRK_MSB_ON_THE_RIGHT`는 byte 위치에는 영향을 주지 않고 byte 내부의 bit offset을 반전합니다.

QUIRK_LITTLE_ENDIAN layout

3. `QUIRK_LITTLE_ENDIAN`을 설정한 layout입니다.

`QUIRK_LITTLE_ENDIAN`은 memory region의 각 4-byte word 안에서 모든 byte를 word boundary에 대해 mirror된 위치에 배치합니다.

MSB-right와 little-endian 조합

4. `QUIRK_MSB_ON_THE_RIGHT`와 `QUIRK_LITTLE_ENDIAN`을 모두 설정한 layout입니다.

QUIRK_LSW32_IS_FIRST layout

5. `QUIRK_LSW32_IS_FIRST`만 설정한 layout입니다.

8-byte memory region의 첫 4 byte는 least-significant 4-byte word에 대응하고 다음 4 byte는 more-significant 4-byte word에 대응합니다.

LSW-first와 MSB-right 조합

6. `QUIRK_LSW32_IS_FIRST`와 `QUIRK_MSB_ON_THE_RIGHT`를 설정한 layout입니다.

LSW-first와 little-endian 조합

7. `QUIRK_LSW32_IS_FIRST`와 `QUIRK_LITTLE_ENDIAN`을 설정한 layout입니다.

세 quirk를 모두 적용한 layout

8. `QUIRK_LSW32_IS_FIRST`, `QUIRK_LITTLE_ENDIAN`, `QUIRK_MSB_ON_THE_RIGHT`를 모두 설정한 layout입니다.

Offset은 항상 quirk가 없는 것처럼 생각하고, memory region에 접근하기 직전에 quirk에 맞춰 변환합니다.

4의 배수가 아닌 buffer 길이

4의 배수가 아닌 buffer 길이에 관한 참고 사항

4-byte group끼리는 little-endian으로, group 내부는 big-endian으로 배치되는 memory layout quirk를 처리하기 위해 4-byte group 개념은 packing API에 내재합니다. 실제 memory access는 byte 단위라는 점과 혼동하면 안 됩니다.

Buffer 길이가 4의 배수가 아니면 한 group이 불완전합니다. Quirk 조합에 따라 buffer를 통해 접근할 수 있는 bitfield가 불연속적일 수 있습니다. Packing API는 이런 불연속이 의도된 layout이 아니라고 보고, most-significant 4-octet group을 실제 사용 가능한 octet 수만큼 논리적으로 줄여 불연속을 피합니다.

다음은 31-byte buffer 예제입니다. Physical buffer offset은 암묵적으로 group 안에서 왼쪽에서 오른쪽으로, column 안에서 위에서 아래로 증가합니다.

Quirk가 없는 경우입니다.

`QUIRK_LSW32_IS_FIRST`를 적용한 경우입니다.

`QUIRK_LITTLE_ENDIAN`을 적용한 경우입니다.

`QUIRK_LITTLE_ENDIAN | QUIRK_LSW32_IS_FIRST`를 적용한 경우입니다.

Deprecated packing() 사용 pattern

의도된 사용법 (Intended use)

이 API를 선택한 driver는 먼저 hardware 문서의 layout과 일치하는 세 quirk 조합, 총 여덟 경우 중 하나를 식별해야 합니다. 지원하는 사용 pattern은 세 가지이며 아래에서 설명합니다.

packing()

이 API function은 deprecated 상태입니다.

`packing()`은 잘못된 API 사용으로부터 programmer를 보호하는 int encoded error code를 반환합니다. Runtime에는 error가 발생하지 않을 것으로 기대하므로 `packing()`을 custom void function으로 감싸 error를 무시할 수 있습니다. 선택적으로 stack을 dump하거나 error 설명을 출력할 수 있습니다.

void my_packing(void *buf, u64 *val, int startbit, int endbit,
                size_t len, enum packing_op op)
{
        int err;

        /* Adjust quirks accordingly */
        err = packing(buf, val, startbit, endbit, len, op, QUIRK_LSW32_IS_FIRST);
        if (likely(!err))
                return;

        if (err == -EINVAL) {
                pr_err("Start bit (%d) expected to be larger than end (%d)\n",
                       startbit, endbit);
        } else if (err == -ERANGE) {
                if ((startbit - endbit + 1) > 64)
                        pr_err("Field %d-%d too large for 64 bits!\n",
                               startbit, endbit);
                else
                        pr_err("Cannot store %llx inside bits %d-%d (would truncate)\n",
                               *val, startbit, endbit);
        }
        dump_stack();
}

Const-correct pack()과 unpack()

pack() and unpack()

이들은 `packing()`의 const-correct variant이며 마지막 `enum packing_op op` argument를 제거합니다.

`pack(...)` 호출은 `packing(..., PACK)`과 같고 더 권장됩니다. `unpack(...)` 호출은 `packing(..., UNPACK)`과 같고 더 권장됩니다.

pack_fields()와 unpack_fields()

pack_fields() and unpack_fields()

Library는 buffer에 많은 field가 있는 상황을 위한 optimized function을 제공합니다. Consumer driver가 field마다 `pack()`과 `unpack()`을 반복 호출하지 말고 code footprint를 줄이는 `pack_fields()`와 `unpack_fields()`를 사용하도록 권장합니다.

이 API는 `struct packed_field_u8` 또는 `struct packed_field_u16` array의 field definition을 사용하므로 consumer driver는 요구 사항에 맞춰 array 크기를 최소화할 수 있습니다.

`pack_fields()`와 `unpack_fields()`는 실제로 macro이며 전달된 fields array의 type을 기준으로 compile time에 적절한 function을 자동 선택합니다.

`pack()`과 `unpack()`보다 나은 또 다른 점은 field definition sanity check가 문제가 되는 code를 실행할 때가 아니라 compile time에 `BUILD_BUG_ON`으로 처리된다는 것입니다. 이 function은 void를 반환하므로 예상치 못한 error를 처리하기 위해 감쌀 필요가 없습니다.

필수는 아니지만 packed buffer를 고정 크기의 structured type으로 감싸는 것이 권장됩니다. 그러면 compiler가 올바른 크기의 buffer 사용을 강제하기 쉽습니다.

다음은 fields API 사용 예제입니다.

/* Ordering inside the unpacked structure is flexible and can be different
 * from the packed buffer. Here, it is optimized to reduce padding.
 */
struct data {
     u64 field3;
     u32 field4;
     u16 field1;
     u8 field2;
};

#define SIZE 13

typedef struct __packed { u8 buf[SIZE]; } packed_buf_t;

static const struct packed_field_u8 fields[] = {
        PACKED_FIELD(100, 90, struct data, field1),
        PACKED_FIELD(90, 87, struct data, field2),
        PACKED_FIELD(86, 30, struct data, field3),
        PACKED_FIELD(29, 0, struct data, field4),
};

void unpack_your_data(const packed_buf_t *buf, struct data *unpacked)
{
        BUILD_BUG_ON(sizeof(*buf) != SIZE;

        unpack_fields(buf, sizeof(*buf), unpacked, fields,
                      QUIRK_LITTLE_ENDIAN);
}

void pack_your_data(const struct data *unpacked, packed_buf_t *buf)
{
        BUILD_BUG_ON(sizeof(*buf) != SIZE;

        pack_fields(buf, sizeof(*buf), unpacked, fields,
                    QUIRK_LITTLE_ENDIAN);
}

Unpacked `struct data`의 member 순서는 packed buffer와 달라도 되며 예제는 padding을 줄이도록 정렬합니다. `packed_buf_t`는 13-byte fixed-size buffer이고 `PACKED_FIELD` array는 logical bit range와 destination member를 연결합니다.

`unpack_your_data()`와 `pack_your_data()`는 `BUILD_BUG_ON`으로 buffer size를 확인하고 `QUIRK_LITTLE_ENDIAN`을 적용해 모든 field를 한 번에 변환합니다.