alloc - Anobium/Great-Cow-BASIC-Help GitHub Wiki

Alloc

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 memory

Implementers 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 Great Cow Basic
    'PPS Tool version: 0.0.6.2
    'PinManager data: v1.81.0
    'Generated for 18f27q43
    '
    'Template comment at the start of the config file
    '
    #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
    Dim mybuffer1startaddress, mybuffer1endaddress as word ' this ONLY required to demonstrate the showing of the address

    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 ms

For more help, see Declaring arrays with DIM

⚠️ **GitHub.com Fallback** ⚠️