Command Handler Functions

General Description

A variety of functions are provided to work with commands:

• Update or read the command data.
• Retrieve the last transfer size (applicable for Block protocols).
• Enable or disable commands.
• Protect commands against write operations.

In this section, functions with the isr suffix are optimized for use during ISRs, typically in command callback functions. APIs without the isr suffix return the MTB_PMBUS_STATUS_CMD_IS_ACTIVE status if the selected command is participating in an active transfer. To access data for specific pages or phases of commands, use APIs with the ext suffix.

Functions
mtb_pmbus_status_t	mtb_pmbus_cmd_update_data (mtb_pmbus_stc_t *inst, uint32_t code, uint8_t *data, uint32_t data_size)
	Update the data buffer for the selected command with new data. More...
void	mtb_pmbus_cmd_update_data_isr (mtb_pmbus_stc_t *inst, uint32_t code, uint8_t *data, uint32_t data_size)
	Update the data buffer for the selected command with new data. More...
mtb_pmbus_status_t	mtb_pmbus_cmd_update_data_ext (mtb_pmbus_stc_t *inst, uint32_t code, int32_t page, int32_t phase, uint8_t *data, uint32_t data_size)
	Update the data buffer for the selected command, page and phase with the new data. More...
void	mtb_pmbus_cmd_update_data_ext_isr (mtb_pmbus_stc_t *inst, uint32_t code, int32_t page, int32_t phase, uint8_t *data, uint32_t data_size)
	Update the data buffer for the selected command, page and phase with the new data. More...
mtb_pmbus_status_t	mtb_pmbus_cmd_read_data (mtb_pmbus_stc_t *inst, uint32_t code, uint8_t *data, uint32_t data_size)
	Read the data from the internal buffer for selected command. More...
void	mtb_pmbus_cmd_read_data_isr (mtb_pmbus_stc_t *inst, uint32_t code, uint8_t *data, uint32_t data_size)
	Read the data from the internal buffer for selected command. More...
mtb_pmbus_status_t	mtb_pmbus_cmd_read_data_ext (mtb_pmbus_stc_t *inst, uint32_t code, int32_t page, int32_t phase, uint8_t *data, uint32_t data_size)
	Read the data from the buffer for the selected command, page and phase. More...
void	mtb_pmbus_cmd_read_data_ext_isr (mtb_pmbus_stc_t *inst, uint32_t code, int32_t page, int32_t phase, uint8_t *data, uint32_t data_size)
	Read the data from the buffer for the selected command, page and phase. More...
mtb_pmbus_status_t	mtb_pmbus_cmd_get_transfer_size (mtb_pmbus_stc_t *inst, uint32_t code, uint8_t *size)
	Returns the number of bytes which is transferred during last transaction. More...
void	mtb_pmbus_cmd_get_transfer_size_isr (mtb_pmbus_stc_t *inst, uint32_t code, uint8_t *size)
	Returns the number of bytes which is transferred during last transaction. More...
mtb_pmbus_status_t	mtb_pmbus_cmd_get_transfer_size_ext (mtb_pmbus_stc_t *inst, uint32_t code, int32_t page, int32_t phase, uint8_t *size)
	Returns the number of bytes which is transferred during last transaction. More...
void	mtb_pmbus_cmd_get_transfer_size_ext_isr (mtb_pmbus_stc_t *inst, uint32_t code, int32_t page, int32_t phase, uint8_t *size)
	Returns the number of bytes which is transferred during last transaction. More...
void	mtb_pmbus_cmd_is_active_isr (mtb_pmbus_stc_t *inst, uint32_t code, bool *status)
	Returns true if command participate in current transfer, otherwise returns false. More...
mtb_pmbus_status_t	mtb_pmbus_cmd_is_active (mtb_pmbus_stc_t *inst, uint32_t code, bool *status)
	Returns true if command participate in current transfer, otherwise returns false. More...
void	mtb_pmbus_cmd_enable_disable_isr (mtb_pmbus_stc_t *inst, uint32_t code, bool status)
	Enable/Disable command. More...
mtb_pmbus_status_t	mtb_pmbus_cmd_enable_disable (mtb_pmbus_stc_t *inst, uint32_t code, bool status)
	Enable/Disable command. More...
mtb_pmbus_status_t	mtb_pmbus_cmd_all_enable_disable (mtb_pmbus_stc_t *inst, bool status)
	Enable/Disable all commands from command table - main ( mtb_pmbus_stc_config_t::cmd_table). More...
mtb_pmbus_status_t	mtb_pmbus_cmd_get_status (mtb_pmbus_stc_t *inst, uint32_t code, bool *status)
	Returns true if a command is executed at least one time. More...
void	mtb_pmbus_cmd_wr_protect_isr (mtb_pmbus_stc_t *inst, uint32_t code, bool status)
	Enable or disable write protection for a specific command. More...
mtb_pmbus_status_t	mtb_pmbus_cmd_wr_protect (mtb_pmbus_stc_t *inst, uint32_t code, bool status)
	Enable or disable write protection for a specific command. More...
mtb_pmbus_status_t	mtb_pmbus_cmd_all_wr_protect (mtb_pmbus_stc_t *inst, bool status)
	Enables or disables write protection for all PMBus commands. More...

Function Documentation

mtb_pmbus_cmd_update_data()

mtb_pmbus_status_t mtb_pmbus_cmd_update_data	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		uint8_t *	data,
		uint32_t	data_size
	)

Update the data buffer for the selected command with new data.

For the Block Read and Block Write-Block Read Process Call protocols: If the updated data size is smaller than the command size in the command table, only updated bytes will be transferred.

This function always updates data from the 0 position.

The function validates the input parameters and returns the appropriate error status.

The function prevents updating the data content if the command is active, to avoid data corruption. Therefore, using this function within a PMBus callback (executed inside an ISR) will have no effect.

Use this function only for not paged/phased commands.

Warning

Updating the command buffer is not an atomic operation and does not occur within a critical section. Therefore, in projects where the command buffer is updated from multiple execution contexts, it is the user's responsibility to ensure the proper synchronization and update order.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
data	The pointer to the data array
data_size	The size of the data array

Returns

mtb_pmbus_status_t

mtb_pmbus_cmd_update_data_isr()

void mtb_pmbus_cmd_update_data_isr	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		uint8_t *	data,
		uint32_t	data_size
	)

Update the data buffer for the selected command with new data.

This function is optimized for use during ISR and is recommended to be used in a command callback. The function skips validation of input parameters and does not check if the command is currently being updated or read by the controller.

For the Block Read and Block Write-Block Read Process Call protocols: If the updated data size is smaller than the command size in the command table, only the updated bytes will be transferred.

This function always updates data from position 0.

Use this function only for non-paged/non-phased commands.

Warning

The updating data for active command can lead to data corruption.

Updating the command buffer is not an atomic operation and does not occur within a critical section. Therefore, in projects where the command buffer is updated from multiple execution contexts, it is the user's responsibility to ensure the proper synchronization and update order.

Parameters

inst	Pointer to the PMBus instance structure
code	Command code
data	Pointer to the data array
data_size	Size of the data array

mtb_pmbus_cmd_update_data_ext()

mtb_pmbus_status_t mtb_pmbus_cmd_update_data_ext	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		int32_t	page,
		int32_t	phase,
		uint8_t *	data,
		uint32_t	data_size
	)

Update the data buffer for the selected command, page and phase with the new data.

For the Block Read and Block Write-Block Read Process Call protocols: If the updated data size is smaller than the command size in the command table, only updated bytes will be transferred.

This function always updates data from the 0 position.

Warning

Updating the command buffer is not an atomic operation and does not occur within a critical section. Therefore, in projects where the command buffer is updated from multiple execution contexts, it is the user's responsibility to ensure the proper synchronization and update order.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
page	The page number to update. If the command is not paged, then use MTB_PMBUS_NO_PAGE_PHASE as input parameters
phase	The phase number to update. If the command is not phased, then use MTB_PMBUS_NO_PAGE_PHASE as input parameters
data	The pointer to the data array
data_size	The size of the data array

Returns

mtb_pmbus_status_t

mtb_pmbus_cmd_update_data_ext_isr()

void mtb_pmbus_cmd_update_data_ext_isr	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		int32_t	page,
		int32_t	phase,
		uint8_t *	data,
		uint32_t	data_size
	)

Update the data buffer for the selected command, page and phase with the new data.

This function is optimized for use during ISR and is recommended to be used in a command callback. The function skips validation of input parameters and does not check if the command is currently being updated or read by the controller.

For the Block Read and Block Write-Block Read Process Call protocols: If the updated data size is smaller than the command size in the command table, only updated bytes will be transferred.

This function always update data from the 0 position.

The function validates the input parameters and returns the appropriate error status.

The function prevents updating the data content if the command is active, to avoid data corruption. Therefore, using this function within a PMBus callback (executed inside an ISR) will have no effect.

Warning

The updating data for active command can lead to data corruption.

Updating the command buffer is not an atomic operation and does not occur within a critical section. Therefore, in projects where the command buffer is updated from multiple execution contexts, it is the user's responsibility to ensure the proper synchronization and update order.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
page	The page number to update. If the command is not paged, then use MTB_PMBUS_NO_PAGE_PHASE as input parameters
phase	The phase number to update. If the command is not phased, then use MTB_PMBUS_NO_PAGE_PHASE as input parameters
data	The pointer to the data array
data_size	The size of the data array

mtb_pmbus_cmd_read_data()

mtb_pmbus_status_t mtb_pmbus_cmd_read_data	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		uint8_t *	data,
		uint32_t	data_size
	)

Read the data from the internal buffer for selected command.

The function validates the input parameters and returns the appropriate error status.

The function prevents reading the data content if the command is active, to avoid data corruption. Therefore, using this function within a PMBus callback (executed inside an ISR) will have no effect.

Warning

Reading the command buffer is not an atomic operation and does not occur within a critical section. Therefore, in projects where the command buffer is accessed from multiple execution contexts, it is the user's responsibility to ensure the proper synchronization and access order.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
data	The pointer to the data array
data_size	The size of the data array

Returns

mtb_pmbus_status_t

mtb_pmbus_cmd_read_data_isr()

void mtb_pmbus_cmd_read_data_isr	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		uint8_t *	data,
		uint32_t	data_size
	)

Read the data from the internal buffer for selected command.

This function is optimized for use during ISR and is recommended to be used in a command callback. The function skips validation of input parameters and does not check if the command is currently being updated or read by the controller.

Warning

The returned data for command which take part in active transfer can be invalid.

Reading the command buffer is not an atomic operation and does not occur within a critical section. Therefore, in projects where the command buffer is accessed from multiple execution contexts, it is the user's responsibility to ensure the proper synchronization and access order.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
data	The pointer to the data array
data_size	The size of the data array

mtb_pmbus_cmd_read_data_ext()

mtb_pmbus_status_t mtb_pmbus_cmd_read_data_ext	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		int32_t	page,
		int32_t	phase,
		uint8_t *	data,
		uint32_t	data_size
	)

Read the data from the buffer for the selected command, page and phase.

The function validates the input parameters and returns the appropriate error status.

The function prevents reading the data content if the command is active, to avoid data corruption. Therefore, using this function within a PMBus callback (executed inside an ISR) will have no effect.

Warning

Reading the command buffer is not an atomic operation and does not occur within a critical section. Therefore, in projects where the command buffer is accessed from multiple execution contexts, it is the user's responsibility to ensure the proper synchronization and access order.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
page	The page number to update. If the command is not paged, then use MTB_PMBUS_NO_PAGE_PHASE as input parameters
phase	The phase number to update. If the command is not phased, then use MTB_PMBUS_NO_PAGE_PHASE as input parameters
data	The pointer to the data array
data_size	The size of the data array

Returns

mtb_pmbus_status_t

mtb_pmbus_cmd_read_data_ext_isr()

void mtb_pmbus_cmd_read_data_ext_isr	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		int32_t	page,
		int32_t	phase,
		uint8_t *	data,
		uint32_t	data_size
	)

Read the data from the buffer for the selected command, page and phase.

This function is optimized for use during ISR and is recommended to be used in a command callback. The function skips validation of input parameters and does not check if the command is currently being updated or read by the controller.

Warning

The returned data for command which take part in active transfer can be invalid.

Reading the command buffer is not an atomic operation and does not occur within a critical section. Therefore, in projects where the command buffer is accessed from multiple execution contexts, it is the user's responsibility to ensure the proper synchronization and access order.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
page	The page number to update. If the command is not paged, then use MTB_PMBUS_NO_PAGE_PHASE as input parameters
phase	The phase number to update. If the command is not phased, then use MTB_PMBUS_NO_PAGE_PHASE as input parameters
data	The pointer to the data array
data_size	The size of the data array

mtb_pmbus_cmd_get_transfer_size()

mtb_pmbus_status_t mtb_pmbus_cmd_get_transfer_size	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		uint8_t *	size
	)

Returns the number of bytes which is transferred during last transaction.

For majority of protocol the size of read/write data equal to command size, but for the Block Write-Block Read Process Call, Block Write, Block Read protocols, the size of transfer can be smaller than the maximum size of command in command table.

The function validates the input parameters and returns the appropriate error status.

The function prevents reading the transfer size if the command is active, to avoid data corruption. Therefore, using this function within a PMBus callback (executed inside an ISR) will have no effect.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
size	The size of the last transaction

Returns

mtb_pmbus_status_t

mtb_pmbus_cmd_get_transfer_size_isr()

void mtb_pmbus_cmd_get_transfer_size_isr	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		uint8_t *	size
	)

Returns the number of bytes which is transferred during last transaction.

This function is optimized for use during ISR and is recommended to be used in a command callback. The function skips validation of input parameters and does not check if the command is currently being updated or read by the controller.

For the majority of protocols, the size of read/write data is equal to the command size, but for the Block Write-Block Read Process Call, Block Write, Block Read protocols, the size of transfer can be smaller than the maximum size of a command in the command table.

Warning

The returned transfer size for command which takes part in active transfer can be invalid.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
size	The size of the last transaction

mtb_pmbus_cmd_get_transfer_size_ext()

mtb_pmbus_status_t mtb_pmbus_cmd_get_transfer_size_ext	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		int32_t	page,
		int32_t	phase,
		uint8_t *	size
	)

Returns the number of bytes which is transferred during last transaction.

For the majority of protocols, the size of read/write data is equal to the command size, but for the Block Write-Block Read Process Call, Block Write, Block Read protocols, the size of transfer can be smaller than the maximum size of command in command table.

The function validates the input parameters and returns the appropriate error status.

The function prevents reading the transfer size if the command is active, to avoid data corruption. Therefore, using this function within a PMBus callback (executed inside an ISR) will have no effect.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
page	The page number to update. If the command is not paged, then use MTB_PMBUS_NO_PAGE_PHASE as input parameters
phase	The phase number to update. If the command is not phased, then use MTB_PMBUS_NO_PAGE_PHASE as input parameters
size	The pointer to transfer size

Returns

mtb_pmbus_status_t

mtb_pmbus_cmd_get_transfer_size_ext_isr()

void mtb_pmbus_cmd_get_transfer_size_ext_isr	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		int32_t	page,
		int32_t	phase,
		uint8_t *	size
	)

Returns the number of bytes which is transferred during last transaction.

This function is optimized for use during ISR and is recommended to be used in a command callback. The function skips validation of input parameters and does not check if the command is currently being updated or read by the controller.

For the majority of protocols, the size of read/write data is equal to the command size, but for the Block Write-Block Read Process Call, Block Write, Block Read protocols, the size of transfer can be smaller than the maximum size of a command in the command table.

Warning

The returned transfer size for command which takes part in active transfer can be invalid.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
page	The page number to update. If the command is not paged, then use MTB_PMBUS_NO_PAGE_PHASE as input parameters
phase	The phase number to update. If the command is not phased, then use MTB_PMBUS_NO_PAGE_PHASE as input parameters
size	The pointer to transfer size

mtb_pmbus_cmd_is_active_isr()

void mtb_pmbus_cmd_is_active_isr	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		bool *	status
	)

Returns true if command participate in current transfer, otherwise returns false.

This function is optimized for use during ISR and is recommended to be used in a command callback. The function skips validation of input parameters and does not check if the command is currently being updated or read by the controller.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
status	True if command is active, otherwise false

mtb_pmbus_cmd_is_active()

mtb_pmbus_status_t mtb_pmbus_cmd_is_active	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		bool *	status
	)

Returns true if command participate in current transfer, otherwise returns false.

The function validates the input parameters and returns the appropriate error status.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
status	True if command is active, otherwise false

Returns

mtb_pmbus_status_t

mtb_pmbus_cmd_enable_disable_isr()

void mtb_pmbus_cmd_enable_disable_isr	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		bool	status
	)

Enable/Disable command.

If the command is enabled, the PMBus Middleware sends ACK bit after receiving the command code and transmits or receives data, otherwise the PMBus sends NACK after receiving the command code.

The function can be used to enable/disable commands from command table - main ( mtb_pmbus_stc_config_t::cmd_table).

This function is optimized for use during ISR and is recommended to be used in a command callback. The function skips validation of input parameters and does not check if the command is currently being updated or read by the controller.

Warning

Enabling/Disabling the command which take part in active transfer can lead to unexpected behavior.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
status	Set to true to enable command, set to false to disable command

mtb_pmbus_cmd_enable_disable()

mtb_pmbus_status_t mtb_pmbus_cmd_enable_disable	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		bool	status
	)

Enable/Disable command.

If the command is enabled, the PMBus Middleware sends ACK bit after receiving the command code and transmits or receives data, otherwise the PMBus sends NACK after receiving the command code.

The function can be used to enable/disable commands from command table - main ( mtb_pmbus_stc_config_t::cmd_table).

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
status	Set to true to enable command, set to false to disable command

Returns

mtb_pmbus_status_t

mtb_pmbus_cmd_all_enable_disable()

mtb_pmbus_status_t mtb_pmbus_cmd_all_enable_disable	(	mtb_pmbus_stc_t *	inst,
		bool	status
	)

Enable/Disable all commands from command table - main ( mtb_pmbus_stc_config_t::cmd_table).

If the command is enabled, the PMBus middleware sends ACK bit after receiving the command code and transmits or receives data, otherwise the PMBus sends NACK after receiving the command code.

The function prevents enabling/disabling the commands if PMBus instance takes part in communication.

Parameters

inst	The pointer to the PMBus instance structure
status	Set to true to enable all the commands, set to false to disable all the commands

Returns

mtb_pmbus_status_t

mtb_pmbus_cmd_get_status()

mtb_pmbus_status_t mtb_pmbus_cmd_get_status	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		bool *	status
	)

Returns true if a command is executed at least one time.

Returns true if a command is executed at least one time (The controller executes transaction for this command and transaction is completed). Returns false if a command never executed after enabling of middleware or after the last calling of mtb_pmbus_cmd_get_status() for this command.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code
status	Status of command execution

Returns

mtb_pmbus_status_t

mtb_pmbus_cmd_wr_protect_isr()

void mtb_pmbus_cmd_wr_protect_isr	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		bool	status
	)

Enable or disable write protection for a specific command.

When write protection is enabled (status = true), the PMBus middleware will NACK any write attempts to the specified command code. When disabled (status = false), normal write access is allowed.

Warning

Enabling/Disabling write protection for the command which take part in active transfer can lead to unexpected behavior.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code for target command
status	Set to true to enable write protection, false to disable

mtb_pmbus_cmd_wr_protect()

mtb_pmbus_status_t mtb_pmbus_cmd_wr_protect	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code,
		bool	status
	)

Enable or disable write protection for a specific command.

When write protection is enabled (status = true), the PMBus middleware will NACK any write attempts to the specified command code. When disabled (status = false), normal write access is allowed.

Parameters

inst	The pointer to the PMBus instance structure
code	The command code for target command
status	Set to true to enable write protection, false to disable

Returns

mtb_pmbus_status_t

mtb_pmbus_cmd_all_wr_protect()

mtb_pmbus_status_t mtb_pmbus_cmd_all_wr_protect	(	mtb_pmbus_stc_t *	inst,
		bool	status
	)

Enables or disables write protection for all PMBus commands.

This function sets the write protection status for all commands in the PMBus instance.

The function prevents enabling/disabling the commands protection if PMBus instance takes part in communication.

Parameters

inst	The pointer to the PMBus instance structure.
status	Set to true to enable write protection, false to disable.

Returns

mtb_pmbus_status_t