grblHAL core  20250922
stream.h
Go to the documentation of this file.
1 /*
2  stream.h - high level (serial) stream handling
3 
4  Part of grblHAL
5 
6  Copyright (c) 2019-2025 Terje Io
7 
8  grblHAL is free software: you can redistribute it and/or modify
9  it under the terms of the GNU General Public License as published by
10  the Free Software Foundation, either version 3 of the License, or
11  (at your option) any later version.
12 
13  grblHAL is distributed in the hope that it will be useful,
14  but WITHOUT ANY WARRANTY; without even the implied warranty of
15  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  GNU General Public License for more details.
17 
18  You should have received a copy of the GNU General Public License
19  along with grblHAL. If not, see <http://www.gnu.org/licenses/>.
20 */
21 
28 #ifndef _STREAM_H_
29 #define _STREAM_H_
30 
31 #define ASCII_SOH 0x01
32 #define ASCII_STX 0x02
33 #define ASCII_ETX 0x03
34 #define ASCII_EOT 0x04
35 #define ASCII_ENQ 0x05
36 #define ASCII_ACK 0x06
37 #define ASCII_BS 0x08
38 #define ASCII_TAB 0x09
39 #define ASCII_LF 0x0A
40 #define ASCII_CR 0x0D
41 #define ASCII_XON 0x11
42 #define ASCII_XOFF 0x13
43 #define ASCII_NAK 0x15
44 #define ASCII_EOF 0x1A
45 #define ASCII_CAN 0x18
46 #define ASCII_EM 0x19
47 #define ASCII_ESC 0x1B
48 #define ASCII_DEL 0x7F
49 #define ASCII_EOL "\r\n"
50 
51 #ifndef RX_BUFFER_SIZE
52 #define RX_BUFFER_SIZE 1024 // must be a power of 2
53 #endif
54 
55 #ifndef TX_BUFFER_SIZE
56 #define TX_BUFFER_SIZE 512 // must be a power of 2
57 #endif
58 
59 #ifndef BLOCK_TX_BUFFER_SIZE
60 #define BLOCK_TX_BUFFER_SIZE 256
61 #endif
62 
63 // Serial baud rate
64 #ifndef BAUD_RATE
65 #define BAUD_RATE 115200
66 #endif
67 
68 // Value to be returned from input stream when no data is available
69 #ifndef SERIAL_NO_DATA
70 #define SERIAL_NO_DATA -1
71 #endif
72 
73 #define BUFNEXT(ptr, buffer) ((ptr + 1) & (sizeof(buffer.data) - 1))
74 #define BUFCOUNT(head, tail, size) ((head >= tail) ? (head - tail) : (size - tail + head))
75 
76 #include <stddef.h>
77 #include <stdint.h>
78 #include <stdbool.h>
79 
80 #include "vfs.h"
81 
82 typedef enum {
88  StreamType_SDCard, // deprecated, use StreamType_File instead
93 
94 typedef enum {
99 
100 typedef enum {
104 
105 typedef enum {
111 
112 typedef enum {
119 
120 typedef union {
121  uint8_t value;
122  struct {
123  uint8_t width :2,
125  parity :3,
126  unused :1;
127  };
129 
130 typedef union {
131  uint8_t value;
132  struct {
133  uint8_t dtr :1,
134  rts :1,
135  unused :6;
136  };
138 
142 typedef bool (*stream_is_connected_ptr)(void);
143 
147 typedef uint16_t (*get_stream_buffer_count_ptr)(void);
148 
152 typedef int16_t (*stream_read_ptr)(void);
153 
159 typedef void (*stream_write_ptr)(const char *s);
160 
165 typedef void (*stream_write_n_ptr)(const char *s, uint16_t len);
166 
167 
171 typedef bool (*stream_write_char_ptr)(const char c);
172 
178 typedef bool (*enqueue_realtime_command_ptr)(char c);
179 
180 
189 typedef bool (*enqueue_realtime_command2_ptr)(char c);
190 
191 
200 
205 typedef bool (*set_format_ptr)(serial_format_t format);
206 
211 typedef bool (*set_baud_rate_ptr)(uint32_t baud_rate);
212 
214 typedef void (*flush_stream_buffer_ptr)(void);
215 
221 typedef void (*cancel_read_buffer_ptr)(void);
222 
241 typedef bool (*suspend_read_ptr)(bool await);
242 
252 typedef bool (*disable_rx_stream_ptr)(bool disable);
253 
259 
260 typedef union {
261  uint8_t value;
262  struct {
263  uint8_t claimable :1,
269  unused :2;
270  };
272 
273 typedef union {
274  uint8_t value;
275  struct {
276  uint8_t webui_connected :1,
277  is_usb :1,
279  passthru :1,
280  unused :4;
281  };
283 
285 typedef struct {
287  uint8_t instance;
309 } io_stream_t;
310 
311 typedef const io_stream_t *(*stream_claim_ptr)(uint32_t baud_rate);
312 
313 typedef struct {
315  uint8_t instance;
319 
320 typedef bool (*stream_enumerate_callback_ptr)(io_stream_properties_t const *properties);
321 
322 typedef struct io_stream_details {
323  uint8_t n_streams;
327 
328 // The following structures and functions are not referenced in the core code, may be used by drivers
329 
330 typedef struct {
331  volatile uint_fast16_t head;
332  volatile uint_fast16_t tail;
333  volatile bool rts_state;
334  bool overflow;
335  bool backup;
336  char data[RX_BUFFER_SIZE];
338 
339 typedef struct {
340  volatile uint_fast16_t head;
341  volatile uint_fast16_t tail;
342  char data[TX_BUFFER_SIZE];
344 
345 typedef struct {
346  uint_fast16_t length;
347  uint_fast16_t max_length;
348  char *s;
351 
352 // double buffered tx stream
353 typedef struct {
354  uint_fast16_t length;
355  uint_fast16_t max_length;
356  char *s;
359  char data2[BLOCK_TX_BUFFER_SIZE];
361 
362 #ifdef __cplusplus
363 extern "C" {
364 #endif
365 
369 int16_t stream_get_null (void);
370 
376  bool stream_rx_suspend (stream_rx_buffer_t *rxbuffer, bool suspend);
377 
379 
380 bool stream_mpg_register (const io_stream_t *stream, bool rx_only, stream_write_char_ptr write_char);
381 
386 bool stream_mpg_enable (bool on);
387 
388 void stream_mpg_set_mode (void *data);
389 
390 bool stream_mpg_check_enable (char c);
391 
392 bool stream_buffer_all (char c);
393 
394 bool stream_tx_blocking (void);
395 
396 bool stream_enqueue_realtime_command (char c);
397 
399 
401 
402 bool stream_connect (const io_stream_t *stream);
403 
404 bool stream_connect_instance (uint8_t instance, uint32_t baud_rate);
405 
406 void stream_disconnect (const io_stream_t *stream);
407 
408 bool stream_connected (void);
409 
410 const io_stream_t *stream_get_base (void);
411 
413 
414 const io_stream_t *stream_null_init (uint32_t baud_rate);
415 
416 io_stream_t const *stream_open_instance (uint8_t instance, uint32_t baud_rate, stream_write_char_ptr rx_handler, const char *description);
417 
418 bool stream_set_description (const io_stream_t *stream, const char *description);
419 
420 void debug_printf(const char *fmt, ...);
421 
422 #if defined(DEBUG) || defined(DEBUGOUT)
423 #define DEBUG_PRINT 1
424 #ifdef DEBUGOUT
425 void debug_write (const char *s);
426 void debug_writeln (const char *s);
427 bool debug_stream_init (void);
428 #endif
429 #else
430 #define DEBUG_PRINT 0
431 #endif
432 
433 #define debug_print(fmt, ...) \
434  do { if(DEBUG_PRINT) debug_printf(fmt, __VA_ARGS__); } while(0)
435 
436 #ifdef __cplusplus
437 }
438 #endif
439 
440 #endif
uint8_t instance
Definition: stream.c:424
uint32_t baud_rate
Definition: stream.c:425
bool(* enqueue_realtime_command_ptr)(char c)
Pointer to function for extracting real-time commands from the input stream and enqueue them for proc...
Definition: stream.h:178
void(* stream_write_n_ptr)(const char *s, uint16_t len)
Pointer to function for writing a n character long string to the output stream.
Definition: stream.h:165
bool stream_connected(void)
Definition: stream.c:186
serial_stopbits_t
Definition: stream.h:105
@ Serial_StopBits0_5
Definition: stream.h:109
@ Serial_StopBits1
Definition: stream.h:106
@ Serial_StopBits2
Definition: stream.h:108
@ Serial_StopBits1_5
Definition: stream.h:107
void stream_disconnect(const io_stream_t *stream)
Definition: stream.c:446
stream_suspend_state_t
Definition: stream.h:94
@ StreamSuspend_Pending
Definition: stream.h:96
@ StreamSuspend_Active
Definition: stream.h:97
@ StreamSuspend_Off
Definition: stream.h:95
uint16_t(* get_stream_buffer_count_ptr)(void)
Pointer to function for getting number of characters available or free in a stream buffer.
Definition: stream.h:147
bool(* stream_is_connected_ptr)(void)
Pointer to function for getting stream connected status.
Definition: stream.h:142
void(* stream_write_ptr)(const char *s)
Pointer to function for writing a null terminated string to the output stream.
Definition: stream.h:159
bool stream_enumerate_streams(stream_enumerate_callback_ptr callback)
Definition: stream.c:88
bool(* stream_enumerate_callback_ptr)(io_stream_properties_t const *properties)
Definition: stream.h:320
bool(* set_format_ptr)(serial_format_t format)
Pointer to function for setting the stream format.
Definition: stream.h:205
bool stream_mpg_check_enable(char c)
Definition: stream.c:474
void stream_mpg_set_mode(void *data)
Definition: stream.c:469
bool stream_enqueue_realtime_command(char c)
Definition: stream.c:174
bool stream_tx_blocking(void)
Definition: stream.c:109
void(* on_linestate_changed_ptr)(serial_linestate_t state)
Pointer to function for handling line state changed events.
Definition: stream.h:258
bool(* stream_write_char_ptr)(const char c)
Pointer to function for writing a single character to the output stream.
Definition: stream.h:171
io_stream_t const * stream_open_instance(uint8_t instance, uint32_t baud_rate, stream_write_char_ptr rx_handler, const char *description)
Definition: stream.c:452
void(* cancel_read_buffer_ptr)(void)
Pointer to function for flushing the input buffer and inserting an ASCII_CAN character.
Definition: stream.h:221
void stream_register_streams(io_stream_details_t *details)
Definition: stream.c:80
io_stream_flags_t stream_get_flags(io_stream_t stream)
Definition: stream.c:382
bool stream_mpg_enable(bool on)
Function for enabling/disabling input from a secondary input stream.
Definition: stream.c:534
#define RX_BUFFER_SIZE
Definition: stream.h:52
int16_t stream_get_null(void)
Dummy function for reading data from a virtual empty input buffer.
Definition: stream.c:119
bool stream_connect_instance(uint8_t instance, uint32_t baud_rate)
Definition: stream.c:437
const io_stream_t * stream_null_init(uint32_t baud_rate)
Definition: stream.c:641
void debug_printf(const char *fmt,...)
Definition: stream.c:787
bool stream_connect(const io_stream_t *stream)
Definition: stream.c:413
bool(* enqueue_realtime_command2_ptr)(char c)
Optional, but recommended, pointer to function for enqueueing realtime command characters.
Definition: stream.h:189
bool stream_mpg_register(const io_stream_t *stream, bool rx_only, stream_write_char_ptr write_char)
Definition: stream.c:487
void(* flush_stream_buffer_ptr)(void)
Pointer to function for flushing a stream buffer.
Definition: stream.h:214
stream_suspend_state_t stream_is_rx_suspended(void)
Definition: stream.c:141
#define TX_BUFFER_SIZE
Definition: stream.h:56
bool stream_set_description(const io_stream_t *stream, const char *description)
Definition: stream.c:401
bool(* set_baud_rate_ptr)(uint32_t baud_rate)
Pointer to function for setting the stream baud rate.
Definition: stream.h:211
struct io_stream_details io_stream_details_t
const io_stream_t *(* stream_claim_ptr)(uint32_t baud_rate)
Definition: stream.h:311
serial_parity_t
Definition: stream.h:112
@ Serial_ParitySpace
Definition: stream.h:117
@ Serial_ParityNone
Definition: stream.h:113
@ Serial_ParityMark
Definition: stream.h:116
@ Serial_ParityEven
Definition: stream.h:114
@ Serial_ParityOdd
Definition: stream.h:115
bool stream_rx_suspend(stream_rx_buffer_t *rxbuffer, bool suspend)
Function for blocking reads from or restoring an input buffer.
Definition: stream.c:146
int16_t(* stream_read_ptr)(void)
Pointer to function for reading a single character from a input stream.
Definition: stream.h:152
#define BLOCK_TX_BUFFER_SIZE
Definition: stream.h:60
bool stream_buffer_all(char c)
Definition: stream.c:169
bool(* disable_rx_stream_ptr)(bool disable)
Pointer to function for disabling/enabling stream input.
Definition: stream.h:252
enqueue_realtime_command_ptr(* set_enqueue_rt_handler_ptr)(enqueue_realtime_command_ptr handler)
Pointer to function for setting the enqueue realtime commands handler.
Definition: stream.h:199
stream_type_t
Definition: stream.h:82
@ StreamType_Bluetooth
Definition: stream.h:85
@ StreamType_Telnet
Definition: stream.h:86
@ StreamType_SDCard
Definition: stream.h:88
@ StreamType_MPG
Definition: stream.h:84
@ StreamType_WebSocket
Definition: stream.h:87
@ StreamType_File
Definition: stream.h:89
@ StreamType_Null
Definition: stream.h:91
@ StreamType_Serial
Definition: stream.h:83
@ StreamType_Redirected
Definition: stream.h:90
serial_width_t
Definition: stream.h:100
@ Serial_8bit
Definition: stream.h:101
@ Serial_7bit
Definition: stream.h:102
bool(* suspend_read_ptr)(bool await)
Pointer to function for blocking reads from and restoring a input buffer.
Definition: stream.h:241
const io_stream_t * stream_get_base(void)
Definition: stream.c:377
Definition: stream.h:322
struct io_stream_details * next
Definition: stream.h:325
io_stream_properties_t * streams
Definition: stream.h:324
uint8_t n_streams
Definition: stream.h:323
Definition: stream.h:313
uint8_t instance
Instance of stream type, starts from 0.
Definition: stream.h:315
stream_type_t type
Type of stream.
Definition: stream.h:314
stream_claim_ptr claim
Definition: stream.h:317
io_stream_flags_t flags
Definition: stream.h:316
Properties and handlers for stream I/O.
Definition: stream.h:285
uint8_t instance
Instance of stream type, starts from 0.
Definition: stream.h:287
flush_stream_buffer_ptr reset_read_buffer
Handler for flushing the input buffer.
Definition: stream.h:296
stream_write_char_ptr write_char
Handler for writing a single character to current stream only.
Definition: stream.h:293
set_enqueue_rt_handler_ptr set_enqueue_rt_handler
Handler for setting the enqueue realtime command character handler.
Definition: stream.h:298
set_format_ptr set_format
Optional handler for setting the stream format.
Definition: stream.h:306
stream_write_ptr write
Handler for writing string to current output stream only.
Definition: stream.h:291
enqueue_realtime_command2_ptr enqueue_rt_command
(Optional) handler for enqueueing a realtime command character.
Definition: stream.h:294
io_stream_state_t state
Optional status flags such as connected status.
Definition: stream.h:288
get_stream_buffer_count_ptr get_rx_buffer_count
Optional handler for getting number of characters in the input buffer.
Definition: stream.h:302
stream_type_t type
Type of stream.
Definition: stream.h:286
on_linestate_changed_ptr on_linestate_changed
Optional handler to be called when line state changes. Set by client.
Definition: stream.h:307
stream_write_n_ptr write_n
Optional handler for writing n characters to current output stream only. Required for Modbus support.
Definition: stream.h:300
get_stream_buffer_count_ptr get_tx_buffer_count
Optional handler for getting number of characters in the output buffer(s). Count shall include any un...
Definition: stream.h:303
disable_rx_stream_ptr disable_rx
Optional handler for disabling/enabling a stream. Recommended?
Definition: stream.h:301
set_baud_rate_ptr set_baud_rate
Optional handler for setting the stream baud rate. Required for Modbus support, recommended for Bluet...
Definition: stream.h:305
stream_is_connected_ptr is_connected
Handler for getting stream connected status.
Definition: stream.h:289
cancel_read_buffer_ptr cancel_read_buffer
Handler for flushing the input buffer and inserting an ASCII_CAN character.
Definition: stream.h:297
stream_write_ptr write_all
Handler for writing string to all active output streams.
Definition: stream.h:292
vfs_file_t * file
File handle, non-null if streaming from a file.
Definition: stream.h:308
stream_read_ptr read
Handler for reading a single character from the input stream.
Definition: stream.h:295
flush_stream_buffer_ptr reset_write_buffer
Optional handler for flushing the output buffer. Any transmit FIFO shall be flushed as well....
Definition: stream.h:304
get_stream_buffer_count_ptr get_rx_buffer_free
Handler for getting number of free characters in the input buffer.
Definition: stream.h:290
suspend_read_ptr suspend_read
Optional handler for saving away and restoring the current input buffer.
Definition: stream.h:299
Definition: stream.h:353
bool use_tx2data
Definition: stream.h:357
uint_fast16_t length
Definition: stream.h:354
uint_fast16_t max_length
Definition: stream.h:355
char * s
Definition: stream.h:356
Definition: stream.h:345
uint_fast16_t length
Definition: stream.h:346
uint_fast16_t max_length
Definition: stream.h:347
char * s
Definition: stream.h:348
Definition: stream.h:330
bool overflow
Definition: stream.h:334
volatile uint_fast16_t head
Definition: stream.h:331
volatile bool rts_state
Definition: stream.h:333
bool backup
Definition: stream.h:335
volatile uint_fast16_t tail
Definition: stream.h:332
Definition: stream.h:339
volatile uint_fast16_t head
Definition: stream.h:340
volatile uint_fast16_t tail
Definition: stream.h:341
Definition: vfs.h:80
Definition: stream.h:260
uint8_t can_set_baud
Definition: stream.h:265
uint8_t claimed
Definition: stream.h:264
uint8_t value
Definition: stream.h:261
uint8_t rx_only
Definition: stream.h:266
uint8_t modbus_ready
Definition: stream.h:267
uint8_t rts_handshake
Definition: stream.h:268
uint8_t claimable
Definition: stream.h:263
uint8_t unused
Definition: stream.h:269
Definition: stream.h:273
uint8_t is_usb
Definition: stream.h:277
uint8_t value
Definition: stream.h:274
uint8_t passthru
Set when stream is in passthru mode.
Definition: stream.h:279
uint8_t webui_connected
Definition: stream.h:276
uint8_t linestate_event
Set when driver supports on_linestate_changed event.
Definition: stream.h:278
uint8_t unused
Definition: stream.h:280
Definition: stream.h:120
uint8_t width
Definition: stream.h:123
uint8_t value
Definition: stream.h:121
uint8_t stopbits
Definition: stream.h:124
uint8_t parity
Definition: stream.h:125
uint8_t unused
Definition: stream.h:126
Definition: stream.h:130
uint8_t rts
Definition: stream.h:134
uint8_t dtr
Definition: stream.h:133
uint8_t value
Definition: stream.h:131
uint8_t unused
Definition: stream.h:135