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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
void	mtb_pmbus_cmd_enable_disable_isr (mtb_pmbus_stc_t *inst, uint32_t code, bool status)
	Enable/Disable command.
mtb_pmbus_status_t	mtb_pmbus_cmd_enable_disable (mtb_pmbus_stc_t *inst, uint32_t code, bool status)
	Enable/Disable command.
mtb_pmbus_status_t	mtb_pmbus_cmd_ext_enable_disable (mtb_pmbus_stc_t *inst, bool status)
	Enable/Disable the extended command.
mtb_pmbus_status_t	mtb_pmbus_cmd_all_enable_disable (mtb_pmbus_stc_t *inst, bool status)
	Enable/Disable all commands from both command tables: main ( mtb_pmbus_stc_config_t::cmd_table) and extended ( mtb_pmbus_stc_config_t::ext_cmd_table).
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.
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.
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.
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.
uint8_t	mtb_pmbus_get_acl (const mtb_pmbus_stc_t *inst, uint32_t cmd_code)
	Returns the Access Control Byte for the specified command code.
void	mtb_pmbus_set_acl_isr (mtb_pmbus_stc_t *inst, uint32_t cmd_code, uint8_t acl_byte)
	ISR-safe: stores the Access Control Byte for the specified command and synchronizes the write-access restriction with the IS_WR_PROTECTED flag.
mtb_pmbus_status_t	mtb_pmbus_set_acl (mtb_pmbus_stc_t *inst, uint32_t cmd_code, uint8_t acl_byte)
	Thread-safe variant of mtb_pmbus_set_acl_isr.
mtb_pmbus_passkey_state_t	mtb_pmbus_get_passkey_state_isr (const mtb_pmbus_stc_t *inst)
	ISR-safe: returns the current PASSKEY state.
uint8_t	mtb_pmbus_get_passkey_read_byte_isr (const mtb_pmbus_stc_t *inst)
	ISR-safe: returns the byte to send as the PASSKEY read response.
void	mtb_pmbus_passkey_transition_isr (mtb_pmbus_stc_t *inst, bool key_matched, bool is_zero_key)
	ISR-safe: drives the PASSKEY state machine one step.
void	mtb_pmbus_passkey_force_locked_isr (mtb_pmbus_stc_t *inst, uint8_t fail_cnt)
	ISR-safe: forces the PASSKEY state to Locked with an initial fail count.
mtb_pmbus_status_t	mtb_pmbus_passkey_force_locked (mtb_pmbus_stc_t *inst, uint8_t fail_cnt)
	Thread-safe variant of mtb_pmbus_passkey_force_locked_isr.
void	mtb_pmbus_set_acl_from_nvm (mtb_pmbus_stc_t *inst, const uint8_t *nvm_acl, uint16_t count)
	Bulk-initialises the ACL table from an NVM-stored array.
void	mtb_pmbus_apply_write_protect_isr (mtb_pmbus_stc_t *inst, uint8_t value)
	ISR-safe: applies a WRITE_PROTECT byte value to all registered commands.
mtb_pmbus_status_t	mtb_pmbus_apply_write_protect (mtb_pmbus_stc_t *inst, uint8_t value)
	Thread-safe variant of mtb_pmbus_apply_write_protect_isr.
mtb_pmbus_status_t	mtb_pmbus_cmd_exit_isr (mtb_pmbus_stc_t *inst)
	Requests to pause the Process Call protocol execution and exit from the ISR handler.
mtb_pmbus_status_t	mtb_pmbus_cmd_complete_transfer (mtb_pmbus_stc_t *inst, uint32_t code)
	Resumes a paused Process Call protocol transaction.
mtb_pmbus_status_t	mtb_pmbus_cmd_process_call_wr_done (mtb_pmbus_stc_t *inst, bool *status)
	Determines if the current MTB_PMBUS_CMD_WRITE_DONE event is for a Process Call protocol.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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 both command tables: main ( mtb_pmbus_stc_config_t::cmd_table) and extended ( mtb_pmbus_stc_config_t::ext_cmd_table).

To disable the extended command, use mtb_pmbus_cmd_ext_enable_disable.

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 both command tables: main ( mtb_pmbus_stc_config_t::cmd_table) and extended ( mtb_pmbus_stc_config_t::ext_cmd_table).

To disable the extended command, use mtb_pmbus_cmd_ext_enable_disable.

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_ext_enable_disable()

mtb_pmbus_status_t mtb_pmbus_cmd_ext_enable_disable	(	mtb_pmbus_stc_t *	inst,
		bool	status )

Enable/Disable the extended 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.

When the extended command is disabled, none commands from the extended table will be transmitted.

Note

This function is only available when MTB_PMBUS_SUPPORT_EXT_CMD is enabled at compile time options.

Parameters

inst	The pointer to the PMBus instance structure
status	Set to true to enable the command, set to false to disable the 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 both command tables: main ( mtb_pmbus_stc_config_t::cmd_table) and extended ( mtb_pmbus_stc_config_t::ext_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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

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

mtb_pmbus_get_acl()

uint8_t mtb_pmbus_get_acl	(	const mtb_pmbus_stc_t *	inst,
		uint32_t	cmd_code )

Returns the Access Control Byte for the specified command code.

Accepts a standard 8-bit code (0x00-0xFF) or an encoded extended code of the form produced by MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

Parameters

inst	The pointer to the PMBus instance structure.
cmd_code	Command code whose ACL byte is queried.

Returns

Current ACL byte value (0x00 = all access permitted).

mtb_pmbus_set_acl_isr()

void mtb_pmbus_set_acl_isr	(	mtb_pmbus_stc_t *	inst,
		uint32_t	cmd_code,
		uint8_t	acl_byte )

ISR-safe: stores the Access Control Byte for the specified command and synchronizes the write-access restriction with the IS_WR_PROTECTED flag.

Must be called from the PMBus ISR context (e.g. in a CMD_WRITE_DONE callback). Enforces Never Again [0] and No More [1] permanence guards — updates are silently rejected with MTB_PMBUS_ERR_ACL_WR_REJECTED if either bit is set.

Parameters

inst	The pointer to the PMBus instance structure.
cmd_code	Target command code (standard or encoded extended).
acl_byte	Access Control Byte value to store.

mtb_pmbus_set_acl()

mtb_pmbus_status_t mtb_pmbus_set_acl	(	mtb_pmbus_stc_t *	inst,
		uint32_t	cmd_code,
		uint8_t	acl_byte )

Thread-safe variant of mtb_pmbus_set_acl_isr.

May be called from any non-ISR context. Disables the PMBus hardware IRQ around the update. Returns MTB_PMBUS_STATUS_IS_BUSY if the bus is active.

Parameters

inst	The pointer to the PMBus instance structure.
cmd_code	Target command code (standard or encoded extended).
acl_byte	Access Control Byte value to store.

Returns

MTB_PMBUS_STATUS_SUCCESS, MTB_PMBUS_STATUS_IS_BUSY, or MTB_PMBUS_STATUS_BAD_PARAM if the encoded extended code has no backing store or is out of range.

mtb_pmbus_get_passkey_state_isr()

mtb_pmbus_passkey_state_t mtb_pmbus_get_passkey_state_isr

(

const mtb_pmbus_stc_t *

inst

)

ISR-safe: returns the current PASSKEY state.

May be called from a command callback or any ISR context.

Parameters

inst	The pointer to the PMBus instance.

Returns

Current mtb_pmbus_passkey_state_t value.

mtb_pmbus_get_passkey_read_byte_isr()

uint8_t mtb_pmbus_get_passkey_read_byte_isr

(

const mtb_pmbus_stc_t *

inst

)

ISR-safe: returns the byte to send as the PASSKEY read response.

Call from the MTB_PMBUS_CMD_READ_REQ event in the PASSKEY command callback.

Parameters

inst	The pointer to the PMBus instance.

Returns

0x00 = Unlocked/SetNotLocked; MTB_PMBUS_PASSKEY_STATE_BYTE_LOCKED_BASE to (MTB_PMBUS_PASSKEY_STATE_BYTE_LOCKED_BASE + MTB_PMBUS_PASSKEY_MAX_FAIL_CNT - 1U) = Locked (fail count in bits [3:0], extractable with MTB_PMBUS_PASSKEY_FAIL_CNT_MASK); MTB_PMBUS_PASSKEY_STATE_BYTE_LOCKED_OUT = LockedOut.

mtb_pmbus_passkey_transition_isr()

void mtb_pmbus_passkey_transition_isr	(	mtb_pmbus_stc_t *	inst,
		bool	key_matched,
		bool	is_zero_key )

ISR-safe: drives the PASSKEY state machine one step.

Must be called from the MTB_PMBUS_CMD_WRITE_DONE callback of the PASSKEY command.

State transition rules:

• Unlocked + non-zero key → SetNotLocked.
• SetNotLocked + matching key → Locked.
• SetNotLocked + all-zero key → Unlocked.
• SetNotLocked + non-matching non-zero key → stays SetNotLocked. The application must detect the mismatch in MTB_PMBUS_CMD_WRITE_BYTE and return false to NACK the last data byte; MTB_PMBUS_CMD_WRITE_DONE is not fired in that case (MW suppresses it when errors are set) and this function is not called.
• Locked + matching key → SetNotLocked (first unlock step).
• Locked + non-matching key → stays Locked; increments fail counter (stealth).
• Locked, fail counter ≥ MTB_PMBUS_PASSKEY_MAX_FAIL_CNT → LockedOut.
• LockedOut → no change.

Parameters

inst	The pointer to the PMBus instance.
key_matched	true if the received passkey matches the application's stored key.
is_zero_key	true if all received passkey data bytes are 0x00.

mtb_pmbus_passkey_force_locked_isr()

void mtb_pmbus_passkey_force_locked_isr	(	mtb_pmbus_stc_t *	inst,
		uint8_t	fail_cnt )

ISR-safe: forces the PASSKEY state to Locked with an initial fail count.

Call after mtb_pmbus_init() and before the PMBus HAL IRQ is enabled, when NVM indicates that a passkey was previously set.

Parameters

inst	The pointer to the PMBus instance.
fail_cnt	Initial fail count. Clamped to MTB_PMBUS_PASSKEY_MAX_FAIL_CNT - 1.

mtb_pmbus_passkey_force_locked()

mtb_pmbus_status_t mtb_pmbus_passkey_force_locked	(	mtb_pmbus_stc_t *	inst,
		uint8_t	fail_cnt )

Thread-safe variant of mtb_pmbus_passkey_force_locked_isr.

Returns MTB_PMBUS_STATUS_IS_BUSY if a transaction is in progress.

Parameters

inst	The pointer to the PMBus instance.
fail_cnt	Initial fail count.

Returns

MTB_PMBUS_STATUS_SUCCESS or MTB_PMBUS_STATUS_IS_BUSY.

mtb_pmbus_set_acl_from_nvm()

void mtb_pmbus_set_acl_from_nvm	(	mtb_pmbus_stc_t *	inst,
		const uint8_t *	nvm_acl,
		uint16_t	count )

Bulk-initialises the ACL table from an NVM-stored array.

Copies up to count bytes from nvm_acl into acl_table[], then synchronizes the IS_WR_PROTECTED flag for every entry with bit [7] set. Never Again [0] and No More [1] guards are bypassed — the NVM image is the authoritative source at power-on.

Must be called after mtb_pmbus_init() and before the PMBus HAL IRQ is enabled.

Parameters

inst	The pointer to the PMBus instance structure.
nvm_acl	Pointer to the application NVM buffer (index = command code).
count	Number of ACL bytes to restore.

mtb_pmbus_apply_write_protect_isr()

void mtb_pmbus_apply_write_protect_isr	(	mtb_pmbus_stc_t *	inst,
		uint8_t	value )

ISR-safe: applies a WRITE_PROTECT byte value to all registered commands.

Sets or clears the IS_WR_PROTECTED flag for every command in inst->cfg->cmd_table (and ext_cmd_table when MTB_PMBUS_SUPPORT_EXT_CMD is enabled) according to the protection level encoded in value:

• MTB_PMBUS_WP_VAL_PROTECT_ALL (0x80): protect all except the Protect Locks group (MTB_PMBUS_WRITE_PROTECT_CMD_CODE, MTB_PMBUS_ACCESS_CONTROL_CMD_CODE, MTB_PMBUS_PASSKEY_CMD_CODE).
• MTB_PMBUS_WP_VAL_PROTECT_IMMEDIATE (0x40): protect all except Protect Locks and MTB_PMBUS_OPERATION_CMD_CODE.
• MTB_PMBUS_WP_VAL_PROTECT_VOLATILE (0x20): protect all except Protect Locks, MTB_PMBUS_OPERATION_CMD_CODE, MTB_PMBUS_ON_OFF_CONFIG_CMD_CODE, and output voltage commands (MTB_PMBUS_VOUT_FIRST_CMD_CODE–MTB_PMBUS_VOUT_LAST_CMD_CODE, MTB_PMBUS_VOUT_TRANS_FIRST_CMD_CODE–MTB_PMBUS_VOUT_TRANS_LAST_CMD_CODE).
• MTB_PMBUS_WP_VAL_NO_PROTECTION (0x00): clear WRITE_PROTECT-sourced protection from all commands. Commands that are also protected by MTB_PMBUS_ACL_BIT_WRITE_ACCESS in the ACL table remain write-protected (most-restrictive-wins rule).

Most-restrictive-wins: WRITE_PROTECT level and MTB_PMBUS_ACL_BIT_WRITE_ACCESS are independent sources of write protection. IS_WR_PROTECTED is set when either source demands protection. Therefore, writing MTB_PMBUS_WP_VAL_NO_PROTECTION does NOT unprotect a command whose acl_table entry has MTB_PMBUS_ACL_BIT_WRITE_ACCESS set.

Stores the new value in inst->write_protect_val for read-back by the user callback.

Must be called from ISR context or with the PMBus HAL IRQ disabled.

Parameters

inst	The pointer to the PMBus instance.
value	WRITE_PROTECT byte value. One of the MTB_PMBUS_WP_VAL_* macros.

mtb_pmbus_apply_write_protect()

mtb_pmbus_status_t mtb_pmbus_apply_write_protect	(	mtb_pmbus_stc_t *	inst,
		uint8_t	value )

Thread-safe variant of mtb_pmbus_apply_write_protect_isr.

Disables the PMBus HAL IRQ, calls mtb_pmbus_apply_write_protect_isr, then re-enables the IRQ. Returns MTB_PMBUS_STATUS_IS_BUSY if a transaction is in progress.

Parameters

inst	The pointer to the PMBus instance.
value	WRITE_PROTECT byte value. One of the MTB_PMBUS_WP_VAL_* macros.

Returns

MTB_PMBUS_STATUS_SUCCESS or MTB_PMBUS_STATUS_IS_BUSY.

mtb_pmbus_cmd_exit_isr()

mtb_pmbus_status_t mtb_pmbus_cmd_exit_isr

(

mtb_pmbus_stc_t *

inst

)

Requests to pause the Process Call protocol execution and exit from the ISR handler.

This function must be called from within the command callback during the MTB_PMBUS_CMD_WRITE_DONE event for Process Call protocols. It allows the application to defer the read response phase, enabling time-consuming processing outside the ISR context.

When called during the allowed window (MTB_PMBUS_CMD_WRITE_DONE event), the function pauses the I2C hardware transmission. The middleware will suspend the transaction after the write phase completes, allowing the application to process the received data and prepare the response outside of ISR context. After processing, the application must call mtb_pmbus_cmd_complete_transfer() to resume and complete the transaction.

Usage pattern:

1. Controller initiates Process Call write phase
2. In MTB_PMBUS_CMD_WRITE_DONE callback, call mtb_pmbus_cmd_exit_isr()
3. Exit ISR and process received data in main application context
4. Update response data buffer
5. Call mtb_pmbus_cmd_complete_transfer() to resume and send response

Parameters

inst	The pointer to the PMBus instance structure

Returns

mtb_pmbus_status_t Status of the operation:

• MTB_PMBUS_STATUS_SUCCESS: Pause request was accepted and hardware transmission paused successfully
• MTB_PMBUS_STATUS_BAD_PARAM: Function was called outside the allowed context (not during MTB_PMBUS_CMD_WRITE_DONE event for Process Call) or hardware pause operation failed

Note

This function should only be used with Process Call protocols

Must be called from within the MTB_PMBUS_CMD_WRITE_DONE event callback

If a command supports both write and process call capabilities (MTB_PMBUS_CMD_CAP_DIR_WR | MTB_PMBUS_CMD_CAP_DIR_PROCESS_CALL), the user can call mtb_pmbus_cmd_process_call_wr_done() function to determine whether the current MTB_PMBUS_CMD_WRITE_DONE event occurred for a Process Call transaction

mtb_pmbus_cmd_complete_transfer()

mtb_pmbus_status_t mtb_pmbus_cmd_complete_transfer	(	mtb_pmbus_stc_t *	inst,
		uint32_t	code )

Resumes a paused Process Call protocol transaction.

This function must be called outside of ISR context after calling mtb_pmbus_cmd_exit_isr() to complete a Process Call protocol transaction. After the write phase completes and the application processes the received data, this function resumes the I2C transaction and sends the response data to the controller.

To apply this function to an extended command, put parameter code into macros MTB_PMBUS_CONV_CMD_EXT_CMD_FORMAT.

Usage pattern:

1. In MTB_PMBUS_CMD_WRITE_DONE callback, call mtb_pmbus_cmd_exit_isr() to pause the transaction
2. Exit ISR and process received data in the main application context
3. Update the command buffer with response data
4. Call mtb_pmbus_cmd_complete_transfer() to resume and complete the transaction

Parameters

inst	The pointer to the PMBus instance structure
code	Command code of the paused Process Call command

Returns

mtb_pmbus_status_t Status of the operation:

• MTB_PMBUS_STATUS_SUCCESS: Transaction resumed and completed successfully
• MTB_PMBUS_STATUS_BAD_PARAM: The specified command is not in paused state (either not a Process Call or mtb_pmbus_cmd_exit_isr() was not called)

Note

This function must be called outside of ISR/callback context

This function should only be used with Process Call protocols

mtb_pmbus_cmd_process_call_wr_done()

mtb_pmbus_status_t mtb_pmbus_cmd_process_call_wr_done	(	mtb_pmbus_stc_t *	inst,
		bool *	status )

Determines if the current MTB_PMBUS_CMD_WRITE_DONE event is for a Process Call protocol.

This function checks whether the current MTB_PMBUS_CMD_WRITE_DONE event occurred for a Process Call transaction. It is useful when a command supports both standard write and Process Call capabilities (MTB_PMBUS_CMD_CAP_DIR_WR | MTB_PMBUS_CMD_CAP_DIR_PROCESS_CALL), allowing the application to distinguish between the two operation types.

When a command supports both capabilities, the WRITE_DONE callback will be triggered for both write and Process Call operations. This function returns true only when the event is for a Process Call, indicating that:

• The pause mechanism is available (mtb_pmbus_cmd_exit_isr() can be called)
• A read phase will follow to send response data back to the controller

Parameters

inst	The pointer to the PMBus instance structure
status	Pointer to a boolean variable that will be updated with the result: true: Current WRITE_DONE event is for a Process Call protocol false: Current WRITE_DONE event is for a standard write operation

Returns

mtb_pmbus_status_t Status of the operation:

• MTB_PMBUS_STATUS_SUCCESS: Status retrieved successfully
• MTB_PMBUS_STATUS_BAD_PARAM: Invalid parameter (status pointer is NULL)

Note

This function should be called from within the MTB_PMBUS_CMD_WRITE_DONE callback