3.4 Obsolete Device API Types and Functions

The following types and functions are still available when a module is compiled for an obsolete API. Compiling for an obsolete API is described in the Model Builder User's Guide.

The DBuffer library is part of the Simics API. Up to Simics 4.0, it was the preferred method to transfer data blocks, such as network packets, inside the simulation. For code using the new link based on the link library, and for new models, we recommend using the frags_t data type instead.

3.4.1 Obsolete Device API Types

dbuffer_t

NAME

dbuffer_t

SYNOPSIS

typedef struct dbuffer dbuffer_t;

DESCRIPTION

This type is used to store blocks of binary data. It is optimized for fast adding and removing of data, and does fast copying between buffers using copy-on-write semantics.

The type is not inherently thread safe, so each instance must have a single thread as owner, and only the owner can read or write from the instance, however ownership can be transferred to another thread. To share the data with other threads, the instance must first be cloned using dbuffer_clone.

init_prefs_t

NAME

init_prefs_t

SYNOPSIS

typedef struct {
        bool batch_mode;
        bool quiet;
        bool verbose;
        bool python_verbose;
        bool disable_istc;
        bool disable_dstc;
        bool module_cache_enable;
        bool rdp;
        bool sign_module;
        const char *log_file;

        /* The Simics project to use */
        const char *project;       // NULL to use saved prefs value
        const char *workspace;     // Deprecated, do not use

        gui_mode_t gui_mode;       // GUI_Mode_Default to use saved prefs value
        cpu_variant_t cpu_mode;    // CPU_Any to use saved prefs value

        const char *package_list;  // internal, do not use

        const char *license_file;  // NULL to use saved prefs value
        const char *expire_time;

        bool no_windows;
        bool fail_on_warnings;
        const char *deprecation_level; // see sim->warn_deprecated
        bool warn_deprecated;       // same as deprecation_level == 2
        bool no_warn_deprecated;    // same as deprecation_level == 0

        bool warn_multithread;  /* deprecated and ignored (bug 21597) */
        bool check_ifaces;
        bool no_global_settings;    // do not read preferences and recent-files

        const char *alt_settings_dir; // internal - for test usage

        /* the following should be -1 if not set by command line options
           to tell SIM_init_simulator() to use the saved preference value */
        int log_enable;

        bool allow_license_gui; // internal, do not use

        const char *eclipse_params; // internal, do not use
} init_prefs_t;

typedef enum {
        GUI_Mode_None,
        GUI_Mode_Mixed,
        GUI_Mode_Only,
        GUI_Mode_Default
} gui_mode_t;

typedef enum {
        Cpu_None, /* internal, do not use */
        Cpu_Any,
        Cpu_Fast,
        Cpu_Stall
} cpu_variant_t;

DESCRIPTION

The init_prefs_t, gui_mode_t and cpu_variant_t types are deprecated and should not be used in new code.

log_type_t

NAME

log_type_t

SYNOPSIS

typedef enum {
        Sim_Log_Info,           // Normal informational message
        Sim_Log_Error,          // Simics error
        Sim_Log_Spec_Violation, // target program violates the specification
        Sim_Log_Unimplemented,  // not implemented in Simics
        Sim_Log_Critical,       // Critical error stopping Simics
        Sim_Log_Trace,          // Breakpoint trace messages
        Sim_Log_Num_Types,      // Do not use
} log_type_t;

DESCRIPTION

This type defines different log types that are used by the logging facility to categorise messages.

3.4.2 Obsolete Device API Functions

dbuffer_append()

NAME

dbuffer_append, dbuffer_prepend, dbuffer_insert — Add data to a dbuffer

SYNOPSIS

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);

DESCRIPTION

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()

NAME

dbuffer_append_external_data, dbuffer_prepend_external_data — Add static data

SYNOPSIS

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);

DESCRIPTION

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.

SEE ALSO

dbuffer_append

dbuffer_append_value()

NAME

dbuffer_append_value, dbuffer_prepend_value — Add data with uniform content

SYNOPSIS

uint8 *
dbuffer_append_value(dbuffer_t *dbuffer, int value, size_t len);

uint8 *
dbuffer_prepend_value(dbuffer_t *dbuffer, int value, size_t len);

DESCRIPTION

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_append and calling memset to set the contents.

The return value is a pointer to the data just added.

SEE ALSO

dbuffer_append

dbuffer_clone()

NAME

dbuffer_clone — Make a full copy of another buffer

SYNOPSIS

dbuffer_t *
dbuffer_clone(dbuffer_t *dbuffer);

DESCRIPTION

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.

SEE ALSO

new_dbuffer, dbuffer_free

dbuffer_copy_append()

NAME

dbuffer_copy_append, dbuffer_copy_prepend — Copy data from a dbuffer

SYNOPSIS

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);

DESCRIPTION

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.

SEE ALSO

dbuffer_append

dbuffer_free()

NAME

dbuffer_free — Release a dbuffer

SYNOPSIS

void
dbuffer_free(dbuffer_t *dbuffer);

DESCRIPTION

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

SEE ALSO

new_dbuffer

dbuffer_len()

NAME

dbuffer_len — Get the size of a dbuffer

SYNOPSIS

size_t
dbuffer_len(const dbuffer_t *dbuffer);

DESCRIPTION

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()

NAME

dbuffer_read, dbuffer_read_all, dbuffer_read_some — Extract data for reading

SYNOPSIS

const uint8 *
dbuffer_read(dbuffer_t *dbuffer, size_t offset, size_t len);

const uint8 *
dbuffer_read_all(dbuffer_t *dbuffer);

const uint8 *
dbuffer_read_some(dbuffer_t *dbuffer, size_t offset, size_t len,
                  size_t *actual_len);

DESCRIPTION

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.

SEE ALSO

dbuffer_update, dbuffer_replace

dbuffer_remove()

NAME

dbuffer_remove, dbuffer_remove_head, dbuffer_remove_tail — Remove data from a dbuffer

SYNOPSIS

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);

DESCRIPTION

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()

NAME

dbuffer_replace, dbuffer_replace_all, dbuffer_replace_some — Replace data

SYNOPSIS

uint8 *
dbuffer_replace(dbuffer_t *dbuffer, size_t offset, size_t len);

uint8 *
dbuffer_replace_all(dbuffer_t *dbuffer);

uint8 *
dbuffer_replace_some(dbuffer_t *dbuffer, size_t offset, size_t len,
                     size_t *actual_len);

DESCRIPTION

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.

SEE ALSO

dbuffer_read, dbuffer_update

dbuffer_split()

NAME

dbuffer_split — Split a dbuffer

SYNOPSIS

dbuffer_t *
dbuffer_split(dbuffer_t *dbuffer, size_t offset);

DESCRIPTION

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.

SEE ALSO

new_dbuffer, dbuffer_free

dbuffer_update()

NAME

dbuffer_update, dbuffer_update_all, dbuffer_update_some — Extract data for updating

SYNOPSIS

uint8 *
dbuffer_update(dbuffer_t *dbuffer, size_t offset, size_t len);

uint8 *
dbuffer_update_all(dbuffer_t *dbuffer);

uint8 *
dbuffer_update_some(dbuffer_t *dbuffer, size_t offset, size_t len,
                    size_t *actual_len);

DESCRIPTION

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.

SEE ALSO

dbuffer_read, dbuffer_replace

new_dbuffer()

NAME

new_dbuffer — Create a new dbuffer

SYNOPSIS

dbuffer_t *
new_dbuffer(void);

DESCRIPTION

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

SEE ALSO

dbuffer_free, dbuffer_clone