6.3.4 Message-buffer manipulation functions

The coNCePTuaL language facilitates verifying message contents and touching every word in a message (see Data touching). The following functions implement those features.

Function: void ncptl_fill_buffer (void *buffer, ncptl_int numbytes, int validity)

Fill a region of memory with known values. If validity is ‘+1’, ncptl_fill_buffer() will fill the first numbytes bytes of buffer with a verifiable sequence of integers (see Data touching). If validity is ‘-1’, ncptl_fill_buffer() will pollute the first numbytes bytes of buffer. Receive buffers should be polluted before reception to avoid false negatives caused, for example, by an inadvertently dropped message destined for a previously validated buffer.

Function: ncptl_int ncptl_verify (void *buffer, ncptl_int numbytes)

Verify the contents of memory filled by ncptl_fill_buffer(). The function returns the number of erroneous bits. ncptl_verify() is used to implement coNCePTuaL’s WITH VERIFICATION construct (see Data touching).

Function: void ncptl_touch_data (void *buffer, ncptl_int numbytes)

Touch every byte in a given buffer. ncptl_touch_data() is used to implement the WITH DATA TOUCHING construct described in Data touching.

The following function, ncptl_touch_memory(), does not actually manipulate message buffers. It is included in this section because of its similarity to ncptl_touch_data(). ncptl_touch_data() touches message buffers to implement the WITH DATA TOUCHING construct; ncptl_touch_memory() touches a hidden memory region to implement the TOUCHES statement.

Function: void ncptl_touch_memory (void *buffer, ncptl_int bufferbytes, ncptl_int wordbytes, ncptl_int firstbyte, ncptl_int numaccesses, ncptl_int bytestride)

Walk a memory region buffer of size bufferbytes bytes. Each “word” to touch contains wordbytes bytes. firstbyte indicates the byte index into buffer from which to start touching. The function will read and write numaccesses “words” with stride bytestride bytes. For example, ‘ncptl_touch_memory (mybuffer, 1048576, 64, 192, 10000, 4096)’ will read and write (but otherwise do nothing with) the 64 bytes that lie 192 bytes into a 1MB memory region, then the 64 bytes starting at offset 4288, then the 64 bytes starting at 192+4096*2, then at 192+4096*3, then at 192+4096*4, and so forth up to 192+4096*10000, wrapping around the 1MB region as necessary.

A bytestride of NCPTL_INT_MIN implies a random stride.

As an important special case, if firstbyte is ‘-1’, then ncptl_touch_memory() will touch one or more message buffers (cf. ncptl_malloc_message() in Memory-allocation functions) instead of the given buffer. In that case, bufferbytes stores the buffer number (a nonnegative number). If bufferbytes is ‘-1’, however, then all message buffers are touched. Note that when firstbyte is ‘-1’, all parameters to ncptl_touch_memory() other than bufferbytes are ignored.

ncptl_touch_memory() is intended to to be used to implement the TOUCHES statement (see Touching memory).