device/class/valio.h header reference
[Devices support library module]
The source code of this header can be browsed online.
Description [link]
See also DRIVER_CLASS_VALIO.
Purpose [link]
The Value IO class gives access to a set of values exposed by a device. The class allows getting, setting and registering for events on a value. However, the byte size, format, unit and encoding of the exposed values are not specified in the class itself. This class is especially relevant for sensors and actuators. This class should only be used to handle low bandwidth transfer of physical values.
The device may expose several different values which are identified using attributes. A device supports a fixed set of attributes. Each attribute is defined by its constant identifier, its fixed byte size for the value and its set of supported operations.
Several operations can be performed on an attribute by submitting the appropriate request to the driver: reading, writing or waiting for an event on a value. The driver is free to support requests depending on the operation and attribute identifier.
Wrong use [link]
This class may not be appropriate in some cases:
Accessing attribute values may be used to control actuators, or even set configuration parameters. Yet it must not be used to implement a control mechanism where accessing a value will be interpreted as a command not related to a physical value. For instance, it can not be used to read a firmware revision or setup a low power mode of the device. Nonetheless, it can be used to set a motor position, set a led intensity, setup a value range or handle calibration of the device.
This class is not appropriate for streaming samples at some fixed data rate. In particular, the user may query values in a loop but the driver is never required to provide the value in constant time. Moreover, only instantaneous or cumulative values can be reported; no fifo can be used to keep some old unread values. In other words, close enough read requests are likely to return the same value.
Size of values must be fixed at compile time and can not vary at runtime. That's why the request does not include a size field.
It must not be used just because no other device class is fitting. An new class should be created when the purpose does not match the scope of the Value IO class described here.
Defining new attributes [link]
Attributes are defined globally at compile time. Defining an attribute implies:
choosing a numerical identifier,
specifying the set of supported operations,
defining a C structure used to store the value,
optionally defining a different C structure used to store the result of write operations,
optionally defining a C structure used to store the parameters for read operations,
optionally defining a C structure used to store the condition for the event condition.
Generic attributes [link]
As explained previously, the device class does not enforce any specific format on values, attributes or operation availability. It is designed as a generic value accessor API between some devices and the user code. However, the device driver and the user code need to use a common representation of the values.
Some libraries may define their own attributes, but some common attribute definitions are provided by libdevice.
Some attribute identifiers are defined along with data encoding for some specific usages. Using these attributes allows interchangeability of devices of the same type. These are available from the following headers:
device/valio/adc.h : Value IO interface for a ADCs
device/valio/button.h : Value IO interface for a button
device/valio/hwclock.h : Value IO interface for a calendar clock
device/valio/keyboard.h : Value IO interface for a keyboard
device/valio/led.h : Value IO interface for a single led
device/valio/motion.h : Value IO interface for a accelerometer
device/valio/motion_sensor.h : Value IO interface definition for motion sensors
device/valio/touchpad.h : Value IO interface for a touchpad
device/valio/uart_config.h : UART configuration driver API
Any library or application developer who does not see fit in existing attribute definition is free to define its own attributes.
Members [link]
Types [link]
- typedef error_t (dev_valio_cancel_t)(const struct device_valio_s *accessor, struct dev_valio_rq_s *rq)
- typedef void (dev_valio_request_t)(const struct device_valio_s *accessor, struct dev_valio_rq_s *rq)
- enum dev_valio_request_type_e
- struct dev_valio_rq_s
- struct device_valio_s
- struct driver_valio_s
Functions [link]
- void dev_valio_rq_done(struct dev_valio_rq_s *rq)
- struct dev_valio_rq_s * dev_valio_rq_from_kr(struct kroutine_s *kr)
- struct dev_valio_rq_s * dev_valio_rq_head(dev_request_queue_root_t *q)
- void dev_valio_rq_init(struct dev_valio_rq_s *rq, kroutine_exec_t *exec)
- void dev_valio_rq_init_immediate(struct dev_valio_rq_s *rq, kroutine_exec_t *exec)
- void dev_valio_rq_init_queue(struct dev_valio_rq_s *rq, kroutine_exec_t *exec, struct kroutine_queue_s *queue)
- void dev_valio_rq_init_seq(struct dev_valio_rq_s *rq, kroutine_exec_t *exec, struct kroutine_sequence_s *seq)
- struct dev_valio_rq_s * dev_valio_rq_pop(dev_request_queue_root_t *q)
- void dev_valio_rq_pushback(dev_request_queue_root_t *q, struct dev_valio_rq_s *rq)
- void dev_valio_rq_remove(dev_request_queue_root_t *q, struct dev_valio_rq_s *rq)
- struct dev_request_s * dev_valio_rq_s_base(struct dev_valio_rq_s *x)
- struct dev_valio_rq_s * dev_valio_rq_s_cast(struct dev_request_s *x)
- error_t dev_valio_wait_op(enum dev_valio_request_type_e type, const struct device_valio_s *accessor, uint16_t attribute, void *data)
- error_t dev_valio_wait_rq(const struct device_valio_s *acc, struct dev_valio_rq_s *rq)
- struct device_accessor_s * device_valio_s_base(struct device_valio_s *x)
- struct device_valio_s * device_valio_s_cast(struct device_accessor_s *x)
Macros [link]
Members detail [link]
#define DEV_VALIO_CANCEL(n) [link]
This macro is declared in device/class/valio.h source file, line 248.
See also dev_valio_request_t.
#define DEV_VALIO_REQUEST(n) [link]
This macro is declared in device/class/valio.h source file, line 234.
See also dev_valio_request_t.
#define DRIVER_VALIO_METHODS(prefix) [link]
This macro is declared in device/class/valio.h source file, line 271.
See also struct driver_valio_s.
#define __DEVICE_VALIO_H__ [link]
This macro is declared in device/class/valio.h source file, line 127.
typedef error_t (dev_valio_cancel_t)(const struct device_valio_s *accessor, struct dev_valio_rq_s *rq) [link]
This typedef is declared in device/class/valio.h source file, line 264.
This function is able to cancels a DEVICE_VALIO_WAIT_EVENT request which have previously been passed to the dev_valio_request_t function.
The function returns 0 if the request has been canceled or -EBUSY if the request has already ended or will terminate very soon. The request kroutine is not executed when this function returns 0.
The content of the data buffer is undefined when a request is canceled.
This declaration involves expansion of the DEV_VALIO_CANCEL macro.
typedef void (dev_valio_request_t)(const struct device_valio_s *accessor, struct dev_valio_rq_s *rq) [link]
This typedef is declared in device/class/valio.h source file, line 246.
This typedef enqueues a request.
The kroutine of the request may be executed from within this function. Please read Nested device request completion.
This declaration involves expansion of the DEV_VALIO_REQUEST macro.
See also Purpose and enum dev_valio_request_type_e.
enum dev_valio_request_type_e [link]
This enum is declared in device/class/valio.h source file, line 145.
This enum specifies the Value IO operation performed by a request.
| Identifier | Description |
|---|---|
| DEVICE_VALIO_READ | This queries the value of an attribute. When this operation is supported, multiple requests can be queued. The driver must sample the value and terminates all read requests as soon as possible. Depending on the attribute, an instantaneous or cumulative value is reported. Reading a value can not change the value for subsequent read requests. For instance, it must not clear an accumulator or pop a fifo. The data field of the request must always point to a buffer large enough to store the retrieved value. Depending on the attribute, the data pointer of the request may also be used to specify some query related parameters to the driver. The request may terminate with the -ENOTSUP error if either the attribute or operation is not supported. |
| DEVICE_VALIO_WRITE | This changes the value of an attribute. When this operation is supported, multiple requests can be queued and will be processed in order. The driver must take action to update the value and must not terminate the request until the change is effective. The data field of the request must always point to a buffer containing a properly initialized value. Depending on the attribute, the buffer may also be used to return a result. This can be the previous value, a feedback value or the actual value reached by the actuator for instance. It is implementation defined if DEVICE_VALIO_READ and DEVICE_VALIO_WRITE requests are pushed on the same queue. The request may terminate with the -ENOTSUP error if either the attribute or operation is not supported. The driver may report the -ERANGE error if the value is out of range. |
| DEVICE_VALIO_WAIT_EVENT | This waits for the value of an attribute to change or satisfy a given condition. When this operation is supported, the driver may optionally support submission of more than one such request. When multiple requests are supported, the order is not relevant and any request with a satisfied condition must terminate immediately. This operation never interferes with read and write requests. When the DEVICE_VALIO_READ operation is relevant for the attribute, the driver stores the new value into the buffer specified in data field of the request. In this case, it must point to a buffer large enough to store the retrieved value. Depending on the attribute, the data pointer of the request may also be used to specify the condition. This is not relevant when the attribute rather relies on a change notification. The request may terminate with the -ENOTSUP error if either the attribute or operation is not supported. The driver may report the -ERANGE error if the condition is out of range. The driver may report -EBUSY if it can not handle more such requests. This kind of request can be canceled by calling the dev_valio_cancel_t function of the driver. |
void dev_valio_rq_done(struct dev_valio_rq_s *rq) [link]
This function is declared in device/class/valio.h source file, line 232.
This function invokes or schedules execution of the valio request callback associated to the request. For use in device drivers.
struct dev_valio_rq_s * dev_valio_rq_from_kr(struct kroutine_s *kr) [link]
This function is declared in device/class/valio.h source file, line 232.
This function retrieves a pointer to the request when in the request completion callback routine.
struct dev_valio_rq_s * dev_valio_rq_head(dev_request_queue_root_t *q) [link]
This function is declared in device/class/valio.h source file, line 232.
This function returns the oldest valio request in the given queue. A NULL pointer is returned if the queue is empty. For use in device drivers.
void dev_valio_rq_init(struct dev_valio_rq_s *rq, kroutine_exec_t *exec) [link]
This function is declared in device/class/valio.h source file, line 232.
This function initializes the given valio request callback. This must be used before submitting the request to a driver.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
void dev_valio_rq_init_immediate(struct dev_valio_rq_s *rq, kroutine_exec_t *exec) [link]
This function is declared in device/class/valio.h source file, line 232.
This function initializes the given valio request callback. This must be used before submitting the request to a driver.
void dev_valio_rq_init_queue(struct dev_valio_rq_s *rq, kroutine_exec_t *exec, struct kroutine_queue_s *queue) [link]
This function is declared in device/class/valio.h source file, line 232.
This function initializes the given valio request callback. This must be used before submitting the request to a driver.
This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.
void dev_valio_rq_init_seq(struct dev_valio_rq_s *rq, kroutine_exec_t *exec, struct kroutine_sequence_s *seq) [link]
This function is declared in device/class/valio.h source file, line 232.
This function initializes the given valio request callback. This must be used before submitting the request to a driver.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
struct dev_valio_rq_s * dev_valio_rq_pop(dev_request_queue_root_t *q) [link]
This function is declared in device/class/valio.h source file, line 232.
This function removes and return the oldest valio request in the queue. A NULL pointer is returned if the queue is empty. For use in device drivers.
void dev_valio_rq_pushback(dev_request_queue_root_t *q, struct dev_valio_rq_s *rq) [link]
This function is declared in device/class/valio.h source file, line 232.
This function insert a new valio request at the end of the given queue. For use in device drivers.
void dev_valio_rq_remove(dev_request_queue_root_t *q, struct dev_valio_rq_s *rq) [link]
This function is declared in device/class/valio.h source file, line 232.
This function removes the specified valio request from the queue. For use in device drivers.
struct dev_valio_rq_s [link]
This struct is declared in device/class/valio.h source file, line 214.
This struct is the Value IO class request structure.
See also dev_valio_request_t.
| Field | Description |
|---|---|
| union <anonymous> { | |
| struct dev_request_s base; | |
| typeof(struct dev_request_s::error) error; | |
| typeof(struct dev_request_s::pvdata) pvdata; | |
| }; | |
| uint16_t attribute; | Attribute identifier |
| enum dev_valio_request_type_e type:2; | Operations |
| void * data; | Data buffer used to store the value. The byte size of the buffer is fixed for a given attribute identifier. |
struct dev_request_s * dev_valio_rq_s_base(struct dev_valio_rq_s *x) [link]
This function is declared in device/class/valio.h source file, line 232.
struct dev_valio_rq_s * dev_valio_rq_s_cast(struct dev_request_s *x) [link]
This function is declared in device/class/valio.h source file, line 232.
error_t dev_valio_wait_op(enum dev_valio_request_type_e type, const struct device_valio_s *accessor, uint16_t attribute, void *data) [link]
This function is declared in device/class/valio.h source file, line 296.
This function perform an operation and stop the scheduler context during the request.
This is available when CONFIG_DEVICE_VALIO and CONFIG_MUTEK_CONTEXT_SCHED are both defined.
See also dev_valio_wait_rq.
error_t dev_valio_wait_rq(const struct device_valio_s *acc, struct dev_valio_rq_s *rq) [link]
This function is declared in device/class/valio.h source file, line 279.
This function use the scheduler api to put current context in wait state during the request. This can only be called from a scheduler context.
This is available when CONFIG_MUTEK_CONTEXT_SCHED is defined.
struct device_valio_s [link]
This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 19 in device/class/valio.h source file, line 269.
This struct is the device accessor object type for the valio device class. This accessor must be initialized by calling the device_get_accessor function.
See also DRIVER_CLASS_VALIO, struct device_accessor_s and Device accessor.
| Field | Description |
|---|---|
| union <anonymous> { | |
| struct device_accessor_s base; | |
| struct <anonymous> { | |
| struct device_s * dev; | |
| struct driver_valio_s * api; | |
| uint_fast8_t number; | |
| }; | |
| }; |
struct device_accessor_s * device_valio_s_base(struct device_valio_s *x) [link]
This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 40 in device/class/valio.h source file, line 269.
This function casts a valio device accessor to a generic device accessor
struct device_valio_s * device_valio_s_cast(struct device_accessor_s *x) [link]
This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 33 in device/class/valio.h source file, line 269.
This function casts a generic device accessor to a valio device accessor
struct driver_valio_s [link]
This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 5 in device/class/valio.h source file, line 269.
This struct is the driver API descriptor for the valio device class.
See also DRIVER_CLASS_VALIO and struct driver_class_s.
| Field | Description |
|---|---|
| uint16_t class_; | |
| uint16_t ctx_offset; | |
| dev_valio_request_t * f_request; | |
| dev_valio_cancel_t * f_cancel; |