hal_stream - streams en tiempo real sin bloqueo
#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, union hal_stream_data
*buf, unsigned *sampleno);
bool hal_stream_readable(hal_stream_t *stream);
int
hal_stream_write(hal_stream_t *stream, union hal_stream_data
*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
Un stream HAL proporciona una capacidad limitada para que dos componentes se comuniquen datos que no se ajustan al modelo de pines HAL. Un lector y un escritor deben acordar una clave (Identificador entero de 32 bits) y una estructura de datos especificada por typestring será hal_stream_create y qué componente (el segundo cargado) hal_stream_attach a la secuencia ya creada.
La parte del espacio de usuario puede ser halstreamer o halsampler. En el caso de halstreamer la clave es 0x48535430 más el número de canal. En el caso de halsampler la clave es 0x48534130 más el número de canal.
hal_stream_create
Crea el flujo dado, inicializando el stream que se
pasa por referencia. Si es un error no diagnosticado si ya
se ha creado una secuencia con la misma key.
hal_stream_destroy
Destruye el stream dado. Es un error no diagnosticado si el
stream todavÃa está conectada por otro
componente. Es un error no diagnosticado si la secuencia se
adjuntó con hal_stream_attach en lugar
de creado con hal_stream_create. Es un error no
diagnosticado si la llamada a hal_stream_destroy se
omite.
hal_stream_attach
Adjunta la secuencia dada, que ya fue creada por
hal_stream_create. Si se especifica typestring, esta
llamada falla si no coincide con la cadena de texto con la
que se creó la secuencia. Si el argumento
typetring es NULL, entonces se acepta cualquier
typestring.
hal_stream_detach
Separa la secuencia dada. Es un error no diagnosticado si la
secuencia se creó con hal_stream_create
en lugar de adjuntarla con hal_stream_attach. Es un
error no diagnosticado si la llamada a
hal_stream_detach se omite.
hal_stream_element_count
Devuelve el número de pines.
hal_stream_element_type
Devuelve el tipo del número de pin dado.
hal_stream_readable
Devuelve verdadero si la secuencia tiene al menos una
muestra para leer
hal_stream_read
Si la secuencia tiene una muestra para leer, la almacena en
buf.
hal_stream_writable
Devuelve true si la secuencia tiene espacio para que se
escriba al menos una muestra.
hal_stream_depth
Devuelve el número de muestras que esperan ser
leÃdas.
hal_stream_maxdepth
Devuelve el argumento depth con el que se
creó la secuencia.
hal_stream_num_overruns
Devuelve un número que se incrementa cada vez
que hal_stream_write se llama sin espacio
disponible.
hal_stream_num_underruns
Devuelve un número que se incrementa cada vez
que hal_stream_read se llama sin una muestra
disponible.
hal_stream_wait_readable
Espera hasta que la stream sea legible o se establezca el
indicador de detención.
hal_stream_wait_writable
Espera hasta que la stream se pueda escribir o se establezca
el indicador de detención.
hal_stream_read
Lee un registro desde la stream. Si tiene
éxito, se almacena en el búfer
dado. Opcionalmente, se puede recuperar el
número de muestra. Si no hay muestra
disponible, num_underruns se incrementa. Es un error
no detectado si más de un componente o
funciones en tiempo real llaman a hal_stream_read
concurrentemente
hal_stream_write
Escribe un registro en la stream. Si tiene
éxito, se copió del buffer dado.
Si no hay espacio disponible, num_overruns se
incrementa. En cualquier caso, el valor interno
sampleno se incrementa. Es un error no detectado si
más de un componente o funciones en tiempo
real llaman a hal_stream_write concurrentemente
|
stream |
Un puntero a un objeto stream. En el caso de hal_stream_create y hal_stream_attach esta es una stream no inicializada; en otros casos, debe ser una stream creada o adjuntada por una llamada anterior y aún no separada o destruida. | ||
|
hal_id |
Un identificador de componente HAL devuelto por una llamada anterior a hal_init. | ||
|
key |
La clave para el segmento de memoria compartida. | ||
|
depth |
El número de muestras que pueden no leerse antes de que se pierdan muestras (desbordamiento) |
typestring
Una typestring es una cadena que no distingue entre mayúsculas y minúsculas que consta de uno o más de los siguientes tipos de caracteres:
|
B |
para bool / hal_bit_t |
|||
|
S |
para int32_t / hal_s32_t |
|||
|
U |
para uint32_t / hal_u32_t |
|||
|
F |
para real_t / hal_float_t |
Una typestring está limitada a 16 caracteres.
|
buf |
Un búfer lo suficientemente grande como para contener todos los datos en una muestra. |
sampleno
Si no es NULL, el último número de muestra se almacena aquÃ. Brechas en esta secuencia indican que se produjo un desbordamiento entre la lectura anterior y esta. Si es NULL, el número de muestra no se recupera.
|
stop |
Puntero a un valor que se supervisa mientras espera. Si no es cero, la operación de espera vuelve pronto. Esto permite que una llamada en espera sea terminada en forma segura en el caso de una señal. |
En el árbol fuente debajo src/hal/components, sampler.c y streamer.c hay componentes en tiempo real que leen y escriben streams 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_num_underruns, hal_stream_num_underruns, hal_stream_num_underruns, se pueden llamar desde código en tiempo real.
hal_stream_wait_writable, hal_stream_wait_writable se puede llamar desde el código ULAPI.
Se pueden invocar otras funciones en cualquier contexto, incluidos los contextos en tiempo real.
hal_stream_create, hal_stream_attach, hal_stream_read, hal_stream_write, hal_stream_detachy hal_stream_destroy devuelven un código de estado RTAPI. Los valores de retorno de otras funciones se explicaron anteriormente.
La sobrecarga de memoria de una secuencia puede ser grande. Cada elemento en un registro usa 8 bytes, y el número de muestra implÃcito también usa 8 bytes. Como resultado, una stream que se usa para transportar valores de 8 bits usa el 94% de su memoria como sobrecarga. Sin embargo, para tamaños de stream modestos, esta sobrecarga no es importante. (esta memoria es parte de su propia región de memoria compartida y no cuenta en contra de la región HAL de memoria compartida utilizada para pines, parámetros y señales)
sampler(9), streamer(9), halsampler(1), halstreamer(1)