hal_stream(3)

SYNOPSIS

#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

BESCHREIBUNG

Ein HAL-Stream bietet eine begrenzte Möglichkeit für zwei Komponenten, Daten zu übermitteln, die nicht in das Modell der HAL-Pins passen. Ein Leser und ein Schreiber müssen sich auf einen key (32-Bit-Integer-Identifikator) und eine durch typestring spezifizierte Datenstruktur einigen. Sie müssen auch vereinbaren, welche Komponente (die zuerst geladene) den Stream hal_stream_create und welche Komponente (die zweite geladene) den bereits erzeugten Stream hal_stream_attach.

Der Nicht-Echtzeit-Teil kann halstreamer oder halsampler sein. Im Fall von halstreamer ist der Schlüssel 0x48535430 plus die Kanalnummer. Im Falle von halsampler ist der Schlüssel 0x48534130 plus die Kanalnummer.

hal_stream_create: Erzeugt den angegebenen Stream, wobei der stream, der als Referenz übergeben wird, initialisiert wird. Es ist ein nicht diagnostizierter Fehler, wenn bereits ein Stream mit demselben key erstellt wurde.
hal_stream_destroy: Zerstört den angegebenen Stream. Es ist ein nicht diagnostizierter Fehler, wenn der Stream noch von einer anderen Komponente angehängt ist. Es ist ein nicht diagnostizierter Fehler, wenn der Stream mit hal_stream_attach angehängt wurde und nicht mit hal_stream_create erzeugt wurde. Es ist ein nicht diagnostizierter Fehler, wenn der Aufruf von hal_stream_destroy ausgelassen wird.
hal_stream_attach: Hängt den angegebenen Stream an, der bereits mit hal_stream_create erstellt wurde. Wenn der Typestring angegeben ist, schlägt dieser Aufruf fehl, wenn er nicht mit dem Typestring übereinstimmt, mit dem der Stream erstellt wurde. Wenn das Argument typestring NULL ist, wird ein beliebiger typestring akzeptiert.
hal_stream_detach: Löscht den angegebenen Stream. Es ist ein nicht diagnostizierter Fehler, wenn der Stream mit hal_stream_create erzeugt und nicht mit hal_stream_attach angehängt wurde. Es ist ein nicht diagnostizierter Fehler, wenn der Aufruf von hal_stream_detach ausgelassen wird.
hal_stream_element_count: Gibt die Anzahl der Pins zurück.
hal_stream_element_type: Gibt den Typ der angegebenen Pin-Nummer zurück.
hal_stream_readable: Gibt true zurück, wenn der Stream mindestens einen Sample zum Lesen hat
hal_stream_read: Wenn der Stream ein Sample zum Lesen hat, speichert der diesen in buf.
hal_stream_writable: Gibt „true“ zurück, wenn der Stream Platz für mindestens einen zu schreibenden Sample hat.
hal_stream_depth: Gibt die Anzahl der Messwerten (engl. samples) zurück, die darauf warten, gelesen zu werden.
hal_stream_maxdepth: Gibt das Argument depth (engl. für Tiefe) zurück, mit dem der Stream erstellt wurde.
hal_stream_num_overruns: Gibt eine Zahl zurück, die jedes Mal erhöht wird, wenn hal_stream_write aufgerufen wird und kein Speicherplatz verfügbar ist.
hal_stream_num_underruns: Gibt eine Zahl zurück, die jedes Mal erhöht wird, wenn hal_stream_read aufgerufen wird, ohne dass ein Sample verfügbar ist.
hal_stream_wait_readable: Wartet, bis der Stream lesbar ist oder das Stop-Flag gesetzt wird.
hal_stream_wait_writable: Wartet, bis der Stream beschreibbar ist oder das Stop-Flag gesetzt wird.
hal_stream_read: Liest einen Datensatz aus dem Stream. Bei Erfolg wird es im angegebenen Puffer gespeichert. Optional kann die Probennummer abgefragt werden. Wenn kein Sample verfügbar ist, wird num_underruns inkrementiert. Es ist ein unerkannter Fehler, wenn mehr als eine Komponente oder Echtzeitfunktion hal_stream_read gleichzeitig aufruft.
hal_stream_write: Schreibt einen Datensatz in den Stream. Wenn erfolgreich, kopiert es von den gegebenen Puffer. Wenn kein Platz verfügbar ist, wird num_overruns erhöht. In jedem Fall wird der Wert der internen sampleno (Proben-Nummer) erhöht. Es wird nicht erkannt, wenn mehr als eine Komponente bzw. Echtzeit-Funktion hal_stream_write zur Gleichen Zeit aufruft.

ARGUMENTE

stream

Ein Zeiger auf ein Stream-Objekt. Im Fall von hal_stream_create und hal_stream_attach ist dies ein nicht initialisierter Stream; in anderen Fällen muss es sich um einen Stream handeln, der durch einen früheren Aufruf erzeugt oder angehängt und noch nicht abgetrennt oder zerstört wurde.

hal_id

Eine HAL-Komponenten-Kennung, die durch einen früheren Aufruf von hal_init zurückgegeben wurde.

key

Der Schlüssel (engl. key) für das gemeinsame Speichersegment.

depth

Die Anzahl der Samples, die ungelesen werden können, bevor Samples verloren gehen (Überlauf, engl. Overrun)

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

Ein Puffer, der groß genug ist, um alle Daten einer Probe aufzunehmen.

sampleno

Falls nicht NULL, wird hier die letzte Probennummer gespeichert. Lücken in dieser Sequenz zeigen an, dass ein Überlauf zwischen dem vorherigen und diesem Lesevorgang stattgefunden hat. Kann NULL sein, in diesem Fall wird die Stichprobennummer nicht abgerufen.

stop

Ein Zeiger auf einen Wert, der während des Wartens überwacht wird. Ist er ungleich Null, kehrt der Wartevorgang vorzeitig zurück. Dadurch kann ein Warteaufruf im Falle eines Signals sicher beendet werden.

SAMPLE CODE

Im Quellbaum unter src/hal/components sind sampler.c und streamer.c Echtzeitkomponenten, die HAL-Streams lesen und schreiben.

REALTIME CONSIDERATIONS

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.

Andere Funktionen können in jedem Kontext, auch in Echtzeit, aufgerufen werden.

RETURN VALUE

hal_stream_create, hal_stream_attach, hal_stream_read, hal_stream_write, *hal_stream_detach und hal_stream_destroy geben einen RTAPI-Statuscode zurück. Die Rückgabewerte der anderen Funktionen werden oben erläutert.

BUGS

Der Speicher-Overhead eines Streams kann sehr groß sein. Jedes Element in einem Datensatz belegt 8 Byte, und die implizite Stichprobennummer belegt ebenfalls 8 Byte. Ein Datenstrom, der für den Transport von 8-Bit-Werten verwendet wird, verbraucht daher 94 % seines Speichers als Overhead. Bei bescheidenen Streamgrößen ist dieser Overhead jedoch nicht von Bedeutung. (Dieser Speicher ist Teil eines eigenen gemeinsamen Speicherbereichs und wird nicht auf den gemeinsamen HAL-Speicherbereich angerechnet, der für Pins, Parameter und Signale verwendet wird.)

SIEHE AUCH

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

hal_stream(3) Manual Page

NAME