About Alloc
Alloc creates a special type of variable - an array variant. This array variant can store values. The values stored in this array variant must be of the same type.
Essentially, ALLOCate will reserve a memory range as described by the given layout that can be used as a RAM buffer or as an array variant.
Layout:
Dim variable_name as ALLOC * memory_size at memory_location
The allocated block of memory will not be initialized.
Example Usage:
Dim my256bytebuffer as alloc * 256 at 0x2400
There is a pointer to allocated memory. Use @variable_name.
Example Pointer
HSerPrint @my256bytebuffer
Extents
This method can be unsafe because undefined behaviour can result if the caller does not ensure that buffer extents are not maintained. Buffer extents are 0 (zero) to the memory_size - 1
Example Extents:
my256bytebuffer(0) = some_variable. Will address location 0x2400
my256bytebuffer(255) = some_variable. Will address location 0x24FF ' the 256th byte of the allocated memoryImplementers of ALLOC must ensure memory constraints remain true.
Safety
This method is unsafe because undefined behaviour can result if the caller does not ensure that buffer extents are not maintained. If buffer extents are exceeded the program may address areas of memory that have adverse impact on the operation of the microcontroller.
Examples of unsafe usage:
my256bytebuffer(256) = some_variable. Will address location 0x2500 ' this is the first byte of BUFFER RAM on the 18FxxQ43 chips... bad things may happen
my256bytebuffer(65535) = some_variable. Will address location 0x123FF ' this is the beyond the memory limit and the operation will write an SFR.Example Program
The following example program shows the ALLOCation of a 256 byte buffer at a specific address. The array variant is then populated with data and then shown on a serial terminal.
' Chip Settings and preamble
#CHIP 18F27Q43
#OPTION EXPLICIT
'Generated by PIC PPS Tool for GCBASIC - this explicit to a specific chip
#startup InitPPS, 85
#define PPSToolPart 18f27q43
Sub InitPPS
'Module: UART pin directions
Dir PORTC.6 Out ' Make TX1 pin an output
'Module: UART1
RC6PPS = 0x0020 'TX1 > RC6
End Sub
'Template comment at the end of the config file
' USART settings for USART1
#DEFINE USART_BAUD_RATE 9600
#DEFINE USART_TX_BLOCKING
#DEFINE USART_DELAY 0
'---------------------------
' Main Program
#DEFINE BUFFERSIZE 256 ' gives range of 0 to 255
'DIMension an ArrayVariant using ALLOC to create an ArrayVariant with the size of BUFFERSIZE.
'This array is created at memory location 0x2400.
'This memory location is specific to this chip ( you must ensure other microcontrollers address are valid).
Dim mybuffer1 as ALLOC * BUFFERSIZE at 0x2400
'A data table
Table myDataTable
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
0,1,2,3,4,5,6,7,8,9,0x0A,0X0B,0X0C,0X0D,0X0E,0X0F
End Table
Dim iLoop, tableDataValue, memoryDataValue as byte
'These varaibles are ONLY used to demonstrate the showing of the allocated memory address
Dim mybuffer1startaddress, mybuffer1endaddress as word
mybuffer1startaddress = @mybuffer1
mybuffer1endaddress = mybuffer1startaddress + BUFFERSIZE - 1
HSerPrintCRLF 2
HSerPrint "Buffer test - 256 bytes "
HSerPrint " at address: 0x"
HSerPrint hex( mybuffer1startaddress_h )
HSerPrint hex( mybuffer1startaddress )
HSerPrint " to 0x"
HSerPrint hex( mybuffer1endaddress_h )
HSerPrint hex( mybuffer1endaddress )
HSerPrintCRLF 2
'Load buffer with table data
for iLoop = 0 to 255
ReadTable myDataTable, [word]iLoop+1, tableDataValue
mybuffer1( iLoop ) = tableDataValue
next
wait 100 ms
HserPrint "Print dataDump array to serial terminal"
HSerPrintCRLF
for iLoop = 0 to 255
HSerPrint leftpad(str( myBuffer1(iLoop)),3)
If iLoop % 16 = 15 Then HSerPrintCRLF
next
Wait 100 ms
HSerPrintCRLF
HserPrint "Print memory to serial terminal using PEEK to get the memory location byte value"
HSerPrintCRLF
for iLoop = 0 to 255
memoryDataValue = PEEK ( @myBuffer1+iLoop )
HSerPrint leftpad(str( memoryDataValue ) ,3)
If iLoop % 16 = 15 Then HSerPrintCRLF
next
HSerPrintCRLF
Wait 100 msFor more help, see Declaring arrays with DIM
