Application

Higher-level, application-facing modules built on top of System and Hardware. More...

Collaboration diagram for Application:

Modules
	Human Interface Device (HID)

Typedefs
typedef struct app_t	app_t
	Opaque application instance passed to app callbacks.
typedef void(*	app_callback_start_t) (app_t *app, void *userdata)
	Called once, on the main worker, before the run loop starts dispatching events. More...
typedef void(*	app_callback_event_t) (app_t *app, sys_event_t event, void *userdata)
	Called on a worker for each event the run loop dispatches. More...

Enumerations
enum	app_flag_t {   app_flag_none = 0, app_flag_multicore = (1 << 0), app_flag_signal = (1 << 1), app_flag_user_button = (1 << 2),   app_flag_temperature = (1 << 3), app_flag_stdio_rtt = (1 << 5), app_flag_led = (1 << 6), app_flag_watchdog = (1 << 7),   app_flag_usb = (1 << 8) }
	Feature flags controlling how app_main() runs. More...

Lifecycle
int	app_main (int argc, char *argv[], app_flag_t flags, app_callback_start_t on_start, app_callback_event_t on_event, void *userdata)
	Initialize the sys subsystem, run the event loop, then tear it down. More...

Properties
hid_t *	app_hid (const app_t *app)
	Get the HID instance initialized for this app. More...
hw_led_t *	app_led (const app_t *app)
	Get the on-board LED handle initialized for this app. More...
hw_watchdog_t *	app_watchdog (const app_t *app)
	Get the watchdog handle initialized for this app. More...
hw_usb_t *	app_usb (const app_t *app)
	Get the USB host handle initialized for this app. More...

Methods
void	app_shutdown (int exit_code)
	Request that the running app's event loop stop. More...

Detailed Description

Higher-level, application-facing modules built on top of System and Hardware.

static void on_start(app_t *app, void *userdata) {
  hid_t *hid = app_hid(app);
  if (hid != NULL) {
    hid_register_user_button(hid, KEYCODE_ESC);
  }
}

static void on_event(app_t *app, sys_event_t event, void *userdata) {
  // Handle an event posted via sys_runloop_post(), or a hid_event_t
  // produced by a device registered in on_start (see hid_event_free()).
  if (event == my_exit_event) {
    app_shutdown(0);
  }
}

int main(int argc, char *argv[]) {
  return app_main(argc, argv, app_flag_none, on_start, on_event, NULL);
}

Typedef Documentation

app_callback_event_t

typedef void(* app_callback_event_t) (app_t *app, sys_event_t event, void *userdata)

Called on a worker for each event the run loop dispatches.

Parameters

app	Application instance.
event	Event to handle, as posted via sys_runloop_post() (see sys/runloop.h).
userdata	Opaque pointer, as passed to app_main().

Definition at line 113 of file app.h.

app_callback_start_t

typedef void(* app_callback_start_t) (app_t *app, void *userdata)

Called once, on the main worker, before the run loop starts dispatching events.

Parameters

app	Application instance. Valid for the duration of app_main().
userdata	Opaque pointer, as passed to app_main().

Use this to complete setup that must run before events can be produced, such as registering HID devices or opening buses.

Definition at line 103 of file app.h.

Enumeration Type Documentation

app_flag_t

enum app_flag_t

Feature flags controlling how app_main() runs.

Enumerator
app_flag_none	Default behavior.
app_flag_multicore	Run the event loop across all cores.
app_flag_signal	Register environment signals (TERM, INT, QUIT) as HID events (see app_hid). Has no effect on a platform with no signal support.
app_flag_user_button	Register the board's user button (if any) as a HID event with keycode KEYCODE_BUTTON_USER (see app_hid). Not every board has a user button; has no effect when the board has none.
app_flag_temperature	Register the internal temperature-sensor channel as a polling HID metric source (see hid_register_temperature() and app_hid). Has no effect when the platform has no internal temperature sensor.
app_flag_stdio_rtt	Initialize standard I/O via SEGGER RTT (sys_stdio_rtt) instead of the platform default.
app_flag_led	Initialize the on-board LED if available (see app_led). Has no effect when the platform has no default on-board LED.
app_flag_watchdog	Enable the watchdog (see app_watchdog) - hw_poll(), called every run loop tick, feeds it from there. Has no effect when the platform has no watchdog backend.
app_flag_usb	Initialize the USB host subsystem and register it with HID (see app_usb and app_hid) - hotplug activity flows in as hid_event_type_usb events automatically. Call hw_usb_set_callback() directly on the returned handle to replace that with your own callback instead. Has no effect when the platform has no USB host backend.

Definition at line 41 of file app.h.

             {
  app_flag_none = 0,               
  app_flag_multicore = (1 << 0),   
  app_flag_signal = (1 << 1),      
  app_flag_user_button = (1 << 2), 
  app_flag_temperature = (1 << 3), 
  app_flag_stdio_rtt = (1 << 5),   
  app_flag_led = (1 << 6),         
  app_flag_watchdog = (1 << 7),    
  app_flag_usb = (1 << 8),         
} app_flag_t;

Function Documentation

app_hid()

hid_t* app_hid

(

const app_t *

app

)

Get the HID instance initialized for this app.

Parameters

app	Application instance.

Returns

HID instance. Never NULL once app_main() has called on_start (see app_main) - picofuse-app always links picofuse-hid.

app_led()

hw_led_t* app_led

(

const app_t *

app

)

Get the on-board LED handle initialized for this app.

Parameters

app	Application instance.

Returns

LED handle, or NULL if app_flag_led was not passed to app_main(), or the platform has no default on-board LED (see hw_led_init_default()).

Call hw_led_set()/hw_led_blink() on it directly.

app_main()

int app_main	(	int	argc,
		char *	argv[],
		app_flag_t	flags,
		app_callback_start_t	on_start,
		app_callback_event_t	on_event,
		void *	userdata
	)

Initialize the sys subsystem, run the event loop, then tear it down.

Parameters

argc	Argument count, as passed to main().
argv	Argument vector, as passed to main().
flags	Feature flags selecting optional behavior (see app_flag_t).
on_start	Called once, on the main worker, before the event loop starts. May be NULL.
on_event	Called for each event the loop dispatches. May be NULL if nothing ever posts events.
userdata	Opaque pointer passed through to on_start and on_event.

Returns

Exit code, suitable for returning directly from main().

Calls sys_init() (with sys_stdio_rtt if app_flag_stdio_rtt is set, otherwise the platform default), hw_init(), and hid_init() (see app_hid), initializes the on-board LED if app_flag_led is set and available (see app_led), registers environment signals as HID events if app_flag_signal is set, registers the board's user button as a HID event if app_flag_user_button is set, registers the internal temperature sensor as a HID metric source if app_flag_temperature is set, enables the watchdog if app_flag_watchdog is set and available (see app_watchdog), initializes the USB host subsystem and registers it with HID if app_flag_usb is set and available (see app_usb and hw_usb_register_hid()), then runs the event loop across every available core if app_flag_multicore is set, or on the calling thread alone otherwise. Every run loop tick calls hw_poll(), which feeds the watchdog when enabled (see hw_watchdog_enable()). Blocks until app_shutdown is called from within a callback (or from another thread), then tears down (hid_deinit(), hw_led_deinit(), hw_watchdog_deinit(), hw_usb_deinit(), hw_exit(), sys_exit()).

app_shutdown()

void app_shutdown

(

int

exit_code

)

Request that the running app's event loop stop.

Parameters

exit_code

Value app_main() returns once the loop has drained and stopped.

Safe to call from any callback or thread. Equivalent to sys_runloop_shutdown(), exposed here so callers do not need to include sys/runloop.h directly.

app_usb()

hw_usb_t* app_usb

(

const app_t *

app

)

Get the USB host handle initialized for this app.

Parameters

app	Application instance.

Returns

USB host handle, or NULL if app_flag_usb was not passed to app_main(), or the platform has no USB host backend (see hw_usb_init()).

Already registered with HID (see app_hid) via hw_usb_register_hid()

• hotplug activity flows in as hid_event_type_usb events. Call hw_usb_set_callback() directly on this handle to replace that with your own callback instead.

app_watchdog()

hw_watchdog_t* app_watchdog

(

const app_t *

app

)

Get the watchdog handle initialized for this app.

Parameters

app	Application instance.

Returns

Watchdog handle, or NULL if app_flag_watchdog was not passed to app_main(), or the platform has no watchdog backend (see hw_watchdog_init()).

app_main() already calls hw_watchdog_enable() to start feeding this from hw_poll() (see its own doc) - call hw_watchdog_reset() on it directly to force an earlier reset, or hw_watchdog_enable() to stop feeding it.