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:
C API
-----
- 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+)
- Automatic board probing via installed config files
Python Bindings
---------------
- Manual GPIO Manipulation through sysfs (Value, Edge, Direction, Exporting)
- Blocking GPIO Interrupts with timeout
- Non-blocking GPIO Interrupts with callback mechanism
- I2C transfers
Please see the roadmap folder and Github issue tracker for future ideas
and feature requests.
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
further 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] [--enable-python=<version>]
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. Omitting this flag will leave
debug enabled.
--enable-python=VER : enable specified python language bindings to
libsoc API.
--enable-board=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
- python[2|3]-dev (optional for python bindings)
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.
Python bindings are in bindings/python and are commented in a similar
manner. There is also test code in the test/ directory which gives
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.