Allocating Memory for Buffers

Each buffer has a certain size (i.e., a memory capacity). This capacity is allocated upon request from your program. When the device initially boots, no memory is allocated to buffers at all.

Memory for buffers is allocated in pages. A page is 256 bytes of memory. Allocating memory for a buffer is a two-step process: First you have to request for a specific allocation (a number of pages) and then you have to perform the actual allocation. For the RX buffer, request memory using ser.rxbuffrq and for the TX buffer, request it using ser.txbuffrq.

The allocation method (sys.buffalloc) applies to all buffers previously specified, in one fell swoop. Hence:

dim in, out as byte

out = ser.txbuffrq(10) ' Requesting 10 pages for the TX buffer. Out will then contain how many can actually be allocated.

in = ser.rxbuffrq(7) ' Requesting 7 pages for the RX buffer. Will return number of pages which can actually be allocated.

' ....  Allocation requests for buffers of other objects .... 

sys.buffalloc ' Performs actual memory allocation, as per previous requests.

Actual memory allocation takes up to 100ms, so it is usually done just once, on boot, for all required buffers. If you do not require some buffer, you may choose not to allocate any memory to it. In effect, it will be disabled.

You may not always get the full amount of memory you have requested. Memory is not an infinite resource, and if you have already requested (and received) allocations for 95% of the memory for your platform, your next request will get up to 5% of memory, even if you requested 10%.

There is a small overhead for each buffer. Meaning, not 100% of the memory allocated to a buffer is actually available for use. A certain number of bytes in each buffer is reserved for variables needed to administer this buffer. This number is 17 for 16-bit platforms and 33 for 32-bit platforms. Platform type is specified in your platform documentation.

Thus, if we request (and receive) a buffer with 2 pages (256 * 2 = 512), then we can only store 512 - 17 or 512 - 33 bytes in this buffer, depending on the platform type.

You can only change the size of buffers that belong to serial ports that are closed (ser.enabled = 0) at the moment the sys.buffalloc method executes. If the port is opened at the time the sys.buffalloc method executes, then buffer capacities for this port will remain unchanged, even if you requested changes through ser.rxbuffrq and ser.txbuffrq.