СИНТАКСИС
#include <hal.h>
int hal_stream_create(hal_stream_t* stream, int comp_id, int key, int depth, const char* typestring);
void hal_stream_destroy(hal_stream_t* stream);
int hal_stream_attach(hal_stream_t* stream, int comp_id, int key, const char* typestring);
int hal_stream_detach(hal_stream_t* stream);
int hal_stream_element_count(hal_stream_t* stream);
hal_type_t hal_stream_element_type(hal_stream_t* stream, int idx);
int hal_stream_depth(hal_stream_t* stream);
int hal_stream_maxdepth(hal_stream_t* stream);
int hal_stream_num_underruns(hal_stream_t* stream);
int hal_stream_num_overruns(hal_stream_t* stream);
int hal_stream_read(hal_stream_t* stream, hal_stream_data_u *buf, unsigned* sampleno);
bool hal_stream_readable(hal_stream_t* stream);
int hal_stream_write(hal_stream_t* stream, hal_stream_data_u *buf);
bool hal_stream_writable(hal_stream_t* stream);
#ifdef ULAPI
void hal_stream_wait_writable(hal_stream_t* stream, sig_atomic_t* stop);
void hal_stream_wait_readable(hal_stream_t* stream, sig_atomic_t* stop);
#endifОПИС
Потік HAL надає обмежену можливість двом компонентам обмінюватися даними, які не відповідають моделі контактів HAL. Читач і записувач повинні домовитися про key (32-бітний цілочисельний ідентифікатор) і структуру даних, визначену typestring. Вони також повинні домовитися, який компонент (перший завантажений) буде hal_stream_create потік, а який компонент (другий завантажений) буде hal_stream_attach до вже створеного потоку.
The non-realtime part can be halstreamer(1) or halsampler(1). In the case of halstreamer(1) the key is 0x48535430 plus the channel number. In the case of halsampler(1)* the key is 0x48534130 plus the channel number.
- hal_stream_create()
-
Створити заданий потік, ініціалізуючи stream, який передається за посиланням. Це недіагностована помилка, якщо потік вже створено з тим самим key.
- hal_stream_destroy()
-
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 hal_stream_attach() rather than created with hal_stream_create(). It is an undiagnosed error if the call to hal_stream_destroy() is omitted.
- hal_stream_attach()
-
Attach the given stream, which was already created by hal_stream_create(). If the typestring is specified, this call fails if it does not match the typestring the stream was created with. If the typestring argument is NULL, then any typestring is accepted.
- hal_stream_detach()
-
Detach the given stream. It is an undiagnosed error if the stream was created with hal_stream_create() rather than attached with hal_stream_attach(). It is an undiagnosed error if the call to hal_stream_detach() is omitted.
- hal_stream_element_count()
-
Повертає кількість контактів.
- hal_stream_element_type()
-
Повертає тип заданого PIN-коду.
- hal_stream_readable()
-
Повертає значення true, якщо потік має хоча б один зразок для зчитування
- hal_stream_read()
-
Якщо потік має один зразок для зчитування, він зберігається в buf.
- hal_stream_writable()
-
Повертає значення true, якщо в потоці є місце для запису хоча б одного семпла.
- hal_stream_depth()
-
Повертає кількість зразків, що очікують на зчитування.
- hal_stream_maxdepth()
-
Returns the depth argument that the stream was created with.
- hal_stream_num_overruns()
-
Returns a number which is incremented each time hal_stream_write() is called without space available.
- hal_stream_num_underruns()
-
Returns a number which is incremented each time hal_stream_read() is called without a sample available.
- hal_stream_wait_readable()
-
Waits until the stream is readable or the stop flag is set.
This function cannot be called from realtime. - hal_stream_wait_writable()
-
Waits until the stream is writable or the stop flag is set.
This function cannot be called from realtime. - hal_stream_read()
-
Reads a record from stream. If successful, it is stored in the given buffer. Optionally, the sample number can be retrieved. If no sample is available, num_underruns is incremented. It is an undetected error if more than one component or real-time function calls hal_stream_read() concurrently.
- hal_stream_write()
-
Writes a record to the stream. If successful, it copied from the given buffer. If no room is available, num_overruns is incremented. In either case, the internal sampleno value is incremented. It is an undetected error if more than one component or real-time function calls hal_stream_write() concurrently.
АРГУМЕНТИ
- stream
-
A pointer to a stream object. In the case of hal_stream_create() and hal_stream_attach() this is an uninitialized stream; in other cases, it must be a stream created or attached by an earlier call and not yet detached or destroyed.
- hal_id
-
An HAL component identifier returned by an earlier call to hal_init(3).
- key
-
Ключ для сегмента спільної пам’яті.
- depth
-
Кількість зразків, які можна прочитати, перш ніж будь-які зразки будуть втрачені (переповнені)
- typestring
-
A typestring is limited to 20 characters. A typestring is a case-insensitive string which consists of one or more of the following type characters:
-
B for bool / hal_bit_t
-
S for rtapi_s32 / hal_s32_t
-
U for rtapi_u32 / hal_u32_t
-
F for real_t / hal_float_t
-
L for rtapi_s64 / hal_s64_t
-
K for rtapi_u64 / hal_u64_t
-
- buf
-
Буфер, достатньо великий, щоб зберігати всі дані в одному зразку.
- sampleno
-
Якщо не NULL, тут зберігається номер останнього зразка. Пропуски в цій послідовності вказують на те, що між попереднім і цим зчитуванням стався перебіг. Може бути NULL, у цьому випадку номер зразка не витягується.
- стій
-
Вказівник на значення, яке контролюється під час очікування. Якщо воно не дорівнює нулю, операція очікування повертається раніше. Це дозволяє безпечно завершити виклик очікування у разі сигналу.
ЗРАЗОК КОДУ
У дереві вихідного коду в розділі src/hal/components, sampler.c та streamer.c – це компоненти реального часу, які читають та записують потоки HAL.
МІРКУВАННЯ В РЕАЛЬНОМУ ЧАСІ
The hal_stream_wait_readable() and hal_stream_wait_writable() cannot be called from realtime.
Інші функції можна викликати в будь-якому контексті, включаючи контексти реального часу.
ПОВЕРНЕНЕ ЗНАЧЕННЯ
The functions hal_stream_create(), hal_stream_attach(), hal_stream_read(), hal_stream_write(), hal_stream_detach() and hal_stream_destroy() return an RTAPI status code. Other functions' return values are explained above.
ПОМИЛКИ
Навантаження на пам’ять потоку може бути великим. Кожен елемент у записі використовує 8 байт, а неявне число зразків також використовує 8 байт. Як результат, потік, який використовується для передачі 8-бітних значень, використовує 94% своєї пам’яті як навантаження. Однак для потоків помірного розміру це навантаження не є важливим. (Ця пам’ять є частиною власної області спільної пам’яті і не враховується в області спільної пам’яті HAL, яка використовується для контактів, параметрів і сигналів.)