README

Library dtree
=============

The library can be used to read information about devices that is
located in _device tree_ structure. In Linux this is usually placed
at `/proc/device-tree`. Device tree is available in embedded devices.


Tutorial
--------

The public API of the library is located in `dtree.h`. It contains a lot of
documentation that should be up to date. The API consists of several functions
to access the tree. Currently there is only one implementation of that API:
`dtree_procfs.c` that is used to parse the directory structure of `/proc/device-tree`.

The core of the library is structure `dtree_dev_t`. It contains the information
about the device. Currently it offers these properties:

* `name` - name of the device
* `base` - base address of the device
* `high` - highest address of the device (not mandatory, can be set to be <= `base`, if not available)
* `compat` - array of compatible device types (finished with NULL)

The library is not reentrant and thus not thread safe. If it is successfully
initialized by call dtree_open() it has to be closed by dtree_close() before
program exit to free resources (even on die call...).


### Look up a device

	int err = dtree_open("/proc/device-tree");
	die_on_error(err);

	struct dtree_dev_t *eth = dtree_byname("ethernet");
	if(eth == 0)
		die_no_ethernet();

	process_eth(eth);
	dtree_dev_free(eth);

	dtree_close();

Note call to `dtree_dev_free()` after the device information
is not used anymore.


### List available devices

	int err = dtree_open("/proc/device-tree");
	die_on_error(err);

	struct dtree_dev_t *dev = NULL;
	while((dev = dtree_next()) != NULL) {
		process_dev(dev);
		dtree_dev_free(dev);
	}

	dtree_close();

### Search again with reset

	// declarations, open dtree...
	
	eth = dtree_byname("ethernet");
	dtree_reset();
	serial = dtree_byname("serial");

	process(eth, serial);
	dtree_dev_free(eth);
	dtree_dev_free(serial);

	// go on and finally close dtree...


### Error handling

	// declarations...

	if(dtree_open(DT_PATH) != 0) {
		die(dtree_errstr());
	}

	eth = dtree_byname("ethernet");
	if(eth == NULL) {
		if(dtree_iserror())
			die(dtree_errstr());
		else
			die("Ethernet device is not present in the system");
	}

	dtree_close();


Testing
-------

Testing of the library is done in `test/` directory. There are few simple tests based
on fake `device-tree` directory structure.