pincw buf

increments the two-byte value stored at SRAM label buf. By convention, the PicoWeb server’s standard pcode uses an n-byte scratch buffer located starting at SRAM location buf for general purpose working storage, a kind of pcode "register set".

The pcode interpreter maintains a separate 5-deep pcode return address stack which is used store return address needed to implement the pcall and pret pcode instructions.

PicoWeb pcode can be freely intermixed with AVR assembly language providing that a pbegin pcode instruction us used to enter a pcode section and a pend pcode instruction is used to exit a pcode section. Failure to observe this rule will produce unpredictable results.

User-Supplied Pcode Opcodes - Users can add their own pcode opcodes, providing certain conventions are followed. The following example shows code for a user-supplied pcode instruction called pmycode that takes three operands:

  pmycode: pcode_routine 3
           .
           .  (user-supplied code goes here)
           .
           ret   ; return to pcode interpreter

The first line of this sample routine tells the PicoWeb development system that pmycode is a new, legal pcode instruction which requires exactly three operands.

Pcode Instruction Memory Format – Pcode source instructions are pre-processed by the PicoWeb development environment and converted into a series of AVR assembler .dw pseudo-ops. Each pcode instruction generates a single 16-bit pcode opcode word followed by zero or more 16-bit pcode operand words. The bottom 12 bits of the opcode word are the address of the native execution routine. The uppermost bit of the opcode word is an "extended addressing" flag. If this bit is set, extended addressing is enabled, otherwise it is disabled. Extended addressing controls how the operand words are interpreted. When extended addressing is disabled, all operand words are considered "immediate" operands. When extended addressing is enabled, the uppermost three bits in each operand word specify which extended addressing mode(s) are to be applied, with the lower 13 bits of the operand are treated as an address.

AAAAAAAAAAAA = address of pcode routine in on-chip or external EEPROM memory

IIIIIIIIIIIIIIII = immediate data value

AAAAAAAAAAAAA = address of pcode routine in on-chip or external EEPROM memory

W = 0: fetch 16-bit data word at address AAAAAAAAAAAAA (indirect word addressing)

W = 1: fetch 8-bit data byte at address AAAAAAAAAAAAA (indirect byte addressing)

S = 0: do nothing after fetching data

S = 1: swap high/low bytes after fetching data

A pcode opcode word of all zeros (.dw 0) will cause the pcode interpreter to exit and jump to the first AVR assembly language instruction after the zero word. (The pcode opcode pend is defined to have all 16 opcode word bits set to zero.)

The following example is a pcode routine called decconv which converts a passed 16-bit signed integer value into ASCII digits, then outputs that text (to the serial port or to the Ethernet) using the pcode I/O opcode pputch. This "pure pcode" routine uses 11 bytes of SRAM starting at the label buf to perform its work. It can be called from pcode as in the following pcode example, which will output the string "-12345":

   pmovwi  buf,-12345
   pcall   decconv

The routine decconv can be placed in the AVR microprocessor’s on-chip program memory, or it can be placed in the PicoWeb server’s external serial EEPROM memory. Execution speed is much slower from the external SEEPROM memory because in that case the opcode and operand words must be fetched serially as they are executed (i.e., one bit at a time at the rate of ~400 Kbits/sec over the I²C bus).

   ;
   ; decconv – integer to decimal converter
   ;
   ; inputs:
   ;   buf = 16-bit signed integer to convert
   ;
   ; outputs:
   ;   ASCII value, printed with pputc
   ;
   ; method:
   ;   repeatedly divide input by 10 until quotient is 0, using the remainder 
   ;   to make ASCII digits.  The ASCII digits are buffered, then output at 
   ;   end in reverse order.  Negative inputs get a leading '-' sign.
   ;   
   ; caveats:
   ;   MUST be called with a pcall!!
   ;   Destroys SRAM locations buf through buf+10
   ;
   #define DEC_VAL buf                   ; word to convert (destroyed!)
   #define DEC_REM buf+2                 ; remainder from divide op
   #define DIG_PTR buf+4                 ; text buffer pointer
   #define DIG_BUF buf+6                 ; text buffer (5 bytes max.)
   
   decconv:
       pmovwi DIG_PTR,DIG_BUF            ; initialize pointer to DIG_BUF
       pbitwi DEC_VAL,0x8000             ; what's the sign of input?
       pjumpeq decconv1                  ; positive...start conversion
       pnegw DEC_VAL                     ; negative...negate input word
       pputc '-'                         ; output leading minus sign
   decconv1:
       pdiv DEC_VAL,[DEC_VAL],10         ; do next digit (divide by 10)
       paddwi DEC_REM,'0'                ; convert digit for display
       pmovbi [DIG_PTR],[byte DEC_REM]   ; save ASCII digit
       pincw DIG_PTR                     ; bump past digit just stored
       psubwi DEC_VAL,0                  ; test remaining value
       pjumpne decconv1                  ; more to convert if non-zero
   decconv2:
       pdecw DIG_PTR                     ; point to next digit to output
       pputcb [byte DIG_PTR]             ; output ASCII digit
       pcmpwi DIG_PTR,DIG_BUF            ; are we back to the beginning?
       pjumpne decconv2                  ; nope...do another digit
       pret                              ; yes...return to caller

Preprocessor #define statements are used in the example to make the source code more readable. These #define statements call out SRAM locations in the PicoWeb server’s general purpose "scratch" buffer buf.

Note the use of square brackets ([ ]) on three of the sample pcode instruction lines indicating "indirect addressing". For example, the pmovbi pcode opcode (move byte) expects a destination memory address as its first operand and an immediate value as its second operand. In the example, the destination address is specified as [DIG_PTR], an indirect addressing form, which tells the pcode interpreter to instead use DIG_PTR as a pointer to the "real" target byte address. The routine increments DIG_PTR as it converts digits, allowing the ASCII digits to be stored sequentially starting at memory location DIG_BUF.

On the same sample pcode pmovbi instruction line, the second operand normally supplies an immediate source byte. However, in the example, this operand is specified as [byte DEC_REM], a more complex indirect addressing mode, which tells the pcode interpreter to fetch the byte stored at memory location DEC_REM, instead of simply taking the immediate value supplied as the second pcode operand. If the second operand was specified as simply "DEC_REM", then the pcode instruction would (incorrectly) repeatedly store the low byte of the literal address DEC_REM!