LinuxCNC Documentation

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.

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()

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()

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()

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()

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.

ARGUMENTE

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

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

The hal_stream_wait_readable() and hal_stream_wait_writable() cannot be called from realtime.

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

RETURN VALUE

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.

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)