What is libsoc?
------------------------------------------------------------------------

libsoc is a C library to interface with common peripherals found in
System on Chips through generic Linux Kernel interfaces.

It is aimed at new Linux users, and intends to be a stepping stone to
enable a user to get started quickly. It is optimised for reliability
rather than speed. While the library should be fast, no guarantees are
made on it's determinism and it should not be used in time critical
routines.

Why libsoc?
------------------------------------------------------------------------

libsoc was born due to the influx of new embedded Linux boards becoming
available cheap, and to hobbyists. There are currently numerous
libraries that do interfacing with common SoC peripherals, but they all
tend to be centred around a particular board or SoC. This leads to board
specific hacks and in some cases direct bypassing of the Linux Kernel.

libsoc aims to be generic and compatible with any SoC that has drivers
exposing the correct interfaces for the defined peripheral.

What peripherals does it support?
------------------------------------------------------------------------

Current Support:

- Manual GPIO Manipulation through sysfs (Value, Edge, Direction, Exporting)
- Blocking GPIO Interrupts with timeout
- Non-blocking GPIO Interrupts with callback mechanism (pthread based)
- SPI transfers using spidev
- I2C transfers using ioctls
- PWM support through sysfs (Linux 3.12+)

Future ideas are:

- A/D Converters
- UART

Please see the roadmap folder for more information

Does libsoc support the SoC on my board?
------------------------------------------------------------------------

The real question here is, do your SoC drivers use the generic Linux
Kernel interfaces to expose functionality to userspace. If the answer is
yes, then libsoc supports your board!

How is libsoc licenced?
------------------------------------------------------------------------

libsoc is licenced under the LGPLv2.1, please see the COPYING file for
futher details.

How do I build libsoc?
------------------------------------------------------------------------

libsoc uses the autotools build system. A script called autogen.sh is
included to setup the build. Exact steps:

1) ./autogen.sh
2) ./configure [--disable-debug] [--enable-board=<board>]
               [--with-board-configs]
3) make

--disable-debug      : disables the debug code, turn off the debug to
                       get the fastest operation but at the cost of any
                       debug print outs. Ommiting this flag will leave
                       debug enabled.
--enable-python2     : enable python2 language bindings to libsoc API.
--enable-python3     : enable python3 language bindings to libsoc API.
--enable-board       : install board specific GPIO pin mappings file.
                       This enables the use of the libsoc_board_gpio_id
                       function to look up GPIO ID's based on how the
                       pin is named for a supported board. Supported
                       board can be found under ./contrib/board_files.
                       If --with-board-configs is also used, a symlink
                       will be created.
--with-board-configs : install all the contributed board configuration
                       files to $PREFIX/share/libsoc.

Dependencies
------------------------------------------------------------------------

- pthreads
- libgcc

How do I use libsoc?
------------------------------------------------------------------------

The libsoc public functions are documented in the include files in the
lib/include directory. There are also test programs in the test/
directory which give examples of use.

Can I help?
------------------------------------------------------------------------

libsoc is Open Source Software and as such you are welcome to browse the
code and either add features, or fix bugs. Please submit pull requests,
and bugs to http://www.github.com/jackmitch/libsoc. If you have any
comments or questions, I can be contacted by email at the address
jack_at_embed_dot_me_dot_uk.