LibK is a lightweight firmware development library that is designed for flash based, resource constrained microcontrollers that are not able to run a full modern operating system. LibK uses protothread-based, cooperative multitasking to make all I/O operatins non-blocking and to make the most of the already constrained CPU by never wasting any clock cycles waiting for an I/O operation to complete.

Included in LibK you will find many device drivers that make it possible to use the supported devices in your project directly without having to implement the device drivers yourself. The device drivers have also been rewritten by me to use cooperative multitasking so that no device can ever slow down your application just because it is slow.

Using LibK you can build portable applications for AVR-8, STM32 and PC.

LibK build system is originally designed for building on Ubuntu linux so it may require modifications if you want to build on a different system. The build process uses Makefiles that it includes from all of the subfolders. Each subfolder has it's own Makefile, KConfig file and a README.md (docs) file. All of these files are aggregated by make and then compiled into their respective targets.

To compile LibK you will also need appropriate gcc toolchain for your hardware target.

• avr-gcc and avr-libc for compiling for atmega, arduino, avr32
• arm-none-eabi-gcc for compiling for sam3, stm32 and other arm architectures
• pandoc for compiling this PDF from all readme files (although you should have this PDF included)
• clang (scan-build) for enabling static analysis of the code during the build
• lib-curses for compiling menuconfig (for editing libk configurations)
• avrdude for flashing avr chips

On Ubuntu:

sudo apt-get install gcc-avr gcc-arm-none-eabi avr-libc pandoc libncurses5-dev avrdude

Build everything:

make buildall

This will build all supported architectures, produce corresponding libraries and compile examples as well.

The above will in fact invoke build commands for each target. For building a specific target library use BUILD variable that you pass to MAKE like this:

make BUILD=arm-stm32f103

The parameter to this command should be the same string as the config file name of the corresponding config in the "configs" folder. The build script will then include appropriate source files relevant only for that target and compile them into a corresponding static library.

Note: Depending on how your target flashing process works, these instructions may not apply to you. In that case, find out how to actually burn a binary file on your architecture from the documentation of your target device.

All libk programs compile to binary elf files that are then converted to either a binary blob or a hex file using appropriate objdump utility for the target platform. This resulting hex or bin file can then be directly passed to the flashing software and transferred to the target chip. Usually this transfer is done over a usb to serial converter.

• Avr platform uses tool avrdude and expects avr to be connected to usbasp programmer. For flashing using a different programmer you will need to modify the makefiles (in examples folders).
• STM32 uses builtin ST bootloader and the stm32flash utility. You will need to explicitly boot the chip into the bootloader mode by holding boot0 low at poweron. Some firmwares also support booting into the bootloader from software (check the fst6-demo example for this can be done. It implements a firmware upgrade command).

When building your own software, you will usually link libk into your project and then flash using your standard flashing process. For the examples provided inside libk, there are however makefile targets specified for flashing each of the examples. All examples are built using "make BUILD=(target) build-(example name)" pattern and installed using the corresponding "make BUILD=(target) build-(example name)" pattern.

make BUILD=arm-stm32f100mdvl build-fst6-demo
make BUILD=arm-stm32f100mdvl install-fst6-demo

Note: if you get a "permission denied" when trying to access your serial port as normal user in linux, then make sure to add yourself to the "dialout" group.

This project consists of many different parts and code from other people, distributed under their own licenses - some parts are GPL, some are MIT.

The project as a whole however is distributed under GPL version 3.

Device drivers in libk operate on a higher level than architecture code. So they are largely architecture agnostic. Device drivers typically use interfaces to access services provided by the architecture and they can also export interfaces to other drivers in order to eliminate dependencies between drivers on each other.

Drivers are tested on avr. Other architectures may not have full drivers support until there is stable architecture abstraction layer written for that architecture.

(devices marked as quarantine are drivers that have not been updated yet after changes to the core api. Code has been included in the source tree but it has not yet been updated to work nicely with other facilities of libk)

• To maintain small memory footprint and use minimal amount of ram
• To take advantage of as much of the (limited) CPU power as possible
• To maintain high portability across all of the supported platforms
• To minimize the amount of code inside the application that needs to be changed to support a new platform.

How the design goals are currently implemented:

• LibK places as much constant data as possible into flash and thus frees up a lot of ram for use in the application
• LibK uses cooperative multitasking inside the kernel and all drivers are written to never block the cpu while waiting for an external event or I/O.
• LibK uses asynchronous I/O at all times, meaning that no read or write operation is ever blocking. This allows for other tasks to happen while a task is waiting for io.
• LibK uses protothreads instead of conventional threads - this means that threads never have any stack and all threads execute inside the same stack space of the main application. It also have many other advantages that are discussed further in this document.

LibK is a lightweight kernel that implements cooperative multitasking using stackless threads. Stackless threads have been chosen because they are the most lightweight kind of threads available and they have very small overhead. There are however both advantages and also some disadvantages to using stackless protothreads.

Advantages of stackless protothreads:

• Allow device drivers to be written such that no CPU cycles are ever wasted waiting for I/O. The device driver can simply return control to the application and wait until the next time it has the chance to run.
• Writing asynchronous tasks becomes a lot easier because they can be written linearly instead of being organized as a complicated state machine.
• No thread is ever interrupted while it is in the middle of some operation. Threads always run to completion. Meaning that we can design our code without having to think about byte level synchronization (device level syncrhonization is required though).
• No stack also means that we never run out of stack space inside a thread.
• Context switching is very fast - current thread method saves it's resume point, returns to libk scheduler, libk scheduler loads the address of the next thread function to run, and calls it.
• Not a problem to have tens of threads for each asynchronous action. Since threads are just normal methods minus the stack, we can have many threads without experiencing significant slowdown.
• Synchronization is much easier because all code that you "see" is atomic until it explicitly releases control to the scheduler. We thus do not have to worry about non atomic memory access.

Disadvantages of this approach:

• Stackless means that no variable on the thread method stack is valid after a thread returns and then resumes again. Although we can easily solve this by maintaining the context inside a separate object to which the thread is attached.
• No preemption also means that a thread can keep CPU to itself for as long as it wishes. It is up to the programmer to release the CPU as quickly as possible. Since device drivers usually use interrupt requests to respond in realtime anyway, this limitation has not proven to be a problem so far.
• No thread can ever call another thread or spawn a new thread. Threads are only single level. All other code called from inside the thread can be considered to execute atomically (except for when it is interrupted by an ISR).
• Data that needs to be saved across multiple thread switches must be stored in memory (this is a problem with all multitasking though).
• Longer response times for tasks - a task can lose cpu for as long as it takes the heavies task to finish. This is solved by programmer explicitly designing threads such that control is periodically released to the scheduler.

Stackless threads in libk are designed to solve one specific problem: busy waits. I settled for this approach because it has been the most lightweight solution to this problem. Almost 98% of all embedded code uses busy waits - the standard way to solve this problem is by implementing a scheduler that is able to interrupt a currently running task in the middle of it's busy loop and switch to a different task. This however also comes with a lot of subtle problems that result in much more synchronization code all around the application to ensure atomic access to shared data.

With protothreads, it is instead possible to minimize the amount of locking and synchronization necessary, while at the same time to enjoy a healthy degree of multitasking where CPU rarely is just idly spinning inside some delay loop.

The main area where this kind of multitasking really is useful is device drivers that do a lot of I/O. I/O operations are by far the greatest bottleneck in most embedded systems that don't use multitasking and instead resort to idly waiting for an I/O operation to complete. LibK solves this problem by doing minimal caching of data and also by never waiting for an I/O operation to complete and instead letting another task run while I/O is in progress.

Another attractive feature of libk threading is that it is completely implemented in software - meaning that it will work the same on all hardware. It is after all just an array of "update" methods that the kernel schedules periodically.

I have found that I could improve performance with protothreading almost 100x. When I eliminated all busy delay loops in the device drivers I have found that my application was able to run a lot faster and also it has become much more responsive. I have not howerver noticed a significant memory overhead. By far the main memory overhead (which is also a necessary evil) is caching data in memory so that it can be retained while another thread has control of the CPU. Most drivers use caching in one way or another.

When you want to implement support for a new chip, what you would need to do is implement all of the interfaces defined in arch/interface.h file. We will take a look at these interfaces in turn below. But first a little on how things are put together.

The whole arch layer for an architecture can be included into your application by including arch/soc.h file. It will automatically include needed files according to include/autoconfig.h file (generated by 'make menuconfig')

#include <arch/soc.h>

This layer consists of following devices:

• ADC - analog to digital converters
• DAC - digital to analog converters
• GPIO - on chip general purpose io driver
• PWM - pulse width modulation peripherals
• SPI - on board serial peripheral interface peripherals
• I2C/TWI - i2c interfaces
• UART - asynchronous serial interfaces
• CAN - controller area network interfaces

The arch layer is built around the idea of being really fast. Because this is the absolutely lowest layer that is closest to hardware, the methods of this layer get called a lot of times. This layer is responsible for providing a human readable interface to chip register operations.

We would typically implement this layer by wrapping register operations in macro expressions. You can take a look at how this is done in one of the header files found in for instance arch/avr/m328p folder. All cpu operations are wrapped in macros. You don't have to use macros on higher layers, but this layer is usually very simple (ie all "method" calls in this layer really just write values to some memory location) so we actually want to do this with macros. You can for instance look at the implementation of gpio interface in arch/avr/m328p/gpio.h

There are typically two ways to access devices on the soc. You can either call the arch layer directly (ie call the macros) or you can use generic interfaces that the arch layer can create for you in order to access the devices generically. Generic interfaces are designed to allow interchangable use of many different types of devices that can provide the same kind of service. For example, libc FILE handle is a type of generic interface. It has get() and put() function pointers that get called by getc/putc. This way you can use FILE to access a file on any filesystem, you can access a device, you can access a fifo pipe - all thought exactly the same interface.

This is exactly what we want to have for our device drivers as well!

But there is one problem: the devices that we are working with are all flash based controllers that usually have little memory - both flash and ram. We can not use really rich interfaces like the linux kernel. And we don't want to force the user to use interfaces. We want to provide interfaces simply as an essential feature for enabling driver reuse and for adding a great deal of flexibility for how device drivers are used.

You should think of interfaces as "services" that the device provides as opposed to identifying a specific device. If we make all of our devices "service"-oriented, we can reuse device drivers in many different contexts and pipe data from one driver to another. This is exactly the same philosophy that is used by linux commands where you can create more complex commands easily by simply piping results of one command to the next.

Here are some examples of what interfaces different core devices can export:

Click on the device name to read more!

Martin K. Schröder | info@fortmax.se

Files:

• arch/manufacturer/model/adc.h
• arch/adc.h

These devices are expected to provide a service of reading an analog signal on one of available pins and reporting the value as a digital 16 bit number. Adc implementation is limited to 256 channels (although can easily be extended in the future if one needs more). An adc driver should typically only control one type of device or a few types of devices that are very similar to each other. If a device differs too much, a separate driver should be created.

Macros should be provided for every peripheral separately if multiple devices are available - ie adc0, adc1 etc..

adc0_init_default();
printf("ADC value: %d\n", adc0_read_immediate(channel_id));

For other options it is best to check out implementation specific file in arch///adc.h

Martin K. Schröder | info@fortmax.se

Files:

• arch/manufacturer/model/gpio.h
• arch/gpio.h

A general purpose io is any kind of parallel device where it is possible to address each bit separately and which can be one or more bytes wide. It must be possible to write individual bits separately and also to write full "words" which are as wide as the width of the gpio interface. For internal devices it may be convenient to group all gpio interfaces together so that the user can use a continuous pin indexing scheme (ie for 3x8 bit on board parallel ports the pins can be numbered 0-24 in order to provide a generic way to access the port).

	gpio_init();
		while(1){
			gpio_write_pin(GPIO_PB0, 1);
			delay_ms(500);
			gpio_write_pin(GPIO_PB0, 0);
			delay_ms(500);
		}
	}

Martin K. Schröder | info@fortmax.se

Files:

• arch/manufacturer/model/twi.h
• arch/twi.h

The public interface used by the i2c bus is packet_interface. This is because i2c is a protocol based state machine that expects some standard data to operate. In this respect it operates just like any packet interface - it sends data buffers and receives data into a buffer. One special case that takes the point home is this: i2c devices sometimes expect a write operation followed by a repeated start signal and then a read operation. This sequence is used to read values from an i2c device. Using packet interface allows us to model this behaviour since it has begin(), end() write() and read() methods. Serial interface would be inappropriate here.

char buffer[] = {DEVICE_ADDRESS, 'H', 'e', 'l', 'l', 'o'}; 
twi0_init(100000);
twi0_begin();
twi0_start_write(buffer, 6);
twi0_start_read(buffer, 6); // will read data into buffer starting at buffer[1].. 
twi0_end()

Martin K. Schröder | info@fortmax.se

Files:

• arch/manufacturer/model/pwm.h
• arch/pwm.h

PWM interface is for controlling pwm hardware. Usually it would be built in, timer driven pwm channels, but the system does not limit you to just on board pwm channel You could just as easily have a driver for an i2c or spi pwm controller export this kind of interface and this would allow you to pass it to any component that requires a pwm interface (such as for example a motor speed controller).

The basic pulse width modulator interface consists of following methods:

pwm0_init(); pwm1_init();

pwm0_set(1500); // half throttle pwm0_set(1000); // zero throttle pwm0_set(2000); // full throttle

Martin K. Schröder | info@fortmax.se

Files:

• arch/manufacturer/model/spi.h
• arch/spi.h

SPI peripherals can be accessed by using standard serial_interface. A method for each peripheral must be provided: spi0_get_serial_interface() that returns struct serial_interface.

hwspi0_init_default();

uint8_t data = hwspi0_transfer('X'); 

Martin K. Schröder | info@fortmax.se

Files:

• arch/manufacturer/model/time.h
• arch/time.h

It is often necessary for implementation to provide a timer/counter for counting cpu clock cycles because this is the only way to do fairly exact timing when interrupts are enabled. More complex chips usually have a dedicated timer for this and an instruction to read clock counter. But for architectures that do not have this functionality, one of the timers needs to be used.

In the rest of the system clock counter value can be used in many ways - from simple delays to asynchronous events. If you disable this functionality then some drivers may stop working, but ideally they would not even compile. There is a special config field called CONFIG_TIMESTAMP_COUNTER that enables timestamping functionality and drivers that need this functionality should be configured in the corresponding KConfig file to depend on it being set.

Timer counter currently does not export interfaces. This may change when drivers would require an abstract timer object. For now, timers are mostly only used directly by drivers in the arch layer. While higher level drivers mostly only use timestamping to calculate delays and timeouts.

There are more timer hardware specific methods but they will not be covered here for now. Instead, have a look at implementation specific time.h file to get an idea.

timestamp_init();
timeout_t timeout = timeout_from_now(1000000); // 1s timeout
while(1){
	// do work
	if(timeout_expired(timeout))
		break; // will stop after 1 second
}

Martin K. Schröder | info@fortmax.se

Files:

• arch/manufacturer/model/uart.h
• arch/uart.h

As with many other peripherals, a chip can have several uarts. All uarts should export a serial_interface for generic access.

Check out definition of struct serial_interface in arch/interface.h

Implementation is as always free to either use buffered interrupt driven uart or simple non buffered uart. The advantage of implementing a buffered uart is that all write operations can return to higher level code much quicker so that application can carry on while uart sends the data in the background. So it is always preferable to at least have a small buffer.

|

It is up to higher level code to provide printf functionality. However, uart code may export a file descriptor for the uart making it possible to use standard fprintf() functionality pretty easily. If this is done, then global uart file descriptors are exported and named uartX_fd for each available uart. This removes the need to write custom printf functions because we can just use libc.

uart0_init(32400);

// accessing directly
uart0_putc('X');

// using an interface
struct serial_interface serial = uart0_get_serial_interface();
char buffer[] = "Hello World!"; 
serial.putn(&serial, buffer, strlen(buffer));

// using file descriptor
fprintf(uart0_fd, "Hello %s\n", "World!"); 

Author: Martin K. Schröder, 2015

TTY drivers need to use generic display interface so that it can be used with any GLCD display.