Note: this needs update in brood-5 PURRR18 1.0 boot standard ------------------------- * Initial communication with the boot interpreter uses a serial 9600 Baud, 8 data bits, 1 stop bit, no parity protocol. There are 16 commands. The remaining 240 commands are reserved, and behaviour is currently unspecified. This protocol is designed to work reliably with a 1--byte buffer. BASIC: 0 NOP ( -- ) Do nothing. 1 RECEIVE ( -- byte) Transfer a byte from host -> target stack. 2 TRANSMIT ( byte -- ) Transfer a byte from target stack -> host. 3 EXECUTE ( lo hi -- ) Call 16 bit machine word on stack (byte address). PIC18 EXTENSIONS: 4 LDA ( -- ) Receive 2 bytes, store in A register. 5 LDF ( -- ) Receive 2 bytes, sotre in F register. 6 ACK ( -- ) Transmit a 00 byte. 7 RESET ( -- ) Reset target. 8 N@A+ ( n -- ) Transmit a ram block, start at address in A register + increment 9 N@F+ ( n -- ) Transmit a flash block, start at address in F register + increment A N!A+ ( n -- ) Receive a ram block, start at address in A register + increment B N!F+ ( n -- ) Receive a flash block(*), start at address in F register + increment C CHKBLK ( -- ) AND all bytes in flash block at F, transmit result. D PREPLY ( -- ) Transmit identification string. E FERASE ( -- ) Erase flash block at F. F FPROG ( -- ) Program flash block at F. (*) This stores the data in an 8 byte flash write buffer. See PIC18 datasheet. Given the boot kernel dictionary, the first 3 words commands are sufficient for communication. The other 12 commands are shortcuts that make communication a bit more efficient, and provide an interface that enables programming without access to the dictionary. * The .state file is a single s-expression containing a hierarchical dictionary, which is a list of (name . value) pair for which the value can be a hierarchical dictionary. The value of the toplevel element 'dict' is a dictionary with (name . address) pairs reflecting the absolute word addresses of the Purrr words in the bootloader. For example: ((dict (here . 288) (warm . 222) (hello . 217) (init-all-but-rs . 207) (f-> . 199) (_route . 193) (_route/e . 190) (chkblk . 177) (ldf . 170) (lda . 163) (preply . 158) (n!a+ . 149) (n@a+ . 140) (n!f+ . 130) (n@f+ . 120) (interpreter . 117) (interpret . 99) (safe . 95) (check . 90) (fprog . 86) (ferase . 82) (ack . 79) (jsr . 71) (transmit . 66) (receive . 52) (program . 46) (erase . 43) (engage . 33) (ram (here . 0)) (boot-40 . 32) (boot . 0) (isr-low . 268) (isr-high . 260) (application . 256)) The other top level elements in the state file contain metadata: path A list of strings describing the search path for forth files. port The device node of the serial port connecting to the target. config-bits The PIC18 configuration bits. file Contains a directory of files associated to the project prj The toplevel project directory. state The project state file. monitor Source code for the boot interpreter. hex Name of the HEX file to store boot interpreter code. application Toplevel application source file. Example: ((path "." "/" "pic18" "prj/CATkit") (port "/dev/ttyUSB0") (file (prj "prj/CATkit") (state "monitor.state") (monitor "monitor.f") (hex "monitor.hex") (application "sheepsint.f")) (config-bits '(3145728 (0 200 15 0 0 128 128 0 3 192 3 224 3 64))))