Table of Contents

The USB Wildcard User Guide

<< Previous | Next>>

Glossary of Mosaic USB Driver Functions

This glossary defines important constants and functions from the USB driver code and demo program.

Overview of Glossary Notation

The main glossary entries presented in this document are listed in case-insensitive alphabetical order (the underscore character comes at the end of the alphabet).  The keyword name of each entry is in bold typeface.  Each function is listed with both a C-style declaration and a Forth-style stack comment declaration as described below.  The "C:" and "4th:" tags at the start of the glossary entry distinguish the two declaration styles.

The Forth language is case-insensitive, so Forth programmers are free to use capital or lower case letters when typing keyword names in their program.  Because C is case sensitive, C programmers must type the keywords exactly as shown in the glossary.  The case conventions are as follows:

           ◙   Function names begin with a capital letter, and every letter after an underscore is capitalized.  Other letters are lower case, except for capitalized acronyms such as "USB".

           ◙   Constant names and C macros use capital letters.

           ◙   Variable names use lower case letters.

Each glossary entry starts with C-style and Forth-style declarations, and presents a description of the function.  Here is a sample glossary entry:

C:   uchar USB_Key_Module ( int module_num )

4th: USB_Key_Module (module_num -- char )

Waits (if necessary) for receipt of a character from the USB port on the specified Wildcard module, and returns the received character.  PAUSEs while waiting.  The returned byte is the next pending character in the input buffer (that is, the oldest unretrieved character in the receive buffer). See also USB_Key and USB_Revector.

The C declaration specifies that return data type before the function name, and lists the comma-delimited input parameters between parentheses, showing the type and a descriptive name for each.

The Forth declaration contains a "stack picture" between parentheses; this is recognized as a comment in a Forth program.  The items to the left of the double-dash ( -- ) are input parameters, and the item to the right of the double-dash is the output parameter.  Forth is stack-based, and the first item shown is lowest on the stack. In the Forth declaration the parameter names and their data types are combined.  All unspecified parameters are 16-bit integers.  Forth promotes all characters to integer type. 

The presence of both C and Forth declarations is helpful: the C syntax shows the types of the parameters, and the Forth declaration provides a descriptive name of the output parameter.

Glossary Quick Reference

Serial I/O Functions

int  USB_Ask_Key ( void )

int    USB_Ask_Key_Module ( int module_num )

void  USB_Emit ( uchar character )

void  USB_Emit_Module ( uchar character, int module_num )

void  USB_Flush (int module_num )

uchar USB_Key ( void )

uchar USB_Key_Module (int module_num )

void   USB_Revector ( void )

void   USB_Send_Immediate_Wakeup (int module_num )

Module Selection Variable

usb_module

Demonstration Program

USB_MODULE_NUM

void USB_Demo ( void )

Glossary Entries

C:   int USB_Ask_Key ( void )

4th: USB_Ask_Key ( -- flag )

Returns a flag indicating the receipt of a character on the USB port.  The contents of the usb_module variable specifies the module number.  The flag is true true (-1) if there is at least one character in the input buffer.  Otherwise the returned flag is false (0). See also USB_Ask_Key_Module and USB_Revector.

C:   int USB_Ask_Key_Module ( int module_num )

4th: USB_Ask_Key_Module ( module_num -- flag )

Returns a flag indicating the receipt of a character on the USB port.  The flag is true (-1) if there is at least one character in the input buffer of the specified channel.  Otherwise the returned flag is false (0). See also USB_Ask_Key and USB_Revector.

C:   void USB_Demo ( void )

4th: USB_Demo ( -- )

The top level function in the demonstration program. When called, it builds and activates a task named USB_TASK which runs the infinite loop USB_Monitor program to exchange data on the USB port. The task revectors the Emit, Key and Ask_Key (also called ?KEY) primitives so that all task I/O is implemented via the USB Wildcard.  The default QED-Forth task stays active using the serial port on the Mosaic Controller.  Thus, invoking this function allows you to simultaneously run an additional serial connection on the Mosaic Controller.  To exercise the demo, start the Mosaic terminal and set its Settings->Comm->Port to the USB Wildcard’s hardware port assigned by your PC (use your PC’s “Hardware Device Manager” to find out which port is assigned to the Mosaic USB Wildcard).

C:   void USB_Emit ( uchar character )

4th: USB_Emit ( char -- )

This function queues the specified character in the output buffer for transmission on the USB port. The usb_module variable specifies the module number.  If the output buffer is full, this routine waits and PAUSEs until there is room in the buffer, then puts the specified character in the buffer so that it will be transmitted. See also USB_ Emit_Module and USB_Revector.

C:   void USB_Emit_Module ( uchar character, int module_num )

4th: USB_Emit_Module ( char \module_num -- )

Queues the specified character in the output buffer for transmission on the USB port.  If the output buffer is full, this routine waits and PAUSEs until there is room in the buffer, then puts the specified character in the buffer so that it will be transmitted. See also USB_Emit and USB_Revector.

C:   void USB_Flush ( int module_num )

4th: USB_Flush ( module_num -- )

Reads and discards any input characters that are present in the receive buffer of the specified USB module. This function is useful when initializing the USB port to ensure that any “garbage” characters in the input buffer are discarded.

C:   uchar USB_Key ( void )

4th: USB_Key ( -- char )

Waits (if necessary) for receipt of a character from the USB port, and returns the received character. The usb_module variable specifies the module number.  PAUSEs while waiting.  The returned byte is the next pending character in the input buffer (that is, the oldest unretrieved character in the receive buffer). See also USB_Key_Module and USB_Revector.

C:   uchar USB_Key_Module ( int module_num )

4th: USB_Key_Module (module_num -- char )

Waits (if necessary) for receipt of a character from the USB port on the specified Wildcard module, and returns the received character.  PAUSEs while waiting.  The returned byte is the next pending character in the input buffer (that is, the oldest unretrieved character in the receive buffer). See also USB_Key and USB_Revector.

C:   int usb_module

4th: usb_module ( -- xaddr )

A 16-bit variable that holds the module_num of the USB Wildcard.  The contents of this variable are used by USB_Ask_Key, USB_Key, USB_Emit, and USB_Revector.  Functions that rely on this variable are not re-entrant. 

Note: It is possible to install and control more than one USB Wildcard on a single controller, but in this case the functions USB_Ask_Key_Module, USB_Key_Module, and USB_Emit_Module should be used to specify which module is being accessed.

C:   USB_MODULE_NUM

4th: USB_MODULE_NUM ( -- n )

A constant in the demonstration program whose value equals the Wildcard number.  This value must correspond to the jumper settings as shown in Table 1‑3.  Edit the source code of the demonstration program so that the value of this constant matches your hardware jumper settings.  This constant is used by the demonstration program to initialize the usb_module variable; see its glossary entry.

C: void USB_Revector ( void )

4th: USB_Revector (-- )

Revectors serial I/O in the current task to use the USB wildcard port whose module number is stored in the usb_module variable. After executing this function, the serial I/O primitives Emit, Key, and AskKey (?KEY in Forth) will execute USB_Emit, USB_Key, and USB_Ask_Key, and higher level print and scan functions that invoke these primitives in the current task will use the USB port.