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

#include <stdint.h>

Rahix's avatar
Rahix committed
6
7
8
9
10
11
12
#ifndef __SPHINX_DOC
/* stddef.h is not recognized by hawkmoth for some odd reason */
#include <stddef.h>
#else
typedef unsigned int size_t;
#endif /* __SPHINX_DOC */

13
14
15
#include "FreeRTOS.h"
#include "queue.h"

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

19
20
21
/**
 * **Stream Descriptors**:
 *
22
23
24
25
 *    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.
26
27
 */
enum stream_descriptor {
koalo's avatar
koalo committed
28
	/** BHI160 */
29
	SD_BHI160_ACCELEROMETER,
koalo's avatar
koalo committed
30
	SD_BHI160_ORIENTATION,
koalo's avatar
koalo committed
31
	SD_BHI160_GYROSCOPE,
32
33
34
35
	/** Highest descriptor must always be ``SD_MAX``. */
	SD_MAX,
};

Rahix's avatar
Rahix committed
36
37
38
39
40
41
/**
 * 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:
 */
42
struct stream_info {
Rahix's avatar
Rahix committed
43
44
45
46
47
	/**
	 * A FreeRTOS queue handle.
	 *
	 * Management of this queue is the sensor drivers responsibility.
	 */
48
	QueueHandle_t queue;
Rahix's avatar
Rahix committed
49
	/** The size of one data packet (= queue element). */
50
	size_t item_size;
Rahix's avatar
Rahix committed
51
	/**
Rahix's avatar
Rahix committed
52
53
	 * An optional function to call before performing the read.  Set to
	 * ``NULL`` if unused.
Rahix's avatar
Rahix committed
54
55
56
57
	 *
	 * ``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
58
59
	 *
	 * The function registered here should never block for a longer time.
Rahix's avatar
Rahix committed
60
	 */
61
62
63
64
65
66
	int (*poll_stream)();
};

/**
 * Register a stream so it can be read from Epicardium API.
 *
Rahix's avatar
Rahix committed
67
 * :param int sd: Stream Descriptor.  Must be from the :c:type:`stream_descriptor` enum.
68
69
70
71
72
 * :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.
73
 *    - ``-EBUSY``: The descriptor lock could not be acquired.
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 */
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``.
88
 *    - ``-EBUSY``: The descriptor lock could not be acquired.
89
90
91
92
93
94
95
96
97
 */
int stream_deregister(int sd, struct stream_info *stream);

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

#endif /* STREAM_H */