Clock Control RTOS Driver#

This driver can be used to operate GPIO ports on xcore in an RTOS application.

Initialization API#

The following structures and functions are used to initialize and start a GPIO driver instance.

typedef struct rtos_clock_control_struct rtos_clock_control_t#

Typedef to the RTOS Clock Control driver instance struct.

void rtos_clock_control_start(rtos_clock_control_t *ctx)#

Starts an RTOS clock control driver instance. This must only be called by the tile that owns the driver instance. It may be called either before or after starting the RTOS, but must be called before any of the core clock control driver functions are called with this instance.

rtos_clock_control_init() must be called on this clock control driver instance prior to calling this.

Parameters:

  • ctx – A pointer to the clock control driver instance to start.

void rtos_clock_control_init(rtos_clock_control_t *ctx)#

Initializes an RTOS clock control driver instance. There should only be one per tile. This must only be called by the tile that owns the driver instance. It may be called either before or after starting the RTOS, but must be called before calling rtos_clock_control_start() or any of the core clock control driver functions with this instance.

Parameters:

  • ctx – A pointer to the GPIO driver instance to initialize.

struct rtos_clock_control_struct#
#include <rtos_clock_control.h>

Struct representing an RTOS clock control driver instance.

The members in this struct should not be accessed directly.

Core API#

The following functions are the core GPIO driver functions that are used after it has been initialized and started.

inline void rtos_clock_control_set_ref_clk_div(rtos_clock_control_t *ctx, unsigned divider)#

Sets the reference clock divider register value for the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

  • divider – The value + 1 to write to XS1_SSWITCH_REF_CLK_DIVIDER_NUM

inline unsigned rtos_clock_control_get_ref_clk_div(rtos_clock_control_t *ctx)#

Gets the reference clock divider register value for the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

inline void rtos_clock_control_set_processor_clk_div(rtos_clock_control_t *ctx, unsigned divider)#

Sets the tile clock divider register value for the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

  • divider – The value + 1 to write to XS1_PSWITCH_PLL_CLK_DIVIDER_NUM

inline unsigned rtos_clock_control_get_processor_clk_div(rtos_clock_control_t *ctx)#

Gets the tile clock divider register value for the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

inline void rtos_clock_control_set_switch_clk_div(rtos_clock_control_t *ctx, unsigned divider)#

Sets the switch clock divider register value for the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

  • divider – The value + 1 to write to XS1_SSWITCH_CLK_DIVIDER_NUM

inline unsigned rtos_clock_control_get_switch_clk_div(rtos_clock_control_t *ctx)#

Gets the switch clock divider register value for the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

inline unsigned rtos_clock_control_get_ref_clock(rtos_clock_control_t *ctx)#

Gets the calculated reference clock frequency for the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

inline unsigned rtos_clock_control_get_processor_clock(rtos_clock_control_t *ctx)#

Gets the calculated core clock frequency for the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

inline unsigned rtos_clock_control_get_switch_clock(rtos_clock_control_t *ctx)#

Gets the calculated switch clock frequency for the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

Sets the intra token delay and inter token delay to the xlinks within an address range, inclusive, for the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

  • start_addr – The starting link address

  • end_addr – The ending address

  • delay_intra – The intra token delay value

  • delay_inter – The inter token delay value

Resets the xlinks within an address range, inclusive for the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

  • start_addr – The starting link address

  • end_addr – The ending address

inline void rtos_clock_control_set_node_pll_ratio(rtos_clock_control_t *ctx, unsigned pre_div, unsigned mul, unsigned post_div)#

Sets the tile clock PLL control register value on the tile that owns this driver instance. The value set is calculated from the divider stage 1, multiplier stage, and divider stage 2 values provided.

VCO freq = fosc * (F + 1) / (2 * (R + 1)) VCO must be between 260MHz and 1.3GHz for XS2 Core freq = VCO / (OD + 1)

Refer to the xcore Clock Frequency Control document for more details.

Note: This function will not reset the chip and wait for the PLL to settle before re-enabling the chip to allow for large frequency jumps. This will cause a delay during settings.

Note: It is up to the application to ensure that it is safe to change the clock.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

  • pre_div – The value of R

  • mul – The value of F

  • post_div – The value of OD

inline void rtos_clock_control_get_node_pll_ratio(rtos_clock_control_t *ctx, unsigned *pre_div, unsigned *mul, unsigned *post_div)#

Gets the divider stage 1, multiplier stage, and divider stage 2 values from the tile clock PLL control register values on the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

  • pre_div – A pointer to be populated with the value of R

  • mul – A pointer to be populated with the value of F

  • post_div – A pointer to be populated with the value of OD

inline void rtos_clock_control_get_local_lock(rtos_clock_control_t *ctx)#

Gets the local lock for clock control on the tile that owns this driver instance. This is intended for applications to use to prevent clock changes around critical sections.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

inline void rtos_clock_control_release_local_lock(rtos_clock_control_t *ctx)#

Releases the local lock for clock control on the tile that owns this driver instance.

Parameters:

  • ctx – A pointer to the clock control driver instance to use.

RPC Initialization API#

The following functions may be used to share a GPIO driver instance with other xcore tiles. Tiles that the driver instance is shared with may call any of the core functions listed above.

void rtos_clock_control_rpc_client_init(rtos_clock_control_t *cc_ctx, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *host_intertile_ctx)#

Initializes an RTOS clock control driver instance on a client tile. This allows a tile that does not own the actual driver instance to use a driver instance on another tile. This will be called instead of rtos_clock_control_init(). The host tile that owns the actual instance must simultaneously call rtos_clock_control_rpc_host_init().

Parameters:

  • cc_ctx – A pointer to the clock control driver instance to initialize.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as cc_ctx.

  • host_intertile_ctx – A pointer to the intertile driver instance to use for performing the communication between the client and host tiles. This must have the same scope as cc_ctx.

void rtos_clock_control_rpc_host_init(rtos_clock_control_t *cc_ctx, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *client_intertile_ctx[], size_t remote_client_count)#

Performs additional initialization on a clock control driver instance to allow client tiles to use the clock control driver instance. Each client tile that will use this instance must simultaneously call rtos_clock_control_rpc_client_init().

Parameters:

  • cc_ctx – A pointer to the clock control driver instance to share with clients.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as cc_ctx.

  • client_intertile_ctx – An array of pointers to the intertile driver instances to use for performing the communication between the host tile and each client tile. This must have the same scope as cc_ctx.

  • remote_client_count – The number of client tiles to share this driver instance with.

void rtos_clock_control_rpc_config(rtos_clock_control_t *cc_ctx, unsigned intertile_port, unsigned host_task_priority)#

Configures the RPC for a clock control driver instance. This must be called by both the host tile and all client tiles.

On the client tiles this must be called after calling rtos_clock_control_rpc_client_init(). After calling this, the client tile may immediately begin to call the core clock control functions on this driver instance. It does not need to wait for the host to call rtos_clock_control_start().

On the host tile this must be called both after calling rtos_clock_control_rpc_host_init() and before calling rtos_clock_control_start().

Parameters:

  • cc_ctx – A pointer to the clock control driver instance to configure the RPC for.

  • intertile_port – The port number on the intertile channel to use for transferring the RPC requests and responses for this driver instance. This port must not be shared by any other functions. The port must be the same for the host and all its clients.

  • host_task_priority – The priority to use for the task on the host tile that handles RPC requests from the clients.