TLM API, Socket, and Utility Field Guide

How to Read This Lesson

TLM names can look like a wall of templates. Read them by role: transport interface, socket wrapper, payload object, analysis channel, or utility helper. Once you can classify the name, the C++ template shape becomes much less intimidating.

Standard and source context

Use the TLM clauses in Docs/LRMs/SystemC_LRM_1666-2023.pdf for portable behavior. Use .codex-src/systemc/src/tlm_core and .codex-src/systemc/src/tlm_utils for implementation reading.

Transport Interfaces

tlm_blocking_transport_if, tlm_fw_transport_if, tlm_bw_transport_if, tlm_fw_direct_mem_if, tlm_bw_direct_mem_if, tlm_fw_nonblocking_transport_if, and tlm_bw_nonblocking_transport_if define who can call whom. The naming is literal: forward path goes initiator to target, backward path goes target to initiator.

tlm_transport_dbg_if, tlm_transport_channel, tlm_core_ifs, and plain "transports" vocabulary sit beside the same idea: a transaction-level model is primarily a set of typed transport calls, not signal toggles.

b_transport is the blocking transport call. It is easiest to reason about because one call represents one transaction and the delay argument is updated as the call travels.

nb_transport_fw and nb_transport_bw are non-blocking transport calls. They carry a tlm_phase and return a tlm_sync_enum, so you review them as a state machine, not as a normal function call.

Socket Families

tlm_base_socket_if, tlm_base_initiator_socket, tlm_base_initiator_socket_b, tlm_base_initiator_socket_export, tlm_base_target_socket, tlm_base_target_socket_b, tlm_base_target_socket_port, tlm_initiator_socket, and tlm_target_socket are the socket architecture.

The practical split is simple. Base socket types hold the generic binding machinery. Concrete initiator and target sockets are what models normally instantiate. If you are debugging a failed bind, follow the socket down to the port/export/interface layers rather than starting with the payload.

tlm_base_protocol_types, tlm_base_protocol, tlm_payload_type, tlm_phase_type, and tlm_socket_category are template vocabulary that lets the same socket framework support a protocol-specific payload and phase set.

The plural documentation names tlm_initiator_sockets, tlm_target_sockets, and tlm_ports usually indicate documentation groups rather than classes you instantiate directly. In source reading, they still help you locate the socket and port families.

Implementation names such as tlm_initiator_socket_base, tlm_initiator_socket_b, tlm_target_socket_base, tlm_target_socket_b, tlm_slave_imp, and tlm_nonblocking_port are adapter and base-class pieces under the friendly socket API.

Payload, DMI, and Extensions

tlm_generic_payload is the standard transaction object. It carries command, address, data pointer, byte enable pointer, streaming width, response status, and extensions. Every target should leave the response status in a meaningful state.

tlm_response_status tells the initiator how the target handled the transaction. tlm_gp_option tells how much of the generic-payload protocol the transaction is using. Review both when a model mixes fast approximate paths with stricter protocol checking.

tlm_dmi, get_direct_mem_ptr, and transport_dbg are optional fast paths. They are not replacements for protocol correctness. Treat them as negotiated capabilities: if the target cannot guarantee the requested access, it must say no.

tlm_extension, tlm_extension_registry, and custom extension classes let you carry model-specific metadata without changing the base payload. Good extensions are documented, cloned correctly, and owned clearly.

Analysis and TLM-1 Compatibility Names

Names such as tlm_analysis_if, tlm_analysis_fifo, tlm_write_if, tlm_fifo_put_if, tlm_fifo_get_if, tlm_blocking_get_if, tlm_blocking_peek_if, tlm_blocking_get_peek_if, tlm_nonblocking_put_if, tlm_nonblocking_get_if, tlm_nonblocking_peek_if, tlm_put_if, tlm_get_peek_if, tlm_transport_if, tlm_slave_if, tlm_channels, and tlm_1_interfaces mostly live around analysis and older TLM communication styles.

Also recognize tlm_get_if, tlm_peek_if, tlm_nonblocking_get_peek_if, tlm_fifo_debug_if, tlm_delayed_write_if, tlm_analysis_triple, tlm_bool, tlm_req_rsp_channels, tlm_master_if, tlm_slave_to_transport, tlm_transport_to_master, tlm_master_slave_ifs, tlm_blocking_master_if, tlm_blocking_slave_if, tlm_nonblocking_master_if, tlm_nonblocking_slave_if, tlm_nonblocking_put_port, tlm_nonblocking_get_port, and tlm_nonblocking_peek_port. These are mostly adapter, FIFO, analysis, and legacy channel vocabulary.

FIFO-specific implementation names include tlm_delayed_analysis_if, tlm_fifo_ifs, tlm_fifo_config_size_if, tlm_fifo_peek, tlm_fifo_put_get, and tlm_fifo_resize. Read these as channel internals rather than as the preferred public TLM-2.0 VP style.

In modern TLM-2.0 virtual-platform modeling, you usually see tlm_generic_payload and sockets first. The TLM-1 and analysis names still matter for scoreboards, monitors, trace collection, adapters, and legacy models.

Endianness Helpers

tlm_endianness, tlm_endian_context, tlm_endian_context_pool, tlm_from_hostendian, tlm_from_hostendian_aligned, tlm_from_hostendian_generic, tlm_from_hostendian_single, tlm_from_hostendian_word, and related helpers exist because payload byte lanes are not the same thing as the host CPU's native layout.

The reverse helpers tlm_to_hostendian_generic, tlm_to_hostendian_word, tlm_to_hostendian_aligned, and tlm_to_hostendian_single show the same concern in the other direction. If a target converts data for host-side algorithm code, the model should document when the payload is in bus order and when it is in host order.

tlm_endian_conv, tlm_data, and tlm_version_string_2 are lower-level helper names you may see while following conversion or version-source code.

If your platform is memory-mapped and firmware-visible, be explicit about endian assumptions. A model that passes tests on one host but changes behavior on another host is not a portable TLM model.

Event and Phase Utilities

tlm_phase, tlm_phase_registry, tlm_event_finder_t, tlm_sync_enum, tlm_tag, tlm_array, tlm_put_get_imp, and payload event queue utilities are glue around protocol state and callback scheduling.

tlm_phase_enum and tlm_phase_name_arg are phase-support names. tlm_adapters, tlm_helpers, and tlm_master_imp show up in source areas that connect old and new communication styles.

Version Names

tlm_version, tlm_version_major, tlm_version_minor, tlm_version_patch, tlm_version_originator, tlm_version_prerelease, tlm_version_release_date, tlm_version_string, tlm_release, tlm_is_prerelease, tlm_copyright, and tlm_copyright_string are version and distribution metadata. They do not change transaction behavior, but they are useful when diagnosing mismatched library installations.

The review question is: can you draw the phase transition for every non-blocking transaction? If not, the model may be relying on callback ordering by accident.

Senior Review Checklist

• Are sockets bound in the intended direction?
• Does every target set response status?
• Are DMI and debug transport optional and safe?
• Are byte enables, streaming width, and endian behavior tested?
• Are extensions cloned, cleared, and documented?
• Is temporal decoupling visible in the code rather than hidden in a helper?