OsResultE OsFCtl( UInt8T stream, char action, ... );
Function OsFCtl() should be called by the client application to perform control actions on a stream. The return value is currently unused. The first argument is the stream identifier. The second argument defines the control action that will be performed. Not all actions are applicable to all stream types. Additional arguments provide parameters for the action and must be supplied in accordance with the action given.
The OS_DISPLAY_ON_OFF action is applicable to stream OS_DISPLAY. It turns the entire display device on and off. A single integer argument must be supplied after the action argument. If its value is zero, the display will be turned off. If its value is non-zero, the display will be turned on.
The OS_CURSOR_ON_OFF action is applicable to stream OS_DISPLAY. It controls the appearance of a cursor at the text insertion point. A single integer argument must be supplied after the action argument. If its value is zero, no cursor will appear. If its value is non-zero, a cursor will appear according to the capabilities of the display device. For example, using the HD44780U display device, a steady underline cursor appears. Consult supplementary documentation for particular display devices.
The OS_SET_POSITION action is applicable to stream OS_DISPLAY. It moves the insertion point to a specified character row and column. A single integer argument must be supplied after the action argument. The most significant byte should contain the zero-based row number and the least significant byte the zero-based column number. The macro OS_ROW_COL( row, col ) is provided in the header file Ecros.h to convert row and column numbers to an integer argument. If the insertion point is positioned off the display, no output written to the display stream will appear on the display.
The example below shows the insertion point of the display device being set to row 1 (the second row down) and column 10 (the eleventh column from the left).
OsFCtl( OS_DISPLAY, OS_SET_POSITION, OS_ROW_COL( 1, 10 ) );
The OS_HIGHLIGHT_ROW action is applicable to stream OS_DISPLAY and
The OS_SET_LIGHTING action is applicable to stream OS_DISPLAY. The lighting (illumination) of the display can be set according to hardware capabilities. A single integer argument must be supplied after the action argument. If its value is zero, display lighting will be turned off. If its value is non-zero, display lighting will be turned on according to the capabilities of the display device. For example, using the ECROS Technology Z8 Encore! Prototyping System, any non-zero value will turn on the LCD backlight at fixed intensity. Other hardware may implement intensity control. Consult supplementary documentation for particular harware.
The OS_SET_FONT action is applicable to stream OS_DISPLAY. For display devices that support multiple fonts, it sets the font that will be used. Consult supplementary documentation for particular display devices. Note that the HD44780U display device does not support multiple fonts.
The OS_SET_EVENTS action is applicable to streams OS_UART0 and OS_UART1. It should be used by the application to select event-driven operation of the UART streams. From one to three integer arguments must be supplied after the action argument.
The first integer argument, which is mandatory, contains a number of flags in the most significant byte and a timeout value in the least significant byte. The flags are as follows:
Bit 15 - RCV/XMT. If 1, then the action is applied to the receive side of the stream; if 0 the action is applied to the transmit side.
Bit 14 - ON/OFF. If 1, then event-driven operation will be enabled; if 0 event-driven operation will be disabled and all remaining arguments will be ignored.
Bit 13 - TIMEOUT. If, 1 then the value in the least significant byte is used to set a timeout; if 0 then the least significant byte is ignored and no timeout is set (see also below).
Bit 12 - FULLNESS. If, 1 then an event will be sent when the number of buffered characters reaches the value specified by the most significant byte of the second argument; if 0 then an event will be sent for the receive side of the stream when the buffer is nearly full and for the transmit side of the stream when the buffer is empty (see also below).
Bit 11 - CHARACTER. If, 1 then an event will be sent when the character specified by the least significant byte of the second argument is received; if 0 then events are not sent based on received characters (see also below).
Bit 10 - CUSTOM. If 1, then the target task and the pattern of events sent to that task are specified by the third argument; if 0 then the currently executing task is sent the standard events (see also below).
Bits 9 and 8 are not used.
Bits 7 to 0 - Timeout. If the TIMEOUT flag is set, the 8-bit value in the least significant byte of the first integer argument is used to set a timeout. This results in an event being sent to the task if one or more characters are received but the timeout expires after the last character. The timeout is reset for each received character. If no characters are received, the timeout is not started. The timeout value must be specified in system ticks (for example, milliseconds) and cannot be greater than 255 ticks. If the value is zero, then the event will be sent immediately on receipt of the first character. If the TIMEOUT flag is not set, then not timeout will occur and no event will be sent until triggered by some other condition.
The second integer argument is only required if either the FULLNESS or CHARACTER flags are set. The most significant byte should be the number of characters in the stream buffer that triggers the sending of the events. If this is zero, greater than the buffer size, or if the FULLNESS flag is not set, then the receive side of a stream sends events when its buffer is seven eighths full and the transmit side of a stream sends events when its buffer is empty. The least significant byte should be the character or octet the receipt of which you want to trigger the sending of the events. All values, including zero, are allowed and only if the CHARACTER flag is not set are events not sent based on the characters received. The CHARACTER flag has no effect on the transmit side of streams.
The third integer argument is only required if the CUSTOM flag is set. The least significant byte should be the task to which events are to be sent when triggered by the specified stream conditions. If this is zero, events will be sent to the currently executing task. The most significant byte should be the pattern of events to be sent to the task. If this is zero, the standard events will be sent, which is event 2 for a timeout and event 0 for a fullness or character trigger condition. Note that if both bytes are zero, the standard events are sent to the current task, which is better achieved by not setting the CUSTOM flag and omitting the third argument entirely.
first argument |
second argument |
third argument |
|||
|---|---|---|---|---|---|
m.s.b. |
l.s.b. |
m.s.b. |
l.s.b. |
m.s.b. |
l.s.b. |
Flags |
Timeout |
Fullness |
Character |
Events |
Task |
The example below shows .
OsFCtl( OS_UART1, OS_SET_EVENTS, <<to do>> );