Devices

Devices

A new device can be defined by creating a source file in device. The functionality the device file must provide is detailed in shared/sunneed_device_interface.h.

Devices represent the trusted relationship between the sunneed core and the physical peripherals that the host machine can utilize. Managing power is the responsibility of the device itself; sunneed relies on the device to tell it when power events are happening.

The following is an example event flow for interaction between sunneed and a device. The device in question utilizes the FILE_LOCK device type with the ON_OFF consumption type.

1. sunneed starts up and runs the device's init function. The device subscribes to sunneed's file write event.
2. A client program attempts to write to a file locked by the device.
3. sunneed intercepts the write (TODO Document how that all works) and fires the file write even to all subscribers.
4. The device receives the file write event and confirms that the path being written to is the file it has locked.
5. The device checks the value being written to the device, and if it matches a certain value (let's say 1 here) it tells sunneed that its consumption has entered the ON state.
6. At the end of each quantum, sunneed notes that the device is still in its ON state, and bills the requestor appropriately.
7. Eventually sunneed intercepts another write and tells the device about it. The device matches it to its OFF value (say, 0) and tells sunneed it is entering its OFF state.

Device API

init

init is run once at load-time (during sunneed's startup process). See Device Initialization.

The init function receives the sunneed_event_listeners struct. This is a struct containing pointers to the heads of a bunch of linked lists, each representing a different event. The device can assign function pointers to these heads, to define a function to be run when that event is triggered. TODO Document events.

device_type_kind

An instance of type sunneed_device_type that defines how sunneed should interact with this device. See Device Types.

get_device_type_data

Returns an instance of one of the device_type_* structs defined in sunneed_device_type.h. This must correspond with the device_type_kind.

device_flags

A bitfield containing flags. See sunneed_device_interface.h for a list of flags.

consumption_type_kind

An instance of type sunneed_consumption_type that defines how this device consumes power. See Consumption Types.

Device types

There is currently one device type:

• DEVICE_TYPE_FILE_LOCK: This device takes ownership of one or more files. A tenant writing to that file triggers a consumption event.

Consumption types

There is currently one consumption type:

• CONSUMPTION_TYPE_ON_OFF: This device begins consuming power upon a certain event. It continuously consumes power until another certain event happens.

Device initialization

Upon initialization, the device can do any calculations or setup operations that only need to happen once. This is also where the device can subscribe to sunneed events.