hal_stream.3hal
1 .TH hal_stream "3hal" "2006-10-12" "LinuxCNC Documentation" "HAL" 2 .de FU 3 .sp 4 .ti -4 5 \\$* 6 .. 7 .de FF 8 .br 9 .ti -4 10 \\$* 11 .. 12 .SH NAME 13 14 hal_stream \- non-blocking realtime streams 15 16 .SH SYNOPSIS 17 18 .FU .B #include <hal.h> 19 .FU int hal_stream_create(hal_stream_t *stream, int comp_id, int key, int depth, const char *typestring); 20 .FF void hal_stream_destroy(hal_stream_t *stream); 21 .FF int hal_stream_attach(hal_stream_t *stream, int comp_id, int key, const char *typestring); 22 .FF int hal_stream_detach(hal_stream_t *stream); 23 24 .FU int hal_stream_element_count(hal_stream_t *stream); 25 .FF hal_type_t hal_stream_element_type(hal_stream_t *stream, int idx); 26 .FF int hal_stream_depth(hal_stream_t *stream); 27 .FF int hal_stream_maxdepth(hal_stream_t *stream); 28 .FF int hal_stream_num_underruns(hal_stream_t *stream); 29 .FF int hal_stream_num_overruns(hal_stream_t *stream); 30 31 .FU int hal_stream_read(hal_stream_t *stream, union hal_stream_data *buf, unsigned *sampleno); 32 .FF bool hal_stream_readable(hal_stream_t *stream); 33 34 .FU int hal_stream_write(hal_stream_t *stream, union hal_stream_data *buf); 35 .FF bool hal_stream_writable(hal_stream_t *stream); 36 37 .FU .B #ifdef ULAPI 38 .FF void hal_stream_wait_writable(hal_stream_t *stream, sig_atomic_t *stop); 39 .FF void hal_stream_wait_readable(hal_stream_t *stream, sig_atomic_t *stop); 40 .FF .B #endif 41 42 43 .SH DESCRIPTION 44 A HAL stream provides a limited ability for two components to communicate 45 data which does not fit within the model of HAL pins. A reader and a writer 46 must agree on a 47 .I key 48 (32-bit integer identifier) and a data structure 49 specified by 50 .I typestring 51 . They must also agree which component (the first one loaded) 52 will 53 .B hal_stream_create 54 the stream, and wich component (the second one loaded) will 55 .B hal_stream_attach 56 to the already-created stream. 57 58 The userspace part can be 59 .BR halstreamer " or " halsampler . 60 In the case of 61 .B halstreamer 62 the key is 0x48535430 plus the channel number. In the case of 63 .B halsampler 64 the key is 0x48534130 plus the channel number. 65 66 .SS \fBhal_stream_create\fR 67 Create the given stream, initializing the \fIstream\fR which is passed by 68 reference. If is an undiagnosed error if a stream has already been created with the same \fIkey\fR. 69 70 .SS \fBhal_stream_destroy\fR 71 Destroy the given stream. It is an undiagnosed error if the stream is still attached by another component. It is an undiagnosed error if the stream was attached with 72 .B hal_stream_attach 73 rather than created with 74 .BR hal_stream_create . 75 It is an undiagnosed error if the call to 76 .B hal_stream_destroy 77 is omitted. 78 79 .SS \fBhal_stream_attach\fR 80 Attach the given stream, which was already created by 81 .BR hal_stream_create . 82 If the typestring is specified, this call fails if it does not match the 83 typestring the stream was created with. If the typestring argument is NULL, 84 then any typestring is accepted. 85 86 .SS \fBhal_stream_detach\fR 87 Detach the given stream. It is an undiagnosed error if the stream was created with 88 .B hal_stream_create 89 rather than attached with 90 .BR hal_stream_attach . 91 It is an undiagnosed error if the call to 92 .B hal_stream_detach 93 is omitted. 94 95 .SS \fBhal_stream_element_count\fR 96 Returns the number of pins. 97 98 .SS \fBhal_stream_element_type\fR 99 Returns the type of the given pin number. 100 101 .SS \fBhal_stream_readable\fR 102 Returns true if the stream has at least one sample to read 103 .SS \fBhal_stream_read\fR 104 If the stream has one sample to read, stores it in buf. 105 .SS \fBhal_stream_writable\fR 106 Returns true if the stream has room for at least one sample to be written. 107 .SS \fBhal_stream_depth\fR 108 Returns the number of samples waiting to be read. 109 .SS \fBhal_stream_maxdepth\fR 110 Returns the 111 .B depth 112 argument that the stream was created with. 113 .SS \fBhal_stream_num_overruns\fR 114 Returns a number which is incremented each time 115 .B hal_stream_write 116 is called without space available. 117 .SS \fBhal_stream_num_underruns\fR 118 Returns a number which is incremented each time 119 .B hal_stream_read 120 is called without a sample available. 121 122 .SS \fBhal_stream_wait_readable\fR 123 Waits until the stream is readable or the stop flag is set. 124 125 .SS \fBhal_stream_wait_writable\fR 126 Waits until the stream is writable or the stop flag is set. 127 128 .SS \fBhal_stream_read\fR 129 Reads a record from stream. If successful, it is stored 130 in the given buffer. Optionally, the sample number can be retrieved. 131 If no sample is available, 132 .I num_underruns 133 is incremented. It is an undetected error if more than one component or 134 real-time function calls 135 .B hal_stream_read 136 concurrently. 137 138 .SS \fBhal_stream_write\fR 139 Writes a record to the stream. If successful, it copied from the given 140 buffer. If no room is available, 141 .I num_overruns 142 is incremented. In either case, the internal 143 .I sampleno 144 value is incremented. 145 It is an undetected error if more than one component or 146 real-time function calls 147 .B hal_stream_write 148 concurrently. 149 150 .SH ARGUMENTS 151 .IP \fIstream\fR 152 A pointer to a stream object. In the case of 153 .BR hal_stream_create " and " hal_stream_attach 154 this is an uninitialized stream; in other cases, it must be a stream 155 created or attached by an earlier call and not yet detached or destroyed. 156 157 .IP \fIhal_id\fR 158 An HAL component identifier returned by an earlier call to \fBhal_init\fR. 159 160 .IP \fIkey\fR 161 The key for the shared memory segment. 162 163 .IP \fIdepth\fR 164 The number of samples that can be unread before any samples are lost (overrun) 165 166 .IP \fItypestring\fR 167 A typestring is a case-insensitive string which consists of one or more of the following type characters: 168 .RS 4 169 .IP B 170 for bool / hal_bit_t 171 .IP S 172 for int32_t / hal_s32_t 173 .IP U 174 for uint32_t / hal_u32_t 175 .IP F 176 for real_t / hal_float_t 177 .RE 178 A typestring is limited to 16 characters. 179 .IP \fIbuf\fR 180 A buffer big enough to hold all the data in one sample. 181 182 .IP \fIsampleno\fR 183 If non-NULL, the last sample number is stored here. Gaps in this sequence 184 indicate that an overrun occured between the previous read and this one. May 185 be NULL, in which case the sample number is not retrieved. 186 187 .IP \fIstop\fR 188 A pointer to a value which is monitored while waiting. If it is nonzero, 189 the wait operation returns early. This allows a wait call to be safely 190 terminated in the case of a signal. 191 192 .SH SAMPLE CODE 193 In the source tree under 194 .IR src/hal/components , 195 .BR sampler.c " and " streamer.c 196 are realtime components that read and write hal streams. 197 198 .SH REALTIME CONSIDERATIONS 199 .BR hal_stream_read ", " hal_stream_readable ", " hal_stream_write ", " hal_stream_writable ", " hal_stream_element_count ", " hal_tream_pin_type ", " hal_stream_depth ", " hal_stream_maxdepth ", " hal_stream_num_underruns ", " hal_stream_number_overruns 200 may be called from realtime code. 201 202 .BR hal_stream_wait_writable ", " hal_stream_wait_writable 203 may be called from ULAPI code. 204 205 Other functions may be called in any context, including realtime contexts. 206 .SH RETURN VALUE 207 .BR hal_stream_create " , " hal_stream_attach " , " hal_stream_read " , " hal_stream_write " , " hal_stream_detach " and " hal_stream_destroy 208 return an RTAPI status code. Other functions' return values are explained above. 209 210 .SH BUGS 211 The memory overhead of a stream can be large. Each element in a record uses 8 212 bytes, and the implicit sample number also uses 8 bytes. As a result, a stream 213 which is used to transport 8-bit values uses 94% of its memory as overhead. 214 However, for modest stream sizes this overhead is not important. (this memory 215 is part of its own shared memory region and does not count against the 216 HAL shared memory region used for pins, parameters and signals) 217 218 .SH SEE ALSO 219 .BR sampler (9), 220 .BR streamer (9), 221 .BR halsampler (1), 222 .BR halstreamer (1)