stream.h 3.01 KB
Newer Older
1
2
3
4
5
#ifndef STREAM_H
#define STREAM_H

#include <stdint.h>

Rahix's avatar
Rahix committed
6
#ifndef __SPHINX_DOC
Rahix's avatar
Rahix committed
7
/* Some headers are not recognized by hawkmoth for some odd reason */
Rahix's avatar
Rahix committed
8
9
#include <stddef.h>

10
11
#include "FreeRTOS.h"
#include "queue.h"
Rahix's avatar
Rahix committed
12
13
14
15
#else
typedef unsigned int size_t;
typedef void *QueueHandle_t;
#endif /* __SPHINX_DOC */
16

17
18
19
/* Time to wait for the descriptor table lock to become available */
#define STREAM_MUTEX_WAIT pdMS_TO_TICKS(100)

20
21
22
/**
 * **Stream Descriptors**:
 *
23
24
25
26
 *    This enum defines all known stream descriptors.  Internally, the stream
 *    module allocates an array slot for each ID defined here.  For that to
 *    work, :c:macro:`SD_MAX` must be greater than the highest defined ID.
 *    Please keep IDs in sequential order.
27
28
 */
enum stream_descriptor {
29
	/** BHI160 Accelerometer */
30
	SD_BHI160_ACCELEROMETER,
31
	/** BHI160 Magnetometer */
32
	SD_BHI160_MAGNETOMETER,
33
	/** BHI160 Orientation Sensor */
koalo's avatar
koalo committed
34
	SD_BHI160_ORIENTATION,
35
	/** BHI160 Gyroscope */
koalo's avatar
koalo committed
36
	SD_BHI160_GYROSCOPE,
37
	/** MAX30001 ECG */
schneider's avatar
schneider committed
38
	SD_MAX30001_ECG,
39
	SD_MAX86150,
40
41
42
43
	/** Highest descriptor must always be ``SD_MAX``. */
	SD_MAX,
};

Rahix's avatar
Rahix committed
44
45
46
47
48
49
/**
 * Stream Information Object.
 *
 * This struct contains the information necessary for :c:func:`epic_stream_read`
 * to read from a sensor's stream.  This consists of:
 */
50
struct stream_info {
Rahix's avatar
Rahix committed
51
52
53
54
55
	/**
	 * A FreeRTOS queue handle.
	 *
	 * Management of this queue is the sensor drivers responsibility.
	 */
56
	QueueHandle_t queue;
Rahix's avatar
Rahix committed
57
	/** The size of one data packet (= queue element). */
58
	size_t item_size;
Rahix's avatar
Rahix committed
59
	/**
Rahix's avatar
Rahix committed
60
61
	 * An optional function to call before performing the read.  Set to
	 * ``NULL`` if unused.
Rahix's avatar
Rahix committed
62
63
64
65
	 *
	 * ``poll_stream()`` is intended for sensors who passively collect data.
	 * A sensor driver might for example retrieve the latest samples in this
	 * function instead of actively polling in a task loop.
Rahix's avatar
Rahix committed
66
67
	 *
	 * The function registered here should never block for a longer time.
Rahix's avatar
Rahix committed
68
	 */
69
70
71
72
73
74
	int (*poll_stream)();
};

/**
 * Register a stream so it can be read from Epicardium API.
 *
Rahix's avatar
Rahix committed
75
 * :param int sd: Stream Descriptor.  Must be from the :c:type:`stream_descriptor` enum.
76
77
78
79
80
 * :param stream_info stream: Stream info.
 * :returns: ``0`` on success or a negative value on error.  Possible errors:
 *
 *    - ``-EINVAL``: Out of range sensor descriptor.
 *    - ``-EACCES``: Stream already registered.
81
 *    - ``-EBUSY``: The descriptor lock could not be acquired.
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 */
int stream_register(int sd, struct stream_info *stream);

/**
 * Deregister a stream.
 *
 * :param int sd:  Stream Descriptor.
 * :param stream_info stream: The stream which should be registered for the
 *    stream ``sd``.  If a different stream is registered, this function
 *    will return an error.
 * :returns: ``0`` on success or a negative value on error.  Possible errors:
 *
 *    - ``-EINVAL``: Out of range sensor descriptor.
 *    - ``-EACCES``: Stream ``stream`` was not registered for ``sd``.
96
 *    - ``-EBUSY``: The descriptor lock could not be acquired.
97
98
99
100
101
102
103
104
105
 */
int stream_deregister(int sd, struct stream_info *stream);

/*
 * Initialize stream interface.  Called by main().
 */
int stream_init();

#endif /* STREAM_H */