weAut_01' devices for communication input/output supported by weAutSys can be used directly and via the respective modules / functions. Additionally some of those devices are offered (wrapped) as standard (or stdio.h) streams. In the reset default state stdin/err/out go to or come from the UART.
The reasons for using such streams instead of direct I/O programming / usage are
The last point is strongly deprecated. printf, scanf and cognates are quite resource hungry. For a small µController (in a resource saving appliance) and in a non preemptive (Protothreads) runtime this will quickly get a problem and shall be restricted to debugging and may be initialisation before the real (time) work. Using weAutSys' formatting and parsing functions instead will reduce the memory and processor usage by factors five and more.
Files | |
file | log_streams.h |
Buffered log stream (definitions) | |
file | streams.h |
Streams (definitions) | |
Data Structures | |
struct | streamClassDescript_t |
Extra stream (type) specific data. More... | |
Defines | |
#define | AVAILABLE_UNKNOWN 0xFFFF |
Available input unknown. | |
#define | LAN_IS_STDOUT |
stdout is the LAN stream output (Ethernet, uIP) | |
#define | SER_IS_STDOUT |
stdout is the serial output (UART) | |
#define | USE_AVR_GCC_FILE 1 |
use AVR FILE type internals | |
The buffered log streams | |
FILE | bufLogStreams |
The stream "device" being a buffer for logging. | |
struct thr_data_t * | bufLogCons |
The consumer of buffered log streams output (text) data. | |
void | bufLogStreamsInit (void) |
Initialise the buffered log streams. | |
void | bufLogStreamsOpen (void) |
Open the buffered log streams. | |
uint16_t | bufLogInBufferd (FILE *streams) |
The number of characters buffered in buffered log streams for input. | |
int | bufLogGetC (void) |
Get one byte from buffered stream input. | |
uint16_t | bufLogGetChars (char *dst, uint16_t n) |
Get a number of bytes from buffered stream input. | |
uint8_t | uartPutLogBuf (void) |
Put characters from buffered log streams to serial output. | |
uint16_t | bufLogStreamsOutSpace (FILE *streams) __attribute__((pure)) |
The buffer space available for buffered log streams output. | |
uint8_t | bufLogCheckOutSpace (uint16_t const reqSpace, FILE *const streams) |
Check the space available buffered log streams output. | |
void | bufLogPutC (char const c) |
Put one byte to buffered stream output. | |
void | bufLogPut2C (char const c1, char const c2) |
Put two bytes to buffered stream output. | |
int | bufLogGetChar (FILE *const stream) |
Get one byte from buffered stream input. | |
int | bufLogPutChar (char c, FILE *const stream) |
Put one byte to buffered stream output. | |
int | bufLogPutSt (char *src, FILE const *const stream) |
Put a RAM string (some characters) to buffered stream output. | |
int | bufLogPutSt_P (char *src, FILE const *const stream) |
Put some characters from program space to buffered stream output. | |
#define | BUF_STREAMS_CAP 2047 |
The buffered log streams capacity. | |
#define | bufLogConsIsUART |
The UART is the consumer of buffered log streams output (text) data. | |
#define | bufLogSetConsumer(tD) |
Set the consumer of buffered log streams output (text) data. | |
#define | bufLogSetUART() |
Set the UART as consumer of buffered log streams output. | |
#define | BufLogInBufferd |
The number of characters buffered in buffered log streams for input. | |
Common stream handling definitions | |
typedef uint16_t(* | str2InBufferd )(const FILE *stream) |
Function pointer / type: number of characters buffered for input. | |
typedef uint16_t(* | str2OutSpace )(const FILE *stream) |
Function pointer / type: buffer space available for output. | |
typedef uint8_t(* | str2CheckOutSpace )(uint16_t reqSpace, const FILE *stream) |
Function pointer / type: checking the space available for output. | |
typedef int(* | str2PutS )(char *src, const FILE *stream) |
Function pointer / type: writing a RAM string to output. | |
typedef int(* | str2PutS_P )(prog_char *src, const FILE *stream) |
Function pointer / type: writing a flash memory string to output. | |
typedef struct streamClassDescript_t | streamClassDescript_s |
Extra stream (type) specific data (structure) | |
uint16_t | inBufferd (const FILE *stream) |
Number of characters buffered for input. | |
uint16_t | outSpace (const FILE *stream) |
Buffer space available for output. | |
uint8_t | checkOutSpace (uint16_t reqSpace, const FILE *stream) |
Checking the space available for output. | |
int | putSt (char *src, const FILE *stream) |
Write a RAM string to output. | |
int | putSt_P (char const *src, const FILE *stream) |
Write a flash memory string to output. | |
#define | PT_YIELD_OUT_SPACE(pt, requSpace, streams) |
Set standard I/O and exit or yield for requested output space. | |
#define | PT_WAIT_OUT_SPACE(pt, requSpace, streams) |
Set standard I/O and exit or wait for requested output space. | |
The serial streams | |
FILE | serStreams |
The stream "device" connected to the serial IO / UART(0) | |
void | serStreamsOpen (void) |
Open the serial (UART) streams. | |
uint16_t | serStreamsOutSpace (FILE *streams) |
The buffer space available for serial output. | |
uint8_t | serCheckOutSpace (uint16_t reqSpace, FILE *streams) |
Check the space available for serial output. | |
int | serPutChar (char c, FILE *stream) |
Put one byte to serial output. | |
Recommended standard I/O functions | |
void | stdPutC (char c) |
Write a character to stdout . | |
void | logStackS (uint8_t maxBytes) |
Log the stack frame to stdout. | |
#define | stdPutS(src) |
Write a RAM string to stdout . | |
#define | stdPutS_P(src) |
Write a flash memory string to stdout . | |
The Ethernet / LAN streams | |
FILE | lanStreams |
The stream "device" connected to the Ethernet (uIP) | |
void | lanStreamsInit (void) |
Initialise the Ethernet / LAN streams. | |
void | lanStreamsEcho (void) |
Set the Ethernet / LAN streams to echo input. | |
void | lanStreamsOpen (void) |
Open the Ethernet / LAN streams. | |
void | lanStreamSend (void) |
Sends the LAN streams data (over the Ethernet) | |
uint16_t | lanStreamsOutSpace (FILE *streams) |
The buffer space available for Ethernet / LAN streams output. | |
uint8_t | lanCheckOutSpace (uint16_t reqSpace, FILE *streams) |
Check the space available Ethernet / LAN streams output. | |
uint16_t | lanInBufferd (FILE *streams) |
The number of characters buffered from LAN (stream) input. | |
int | lanGetC (void) |
Get one byte from LAN stream input. | |
void | lanPutC (char c) |
Put one byte to LAN stream output. | |
int | lanGetChar (FILE *stream) |
Get one byte from LAN stream input. | |
int | lanPutChar (char c, FILE *stream) |
Put one byte to LAN stream output. | |
int | lanPutChars (char *src, uint16_t n) |
Put some characters to LAN stream output. | |
int | lanPutSt (char *src, const FILE *stream) |
Put a RAM string (some characters) to LAN stream output. | |
int | lanPutSt_P (char *src, const FILE *stream) |
Put some characters from program space to LAN stream output. | |
The nul device | |
FILE | nulStreams |
The stream "device" connected to the nul device. | |
void | nulStreamsOpen (void) |
Open the nul streams. | |
uint16_t | nulStreamsOutSpace (FILE *streams) |
The buffer space available for nul output. | |
uint8_t | nulCheckOutSpace (uint16_t reqSpace, FILE *streams) |
Check the space available for nul streams output. | |
uint16_t | nulInBufferd (FILE *streams) |
The number of characters buffered from nul input. | |
int | nulGetC (void) |
Get one byte from nul stream input. | |
void | nulPutC (char c) |
Put one byte to nul stream output. | |
int | nulPutChar (char c, FILE *stream) |
Put one byte to nul stream output. | |
int | nulGetChar (FILE *stream) |
Get one byte from nul stream input. | |
int | nulPutSt (char *const src, const FILE *stream) |
Put a string (some characters) to nul stream output. | |
Functions | |
void | initStdStreams (FILE *initStream) |
Initialise the standard streams. | |
void | streamsClose (void) |
Close other standard streams. | |
uint8_t | switchStdStreams (FILE *toStream) |
Switch the standard streams to another stream. |
#define BUF_STREAMS_CAP 2047 |
The buffered log streams capacity.
The value must be (a power of 2 - 1) and at least 255.
#define bufLogConsIsUART |
The UART is the consumer of buffered log streams output (text) data.
This evaluates to true if the serial output is to consume the buffered logs.
#define bufLogSetConsumer | ( | tD | ) |
Set the consumer of buffered log streams output (text) data.
If the consumer is set to 0
or NULL
there is no consumer and all output will go to the log streams (except the last BUF_STREAMS_CAP bytes will be forgotten).
A value of 1
means the serial interface is the consumer. This presupposes the UART being connected to a (human readable) text mode device.
Any other value must be a pointer to a thread data structure. A suitable thread function has to recognise this and handle the buffered log output. weAutSys' Telnet server e.g. does this.
At any given moment there can be just one or none (0) consumer for the buffered log streams output.
tD | pointer to the consumer's thread data structure or 0 or 1 |
#define bufLogSetUART | ( | ) |
Set the UART as consumer of buffered log streams output.
This sets the UART as consumer of log output. This presupposes the UART being connected to a (human readable) text mode device.
If this pre-condition is met this may be called by user software's initialisation (phase 2) to prevent the first active Telnet client from automatically get that role. This may be mandatory if Telnet debugging is on.
#define BufLogInBufferd |
The number of characters buffered in buffered log streams for input.
#define PT_YIELD_OUT_SPACE | ( | pt, | |
requSpace, | |||
streams | |||
) |
Set standard I/O and exit or yield for requested output space.
This is a macro to be used inside a protothread.
It sets a re-entry point for the next schedule of pt
(after eventually yielding or waiting). Then it switches the standard output to streams
and exits the calling thread pt
(returning PT_EXITED) if that is not possible (cause streams
is NULL
e.g.).
If the switching to / opening of streams
was feasible this macro then
Otherwise the opening of streams
is un-done and
pt
, if the requested space may become available in the future by just waiting pt
, if the requested space will not become available by yielding / waiting but may be by other's activities. streams
is not usable or NULL
pt | the pointer to the protothread control structure. |
requSpace | the requested output space |
streams | the stream to use and switch stdout to |
#define PT_WAIT_OUT_SPACE | ( | pt, | |
requSpace, | |||
streams | |||
) |
Set standard I/O and exit or wait for requested output space.
This is a macro to be used inside a protothread.
It sets a re-entry point for the next schedule of pt
(after eventually yielding or waiting). Then it switches the standard output to streams
and exits the calling thread pt
(returning PT_EXITED) if that is not possible (cause streams
is NULL
e.g.).
If the switching to / opening of streams
was feasible this macro then
Otherwise the opening of streams
is un-done and
pt
, if the requested space may become available in the future by just waiting pt
, if the requested space will not become available by yielding / waiting but may be by other's activities. streams
is not usable or NULL
pt | the pointer to the protothread control structure. |
requSpace | the requested output space |
streams | the stream to use and switch stdout to |
#define SER_IS_STDOUT |
stdout is the serial output (UART)
This evaluates to true, if stdout goes to the UART.
#define LAN_IS_STDOUT |
stdout is the LAN stream output (Ethernet, uIP)
This evaluates to true, if stdout goes via uIP to the Ethernet.
#define stdPutS | ( | src | ) |
#define stdPutS_P | ( | src | ) |
Write a flash memory string to stdout
.
This is an abbreviation for putSt_P(src, stdout)
.
typedef uint16_t(* str2InBufferd)(const FILE *stream) |
Function pointer / type: number of characters buffered for input.
A function of this type returns the number of bytes that can be fetched from the stream's input without getting EOF.
For buffered devices with known state the answer will be correct.
In other cases the number of characters readable in one run without EOF is unknown. Then a large number with bit 15 set (0xFFFF AVAILABLE_UNKNOWN) is returned.
typedef uint16_t(* str2OutSpace)(const FILE *stream) |
Function pointer / type: buffer space available for output.
A function of this type returns the number of bytes that can currently be output to the stream in one run without waiting or overflow.
For buffered devices with known state the answer will be correct.
In other cases a large number with bit 15 set (0xFFFF AVAILABLE_UNKNOWN) is returned.
typedef uint8_t(* str2CheckOutSpace)(uint16_t reqSpace, const FILE *stream) |
Function pointer / type: checking the space available for output.
A function of this type checks the requested space against the buffer space available.
If the stream is, for example the UART, its function checks the requested space against the UART buffer size or available space. Return values are 0, 2 or 4.
If the stream is the LAN respectively the currently handled IP connection the respective function checks the requested space against the actual connection's remaining output space. Return values are 0, 3 or 4.
For other devices with known state the correct / appropriate answer is given.
For an unknown device 1 is returned and for no (NULL) device 4.
reqSpace | the number of bytes requested for output in one complete step |
stream | the stream In Implementations for one single (singleton) concrete stream, this parameter is usually ignored. |
typedef int(* str2PutS)(char *src, const FILE *stream) |
Function pointer / type: writing a RAM string to output.
A function of this type writes the content of the string src
to the stream
. It will never block.
It returns the number of characters transferred. If not enough space is available the returned value will be smaller than the length of the string src
. It may even be 0. In the latter case nothing was output.
Hence this operation should be (indirectly) guarded by outSpace() or PT_YIELD_OUT_SPACE .
The output stops after at the first 0 in src. By that this is a string output function. To send a (binary) 0 use stdPutC() or fputc()
.
src | the characters to be output (pointer to RAM not NULL !) |
stream | the destination stream |
typedef int(* str2PutS_P)(prog_char *src, const FILE *stream) |
Function pointer / type: writing a flash memory string to output.
A function of this writes the content of the string src
to the stream
. It will never block.
It returns the number of characters transferred. If not enough space is available the returned value will be smaller than the length of the string src
. It may even be 0. In the latter case nothing was output.
Hence this operation should be (indirectly) guarded by outSpace() or PT_YIELD_OUT_SPACE .
The output stops after at the first 0 in src. By that this is a string output function. To send a (binary) 0 use stdPutC() or fputc()
.
src | the characters to be output (pointer to flash memory not NULL !) |
stream | the destination stream |
void bufLogStreamsInit | ( | void | ) |
Initialise the buffered log streams.
This function initialises and clears the bufLogStreams.
void bufLogStreamsOpen | ( | void | ) |
Open the buffered log streams.
This function sets the standard streams stdin/out/err to the bufLogStreams.
This "switching" will be rescinded by streamsClose() .
This function just (re-) opens leaving all else state un-changed.
uint16_t bufLogInBufferd | ( | FILE * | streams | ) |
The number of characters buffered in buffered log streams for input.
This function returns the number of bytes that can be fetched from buffered log streams input by bufLogGetChar(FILE*) respectively bufLogGetC() without getting EOF.
The returned value is in the range 0 .. BUF_STREAMS_CAP. If 0 is returned nothing should be read.
int bufLogGetC | ( | void | ) |
Get one byte from buffered stream input.
This function never blocks. It returns a byte value read or EOF.
uint16_t bufLogGetChars | ( | char * | dst, |
uint16_t | n | ||
) |
Get a number of bytes from buffered stream input.
This function never blocks. It reads up to n
bytes from the buffered stream to the buffer dst
.
This is mainly intended as helper function for consuming and forward the log output buffered so far.
n
uint8_t uartPutLogBuf | ( | void | ) |
Put characters from buffered log streams to serial output.
This function will put as much as possible characters from the buffered log streams to the UART. Returned is the number of characters transferred; its type is byte as long as we stick to UART buffers capacity below 256.
uint16_t bufLogStreamsOutSpace | ( | FILE * | streams | ) |
The buffer space available for buffered log streams output.
uint8_t bufLogCheckOutSpace | ( | uint16_t const | reqSpace, |
FILE *const | streams | ||
) |
Check the space available buffered log streams output.
This function might give a positive answer to repeated request for more characters than space available even if that might lead to loosing the oldest output. The rationale for this "lie" is that a standard programmed yielding for output space wont't hold a thread on logging (debug) output more than twice.
void bufLogPutC | ( | char const | c | ) |
Put one byte to buffered stream output.
This function never blocks and does the output. If there was no space in the buffer the "oldest" character there will be overwritten. Hence this operation should be (indirectly) guarded by bufLogStreamsOutSpace().
c | the character to be output |
void bufLogPut2C | ( | char const | c1, |
char const | c2 | ||
) |
Put two bytes to buffered stream output.
This function acts like two times bufLogPutC but is a bit more efficient (and readable).
c1 | the first character to be output |
c2 | the second character to be output |
int bufLogGetChar | ( | FILE *const | stream | ) |
Get one byte from buffered stream input.
This function never blocks. It returns a byte value read or EOF.
This function may be used directly for input but then bufLogGetC() is a better choice. Usually this function is used indirectly via stdin of stdio.h as this functions signature is what stdio expects of underlying input streams.
stream | (passed by stdio input) totally ignored by this function |
int bufLogPutChar | ( | char | c, |
FILE *const | stream | ||
) |
Put one byte to buffered stream output.
This function does exactly the the same as the preferable bufLogPutC() except for the extra parameter of type FILE * that is for sake of the standard I/O usage.
c | the character to be output |
stream | (passed by stdio output) totally ignored by this function |
int bufLogPutSt | ( | char * | src, |
FILE const *const | stream | ||
) |
Put a RAM string (some characters) to buffered stream output.
This function never blocks. It returns the number of characters transferred. If not enough buffer space is available the returned value will be smaller than the length of the RAM string src
. This space restriction applies to the size of the buffer and not to the free space. If the latter is insufficient this function will just overwrite the oldest output.
This operation should be (indirectly) guarded by bufLogStreamsOutSpace() or bufLogCheckOutSpace().
The output stops at the first 0 in src
. By that this is a string output function. To send a (binary) 0 use bufLogPutC(0).
src | the characters to be output |
stream | the current stream (not used) |
int bufLogPutSt_P | ( | char * | src, |
FILE const *const | stream | ||
) |
Put some characters from program space to buffered stream output.
This function never blocks. It returns the number of characters transferred. If not enough buffer space is available the returned value will be smaller than the length of the flash memory string src
. This space restriction applies to the size of the buffer and not to the free space. If the latter is insufficient this function will just overwrite the oldest output.
This operation should be (indirectly) guarded by bufLogStreamsOutSpace() or bufLogCheckOutSpace().
The output stops at the first 0 in src
. By that this is a string output function. To send a (binary) 0 use bufLogPutC(0).
src | the characters to be output in flash memory |
stream | the current stream (not used) |
uint16_t inBufferd | ( | const FILE * | stream | ) |
Number of characters buffered for input.
This is the common function implementing the standard behavior. It delegates all else cases (late binding) to the stream type specific function if such is set in the stream (type) specific data.
For this function's behavior see the description in its pointer / type.
uint16_t outSpace | ( | const FILE * | stream | ) |
Buffer space available for output.
This is the common function implementing the standard behavior. It delegates all else cases (late binding) to the stream type specific function if such is set in the stream (type) specific data.
For this function's behavior see the description in its str2OutSpace()"pointer / type".
uint8_t checkOutSpace | ( | uint16_t | reqSpace, |
const FILE * | stream | ||
) |
Checking the space available for output.
This is the common function implementing the standard behavior. It delegates all else cases (late binding) to the stream type specific function if such is set in the stream (type) specific data.
For this function's behavior see the description in its str2CheckOutSpace()"pointer / type".
int putSt | ( | char * | src, |
const FILE * | stream | ||
) |
Write a RAM string to output.
This is the common function implementing the standard behavior. It delegates all normal cases (late binding) to the stream type specific function if such is set in the stream (type) specific data; if no such function is set it uses fputs()
.
For this function's behavior see the description in its pointer / type.
int putSt_P | ( | char const * | src, |
const FILE * | stream | ||
) |
Write a flash memory string to output.
This is the common function implementing the standard behavior. It delegates all else cases (late binding) to the stream type specific function if such is set in the stream (type) specific data; if no such function is set it uses fputs_P()
.
For this function's behavior see the description in its pointer / type.
void initStdStreams | ( | FILE * | initStream | ) |
Initialise the standard streams.
This function is usually called once at system start up but might be called any time to change or assure the standard streams.
Anyway it will switch to the (then) actual standard streams acting hence effectively as streamsClose(). (Additionally all extra data for pre-defined streams will be reset / refreshed.) Do not call when these (side-) effects may be disturbing.
If the parameter is NULL and standard streams were set already they are just kept. Otherwise nulStreams are used as default.
initStream | pointer to initial stream for standard streams |
uint8_t switchStdStreams | ( | FILE * | toStream | ) |
Switch the standard streams to another stream.
This function sets the standard streams stdin/out/err to the toStream
. If toStream
is NULL nothing is done.
toStream | pointer streams to switch the standard streams to |
void streamsClose | ( | void | ) |
Close other standard streams.
This function just reverses the (stream switching) effect of switchStdStreams() by setting back all standard streams to their initial standard source and destination.
void serStreamsOpen | ( | void | ) |
Open the serial (UART) streams.
This function sets the standard streams stdin/out/err to the serStreams if (and only if) not yet so set.
This "switching" will be rescinded by streamsClose() .
uint16_t serStreamsOutSpace | ( | FILE * | streams | ) |
The buffer space available for serial output.
Same as uartOutSpace (other common signature).
uint8_t serCheckOutSpace | ( | uint16_t | reqSpace, |
FILE * | streams | ||
) |
Check the space available for serial output.
int serPutChar | ( | char | c, |
FILE * | stream | ||
) |
Put one byte to serial output.
This function never blocks. It returns the byte c
output if the operation was feasible or -1 resp. EOF if not. In the latter case c
is not output.
Hence this operation should be (indirectly) guarded by uartOutSpace().
c | the character to be output |
stream | unused, irrelevant (signature required by stdio) |
void stdPutC | ( | char | c | ) |
Write a character to stdout
.
If USE_AVR_GCC_FILE is defined with a not 0 value this function calls the stdout stream's character output implementation directly.
Without the direct call optimisation the following holds:
If the stdout is the UART or the current LAN this function just calls serPutChar(c, NULL) resp. lanPutC(c) directly.
For all other streams fputc(c, stdout)
is used.
void logStackS | ( | uint8_t | maxBytes | ) |
Log the stack frame to stdout.
maxBytes | the max. number of bytes logged including the stack frame |
void lanStreamsInit | ( | void | ) |
Initialise the Ethernet / LAN streams.
This function initialises the lanStreams for usage with uip_appdata newly received or to be sent and additionally opens it.
void lanStreamsEcho | ( | void | ) |
Set the Ethernet / LAN streams to echo input.
This function should be called after inititialising the lanStreams and before the first output.
The received data will then be set as beginning of the data to be sent. This will be a 1:1 echo if nothing else is output.
void lanStreamsOpen | ( | void | ) |
Open the Ethernet / LAN streams.
This function sets the standard streams stdin/out/err to the lanStreams.
This "switching" will be rescinded by streamsClose() .
This function just (re-) opens leaving all else state (like buffer indices) un-changed. For a first open use lanStreamsInit() .
void lanStreamSend | ( | void | ) |
uint8_t lanCheckOutSpace | ( | uint16_t | reqSpace, |
FILE * | streams | ||
) |
Check the space available Ethernet / LAN streams output.
uint16_t lanInBufferd | ( | FILE * | streams | ) |
The number of characters buffered from LAN (stream) input.
This function returns the number of bytes that can be fetched from LAN (stream) input by lanGetChar(FILE*) respectively lanGetC() without getting EOF.
The returned value is in the range 0 .. uip_datalen(). If 0 is returned nothing should be read.
int lanGetC | ( | void | ) |
Get one byte from LAN stream input.
This function never blocks. It returns a byte value read or EOF.
Hence this operation should be (indirectly) guarded by lanInBufferd().
void lanPutC | ( | char | c | ) |
Put one byte to LAN stream output.
This function never blocks even if no output operation is feasible. Hence this operation should be (indirectly) guarded by lanStreamsOutSpace().
This function will be used by stdio as output driver entry indirectly by lanPutChar(char c, FILE *stream). It may as well be used directly for output to the current IP connection.
c | the character to be output |
int lanGetChar | ( | FILE * | stream | ) |
Get one byte from LAN stream input.
This function never blocks. It returns a byte value read or EOF.
Hence this operation should be (indirectly) guarded by lanInBufferd().
This function may be used directly for input but then lanGetC(() is a better choice. Usually this function is used indirectly via stdin of stdio.h as this functions signature is what stdio expects of underlying input streams.
stream | (passed by stdio input) totally ignored by this function |
int lanPutChar | ( | char | c, |
FILE * | stream | ||
) |
Put one byte to LAN stream output.
This function does exactly the the same as the preferable lanPutC() except for the extra parameter of type FILE
* that is for sake of the standard I/O usage.
c | the character to be output |
stream | (passed by stdio output) totally ignored by this function |
int lanPutChars | ( | char * | src, |
uint16_t | n | ||
) |
Put some characters to LAN stream output.
This function never blocks. It returns the number of characters transferred. If not enough space is available the returned value will be smaller than n
or than the length of the string src
. It may even be 0. In the latter case nothing was output.
Hence this operation should be (indirectly) guarded by lanStreamsOutSpace().
The output stops after n (or space permitting) characters or at the first 0 in src. By that this is a string output function. To send a (binary) 0 use lanPutC(char c).
src | the characters to be output |
n | the maximum number of characters to be output |
int lanPutSt | ( | char * | src, |
const FILE * | stream | ||
) |
Put a RAM string (some characters) to LAN stream output.
This function never blocks. It returns the number of characters transferred. If not enough space is available the returned value will be smaller than the length of the string src
. It may even be 0. In the latter case nothing was output.
Hence this operation should be (indirectly) guarded by lanStreamsOutSpace().
The output stops after at the first 0 in src. By that this is a string output function. To send a (binary) 0 use lanPutC(char c).
src | the characters to be output (0 terminated) |
stream | the current Ethernet connection as stream (not used) |
int lanPutSt_P | ( | char * | src, |
const FILE * | stream | ||
) |
Put some characters from program space to LAN stream output.
This function never blocks. It returns the number of characters transferred. If not enough space is available the returned value will be smaller than the length of the string src
. It may even be 0. In the latter case nothing was output.
Hence this operation should be (indirectly) guarded by lanStreamsOutSpace().
src | the characters to be output in flash memory (0 terminated) |
stream | the current Ethernet connection as stream (not used) |
void nulStreamsOpen | ( | void | ) |
Open the nul streams.
This function sets the standard streams stdin/out/err to the nulStreams.
This "switching" will be rescinded by streamsClose() .
uint16_t nulStreamsOutSpace | ( | FILE * | streams | ) |
The buffer space available for nul output.
This function always says 4095. It is provided to implement a stream that swallows and forgets all output.
uint8_t nulCheckOutSpace | ( | uint16_t | reqSpace, |
FILE * | streams | ||
) |
Check the space available for nul streams output.
This function always returns 0 i.e. available. It is provided to implement a stream that swallows unlimited amount of output (by just forgetting it).
uint16_t nulInBufferd | ( | FILE * | streams | ) |
The number of characters buffered from nul input.
This function returns always 0 as there will be no input from nul. It is provided to implement an input stream that will never deliver anything respectively be always empty.
int nulGetC | ( | void | ) |
Get one byte from nul stream input.
This function is provided to implement an input stream that will never deliver anything respectively be always empty.
void nulPutC | ( | char | c | ) |
Put one byte to nul stream output.
This function never blocks and does nothing. It is provided to implement a stream that swallows unlimited amount of output (by just forgetting it).
All other output functions to nul do have no effect, also.
c | the character to be output |
int nulPutChar | ( | char | c, |
FILE * | stream | ||
) |
Put one byte to nul stream output.
This function never blocks. It returns the byte c
provided as parameter value and does nothing else. It is provided to implement a stream that swallows and forgets all output.
c | the character to be output |
stream | unused, irrelevant (signature required by stdio) |
int nulGetChar | ( | FILE * | stream | ) |
Get one byte from nul stream input.
This function returns EOF
. It is provided to implement an input stream that will never deliver anything respectively always be empty.
stream | (passed by stdio input) totally ignored by this function |
EOF
int nulPutSt | ( | char *const | src, |
const FILE * | stream | ||
) |
Put a string (some characters) to nul stream output.
This function never blocks. It returns 1 no matter the parameters and does nothing else. It is provided to implement a stream that swallows unlimited amount of output (by just forgetting it).
As the pointer to the characters to output src
is not de-referenced this function works for RAM and program (flash) memory strings as well.
src | the characters to be output (not used) |
stream | (not used) |
FILE bufLogStreams |
The stream "device" being a buffer for logging.
This stream is a buffer (or pipe or decorator) for output. Its intended use is as buffered log output to humans.
The buffered content is available by input or by bulk copying out of the buffered text to be consumed and send forth by an appropriate device respectively application, be it the UART or one Telnet connection.
Every usage of the log buffered stream device via standard streams shall be embraced by bufLogStreamsOpen() and streamsClose().
struct thr_data_t* bufLogCons |
The consumer of buffered log streams output (text) data.
This (16 bit) value points to the state data structure of the application to regularly consume (and send forward) the bufLogStreams text buffered so far.
Special values are:
NULL or 0 : no consuming device or application <br > 1 : the UART shall output all buffered text.
FILE serStreams |
The stream "device" connected to the serial IO / UART(0)
On (default) initialisation this stream will be used for the standard streams.
FILE lanStreams |
The stream "device" connected to the Ethernet (uIP)
This stream shall only be used while handling Ethernet messages, i.e. directly or indirectly in uip_appcall(), uipAppcall() or udp_appcall(). It will work on uip_appdata, i.e. use it as buffer for both directions.
Output functions must not be used before uip_appdata as input (message) is fully processed.
Every usage shall be embraced by lanStreamsOpen() and streamsClose() if used via standard streams.
FILE nulStreams |
The stream "device" connected to the nul device.
This stream shall only be used as initial standard streams if no other character / byte oriented I/O is permanently available (from reset on). That usually means the UART is reserved for other purposes.
This streams shall be set respectively opened as standard I/O (stdio) whenever no other stream is available therefore. The rationale is any (user) thread might use standard I/O (stdio) any time.
The "device" features all in/output functions optimised for doing nothing. It is always available, i.e. from reset phase 1 on until shutdown.