LinuxCNC Documentation

СИНТАКСИС

#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 до вже створеного потоку.

Нереальним часом може бути halstreamer або halsampler. У випадку halstreamer ключом є 0x48535430 плюс номер каналу. У випадку halsampler ключом є 0x48534130 плюс номер каналу.

hal_stream_create

Створити заданий потік, ініціалізуючи stream, який передається за посиланням. Це недіагностована помилка, якщо потік вже створено з тим самим key.

hal_stream_destroy

Знищити заданий потік. Якщо потік все ще приєднаний іншим компонентом, це є недіагностованою помилкою. Якщо потік був приєднаний за допомогою hal_stream_attach, а не створений за допомогою hal_stream_create, це є недіагностованою помилкою. Якщо виклик hal_stream_destroy пропущено, це є недіагностованою помилкою.

hal_stream_attach

Приєднати заданий потік, який вже був створений за допомогою hal_stream_create. Якщо вказано тип рядка, цей виклик завершиться невдачею, якщо він не відповідає типу рядка, з яким був створений потік. Якщо аргумент типу рядка має значення NULL, то приймається будь-який тип рядка.

hal_stream_detach

Від’єднати заданий потік. Якщо потік був створений за допомогою hal_stream_create, а не приєднаний за допомогою hal_stream_attach, це є недіагностованою помилкою. Якщо виклик hal_stream_detach пропущено, це є недіагностованою помилкою.

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

Повертає аргумент глибина, за допомогою якого було створено потік.

hal_stream_num_overruns

Повертає число, яке збільшується щоразу, коли викликається hal_stream_write без доступного місця.

hal_stream_num_underruns

Повертає число, яке збільшується щоразу, коли викликається hal_stream_read без доступного зразка.

hal_stream_wait_readable

Очікує, поки потік стане доступним для читання або не буде встановлено прапорець зупинки.

hal_stream_wait_writable

Очікує, поки потік стане доступним для запису або не буде встановлено прапорець зупинки.

hal_stream_read

Зчитує запис із потоку. У разі успіху він зберігається у вказаному буфері. За бажанням можна отримати номер зразка. Якщо зразка немає, збільшується значення num_underruns. Якщо більше ніж один компонент або функція реального часу одночасно викликають hal_stream_read, це вважається невиявленою помилкою.

hal_stream_write

Записує запис у потік. У разі успіху він копіюється з заданого буфера. Якщо місця недостатньо, num_overruns збільшується. У будь-якому випадку внутрішнє значення sampleno збільшується. Якщо більше ніж один компонент або функція реального часу одночасно викликає hal_stream_write, це вважається невиявленою помилкою.

АРГУМЕНТИ

stream

Покажчик на об’єкт потоку. У випадку hal_stream_create та hal_stream_attach це неініціалізований потік; в інших випадках це повинен бути потік, створений або приєднаний попереднім викликом і ще не від’єднаний або знищений.

hal_id

Ідентифікатор компонента HAL, повернутий попереднім викликом hal_init.

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.

МІРКУВАННЯ В РЕАЛЬНОМУ ЧАСІ

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 may be called from realtime code.

hal_stream_wait_writable, hal_stream_wait_writable may be called from ULAPI code.

Інші функції можна викликати в будь-якому контексті, включаючи контексти реального часу.

ПОВЕРНЕНЕ ЗНАЧЕННЯ

Функції hal_stream_create, hal_stream_attach, hal_stream_read, hal_stream_write, hal_stream_detach та hal_stream_destroy повертають код стану RTAPI. Значення, що повертаються іншими функціями, пояснено вище.

ПОМИЛКИ

Навантаження на пам’ять потоку може бути великим. Кожен елемент у записі використовує 8 байт, а неявне число зразків також використовує 8 байт. Як результат, потік, який використовується для передачі 8-бітних значень, використовує 94% своєї пам’яті як навантаження. Однак для потоків помірного розміру це навантаження не є важливим. (Ця пам’ять є частиною власної області спільної пам’яті і не враховується в області спільної пам’яті HAL, яка використовується для контактів, параметрів і сигналів.)

ДИВІТЬСЯ ТАКОЖ

sampler(9), streamer(9), halsampler(1), halstreamer(1)