osd_hostmod class

This class represents a debug module on the host.

osd_hostmod implements functionality common to all host debug modules, and provides extension for individual host module implementations. Most importantly, osd_hostmod encapsulates all communication with the host controller.

Usage

#include <osd/osd.h>
#include <osd/hostmod.h>

Example

#include <osd/osd.h>
#include <osd/hostmod.h>

const char* HOST_CONTROLLER_URL = "tcp://localhost:6666";

// initialize class
osd_hostmod_ctx *hostmod_ctx;
osd_hostmod_new(&hostmod_ctx);

// connect to host controller
osd_hostmod_connect(hostmod_ctx, HOST_CONTROLLER_URL);

// the subnet controller assigns this host module a unique address
uint16_t addr;
addr = osd_hostmod_get_diaddr(hostmod_ctx);
printf("This module got the address %d assigned.\n", addr);

// read register 0x0000 from module with address 0x0000
uint16_t result;
osd_hostmod_reg_read(hostmod_ctx, 0, 0, 16, &result, 0);
printf("Read returned value %u.\n", result);

// disconnect from host controller
osd_hostmod_disconnect(hostmod_ctx);

// cleanup
osd_hostmod_free(&hostmod_ctx);

Public Interface

Defines

OSD_HOSTMOD_BLOCKING

Flag: fully blocking operation (i.e. wait forever)

Typedefs

typedef osd_result(* osd_hostmod_event_handler_fn)(void *, struct osd_packet *)

Event handler function prototype

The ownership of packet is passed to the handler function.

Functions

osd_result osd_hostmod_new(struct osd_hostmod_ctx ** ctx, struct osd_log_ctx * log_ctx, const char * host_controller_address, osd_hostmod_event_handler_fn event_handler, void * event_handler_arg)

Create new osd_hostmod instance

Return
OSD_OK on success, any other value indicates an error
See
osd_hostmod_free()
Parameters
  • [out] ctx: the osd_hostmod_ctx context to be created
  • [in] log_ctx: the log context to be used. Set to NULL to disable logging
  • [in] host_controller_address: ZeroMQ endpoint of the host controller
  • [in] event_handler: function called when a new event packet is received
  • [in] event_handler_arg: argument passed to the event handler callback

void osd_hostmod_free(struct osd_hostmod_ctx ** ctx)

Free and NULL a communication API context object

Call osd_hostmod_disconnect() before calling this function.

Parameters
  • ctx: the osd_com context object

osd_result osd_hostmod_connect(struct osd_hostmod_ctx * ctx)

Connect to the host controller

Return
OSD_OK on success, any other value indicates an error
See
osd_hostmod_disconnect()
Parameters
  • ctx: the osd_hostmod_ctx context object

osd_result osd_hostmod_disconnect(struct osd_hostmod_ctx * ctx)

Shut down all communication with the device

Return
OSD_OK on success, any other value indicates an error
See
osd_hostmod_run()
Parameters
  • ctx: the osd_hostmod context object

bool osd_hostmod_is_connected(struct osd_hostmod_ctx * ctx)

Is the connection to the device active?

Return
1 if connected, 0 if not connected
See
osd_hostmod_connect()
See
osd_hostmod_disconnect()
Parameters
  • ctx: the osd_hostmod context object

osd_result osd_hostmod_reg_read(struct osd_hostmod_ctx * ctx, void * reg_val, uint16_t diaddr, uint16_t reg_addr, int reg_size_bit, int flags)

Read a register of a module in the debug system

Unless the flag OSD_HOSTMOD_BLOCKING has been set this function times out if the module does not reply within a ZMQ_RCV_TIMEOUT milliseconds.

Return
OSD_OK on success, any other value indicates an error
Return
OSD_ERROR_TIMEDOUT if the register read timed out (only if OSD_HOSTMOD_BLOCKING is not set)
See
osd_hostmod_write()
Parameters
  • ctx: the osd_hostmod_ctx context object
  • [out] reg_val: the result of the register read. Preallocate a variable large enough to hold reg_size_bit bits.
  • diaddr: the DI address of the module to read the register from
  • reg_addr: the address of the register to read
  • reg_size_bit: size of the register in bit. Supported values: 16, 32, 64 and 128.
  • flags: flags. Set OSD_HOSTMOD_BLOCKING to block indefinitely until the access succeeds.

osd_result osd_hostmod_reg_write(struct osd_hostmod_ctx * ctx, const void * reg_val, uint16_t diaddr, uint16_t reg_addr, int reg_size_bit, int flags)

Write a register of a module in the debug system

Return
OSD_OK on success, any other value indicates an error
Return
OSD_ERROR_TIMEDOUT if the register read timed out (only if OSD_HOSTMOD_BLOCKING is not set)
Parameters
  • ctx: the osd_hostmod_ctx context object
  • reg_val: the data to be written. Provide enough data according to reg_size_bit
  • diaddr: the DI address of the accessed module
  • reg_addr: the address of the register to read
  • reg_size_bit: size of the register in bit. Supported values: 16, 32, 64 and 128.
  • flags: flags. Set OSD_HOSTMOD_BLOCKING to block indefinitely until the access succeeds.

osd_result osd_hostmod_reg_setbit(struct osd_hostmod_ctx * hostmod_ctx, unsigned int bitnum, bool bitval, uint16_t diaddr, uint16_t reg_addr, int reg_size_bit, int flags)

Set (or unset) a bit in a debug module configuration register

The setting of a single bit requires a read-modify-write cycle of the register, which is not atomic and not locked.

Return
OSD_OK on success, any other value indicates an error
Return
OSD_ERROR_TIMEDOUT if the register read timed out (only if OSD_HOSTMOD_BLOCKING is not set)
Parameters
  • ctx: the osd_hostmod_ctx context object
  • bitnum: bit to modify (bit 0 = LSB)
  • bitval: value to set the bit to
  • diaddr: the DI address of the accessed module
  • reg_addr: the address of the register to read
  • reg_size_bit: size of the register in bit. Supported values: 16, 32, 64 and 128.
  • flags: flags. Set OSD_HOSTMOD_BLOCKING to block indefinitely until the access succeeds.

uint16_t osd_hostmod_get_diaddr(struct osd_hostmod_ctx * ctx)

Get the DI address assigned to this host debug module

The address is assigned during the connection, i.e. you need to call osd_hostmod_connect() before calling this function.

Return
the address assigned to this debug module
Parameters
  • ctx: the osd_hostmod_ctx context object

unsigned int osd_hostmod_get_max_event_words(struct osd_hostmod_ctx * ctx, unsigned int di_addr_target)

Get the maximum number paylaod of words in an event packet

Return
the number of payload words in an event packet sent to di_addr_target
Parameters
  • ctx: the osd_hostmod_ctx context object

osd_result osd_hostmod_event_send(struct osd_hostmod_ctx * ctx, const struct osd_packet * event_pkg)

Send an event packet to its destination

Return
OSD_OK on success, any other value indicates an error
Parameters
  • ctx: the osd_hostmod_ctx context object
  • event_pkg: the event packet to be sent

osd_result osd_hostmod_event_receive(struct osd_hostmod_ctx * ctx, struct osd_packet ** event_pkg, int flags)

Receive an event packet

By default, this function times out with OSD_ERROR_TIMEOUT if no packet was received. Pass OSD_HOSTMOD_BLOCKING to flags to make the function block until a packet is received.

Return
OSD_OK on success, any other value indicates an error
Parameters
  • ctx: the osd_hostmod_ctx context object
  • [out] event_pkg: the received event packet. Allocated by this function, must be free’d by caller after use.
  • flags: a ORed list of flags (see description)

osd_result osd_hostmod_get_modules(struct osd_hostmod_ctx * ctx, unsigned int subnet_addr, struct osd_module_desc ** modules, size_t * modules_len)

Get a list of all debug modules in a given subnet

Return
OSD_OK on success OSD_ERROR_RESULT_PARTIAL if at least one module failed to enumerate any other value indicates an error
Parameters
  • ctx: the osd_hostmod_ctx context object
  • subnet_addr: the address of the subnet to query for modules
  • [out] modules: the modules found in the given subnet. The array is allocated by this function and ownership passed to the caller, who must free it after use.
  • [out] module_len: the number of entries in modules

osd_result osd_hostmod_mod_describe(struct osd_hostmod_ctx * ctx, uint16_t di_addr, struct osd_module_desc * desc)

Get the description fields of a debug module (type, vendor, version)

Return
OSD_OK on success, any other value indicates an error
Parameters
  • ctx: the osd_hostmod_ctx context object
  • di_addr: the DI address of the module to describe
  • [out] desc: a struct describing the module

osd_result osd_hostmod_mod_set_event_dest(struct osd_hostmod_ctx * ctx, uint16_t di_addr, int flags)

Set this host module as event destination for the module at di_addr

By default, this function times out with OSD_ERROR_TIMEOUT if no packet was received. Pass OSD_HOSTMOD_BLOCKING to flags to make the function block until a packet is received.

Return
OSD_OK on success, any other value indicates an error
See
osd_hostmod_mod_set_event_active()
Parameters
  • ctx: the osd_hostmod_ctx context object
  • di_addr: the address of the DI module
  • flags: a ORed list of flags (see description)

osd_result osd_hostmod_mod_set_event_active(struct osd_hostmod_ctx * ctx, uint16_t di_addr, bool enabled, int flags)

Enable/disable sending of events by the module at DI address di_addr

Events are sent to the DI address configured in the module. Use osd_hostmod_mod_set_evdest() to make this host module receive the events.

By default, this function times out with OSD_ERROR_TIMEOUT if no packet was received. Pass OSD_HOSTMOD_BLOCKING to flags to make the function block until a packet is received.

Return
OSD_OK on success, any other value indicates an error
See
osd_hostmod_mod_set_evdest()
Parameters
  • ctx: the osd_hostmod_ctx context object
  • di_addr: the address of the DI module to enable/disable
  • enabled: 1 to enable event sending, 0 to disable it
  • flags: a ORed list of flags (see description)

struct osd_log_ctx* osd_hostmod_log_ctx(struct osd_hostmod_ctx * ctx)

Get the logging context for this host module (internal use only)

Internal Architecture

Note

This section is targeting developers working on the osd_hostmod module.

Note

TBD