SIM_is_loading_micro_checkpoint — obsolete API function
#include <simics/device-api.h> // in C
// always available in DML
// only supported with SIMICS_API = 6
bool
SIM_is_loading_micro_checkpoint(conf_object_t *obj);
Don’t use. There is no longer a concept of micro-checkpoints after removal of reverse execution.
Cell Context
dbuffer_append, dbuffer_prepend, dbuffer_insert — Add data to a dbuffer
#include <simics/device-api.h> // in C
// always available in DML
uint8 *
dbuffer_append(dbuffer_t *dbuffer, size_t len);
uint8 *
dbuffer_prepend(dbuffer_t *dbuffer, size_t len);
uint8 *
dbuffer_insert(dbuffer_t *dbuffer, size_t offset, size_t len);
These functions will extend the dbuffer with len bytes and return a pointer to the added bytes. The dbuffer_insert function adds the new data at offset in the buffer, while the dbuffer_prepend and dbuffer_append functions add it at the beginning and end, respectively.
The returned pointer points to a memory area that is only guaranteed to contain valid data for the newly added bytes, and it is illegal to reference data before it or more than len-1 bytes ahead. The new memory area is not guaranteed to be initialized.
The returned pointer is also only valid until the next operation on the dbuffer function, except for calling dbuffer_len.
dbuffer_append_external_data, dbuffer_prepend_external_data — Add static data
#include <simics/device-api.h> // in C
// always available in DML
uint8 *
dbuffer_append_external_data(dbuffer_t *dbuffer, void *data,
size_t len, bool adopt);
uint8 *
dbuffer_prepend_external_data(dbuffer_t *dbuffer, void *data,
size_t len, bool adopt);
These functions work similar to dbuffer_append and dbuffer_prepend, but with the difference that the data isn’t copied. Instead, the buffer will reference the data pointed to directly.
If the adopt flag is true, the control of the data block is transferred to the dbuffer. It is assumed to be a block allocated with MM_MALLOC, and will be freed with MM_FREE when the dbuffer is released.
If the adopt flag is false, the dbuffer will not free the memory. Since there is no way to control the lifetime of the external reference if the dbuffer reference has been passed to another function, this option should never be used to point to memory on the stack or to memory that will eventually deallocated. Pointing to static memory is usually safe. This should also only be used for buffers that will only be read from, since there is no way to know when the external pointer is used, and when a copy is used.
dbuffer_append_value, dbuffer_prepend_value — Add data with uniform content
#include <simics/device-api.h> // in C
// always available in DML
uint8 *
dbuffer_append_value(dbuffer_t *dbuffer, int value, size_t len);
uint8 *
dbuffer_prepend_value(dbuffer_t *dbuffer, int value, size_t len);
This adds data to a dbuffer and sets all the added bytes to value. It has the same effect as using dbuffer_append or dbuffer_prepend and calling memset to set the contents.
The return value is a pointer to the data just added.
dbuffer_clone — Make a full copy of another buffer
#include <simics/device-api.h> // in C
// always available in DML
dbuffer_t *
dbuffer_clone(dbuffer_t *dbuffer);
This function returns a new dbuffer that contains the same data as the buffer given in the dbuffer parameter. This doesn’t involve copying any memory, since they can share the same storage initially. However, they are still completely independent, and operations on one buffer has no effect on the other.
The returned dbuffer should be released with dbuffer_free when it is no longer needed.
dbuffer_copy_append, dbuffer_copy_prepend — Copy data from a dbuffer
#include <simics/device-api.h> // in C
// always available in DML
void
dbuffer_copy_append(dbuffer_t *dst, dbuffer_t *src, size_t offset, size_t len);
void
dbuffer_copy_prepend(dbuffer_t *dst, dbuffer_t *src, size_t offset, size_t len);
These functions copies len bytes from the dbuffer src, at offset offset, and adds it to the beginning or end of the dbuffer dst.
This can often be done without actually copying any memory, so it is usually very efficient.
dbuffer_free — Release a dbuffer
#include <simics/device-api.h> // in C
// always available in DML
void
dbuffer_free(dbuffer_t *dbuffer);
Release a dbuffer that will not be used anymore. This will also free any data in the buffer that isn’t also used by other buffers. After calling this function, the dbuffer must not be used anymore.
See also src/include/simics/util/dbuffer.h
dbuffer_len — Get the size of a dbuffer
#include <simics/device-api.h> // in C
// always available in DML
size_t
dbuffer_len(const dbuffer_t *dbuffer);
This function returns the amount of data stored in a dbuffer. This is the number of bytes that will be returned by dbuffer_read_all.
dbuffer_read_some, dbuffer_read, dbuffer_read_all — Extract data for reading
#include <simics/device-api.h> // in C
// always available in DML
const uint8 *
dbuffer_read_some(dbuffer_t *dbuffer, size_t offset, size_t len,
size_t *actual_len);
const uint8 *
dbuffer_read(dbuffer_t *dbuffer, size_t offset, size_t len);
const uint8 *
dbuffer_read_all(dbuffer_t *dbuffer);
The offset and len parameters specify a region of the buffer to read from. The returned pointer is guaranteed to point to a contiguous block of memory of size len. It is illegal to write to the block return by these functions, since they may be shared by other dbuffers. Use the dbuffer_update functions if you need to both read and write to the dbuffer.
The returned pointer is only valid until the next operation on the dbuffer, except for calling dbuffer_len.
The offset and len must specify a valid region, so that the end of the region is not past the end of the dbuffer.
The dbuffer_read_some function takes an actual_len parameter, and may return a smaller buffer than requested. The actual number of valid bytes in the returned buffer is stored in *actual_len. It will return a smaller buffer if it would have had to copy memory to return a pointer to the whole region. This means that you can use this function repeatedly to extract all the requested data in the most efficient way. If NULL is passed for actual_len, it will return the full region.
The dbuffer_read_all function assumes 0 for offset, and buffer_len(dbuffer) for len.
dbuffer_remove, dbuffer_remove_head, dbuffer_remove_tail — Remove data from a dbuffer
#include <simics/device-api.h> // in C
// always available in DML
void
dbuffer_remove(dbuffer_t *dbuffer, size_t offset, size_t remove_len);
void
dbuffer_remove_head(dbuffer_t *dbuffer, size_t remove_len);
void
dbuffer_remove_tail(dbuffer_t *dbuffer, size_t remove_len);
These functions will remove remove_len bytes from dbuffer. The dbuffer_remove function will remove data starting at offset, while the other functions will remove data from the beginning or end of the buffer.
This usually doesn’t involve moving any memory contents, and should be very efficient even if the buffer is large.
The size of data to remove must be available in the buffer. For example offset + remove_len must not be greater than the buffers length. Similarly for the dbuffer_truncate function there must be at least new_size bytes in the current buffer.
dbuffer_replace_some, dbuffer_replace, dbuffer_replace_all — Replace data
#include <simics/device-api.h> // in C
// always available in DML
uint8 *
dbuffer_replace_some(dbuffer_t *dbuffer, size_t offset, size_t len,
size_t *actual_len);
uint8 *
dbuffer_replace(dbuffer_t *dbuffer, size_t offset, size_t len);
uint8 *
dbuffer_replace_all(dbuffer_t *dbuffer);
The offset and len parameters specify a region of the buffer to write to. The returned pointer is guaranteed to point to a contiguous block of memory of size len, but is not guaranteed to contain the existing data in the buffer. Use these functions when completely replacing a region of the buffer with new data.
The returned pointer is only valid until the next operation on the dbuffer, except for calling dbuffer_len.
The offset and len must specify a valid region, so that the end of the region is not past the end of the dbuffer.
The dbuffer_replace_some function takes an actual_len parameter, and may return a smaller buffer than requested. The actual number of valid bytes in the returned buffer is stored in *actual_len. It will return a smaller buffer if it would have had to copy memory to return a pointer to the whole region. This means that you can use this function repeatedly to write all the requested data in the most efficient way. If NULL is passed for actual_len, it will return the full region.
The dbuffer_replace_all function assumes 0 for offset, and buffer_len(dbuffer) for len.
dbuffer_split — Split a dbuffer
#include <simics/device-api.h> // in C
// always available in DML
dbuffer_t *
dbuffer_split(dbuffer_t *dbuffer, size_t offset);
This function returns a new dbuffer that contains the offset first bytes from dbuffer, and removes those bytes from dbuffer The effect is that the dbuffer is split in two halves, leaving the second half in the original dbuffer and returning the first half as a new dbuffer.
The returned dbuffer should be released with dbuffer_free when it is no longer needed.
dbuffer_update_some, dbuffer_update, dbuffer_update_all — Extract data for updating
#include <simics/device-api.h> // in C
// always available in DML
uint8 *
dbuffer_update_some(dbuffer_t *dbuffer, size_t offset, size_t len,
size_t *actual_len);
uint8 *
dbuffer_update(dbuffer_t *dbuffer, size_t offset, size_t len);
uint8 *
dbuffer_update_all(dbuffer_t *dbuffer);
The offset and len parameters specify a region of the buffer to access. The returned pointer is guaranteed to point to a contiguous block of memory of size len. The block can be used for reading and writing data to the dbuffer.
The returned pointer is only valid until the next operation on the dbuffer, except for calling dbuffer_len.
The offset and len must specify a valid region, so that the end of the region is not past the end of the dbuffer.
The dbuffer_update_some function takes an actual_len parameter, and may return a smaller buffer than requested. The actual number of valid bytes in the returned buffer is stored in *actual_len. It will return a smaller buffer if it would have had to copy memory to return a pointer to the whole region. This means that you can use this function repeatedly to access all the requested data in the most efficient way. If NULL is passed for actual_len, it will return the full region.
The dbuffer_update_all function assumes 0 for offset, and buffer_len(dbuffer) for len.
new_dbuffer — Create a new dbuffer
#include <simics/device-api.h> // in C
// always available in DML
dbuffer_t *
new_dbuffer();
This function returns an empty dbuffer. Use it when you need a new dbuffer, and call dbuffer_free when it isn’t needed anymore.
See also src/include/simics/util/dbuffer.h