# Library hwio v0.4

The library comes with few improvements. The API should be the same as in v0.3 (with
some minor semantic changes). Apps that compile with v0.3 should compile even with v0.4.


## Overview of changes

* fixed the mess in headers, now what is in hwio.h represents really just the Public API
* specific hwio backends were moved to separate directories and their code has been
  divided into more modules
* improved documentation (using Doxygen now)
* added unit tests of some general features
* checking of base and range (addressing) is now optional for each implementation
* fixed bug in hwio_byname/byspec when one item is printed many times (duplicated)
* added hwio_tool interface to simplify writing of CLI apps on top of hwio
* added example CLI application xctl based on hwio_tool interface
* changed semantics of hwio_init, now it doesn't accept NULL for phys and src
* done some general clean up of the code
* some minor (and mostly internal) fixes


## Known issues in rc1 (will be fixed in rc2)

* distclean doesn't remove libhwio_tool.a (silly mistake)
* goals clean and distclean are not propagated to xctl
* xctl_comp_enable compares strings using '=='
* missing test of xctl -E<0|1>


## Building

  hwio/ $ make $IMPL
  hwio/ $ ls hwio-$IMPL
  ...
  libhwio_$IMPL.a
  ...

The $IMPL variable is one of 
* debug  intended for debugging
* linux  based on dtree and mmap (probably works on POSIX systems with device-tree available)
* cv2    intended to run on top of libcombo library

The result is placed in the directory of the selected implementation as a library of name
libhwio_$IMPL.a.


## The hwio_tool interface

When building your tool you need either the header hwio_tool.h and the compiled
library libhwio_tool.a itself. So provide -I$HWIO_PATH to your compiler and
-L$HWIO_PATH -lhwio_tool to your linker. See xctl/Makefile for an example.

To build the libhwio_tool.a execute:

  hwio/ $ make tool


## Trying xctl

This version contains a testing xctl tool implementation. It shows how to use the
new hwio_tool interface and shows the recommended style for the tools.

Build & run this way (ignore warnings for now):

  hwio/ $ make tool
  hwio/ $ make debug
  hwio/ $ make -C xctl run-xctl


## Unit tests

The tests are not complete, but they are usable now. Some tests require
other external libraries (hwio-linux depends on dtree library) that must be
compiled and installed properly.

Working example (requires to obtain the dtree v0.9).

  hwio/ $ export DTREE=<path-to-dtree-v0.9-dir>
  hwio/ $ make tests DTREE_PATH=$DTREE DEVICE_TREE=$DTREE/test/device-tree > /dev/null
    Started test_version_match
    Finished test_version_match
    Started test_comp_spec_match
    Finished test_comp_spec_match
    Started test_comp_name_and_spec_match
    Finished test_comp_name_and_spec_match
    Started test_byname
    Finished test_byname
    Started hwio_init
    Finished hwio_init
    Started test_treat_it_as_type
    Finished test_treat_it_as_type
    Started test_use_vendor_and_type
    Finished test_use_vendor_and_type
    Started test_use_type_and_version
    Finished test_use_type_and_version
    Started test_use_vendor_type_version
    Finished test_use_vendor_type_version
    Started test_parse_version
    Finished test_parse_version
    Started hwio_init
    Finished hwio_init
    Started hwio_byspec
    Finished hwio_byspec
  16+0 records in
  16+0 records out
  16 bytes (16 B) copied, 6.4426e-05 s, 248 kB/s
    Started hwio_init
    Finished hwio_init
    Started map_space_if_needed
    Finished map_space_if_needed
    Started hwio_comp_read from 0
    Finished hwio_comp_read from 0
    Started hwio_comp_write to 0
    Finished hwio_comp_write to 0
    Started hwio_comp_read from 0
    Finished hwio_comp_read from 0


### Failed test

Failed test is recognized easily by watching the output. Example of a failed test follows.

  hwio/ $ make tests > /dev/null
    Started test_version_match
    Finished test_version_match
    Started test_comp_spec_match
    Finished test_comp_spec_match
    Started test_comp_name_and_spec_match
    Finished test_comp_name_and_spec_match
    Started test_byname
  ! Assertion failed at test_byname (hwio.c.417): Component not found
  ! Assertion failed at test_byname (hwio.c.417): Component not found
    Finished test_byname


### When DEVICE_TREE is not set properly

  hwio/ $ make tests DTREE_PATH=$DTREE > /dev/null
    Started hwio_byspec
    hwio_byspec: No such file or directory
  ! Failure at main (-1): Failed to hwio_byspec
    make[2]: *** [run-hwio_linux_query] Error 2


### When DTREE_PATH is not set properly

  hwio/ $ make tests > /dev/null
  /usr/lib/gcc/x86_64-unknown-linux-gnu/4.7.1/../../../../lib/crt1.o: In function `_start':
  (.text+0x20): undefined reference to `main'
  collect2: error: ld returned 1 exit status
  make[2]: *** [hwio_linux_dev] Error 1
  hwio_linux_query.c:49:19: fatal error: dtree.h: No such file or directory
  compilation terminated.
  make[2]: *** [hwio_linux_query.o] Error 1
  hwio_linux_query.c:49:19: fatal error: dtree.h: No such file or directory
  compilation terminated.
  make[2]: *** [hwio_linux_query.o] Error 1


### Using newer dtree

The newer version of dtree may be complied as a shared library. Then it is necessary to set
the LD_LIBRARY_PATH to point the directory with libdtree.so or copy that library to a place
where the tests can loaded it.
