hal_port(3)

SYNOPSIS

#include <hal.h>

bool hal_port_read(hal_port_t port, char* dest, unsigned count);
bool hal_port_peek(hal_port_t port, char* dest, unsigned count);
bool hal_port_peek_commit(hal_port_t port, unsigned count);
unsigned hal_port_readable(hal_port_t port);
void hal_port_clear(hal_port_t port);

bool hal_port_write(hal_port_t port, const char* src, unsigned count);
unsigned hal_port_writable(hal_port_t port);

unsigned hal_port_buffer_size(hal_port_t port);

#ifdef ULAPI
void hal_port_wait_readable(hal_port_t** port, unsigned count, sig_atomic_t* stop);
void hal_port_wait_writable(hal_port_t** port, unsigned count, sig_atomic_t* stop);
#endif

BESCHREIBUNG

Ein HAL-Port-Pin ist ein HAL-Pin, der als einseitiger byteorientierter Datenstrom in Echtzeit fungiert. Ein Ausgangsanschluss an einer beliebigen Komponente kann über ein Signal mit einem Eingangsanschluss an einer beliebigen anderen Komponente verbunden werden. Die an den Ausgangsanschluss geschrieben Daten werden für den Eingangsanschluss zugänglich. Ein HAL-Portsignal kann nur einen einzigen Schreiber und einen einzigen Leser verbinden.

Ein Anschluss puffert auch Daten. Die Benutzer sollten die richtige Puffergröße je nach der beabsichtigten Anwendung bestimmen.

hal_port_read(): Reads count bytes from the port into destination buffer dest. A call to hal_port_read() will read count bytes if and only if count bytes are available for reading and otherwise it will leave the port unaffected. Returns true if count bytes were read and false otherwise. This function should only be called by the component that owns the IN PORT pin.
hal_port_peek(): Behaves the same as hal_port_read(), however it does not consume bytes from the HAL port. Repeated calls to hal_port_peek() will return the same data. Returns true if count bytes were read and false otherwise. This function should only be called by the component that owns the IN PORT pin.
hal_port_peek_commit(): Advances the read position in the port buffer by count bytes. A hal_port_peek() followed by a hal_port_peek_commit() would function equivalently to hal_port_read() given the same count value. Returns true if count readable bytes were skipped and are no longer accessible and false if no bytes wer skipped. This function should only be called by the component that owns the IN PORT pin.
hal_port_readable(): Returns the number of bytes available for reading from port. It is safe to call this function from any component.
hal_port_clear(): Leert einen gegebenen Port von allen Daten. hal_port_clear sollte nur von der Komponente aufgerufen werden, die den IN PORT Pin besitzt.
hal_port_write(): Schreibt count bytes von src in den Port. Gibt true zurück, wenn count bytes geschrieben wurden, andernfalls false. Diese Funktion sollte nur von der Komponente aufgerufen werden, die den OUT PORT-Pin besitzt.
hal_port_writable(): Returns the number of bytes that can be written into the port. It is safe to call this function from any component.
hal_port_buffer_size(): Returns the maximum number of bytes that a port can buffer. It is safe to call this function from any component.
hal_port_wait_readable(): Waits until the port has count bytes or more available for reading or the stop flag is set.
This function cannot be called from realtime code.
hal_port_wait_writable(): Waits until the port has count bytes or more available for writing or the stop flag is set.
This function cannot be called from realtime code.

ARGUMENTE

hal_port_t: Ein Handle auf ein Port-Objekt. Erstellt von hal_pin_new.
dest: Ein Array von Bytes, in das hal_port_read und hal_port_peek Daten kopieren. Dieses Array muß vom Aufrufer zugewiesen werden und mindestens so viele Bytes lang sein.
count (engl für Zähler): Die Anzahl der Bytes, die hal_port_read, hal_port_peek und hal_port_write nach dest oder von src kopieren.
src: Ein Array von Bytes, aus dem hal_port_write Daten in den Portpuffer kopiert. Dieses muss mindestens die Größe count bytes haben.
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/raster.comp ist eine Echtzeitkomponente für die Lasersteuerung. src/tests/raster ist ein Testprogramm, das auch die Rasterkomponente mit Python programmiert.

REALTIME CONSIDERATIONS

Most hal_port_*() functions can be called from realtime code.

The exceptions are hal_port_wait_writable() and hal_port_wait_readable(), which may be only called from ULAPI code.

SIEHE AUCH

raster(9)