Core api concept (#144)

* add input debounce code from old fw

* exampl of input api

* change input API to get/release

* revert input API to read

* pointer instead of instance

* add input API description

* add display API

* rewrite display names

* migrate to valuemanager

* add LED API

* add closing brakets

* add sound api

* fix led api

* basic api

* rename API pages

* change pubsub implementation

* move FURI AC -> flapp, add valuemutex example, add valuemanager implementation

* pubsub usage example

* user led example

* update example

* simplify input

* add composed display

* add SPI/GPIO and CC1101 bus

* change cc1101 api

* spi api and devices

* spi api and devices

* move SPI to page, add GPIO

* not block pin open

* backlight API and more

* add minunit tests

* fix logging

* ignore unexisting time service on embedded targets

* fix warning, issue with printf

* Deprecate furi_open and furi_close (#167)

Rename existing furi_open and furi_close to deprecated version

* add exitcode

* migrate to printf

* indicate test by leds

* add testing description

* rename furi.h

* wip basic api

* add valuemutex, pubsub, split files

* add value expanders

* value mutex realization and tests

* valuemutex test added to makefile

* do not build unimplemented files

* fix build furmware target f2

* redesigned minunit tests to allow testing in separate files

* test file for valuemutex minunit testing

* minunit partial test valuemutex

* local cmsis_os2 mutex bindings

* implement furi open/create, tests

* migrate concurrent_access to ValueMutex

* add spi header

* Lib: add mlib submodule.

Co-authored-by: rusdacent <rusdacentx0x08@gmail.com>
Co-authored-by: DrZlo13 <who.just.the.doctor@gmail.com>
This commit is contained in:
coreglitch
2020-10-13 14:22:43 +06:00
committed by GitHub
parent b7c30154f4
commit 942bbfaefe
51 changed files with 1874 additions and 692 deletions

47
core/api-basic/flapp.h Normal file
View File

@@ -0,0 +1,47 @@
#pragma once
#include "flipper.h"
// == Flipper Application control (flapp) ==
typedef FlappHandler uint32_t; // TODO
/*
simply starts application. It call `app` entrypoint with `param` passed as argument
Useful for daemon applications and pop-up.
*/
FlappHandler* flapp_start(void(app*)(void*), char* name, void* param);
/*
swtich to other application.
System **stop current app**, call `app` entrypoint with `param` passed
as argument and save current application entrypoint to `prev` field in
current application registry. Useful for UI or "active" application.
*/
FlappHandler* flapp_switch(void(app*)(void*), char* name, void* param);
/*
Exit application
stop current application (stop thread and clear application's stack),
start application from `prev` entry in current application registry,
cleanup current application registry.
*/
void flapp_exit(void* param);
/*
stop specified `app` without returning to `prev` application.
*/
bool flapp_kill(FlappHandler* app);
/*
If case one app depend on other, notify that app is ready.
*/
void flapp_ready();
/*
Register on-exit callback.
It called before app will be killed.
Not recommended to use in user scenario, only for system purpose
(unregister callbacks, release mutexes, etc.)
*/
bool flapp_on_exit(void(cb*)(void*), void* ctx);

14
core/api-basic/furi.c Normal file
View File

@@ -0,0 +1,14 @@
#include "furi.h"
#include "furi-deprecated.h"
bool furi_create(const char* name, void* ptr) {
return furi_create_deprecated(name, ptr, sizeof(size_t));
}
void* furi_open(const char* name) {
FuriRecordSubscriber* record = furi_open_deprecated(name, false, false, NULL, NULL, NULL);
void* res = furi_take(record);
furi_give(record);
return res;
}

26
core/api-basic/furi.h Normal file
View File

@@ -0,0 +1,26 @@
#pragma once
#include "flipper.h"
/*
== Flipper universal registry implementation (FURI) ==
## Requirements
* start daemon app
* kill app
* start child thread (kill when parent app was killed)
* switch between UI apps
*/
/*
Create record.
creates new record in registry and store pointer into it
*/
bool furi_create(const char* name, void* ptr);
/*
Open record.
get stored pointer by its name
*/
void* furi_open(const char* name);

View File

@@ -0,0 +1,48 @@
#include "pubsub.h"
void init_pubsub(PubSub* pubsub) {
pubsub->count = 0;
for(size_t i = 0; i < NUM_OF_CALLBACKS; i++) {
pubsub->items[i].
}
}
// TODO add mutex to reconfigurate PubSub
PubSubId* subscribe_pubsub(PubSub* pubsub, PubSubCallback cb, void* ctx) {
if(pubsub->count >= NUM_OF_CALLBACKS) return NULL;
pubsub->count++;
PubSubItem* current = pubsub->items[pubsub->count];
current->cb = cb;
currrnt->ctx = ctx;
pubsub->ids[pubsub->count].self = pubsub;
pubsub->ids[pubsub->count].item = current;
flapp_on_exit(unsubscribe_pubsub, &(pubsub->ids[pubsub->count]));
return current;
}
void unsubscribe_pubsub(PubSubId* pubsub_id) {
// TODO: add, and rearrange all items to keep subscribers item continuous
// TODO: keep ids link actual
// TODO: also add mutex on every pubsub changes
// trivial implementation for NUM_OF_CALLBACKS = 1
if(NUM_OF_CALLBACKS != 1) return;
if(pubsub_id != NULL || pubsub_id->self != NULL || pubsub_id->item != NULL) return;
pubsub_id->self->count = 0;
pubsub_id->item = NULL;
}
void notify_pubsub(PubSub* pubsub, void* arg) {
// iterate over subscribers
for(size_t i = 0; i < pubsub->count; i++) {
pubsub->items[i]->cb(arg, pubsub->items[i]->ctx);
}
}

83
core/api-basic/pubsub.h Normal file
View File

@@ -0,0 +1,83 @@
#pragma once
#include "flipper.h"
/*
== PubSub ==
PubSub allows users to subscribe on notifies and notify subscribers.
Notifier side can pass `void*` arg to subscriber callback,
and also subscriber can set `void*` context pointer that pass into
callback (you can see callback signature below).
*/
typedef void(PubSubCallback*)(void*, void*);
typedef struct {
PubSubCallback cb;
void* ctx;
} PubSubItem;
typedef struct {
PubSub* self;
PubSubItem* item;
} PubSubId;
typedef struct {
PubSubItem items[NUM_OF_CALLBACKS];
PubSubId ids[NUM_OF_CALLBACKS]; ///< permanent links to item
size_t count; ///< count of callbacks
} PubSub;
/*
To create PubSub you should create PubSub instance and call `init_pubsub`.
*/
void init_pubsub(PubSub* pubsub);
/*
Use `subscribe_pubsub` to register your callback.
*/
PubSubId* subscribe_pubsub(PubSub* pubsub, PubSubCallback cb, void* ctx);
/*
Use `unsubscribe_pubsub` to unregister callback.
*/
void unsubscribe_pubsub(PubSubId* pubsub_id);
/*
Use `notify_pubsub` to notify subscribers.
*/
void notify_pubsub(PubSub* pubsub, void* arg);
/*
```C
// MANIFEST
// name="test"
// stack=128
void example_pubsub_handler(void* arg, void* ctx) {
printf("get %d from %s\n", *(uint32_t*)arg, (const char*)ctx);
}
void pubsub_test() {
const char* app_name = "test app";
PubSub example_pubsub;
init_pubsub(&example_pubsub);
if(!subscribe_pubsub(&example_pubsub, example_pubsub_handler, (void*)app_name)) {
printf("critical error\n");
flapp_exit(NULL);
}
uint32_t counter = 0;
while(1) {
notify_pubsub(&example_pubsub, (void*)&counter);
counter++;
osDelay(100);
}
}
```
*/

View File

@@ -0,0 +1,24 @@
#include "value-expanders.h"
bool commit_managed(ValueManager* managed, void* value) {
if(value != managed->mutex->value) return false;
notify_pubsub(&managed->pubsub, value);
if(!osMutexGive(managed->mutex)) return false;
return true;
}
bool write_managed(ValueManager* managed, void* data, size_t len, uint32_t timeout) {
void* value = acquire_mutex(managed->mutex, timeout);
if(value == NULL) return false;
memcpy(value, data, len):
notify_pubsub(&managed->pubsub, value);
if(!release_mutex(managed->mutex, value)) return false;
return true;
}

View File

@@ -0,0 +1,56 @@
#pragma once
#include "flipper.h"
/*
== Value composer ==
*/
typedef void(ValueComposerCallback)(void* ctx, void* state);
void COPY_COMPOSE(void* ctx, void* state) {
read_mutex((ValueMutex*)ctx, state, 0);
}
typedef enum {
UiLayerBelowNotify
UiLayerNotify,
UiLayerAboveNotify
} UiLayer;
ValueComposerHandle* add_compose_layer(
ValueComposer* composer, ValueComposerCallback cb, void* ctx, uint32_t layer
);
bool remove_compose_layer(ValueComposerHandle* handle);
void request_compose(ValueComposerHandle* handle);
// See [LED](LED-API) or [Display](Display-API) API for examples.
/*
== ValueManager ==
More complicated concept is ValueManager.
It is like ValueMutex, but user can subscribe to value updates.
First of all you can use value and pubsub part as showing above:
aquire/release mutex, read value, subscribe/unsubscribe pubsub.
There are two specific methods for ValueManager: write_managed, commit_managed
*/
typedef struct {
ValueMutex value;
PubSub pubsub;
} ValueManager;
/*
acquire value, changes it and send notify with current value.
*/
bool write_managed(ValueManager* managed, void* data, size_t len, uint32_t timeout);
/*
commit_managed works as `release_mutex` but send notify with current value.
*/
bool commit_managed(ValueManager* managed, void* value);

View File

@@ -0,0 +1,52 @@
#include "valuemutex.h"
#include <string.h>
bool init_mutex(ValueMutex* valuemutex, void* value, size_t size) {
// mutex without name,
// no attributes (unfortunatly robust mutex is not supported by FreeRTOS),
// with dynamic memory allocation
const osMutexAttr_t value_mutext_attr = {
.name = NULL, .attr_bits = 0, .cb_mem = NULL, .cb_size = 0U};
valuemutex->mutex = osMutexNew(&value_mutext_attr);
if(valuemutex->mutex == NULL) return false;
valuemutex->value = value;
valuemutex->size = size;
return true;
}
void* acquire_mutex(ValueMutex* valuemutex, uint32_t timeout) {
if(osMutexAcquire(valuemutex->mutex, timeout) == osOK) {
return valuemutex->value;
} else {
return NULL;
}
}
bool release_mutex(ValueMutex* valuemutex, void* value) {
if(value != valuemutex->value) return false;
if(osMutexRelease(valuemutex->mutex) != osOK) return false;
return true;
}
bool read_mutex(ValueMutex* valuemutex, void* data, size_t len, uint32_t timeout) {
void* value = acquire_mutex(valuemutex, timeout);
if(value == NULL || len > valuemutex->size) return false;
memcpy(data, value, len > 0 ? len : valuemutex->size);
if(!release_mutex(valuemutex, value)) return false;
return true;
}
bool write_mutex(ValueMutex* valuemutex, void* data, size_t len, uint32_t timeout) {
void* value = acquire_mutex(valuemutex, timeout);
if(value == NULL || len > valuemutex->size) return false;
memcpy(value, data, len > 0 ? len : valuemutex->size);
if(!release_mutex(valuemutex, value)) return false;
return true;
}

123
core/api-basic/valuemutex.h Normal file
View File

@@ -0,0 +1,123 @@
#pragma once
#include "flipper.h"
/*
== ValueMutex ==
The most simple concept is ValueMutex.
It is wrapper around mutex and value pointer.
You can take and give mutex to work with value and read and write value.
*/
typedef struct {
void* value;
size_t size;
osMutexId_t mutex;
} ValueMutex;
/*
Creates ValueMutex.
*/
bool init_mutex(ValueMutex* valuemutex, void* value, size_t size);
/*
Call for work with data stored in mutex.
Returns pointer to data if success, NULL otherwise.
*/
void* acquire_mutex(ValueMutex* valuemutex, uint32_t timeout);
/*
Helper: infinitly wait for mutex
*/
static inline void* acquire_mutex_block(ValueMutex* valuemutex) {
return acquire_mutex(valuemutex, osWaitForever);
}
/*
Release mutex after end of work with data.
Call `release_mutex` and pass ValueData instance and pointer to data.
*/
bool release_mutex(ValueMutex* valuemutex, void* value);
/*
Instead of take-access-give sequence you can use `read_mutex` and `write_mutex` functions.
Both functions return true in case of success, false otherwise.
*/
bool read_mutex(ValueMutex* valuemutex, void* data, size_t len, uint32_t timeout);
bool write_mutex(ValueMutex* valuemutex, void* data, size_t len, uint32_t timeout);
inline static bool write_mutex_block(ValueMutex* valuemutex, void* data, size_t len) {
return write_mutex(valuemutex, data, len, osWaitForever);
}
inline static bool read_mutex_block(ValueMutex* valuemutex, void* data, size_t len) {
return read_mutex(valuemutex, data, len, osWaitForever);
}
/*
Usage example
```C
// MANIFEST
// name="example-provider-app"
// stack=128
void provider_app(void* _p) {
// create record with mutex
uint32_t example_value = 0;
ValueMutex example_mutex;
// call `init_mutex`.
if(!init_mutex(&example_mutex, (void*)&example_value, sizeof(uint32_t))) {
printf("critical error\n");
flapp_exit(NULL);
}
if(furi_create("provider/example", (void*)&example_mutex)) {
printf("critical error\n");
flapp_exit(NULL);
}
// we are ready to provide record to other apps
flapp_ready();
// get value and increment it
while(1) {
uint32_t* value = acquire_mutex(&example_mutex, OsWaitForever);
if(value != NULL) {
value++;
}
release_mutex(&example_mutex, value);
osDelay(100);
}
}
// MANIFEST
// name="example-consumer-app"
// stack=128
// require="example-provider-app"
void consumer_app(void* _p) {
// this app run after flapp_ready call in all requirements app
// open mutex value
ValueMutex* counter_mutex = furi_open("provider/example");
if(counter_mutex == NULL) {
printf("critical error\n");
flapp_exit(NULL);
}
// continously read value every 1s
uint32_t counter;
while(1) {
if(read_mutex(counter_mutex, &counter, sizeof(counter), OsWaitForever)) {
printf("counter value: %d\n", counter);
}
osDelay(1000);
}
}
```
*/

133
core/api-hal/api-spi.h Normal file
View File

@@ -0,0 +1,133 @@
#include "flipper_v2.h"
/*
struct used for handling SPI info.
*/
typedef struct {
SPI_HandleTypeDef* spi;
PubSubCallback cb;
void* ctx;
} SpiHandle;
/*
For transmit/receive data use `spi_xfer` function.
* `tx_data` and `rx_data` size must be equal (and equal `len`)
* `cb` called after spi operation is completed, `(NULL, ctx)` passed to callback.
*/
bool spi_xfer(
SPI_HandleTypeDef* spi,
uint8_t* tx_data, uint8_t* rx_data, size_t len,
PubSubCallback cb, void* ctx);
/*
Blocking verison:
*/
static inline bool spi_xfer_block(SPI_HandleTypeDef* spi, uint8_t* tx_data, uint8_t* rx_data, size_t len) {
semaphoreInfo s;
osSemaphore block = createSemaphoreStatic(s);
if(!spi_xfer(spi, tx_data, rx_data, len, RELEASE_SEMAPHORE, (void*)block)) {
osReleaseSemaphore(block);
return false;
}
osWaitSemaphore(block);
return false;
}
/*
Common implementation of SPI bus: serial interface + CS pin
*/
typedef struct {
GpioPin* cs; ///< CS pin
ValueMutex* spi; ///< <SpiHandle*>
} SpiBus;
/*
For dedicated work with one device there is `SpiDevice` entity.
It contains ValueMutex around SpiBus: after you acquire device
you can acquire spi to work with it (don't forget SPI bus is shared
around many device, release it after every transaction as quick as possible).
*/
typedef struct {
ValueMutex* bus; ///< <SpiBus*>
} SpiDevice;
## SPI IRQ device
/*
Many devices (like CC1101 and NFC) present as SPI bus and IRQ line.
For work with it there is special entity `SpiIrqDevice`.
Use `subscribe_pubsub` for subscribinq to irq events.
*/
typedef struct {
ValueMutex* bus; ///< <SpiBus*>
PubSub* irq;
} SpiIrqDevice;
/*
Special implementation of SPI bus: serial interface + CS, Res, D/I lines.
*/
typedef struct {
GpioPin* cs; ///< CS pin
GpioPin* res; ///< reset pin
GpioPin* di; ///< D/I pin
ValueMutex* spi; ///< <SPI_HandleTypeDef*>
} DisplayBus;
typedef struct {
ValueMutex* bus; ///< <DisplayBus*>
} DisplayDevice;
/*
# SPI devices (F2)
* `/dev/sdcard` - SD card SPI, `SpiDevice`
* `/dev/cc1101_bus` - Sub-GHz radio (CC1101), `SpiIrqDevice`
* `/dev/nfc` - NFC (ST25R3916), `SpiIrqDevice`
* `/dev/display` - `DisplayDevice`
* `/dev/spiext` - External SPI (warning! Lock PA4, PA5, PA6, PA7)
### Application example
```C
// Be careful, this function called from IRQ context
void handle_irq(void* _arg, void* _ctx) {
}
void cc1101_example() {
SpiIrqDevice* cc1101_device = open_input("/dev/cc1101_bus");
if(cc1101_device == NULL) return; // bus not available, critical error
subscribe_pubsub(cc1101_device->irq, handle_irq, NULL);
{
// acquire device as device bus
SpiBus* spi_bus = acquire_mutex(cc1101_device->bus, 0);
if(spi_bus == NULL) {
printf("Device busy\n");
// wait for device
spi_bus = acquire_mutex_block(cc1101_device->bus);
}
// make transaction
uint8_t request[4] = {0xDE, 0xAD, 0xBE, 0xEF};
uint8_t response[4];
{
SPI_HandleTypeDef* spi = acquire_mutex_block(spi_bus->spi);
gpio_write(spi_bus->cs, false);
spi_xfer_block(spi, request, response, 4);
gpio_write(spi_bus->cs, true);
release_mutex(cc1101_device->spi, spi);
}
// release device (device bus)
release_mutex(cc1101_device->bus, spi_bus);
}
}
```
*/

View File

@@ -2,7 +2,6 @@
extern "C" {
#include "flipper.h"
#include "furi.h"
#include "log.h"
#include "startup.h"
#include "tty_uart.h"

View File

@@ -3,4 +3,5 @@ CORE_DIR = $(PROJECT_ROOT)/core
CFLAGS += -I$(CORE_DIR)
ASM_SOURCES += $(wildcard $(CORE_DIR)/*.s)
C_SOURCES += $(wildcard $(CORE_DIR)/*.c)
C_SOURCES += $(wildcard $(CORE_DIR)/api-basic/*.c)
CPP_SOURCES += $(wildcard $(CORE_DIR)/*.cpp)

View File

@@ -7,7 +7,8 @@ extern "C" {
#include "main.h"
#include "flipper_hal.h"
#include "cmsis_os.h"
#include "furi.h"
#include "furi-deprecated.h"
#include "log.h"
#include "input/input.h"

7
core/flipper_v2.h Normal file
View File

@@ -0,0 +1,7 @@
#pragma once
#include "api-basic/furi.h"
//#include "api-basic/flapp.h"
#include "cmsis_os2.h"
#include "api-basic/valuemutex.h"
//#include "api-basic/pubsub.h"

View File

@@ -1,5 +1,4 @@
#include "furi.h"
#include "cmsis_os.h"
#include "furi-deprecated.h"
#include <string.h>
// TODO: this file contains printf, that not implemented on uC target
@@ -28,7 +27,7 @@ static FuriRecord* find_record(const char* name) {
}
// TODO: change open-create to only open
bool furi_create(const char* name, void* value, size_t size) {
bool furi_create_deprecated(const char* name, void* value, size_t size) {
#ifdef FURI_DEBUG
printf("[FURI] creating %s record\n", name);
#endif
@@ -73,7 +72,7 @@ bool furi_create(const char* name, void* value, size_t size) {
return true;
}
FuriRecordSubscriber* furi_open(
FuriRecordSubscriber* furi_open_deprecated(
const char* name,
bool solo,
bool no_mute,
@@ -94,7 +93,7 @@ FuriRecordSubscriber* furi_open(
#endif
// create record if not exist
if(!furi_create(name, NULL, 0)) {
if(!furi_create_deprecated(name, NULL, 0)) {
return NULL;
}

View File

@@ -127,7 +127,7 @@ If NULL, create FURI Pipe (only callbacks management, no data/mutex)
Returns false if registry have not enough memory for creating.
*/
bool furi_create(const char* name, void* value, size_t size);
bool furi_create_deprecated(const char* name, void* value, size_t size);
/*!
Opens existing FURI record by name.
@@ -137,7 +137,7 @@ When appication has exited or record has closed, all handlers is unmuted.
It may be useful for concurrently acces to resources like framebuffer or beeper.
\param[in] no_mute if true, another applications cannot mute this handler.
*/
FuriRecordSubscriber* furi_open(
FuriRecordSubscriber* furi_open_deprecated(
const char* name,
bool solo,
bool no_mute,

View File

@@ -1,5 +1,4 @@
#include "furi.h"
#include "cmsis_os.h"
#include "flipper.h"
// TODO: this file contains printf, that not implemented on uC target

View File

@@ -5,7 +5,7 @@
#include <string.h>
#include "log.h"
#include "furi.h"
#include "flipper.h"
#define PRINT_STR_SIZE 64
@@ -21,5 +21,5 @@ void fuprintf(FuriRecordSubscriber* f, const char* format, ...) {
}
FuriRecordSubscriber* get_default_log() {
return furi_open("tty", false, false, NULL, NULL, NULL);
return furi_open_deprecated("tty", false, false, NULL, NULL, NULL);
}

View File

@@ -1,6 +1,6 @@
#pragma once
#include "furi.h"
#include "flipper.h"
FuriRecordSubscriber* get_default_log();
void fuprintf(FuriRecordSubscriber* f, const char* format, ...);

View File

@@ -1,6 +1,6 @@
#define _GNU_SOURCE
#include <stdio.h>
#include "furi.h"
#include "flipper.h"
#include "main.h"
extern UART_HandleTypeDef DEBUG_UART;
@@ -12,7 +12,7 @@ void handle_uart_write(const void* data, size_t size, void* ctx) {
static ssize_t stdout_write(void* _cookie, const char* buf, size_t n) {
FuriRecordSubscriber* log = pvTaskGetThreadLocalStoragePointer(NULL, 0);
if(log == NULL) {
log = furi_open("tty", false, false, NULL, NULL, NULL);
log = furi_open_deprecated("tty", false, false, NULL, NULL, NULL);
if(log == NULL) {
return -1;
}
@@ -33,11 +33,11 @@ static ssize_t stdout_write(void* _cookie, const char* buf, size_t n) {
}
bool register_tty_uart() {
if(!furi_create("tty", NULL, 0)) {
if(!furi_create_deprecated("tty", NULL, 0)) {
return false;
}
if(furi_open("tty", false, false, handle_uart_write, NULL, NULL) == NULL) {
if(furi_open_deprecated("tty", false, false, handle_uart_write, NULL, NULL) == NULL) {
return false;
}