The Layout Utility

--MUTS provides a utility that allows you to take a collection of bit fields (specifying size and alignment in bits), and lay them out efficiently in some buffer. This is useful for building message headers, but also for dynamically adding fields to structures, fields that are not known in advance. In particular, this is useful for event structures.

SOURCES

include/muts/layout.h
src/muts/layout.c

INCLUDE

#include "muts.h"

INTERFACE

void bit_copy(
	uint8_t *src, int src_offset,
	uint8_t *dst, int dst_offset,
	int nbits
);

typedef struct lo_field {
	char *name;			/* ASCII name of field */
	unsigned int size;		/* in bits */
	unsigned int alignment;		/* in bits */
	char *format;			/* format for printf() */
	unsigned int offset;		/* in bits */
	unsigned int byte_offset;	/* in bytes */
	unsigned int bit_offset;	/* from byte_offset */
	...
} lo_field_t, *lo_field_id;

uint32_t lo_get_val(
	lo_descr_id lod,
	void *buf,
	lo_field_id lof
);

error_t lo_create(
	struct mem_chan *mc,
	lo_descr_id *lodp
);

void lo_add_field(
	lo_descr_id lod,
	lo_field_id lof
);

void lo_new_field(
	lo_descr_id lod,
	lo_field_id lof,
	char *name,
	unsigned int size,
	unsigned int alignment,
	char *format
);

error_t lo_layout(
	lo_descr_id lod,
	int offset,
	int alignment
);

The offset is added to every offset calculated (allowing for a buffer to start off not at the beginning of a structure), and the size of the whole layout is rounded up to the given alignment. Both are given in bits.

Note that this routine only needs to be called by users who don't want to do their own lay out of the fields. The rest of this package works perfectly well without calling lo_layout().

error_t lo_get_field(
	lo_descr_id lod,
	char *name,
	lo_field_id result
);

error_t lo_print(
	lo_descr_id lod,
	void *buf,
	unsigned int options,
	char *indent
);

int lo_size(lo_descr_id lod)

error_t lo_free(lo_descr_id lod);

error_t lo_init(void);

TYPE *LO_ADDR(
	lo_descr_id lod,
	void *buf,
	TYPE type,
	lo_field_id lof
);

TYPE LO_VAR(
	lo_descr_id lod,
	void *buf,
	TYPE type,
	lo_field_id lof
);

int LO_GET_BIT(
	lo_descr_id lod,
	void *buf,
	lo_field_id lof
);

void LO_SET_BIT(
	lo_descr_id lod,
	void *buf,
	lo_field_id lof
);

void LO_CLR_BIT(
	lo_descr_id lod,
	void *buf,
	lo_field_id lof
);

void LO_BIT_SET_VALUE(
	lo_descr_id lod,
	void *buf,
	lo_field_id lof,
	int value
);

void LO_GET_FIELD(
	lo_descr_id lod,
	lo_field_id lof,
	void *in,
	void *out
);

void LO_SET_FIELD(
	lo_descr_id lod,
	lo_field_id lof,
	void *out,
	void *in
);

void LO_COPY_FIELD(
	lo_descr_id lod1,
	void *buf1,
	lo_field_id lof1,
	lo_descr_id lod2,
	void *buf2,
	lo_field_id lof2
);

uint32_t LO_GET_VAL(
	lo_descr_id lod,
	void *buf,
	lo_field_id lof
);

void LO_SET_VAL(
	lo_descr_id lod,
	void *buf,
	lo_field_id lof,
	uint32_t val
);

EXAMPLE

lo_field_t field1 = { "a", 0, 0 };
lo_field_t field2 = { "b", 0, 0 };
lo_field_t field3 = { "c", 0, 0 };

int main(void){
	lo_descr_id lod;
	static uint8_t buf[8];
	int i, val1, val2, val3, width;

	for (width = 1; width < 22; width++) {
		lo_create(0, &lod);

		field1.size = width;
		field1.alignment = width;
		lo_add_field(lod, &field1);
		field2.size = width;
		field2.alignment = width;
		lo_add_field(lod, &field2);
		field3.size = width;
		field3.alignment = width;
		lo_add_field(lod, &field3);

		lo_layout(lod, 0, 32);

		for (i = 0; i < 100; i++) {
			val1 = random() % (1 << width);
			val2 = random() % (1 << width);
			val3 = random() % (1 << width);
			LO_SET_VAL(lod, buf, &field1, val1);
			LO_SET_VAL(lod, buf, &field2, val2);
			LO_SET_VAL(lod, buf, &field3, val3);
			if (LO_GET_VAL(lod, buf, &field1) != val1)
				sys_panic("val1");
			if (LO_GET_VAL(lod, buf, &field2) != val2)
				sys_panic("val2");
			if (LO_GET_VAL(lod, buf, &field3) != val3)
				sys_panic("val3");
		}
	}

	return 0;
}

FUTURE WORK

At this point we're not convinced yet what to do when two fields of the same name are added. Four possibilities: 1) return an error. 2) overwrite. 3) add both separately. 4) ignore if they are the same. For now I just add the field to the list.