COM1_WaitForTxEmpy

COM1_WaitForTxEmpty

Purpose:	Wait until the COM1 Transmit Buffer and the USART Data Register are both completely empty before returning to the caller.
Assumes:	Nothing.
Passed:	Nothing.
Returns:	Nothing.
Alters:	Nothing; even SREG (the FLAGs BYTE) is preserved.
Example:	.ORG 0x3100 ; Change from the oft-used starting address CALL APushAll ; We'll need to use a single Register > R15 LDS R17, bDumpRegFlags ; Retrieve and save a copy of this single PUSH R17 ; System variable needed IN R9, SREG ; Save the FLAGs, which have not changed yet PUSH R31 PUSH R30 ; Save the present 'Z' pointer IN R31, SPH ; Copy the present Stack Pointer to 'Z' IN R30, SPL ; Point 'Z' at the R0 value PushAll() saved ADIW R30, 4 ; by adding the # of PUSHes herein + 1 ORI R17, 1 << BIT_DR_DUMP_STACK STS bDumpRegFlags, R17 ; Turn on the BIT which will also dumps stack OUT SREG, R9 ; Restore the caller's FLAGs LDD R17, Z+17 ; To access any Register saved with PushAll(), LDD R9 , Z+9 ; use the Register number as the LDD adder POP R30 ; Restore the 'Z' pointer; all Registers AND POP R31 ; the FLAGs now have the same values they CALL ADumpRegs_Begin ; had upon to this routine CALL ACOM1_WaitForTxEmpty ; All to demonstrate this wait ... ; Make any choices and/or code changes that are needed for this extension ... POP R16 ; Retrieve and restore the original value that STS bDumpRegFlags, R16 ; bDumpRegFlags had before calling this logic SEZ ; Return "not handled" by setting ZERO flag JMP APopAll ; Restore all Registers (includes R16)
Test it:	This is a little more elaborate example and setup, but it has a very useful routine with some interesting features:
	>DES EEPROM contents: 0000: 10 21 00 9F 01 00 84 FF-04 00 FF FF 28 3C 50 FF .!..........(<.. 0010: C0 00 3F FF 40 08 03 67-FF 25 74 FF FF FF FF FF ..?.@..g.%t..... 0020: 74 28 05 00 FF FF 2A FF-FF 14 30 20 00 30 FF FF t(....*...0 .0.. 0030: 80 16 FF FF FF FF FF FF-60 00 B0 00 80 01 FF FF ........`....... 0040: FF FF FF FF FF FF 00 2F-FF FF FF FF FF FF FF FF ......./........ >N 0 ? ; Read nRF Register 0 (no extension) 0x00 (FF) -> 0xFF = B11111111 >EW 72 = 0x3100 ; Point the extension pointer at our subroutine >DE+ 64 16 ; Confirm that it has that value EEPROM contents: 0040: FF FF FF FF FF FF 00 2F-00 31 FF FF FF FF FF FF ......./.1...... >N 0 ? ; Repeat the command with the extension pointer set 10 32 54 76 98 1110 1312 1514 1716 1918 2120 2322 2524 2726 2928 3130 SP RetAdd SREG ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ------ -------- 0000 01A8 095A FF28-0004 0000 0000 4000-0021 00FF 4E3A 3020-940F 0230 0280 1880 08CE 312A ItHsVNzc STACK contents: 08C0: 18 18 .. 08D0: 95 3A 00 00 A8 01 5A 09-28 FF 04 00 00 00 00 00 .:....Z.(....... 08E0: 00 40 21 00 FF 00 3A 4E-20 30 0F 94 30 02 80 02 .@!...:N 0..0... 08F0: 80 18 39 0C 00 02 23 4D-31 37 30 02 31 0D 3A E9 ..9...#M170.1.:. 0x00 (FF) -> 0xFF = B11111111 >EW 72 = -1 ; Enter 0xFFFF as the EEPROM WORD at 0x48 >DE+ 64 16 EEPROM contents: 0040: FF FF FF FF FF FF 00 2F-FF FF FF FF FF FF FF FF ......./........ >N 0 ? ; Repeat the command with no extension pointer 0x00 (FF) -> 0xFF = B11111111 > >; Our subroutine could also be called directly from the command line: m>; Remember to log in first ... m>@ 0x3100 10 32 54 76 98 1110 1312 1514 1716 1918 2120 2322 2524 2726 2928 3130 SP RetAdd SREG ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ------ -------- 0000 04D4 09CA FF28-0004 0000 0000 4000-0021 0000 0D10 1880-0000 0000 0280 1880 08D4 312A IthsVNzc STACK contents: 08D0: 18 18 95 3A-00 00 D4 04 CA 09 28 FF ...:......(. 08E0: 04 00 00 00 00 00 00 40-21 00 00 00 10 0D 80 18 .......@!....... 08F0: 00 00 00 00 80 02 80 18-31 37 30 02 31 0D 3A E9 ........170.1.:. m>@ 0x3100 12345 10 32 54 76 98 1110 1312 1514 1716 1918 2120 2322 2524 2726 2928 3130 SP RetAdd SREG ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ------ -------- 0000 001B 09D8 FF28-0004 0000 0000 4000-0021 2000 0D10 1880-0000 0239 0280 1880 08D4 312A IthsVNzc STACK contents: 08D0: 18 18 95 3A-00 00 1B 00 D8 09 28 FF ...:......(. 08E0: 04 00 00 00 00 00 00 40-21 00 00 20 10 0D 80 18 .......@!.. .... 08F0: 00 00 39 02 80 02 80 18-31 37 30 02 31 0D 3A E9 ..9.....170.1.:. m>

Notes:	The Operating System handles the COM1 Transmit buffering as a circular FIFO queue. It updates bCOM1TxHeadPtr as characters are enbuffered and bCOM1TxTailPtr as they are transmitted out the COM1 serial port (i.e., placed in UDR0, the USART Data Register.)
	This system function checks waits until the tail pointer reaches the head pointer. It also verifies that the UDRE0 BIT in Register UCSR0A is clear to verify that the last BYTE transmitted has completely cleared the USART.
	It holds in a tight loop, not allowing any additional BYTE to be written to the COM1 Transmit Buffer. This includes the background data output system function.
	If interrupts were not enabled upon calling this function, they are enabled while in it and disabled again (i.e., SREG restored) upon exiting it.
	With interrupts enabled, characters can still be received into the COM1 Receive buffer and the system clock timer update, for example, along with any other interrupt-based process.

Dropin: (setup code)	; Setup for the COM1_WaitForTxEmpty() call: ; Passed: Nothing. ; Returns: Nothing. ; Alters: Nothing.
Also see:	The COM1 Transmit Status group of System Functions and the Command Extensions.