Line data Source code
1 0 : /*
2 : * Copyright (c) 2021 Intel Corporation
3 : * SPDX-License-Identifier: Apache-2.0
4 : */
5 : #ifndef ZEPHYR_INCLUDE_SYS_WINSTREAM_H_
6 : #define ZEPHYR_INCLUDE_SYS_WINSTREAM_H_
7 :
8 : #include <stdint.h>
9 :
10 : /** @brief Lockless shared memory byte stream IPC
11 : *
12 : * The sys_winstream utility implements a unidirectional byte stream
13 : * with simple read/write semantics on top of a memory region shared
14 : * by the writer and reader. It requires no locking or
15 : * synchronization mechanisms beyond reliable ordering of memory
16 : * operations, and so is a good fit for use with heterogeneous shared
17 : * memory environments (for example, where Zephyr needs to talk to
18 : * other CPUs in the system running their own software).
19 : *
20 : * This object does not keep track of the last sequence number read: the
21 : * reader must keep that state and provide it on every read
22 : * operation. After reaching "steady state", 'end' and 'start' are one
23 : * byte apart because the buffer is always full.
24 : */
25 1 : struct sys_winstream {
26 0 : uint32_t len; /* Length of data[] in bytes */
27 0 : uint32_t start; /* Index of first valid byte in data[] */
28 0 : uint32_t end; /* Index of next byte in data[] to write */
29 0 : uint32_t seq; /* Mod-2^32 index of 'end' since stream init */
30 0 : uint8_t data[];
31 : };
32 :
33 : /** @brief Construct a sys_winstream from a region of memory
34 : *
35 : * This function initializes a sys_winstream in an arbitrarily-sized
36 : * region of memory, returning the resulting object (which is
37 : * guaranteed to be at the same address as the buffer). The memory
38 : * must (obviously) be shared between the reader and writer, and all
39 : * operations to it must be coherent and consistently ordered.
40 : *
41 : * @param buf Pointer to a region of memory to contain the stream
42 : * @param buflen Length of the buffer, must be large enough to contain
43 : * the struct sys_winstream and at least one byte of
44 : * data.
45 : * @return A pointer to an initialized sys_winstream (same address as
46 : * the buf parameter).
47 : */
48 1 : static inline struct sys_winstream *sys_winstream_init(void *buf, int buflen)
49 : {
50 : struct sys_winstream *ws = buf, tmp = { .len = buflen - sizeof(*ws) };
51 :
52 : *ws = tmp;
53 : return ws;
54 : }
55 :
56 : /** @brief Write bytes to a sys_winstream
57 : *
58 : * This function writes the specified number of bytes into the stream.
59 : * It will always return synchronously, it does not block or engage in
60 : * any kind of synchronization beyond memory write ordering. Any
61 : * bytes passed beyond what can be stored in the buffer will be
62 : * silently dropped, but readers can detect their presence via the
63 : * sequence number.
64 : *
65 : * @param ws A sys_winstream to which to write
66 : * @param data Pointer to bytes to be written
67 : * @param len Number of bytes to write
68 : */
69 1 : void sys_winstream_write(struct sys_winstream *ws,
70 : const char *data, uint32_t len);
71 :
72 : /** @brief Read bytes from a sys_winstream
73 : *
74 : * This function will read bytes from a sys_winstream into a specified
75 : * buffer. It will always return in constant time, it does not block
76 : * or engage in any kind of synchronization beyond memory ordering.
77 : * The number of bytes read into the buffer will be returned, but note
78 : * that it is possible that an underflow can occur if the writer gets
79 : * ahead of our context. That situation can be detected via the
80 : * sequence number returned via a pointer (i.e. if "*seq != old_seq +
81 : * return_value", an underflow occurred and bytes were dropped).
82 : *
83 : * @param ws A sys_winstream from which to read
84 : * @param seq A pointer to an integer containing the last sequence
85 : * number read from the stream, or zero to indicate "start
86 : * of stream". It is updated in place and returned for
87 : * future calls and for detecting underflows.
88 : * @param buf A buffer into which to store the data read
89 : * @param buflen The length of buf in bytes
90 : * @return The number of bytes written into the buffer
91 : */
92 1 : uint32_t sys_winstream_read(struct sys_winstream *ws,
93 : uint32_t *seq, char *buf, uint32_t buflen);
94 :
95 : #endif /* ZEPHYR_INCLUDE_SYS_WINSTREAM_H_ */
|
