.. index:: buffers, arrays, adc, data processing, fast ram, stack, buffer:create .. _buffers: BUFFERS ======= .. note:: There is no ready-made support code for partially initialised buffers. Either you use NVARIABLE which creates a fully initialised variable of up to 15 cells length, or you use BUFFER: and partially initialise the values yourself in an init routine. Quick Buffer Test ----------------- For the Impatient. :: \ Create the Buffer 'V1', reserve three cells for it. 3 buffer: v1 \ Create word to write to the buffer : v1! ( data index -- ) v1 + c! ; \ write v1 to the buffer 0 0 v1! 1 1 v1! 2 2 v1! \ create read buffer word : v1@ ( index -- data ) v1 + c@ hex. ; \ Read from the buffer 0 v1@ 1 v1@ 2 v1@ \ Output \ 0 v1@ 00000000 ok. \ 1 v1@ 00000001 ok. \ 2 v1@ 00000002 ok. Buffer Usage ------------ You are reading a fast 8 bit Analog to Digital Converter and after 16 readings you process the data, but it's so fast that you only have time to save now and process later, what do you do ? 1. Use the Stack ? You could, but what if you wanted to collect 100 samples ? 2. Use a Buffer. Buffers are used to save/fetch data in (fast) Ram and can be made any length for which you have Ram to spare. .. seealso:: For saving INITIALISED data use an :ref:`ARRAY` 16 byte (character) buffer -------------------------- Create the buffer ^^^^^^^^^^^^^^^^^ Buffers are created in the program as shown with the buffer "data' below. They can't be created from within a Word, and they exist only in ram. The $F mean to reserve 15 bytes. (0 to E = 15) :: $F buffer: data Write to the buffer ^^^^^^^^^^^^^^^^^^^ "data!" takes two parameters, a character (byte) of 8 bits and an index (#) of 0 - $E = 15 ($0F) :: : data! ( c # -- ) data + c! ; $00 0 data! $01 1 data! $02 2 data! $03 3 data! $04 4 data! $05 5 data! $06 6 data! $07 7 data! $08 8 data! $09 9 data! $0A $A data! $0B $B data! $0C $C data! $0D $D data! $0E $E data! Read from the buffer ^^^^^^^^^^^^^^^^^^^^ "data@" takes only one parameter, the index of the data being read. :: : data@ ( # -- u ) data + c@ ; 0 data@ h.2 00 ok. 1 data@ h.2 01 ok. 2 data@ h.2 02 ok. 3 data@ h.2 03 ok. 4 data@ h.2 04 ok. 5 data@ h.2 05 ok. 6 data@ h.2 06 ok. 7 data@ h.2 07 ok. 8 data@ h.2 08 ok. 9 data@ h.2 09 ok. $A data@ h.2 0A ok. $B data@ h.2 0B ok. $C data@ h.2 0C ok. $D data@ h.2 0D ok. $E data@ h.2 0E ok. Find the address of the buffer ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: data hex. 20000530 ok Dump memory from 'data' ^^^^^^^^^^^^^^^^^^^^^^^ The data itself can be seen in the memory dump below. :: $20000530 32 dump 20000530 : 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F | ........ ........ | 20000540 : 18 05 00 20 20 18 05 64 61 74 61 40 80 23 DB 04 | ... ..d ata@.#.. | 20000550 : A6 33 DB 00 F6 18 36 78 70 47 03 00 30 05 00 20 | .3....6x pG..0.. | Second Example, CELLS --------------------- Buffer Creation (Cells) ^^^^^^^^^^^^^^^^^^^^^^^ Cell = 32 bits or byte * 4 :: compiletoflash 10 cells buffer: thingamabobs compiletoram Create Buffer Access Word ^^^^^^^^^^^^^^^^^^^^^^^^^ :: : thingamabob ( # -- a ) cells thingamabobs + ; Store to Buffer ~~~~~~~~~~~~~~~ :: -1 5 thingamabob ! Fetch From Buffer ~~~~~~~~~~~~~~~~~ :: 5 thingamabob @ The Buffer XT ------------- This shows the Word itself is located in Flash memory space. :: ' things hex. 0001677E ok. Yet the "base" index address is in Ram: :: things hex. 20004E0C ok. Show Packed Data ---------------- :: $20004E0C @ hex. F3F2F1F0 ok. Dump the Buffer --------------- :: $20004E0C dump16 20004E00 : 002A 005E 008A 00A6 0032 00F6 004E 00A1 0070 0041 006B 00DA 00F0 00F1 00F2 00F3 | *^..2.N. pAk..... | Proving a buffer only holds X bytes ----------------------------------- Thanks to rsoft, mrmobius and rdrop-exit :: 4 buffer: test here test - hex. 00000004 ok. .. warning:: You may be able to save and retrieve more than 4 bytes in the "test" buffer above, but the data is going somewhere it probably shouldn't ... "buffer overflow" ! as the buffer will only save bytes in index 0 - 3.