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 holdreg_size_bit
bits.diaddr
: the DI address of the module to read the register fromreg_addr
: the address of the register to readreg_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 objectreg_val
: the data to be written. Provide enough data according toreg_size_bit
diaddr
: the DI address of the accessed modulereg_addr
: the address of the register to readreg_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 objectbitnum
: bit to modify (bit 0 = LSB)bitval
: value to set the bit todiaddr
: the DI address of the accessed modulereg_addr
: the address of the register to readreg_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 objectevent_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 objectsubnet_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 inmodules
-
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 objectdi_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 objectdi_addr
: the address of the DI moduleflags
: 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 objectdi_addr
: the address of the DI module to enable/disableenabled
: 1 to enable event sending, 0 to disable itflags
: 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