MIPI DSI-2 sequence-channel command path (HUM Ch 65). More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_mipi_dsi.h"
#include "ra8_mipi_dsi_internal.h"
#include "ra8_mipi_dsi_regs.h"

Include dependency graph for ra8_mipi_dsi_cmd.c:

Enumerations
enum	dsi_cmd_mask_t : uint32_t { k_dsi_cmd_id_mask = 0x0FU }
	Low-nibble mask for the DCS command id. More...

Functions
static uint32_t	internal_ra8_mipi_dsi_make_dsc_a (const ra8_mipi_dsi_command_t *cmd)
	Build descriptor word A from a fully-formed command struct.
static uint32_t	internal_ra8_mipi_dsi_make_dsc_c (const ra8_mipi_dsi_command_t *cmd)
	Build descriptor word C (FINACT / AUXOP / ACTCODE).
static void	internal_ra8_mipi_dsi_stage_payload (const uint8_t *data, uint16_t len)
	Stage long-packet payload bytes into TXPPD0..3R.
static void	internal_ra8_mipi_dsi_pulse_start (uint8_t channel)
	Write the START-bit pulse for the given sequence channel.
static ra8_err_t	internal_ra8_mipi_dsi_validate_cmd (const ra8_mipi_dsi_command_t *cmd)
	Common LP/HS bound-checking for command submission.
static ra8_err_t	internal_check_link_state (const ra8_mipi_dsi_command_t *cmd)
	Run the LINKSR-based pre-condition checks for send_command.
static void	internal_program_descriptor (volatile r_mipi_dsi_descriptor_t dsc, const ra8_mipi_dsi_command_t cmd)
	Fill the four descriptor words for a sequence-channel command.
static void	internal_send_stage_and_pulse (const ra8_mipi_dsi_command_t *cmd)
	Stage payload + descriptor for ra8_mipi_dsi_send_command.
ra8_err_t	ra8_mipi_dsi_send_command (const ra8_mipi_dsi_command_t *cmd)
	Send any sequence-channel command (full-feature path).
ra8_err_t	ra8_mipi_dsi_send_short_packet (ra8_mipi_dsi_dt_t cmd_id, ra8_mipi_dsi_vc_t vc, uint8_t param0, uint8_t param1)
	Send a DSI short packet on sequence channel 0 (LP escape).
ra8_err_t	ra8_mipi_dsi_send_long_packet (ra8_mipi_dsi_dt_t cmd_id, ra8_mipi_dsi_vc_t vc, const uint8_t *data, uint16_t tx_len, bool low_power)
	Send a DSI long-packet write (Generic Long / DCS Long).
ra8_err_t	ra8_mipi_dsi_read_packet (ra8_mipi_dsi_dt_t cmd_id, ra8_mipi_dsi_vc_t vc, uint8_t param0, uint8_t param1, uint8_t *p_rx_buffer, uint16_t rx_len)
	Issue a BTA-then-read on sequence channel 0 and return the captured response payload.

Variables
static const char *	s_tag = "MIPI_DSI"
	Log tag for this translation unit.

Detailed Description

MIPI DSI-2 sequence-channel command path (HUM Ch 65).

Tag: [Ring 3 / HAL] {World: S}

Everything that puts a DCS/generic packet on the wire through a sequence channel: descriptor construction, payload staging into the FIFO, the SQCH start pulse, the LINKSR pre-condition checks, and the short-packet / long-packet / read-packet entry points built on top of ra8_mipi_dsi_send_command().

Split out of ra8_mipi_dsi.c along the seam the module already had. The command path touches none of the driver's module state – not s_initialized, not the clock-mode or ULPS-lane flags – so it needs nothing from the lifecycle TU beyond priv_ra8_mipi_dsi_internal_wait_eq(), which ra8_mipi_dsi_internal.h already publishes. The lifecycle, software-reset, module-stop, HS-clock and ULPS paths stay in ra8_mipi_dsi.c; the video-mode, status and IRQ-dispatch surfaces stay in ra8_mipi_dsi_dispatch.c.

The D-PHY analog block (HUM Ch 64) is owned by ra8_mipi_phy.c.

Every register access carries a HUM Ch 65 citation in the form required by scripts/checks/cite_check.py:

/* HUM Ch 65.X "name", p NNNN *\/

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file ra8_mipi_dsi_cmd.c.

Enumeration Type Documentation

◆ dsi_cmd_mask_t

enum dsi_cmd_mask_t : uint32_t

Low-nibble mask for the DCS command id.

Following the project's "no magic numbers" rule. The remaining implementation-private numeric constants and shift positions shared with ra8_mipi_dsi_dispatch.c live in ra8_mipi_dsi_internal.h.

Enumerator
k_dsi_cmd_id_mask	Low nibble of the DCS command id.

Definition at line 67 of file ra8_mipi_dsi_cmd.c.

Function Documentation

◆ internal_check_link_state()

ra8_err_t internal_check_link_state ( const ra8_mipi_dsi_command_t * cmd )

static

Run the LINKSR-based pre-condition checks for send_command.

HUM Ch 65.2 "LINKSR : Link Status Register" p 3842. Rejects LP / AUX commands while video mode is running and refuses to interleave with a busy sequence channel.

Parameters

[in] cmd Validated command descriptor.

Returns: k_ra8_ok if the link permits the command.

Return values

k_ra8_err_invalid_state	LP/AUX requested during video mode.
k_ra8_err_busy	A sequence channel is mid-transfer.

Precondition: cmd is non-null.

Postcondition: No side effects.

Note: Internal helper, not thread-safe.

Precondition: Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.

Since: 0.1.0

Definition at line 279 of file ra8_mipi_dsi_cmd.c.

References ra8_mipi_dsi_command_t::aux_operation, k_ra8_err_busy, k_ra8_err_invalid_state, k_ra8_mipi_dsi_link_sq0run, k_ra8_mipi_dsi_link_sq1run, k_ra8_mipi_dsi_link_vrun, k_ra8_ok, r_mipi_dsi_regs_t::LINKSR, ra8_mipi_dsi_command_t::low_power, RA8_INTERNAL, ra8_log_error, ra8_mipi_dsi(), and s_tag.

Referenced by ra8_mipi_dsi_send_command().

◆ internal_program_descriptor()

void internal_program_descriptor	(	volatile r_mipi_dsi_descriptor_t *	dsc,
		const ra8_mipi_dsi_command_t *	cmd )

static

Fill the four descriptor words for a sequence-channel command.

HUM Ch 65.2 SQCH0/1DSC0AR..DR pp 3925-3930. Word D points at either the rx or the tx buffer depending on the BTA direction.

Parameters

[in,out]	dsc	Descriptor base for the chosen channel.
[in]	cmd	Validated command descriptor.

Precondition: dsc and cmd are non-null.

Postcondition: Descriptor words A..D reflect cmd.

Note: Internal helper, not thread-safe.

Precondition: Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.

Since: 0.1.0

Definition at line 316 of file ra8_mipi_dsi_cmd.c.

References r_mipi_dsi_descriptor_t::A, r_mipi_dsi_descriptor_t::B, ra8_mipi_dsi_command_t::bta, r_mipi_dsi_descriptor_t::C, r_mipi_dsi_descriptor_t::D, internal_ra8_mipi_dsi_make_dsc_a(), internal_ra8_mipi_dsi_make_dsc_c(), k_ra8_mipi_dsi_bta_read, k_ra8_mipi_dsi_dsc0b_dtsel_seqrm, ra8_mipi_dsi_command_t::p_rx_buffer, ra8_mipi_dsi_command_t::p_tx_buffer, and RA8_INTERNAL.

Referenced by internal_send_stage_and_pulse().

◆ internal_ra8_mipi_dsi_make_dsc_a()

uint32_t internal_ra8_mipi_dsi_make_dsc_a ( const ra8_mipi_dsi_command_t * cmd )

static

Build descriptor word A from a fully-formed command struct.

Parameters

[in] cmd Validated command.

Returns: 32-bit DSC?AR value.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 91 of file ra8_mipi_dsi_cmd.c.

References ra8_mipi_dsi_command_t::bta, ra8_mipi_dsi_command_t::cmd_id, k_dsi_cmd_id_mask, k_ra8_mipi_dsi_bta_mask, k_ra8_mipi_dsi_byte_mask, k_ra8_mipi_dsi_dsc0a_shift_bta, k_ra8_mipi_dsi_dsc0a_shift_data0, k_ra8_mipi_dsi_dsc0a_shift_data1, k_ra8_mipi_dsi_dsc0a_shift_dt, k_ra8_mipi_dsi_dsc0a_shift_fmt, k_ra8_mipi_dsi_dsc0a_shift_spd, k_ra8_mipi_dsi_dsc0a_shift_vc, k_ra8_mipi_dsi_dt_mask, k_ra8_mipi_dsi_vc_mask, k_shift_8, ra8_mipi_dsi_command_t::low_power, ra8_mipi_dsi_command_t::p_tx_buffer, RA8_INTERNAL, ra8_mipi_dsi_command_t::tx_len, and ra8_mipi_dsi_command_t::virtual_channel.

Referenced by internal_program_descriptor().

◆ internal_ra8_mipi_dsi_make_dsc_c()

uint32_t internal_ra8_mipi_dsi_make_dsc_c ( const ra8_mipi_dsi_command_t * cmd )

static

Build descriptor word C (FINACT / AUXOP / ACTCODE).

Parameters

[in] cmd Validated command.

Returns: 32-bit DSC?CR value.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 143 of file ra8_mipi_dsi_cmd.c.

References ra8_mipi_dsi_command_t::action_code, ra8_mipi_dsi_command_t::aux_operation, k_ra8_mipi_dsi_dsc0c_actcode_mask, k_ra8_mipi_dsi_dsc0c_actcode_shift, k_ra8_mipi_dsi_dsc0c_auxop, k_ra8_mipi_dsi_dsc0c_finact, and RA8_INTERNAL.

Referenced by internal_program_descriptor().

◆ internal_ra8_mipi_dsi_pulse_start()

void internal_ra8_mipi_dsi_pulse_start ( uint8_t channel )

static

Write the START-bit pulse for the given sequence channel.

Parameters

[in] channel 0 or 1.

Mirrors FSP R_MIPI_DSI->SQCH?SET0R = SQCHnSET0R_BIT_23 | (n == ch) pattern. Both channel registers must be written so the engine latches the channel-select bit correctly.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 206 of file ra8_mipi_dsi_cmd.c.

References k_ra8_mipi_dsi_sqch_chsel, k_ra8_mipi_dsi_sqch_start, RA8_INTERNAL, ra8_mipi_dsi(), r_mipi_dsi_regs_t::SQCH0SET0R, and r_mipi_dsi_regs_t::SQCH1SET0R.

Referenced by internal_send_stage_and_pulse().

◆ internal_ra8_mipi_dsi_stage_payload()

void internal_ra8_mipi_dsi_stage_payload	(	const uint8_t *	data,
		uint16_t	len )

static

Stage long-packet payload bytes into TXPPD0..3R.

Parameters

[in]	data	Payload bytes.
[in]	len	Length, capped at k_ra8_mipi_dsi_payload_max.

See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 168 of file ra8_mipi_dsi_cmd.c.

References k_ra8_mipi_dsi_payload_max, k_shift_8, RA8_INTERNAL, ra8_mipi_dsi(), r_mipi_dsi_regs_t::TXPPD0R, r_mipi_dsi_regs_t::TXPPD1R, r_mipi_dsi_regs_t::TXPPD2R, and r_mipi_dsi_regs_t::TXPPD3R.

Referenced by internal_send_stage_and_pulse().

◆ internal_ra8_mipi_dsi_validate_cmd()

ra8_err_t internal_ra8_mipi_dsi_validate_cmd ( const ra8_mipi_dsi_command_t * cmd )

static

Common LP/HS bound-checking for command submission.

Parameters

[in] cmd Validated command (caller already null-checked).

Returns: k_ra8_ok if all bounds OK, otherwise an error code.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 234 of file ra8_mipi_dsi_cmd.c.

References k_ra8_err_invalid_arg, k_ra8_err_null_ptr, k_ra8_mipi_dsi_max_hs_bytes, k_ra8_mipi_dsi_max_lp_bytes, k_ra8_mipi_dsi_vc3, k_ra8_ok, ra8_mipi_dsi_command_t::low_power, ra8_mipi_dsi_command_t::p_tx_buffer, RA8_INTERNAL, ra8_mipi_dsi_command_t::tx_len, and ra8_mipi_dsi_command_t::virtual_channel.

Referenced by ra8_mipi_dsi_send_command().

◆ internal_send_stage_and_pulse()

void internal_send_stage_and_pulse ( const ra8_mipi_dsi_command_t * cmd )

static

Stage payload + descriptor for ra8_mipi_dsi_send_command.

For long packets (data-type low nibble > 0x08) we stage the first 16 bytes through TXPPD and let the descriptor's word D point at the caller buffer for the remainder. Sequence channel 0 carries LP commands; channel 1 carries HS commands.

Parameters

[in] cmd Validated command descriptor.

Precondition: Link-state check passed.

Postcondition: Sequence-channel descriptor + payload window programmed and the matching channel pulsed.

Note: Internal helper, not thread-safe.

Precondition: Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.

Since: 0.1.0

Definition at line 349 of file ra8_mipi_dsi_cmd.c.

References ra8_mipi_dsi_command_t::cmd_id, internal_program_descriptor(), internal_ra8_mipi_dsi_pulse_start(), internal_ra8_mipi_dsi_stage_payload(), k_dsi_cmd_id_mask, ra8_mipi_dsi_command_t::low_power, ra8_mipi_dsi_command_t::p_tx_buffer, RA8_INTERNAL, ra8_mipi_dsi(), r_mipi_dsi_regs_t::SQCH0DSC, r_mipi_dsi_regs_t::SQCH1DSC, and ra8_mipi_dsi_command_t::tx_len.

Referenced by ra8_mipi_dsi_send_command().

◆ ra8_mipi_dsi_read_packet()

ra8_err_t ra8_mipi_dsi_read_packet	(	ra8_mipi_dsi_dt_t	cmd_id,
		ra8_mipi_dsi_vc_t	vc,
		uint8_t	param0,
		uint8_t	param1,
		uint8_t *	p_rx_buffer,
		uint16_t	rx_len )

nodiscard

Issue a BTA-then-read on sequence channel 0 and return the captured response payload.

Builds a Generic / DCS read descriptor with BTA = bta_read, kicks the sequence, then leaves response collection to the IRQ – the caller polls ra8_mipi_dsi_rx_result_get() for the slot containing the result.

Parameters

[in]	cmd_id	k_ra8_mipi_dsi_dt_gen_read_* or k_ra8_mipi_dsi_dt_dcs_read.
[in]	vc	Virtual channel.
[in]	param0	First parameter byte.
[in]	param1	Second parameter byte.
[out]	p_rx_buffer	Buffer the IRQ handler will copy RXPPD into.
[in]	rx_len	Maximum bytes the buffer can hold.

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	Read kicked off.
k_ra8_err_null_ptr	p_rx_buffer == nullptr.
k_ra8_err_invalid_arg	vc > 3 or rx_len == 0.
k_ra8_err_busy	Sequence engine running.

Precondition: Driver initialized; PHY in BTA-capable state.; p_rx_buffer lives until the IRQ fires.

Postcondition: Descriptor 0 of channel 0 holds a read header.; SQCH0SET0R pulsed.

Since: 0.1.0

Definition at line 434 of file ra8_mipi_dsi_cmd.c.

References k_ra8_err_invalid_arg, k_ra8_mipi_dsi_bta_read, RA8_CHECK_NULL_PTR, ra8_mipi_dsi_send_command(), s_mipi_dsi_pending_rx_buffer, s_mipi_dsi_pending_rx_len, and s_tag.

◆ ra8_mipi_dsi_send_command()

ra8_err_t ra8_mipi_dsi_send_command ( const ra8_mipi_dsi_command_t * cmd )

nodiscard

Send any sequence-channel command (full-feature path).

Assembles a descriptor from cmd – handles short / long / aux-op / BTA / ack-request / LP vs HS / read-with-rx-buffer in one entry point. This is the FSP-equivalent surface; the helpers above just wrap it.

Parameters

[in] cmd Validated command descriptor.

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	Packet queued.
k_ra8_err_null_ptr	cmd == nullptr.
k_ra8_err_invalid_arg	cmd->virtual_channel > 3, or LP and tx_len > 128, or HS and tx_len > 1024, or aux op while video running.
k_ra8_err_busy	Sequence engine running.
k_ra8_err_invalid_state	LP requested while video mode running.

Precondition: cmd non-NULL.; Driver initialized.

Postcondition: Selected sequence channel descriptor 0 populated.; SQCH*SET0R pulsed.

Since: 0.1.0

Definition at line 370 of file ra8_mipi_dsi_cmd.c.

References internal_check_link_state(), internal_ra8_mipi_dsi_validate_cmd(), internal_send_stage_and_pulse(), k_ra8_mipi_dsi_payload_max, k_ra8_ok, ra8_mipi_dsi_command_t::p_rx_buffer, RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, s_mipi_dsi_pending_rx_buffer, s_mipi_dsi_pending_rx_len, and s_tag.

Referenced by ra8_mipi_dsi_read_packet(), ra8_mipi_dsi_send_long_packet(), and ra8_mipi_dsi_send_short_packet().

◆ ra8_mipi_dsi_send_long_packet()

ra8_err_t ra8_mipi_dsi_send_long_packet	(	ra8_mipi_dsi_dt_t	cmd_id,
		ra8_mipi_dsi_vc_t	vc,
		const uint8_t *	data,
		uint16_t	tx_len,
		bool	low_power )

nodiscard

Send a DSI long-packet write (Generic Long / DCS Long).

Stages the payload bytes into TXPPD0..3R (max 16 bytes) and points the descriptor at the packet RAM. For payloads > 16 bytes the descriptor word D carries an external buffer pointer.

Parameters

[in]	cmd_id	k_ra8_mipi_dsi_dt_gen_long_write or k_ra8_mipi_dsi_dt_dcs_long_write.
[in]	vc	Virtual channel (0..3).
[in]	data	Payload bytes (tx_len long).
[in]	tx_len	Payload length in bytes (max 65535 per spec).
[in]	low_power	true to send via channel 0 (LP), false for channel 1 (HS).

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	Packet queued, START asserted.
k_ra8_err_null_ptr	data == nullptr and tx_len > 0.
k_ra8_err_invalid_arg	vc > 3 or LP and tx_len > 128.
k_ra8_err_busy	Sequence engine already running.

Precondition: Driver initialized.; Either tx_len == 0 or data valid.

Postcondition: Descriptor 0 of the selected channel carries the long-packet header (DATA0 = WC[7:0], DATA1 = WC[15:8]).; SQCH*SET0R pulsed with START + CHSEL for that channel.

Since: 0.1.0

Definition at line 410 of file ra8_mipi_dsi_cmd.c.

References k_ra8_err_null_ptr, k_ra8_mipi_dsi_bta_none, and ra8_mipi_dsi_send_command().

Referenced by ra8_mipi_dsi_send_command_long(), and ra8_mipi_dsi_send_command_payload().

◆ ra8_mipi_dsi_send_short_packet()

ra8_err_t ra8_mipi_dsi_send_short_packet	(	ra8_mipi_dsi_dt_t	cmd_id,
		ra8_mipi_dsi_vc_t	vc,
		uint8_t	param0,
		uint8_t	param1 )

nodiscard

Send a DSI short packet on sequence channel 0 (LP escape).

Backwards-compat helper – assembles a default LP descriptor with SPD=1, BTA=none, no ack, no aux, then pulses START. Equivalent to ra8_mipi_dsi_send_command() with the matching ra8_mipi_dsi_command_t.

Parameters

[in]	cmd_id	One of the k_ra8_mipi_dsi_dt_* short-write constants.
[in]	vc	Virtual channel (0..3).
[in]	param0	First parameter byte.
[in]	param1	Second parameter byte.

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	Packet queued and START asserted.
k_ra8_err_invalid_arg	vc > 3.
k_ra8_err_busy	Sequence engine already running.

Precondition: Driver was initialized via ra8_mipi_dsi_init.; LINKSR.SQ0RUN is 0.

Postcondition: Descriptor 0 of channel 0 carries the assembled header.; SQCH0SET0R was pulsed with START + CHSEL.

Since: 0.1.0

Definition at line 389 of file ra8_mipi_dsi_cmd.c.

References k_ra8_mipi_dsi_bta_none, and ra8_mipi_dsi_send_command().

Referenced by ra8_mipi_dsi_send_command_payload(), and ra8_mipi_dsi_send_command_short().

Variable Documentation

◆ s_tag

const char* s_tag = "MIPI_DSI"

static

Log tag for this translation unit.

Matches the tag used by the sibling MIPI DSI translation units so a console trace reads as one driver.

Note: Read-only after initialisation.

Warning: Do not modify at run time.

Since: 0.1.0

Definition at line 56 of file ra8_mipi_dsi_cmd.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ dsi_cmd_mask_t

Function Documentation

◆ internal_check_link_state()

◆ internal_program_descriptor()

◆ internal_ra8_mipi_dsi_make_dsc_a()

◆ internal_ra8_mipi_dsi_make_dsc_c()

◆ internal_ra8_mipi_dsi_pulse_start()

◆ internal_ra8_mipi_dsi_stage_payload()

◆ internal_ra8_mipi_dsi_validate_cmd()

◆ internal_send_stage_and_pulse()

◆ ra8_mipi_dsi_read_packet()

◆ ra8_mipi_dsi_send_command()

◆ ra8_mipi_dsi_send_long_packet()

◆ ra8_mipi_dsi_send_short_packet()

Variable Documentation

◆ s_tag