Man page - vcmailbox(7)

Packages contains this manual

Package: raspi-utils-core
apt-get install raspi-utils-core

Manuals in package:

Documentations in package:

raspi-utils-core

Manual

VCMAILBOX

NAME
DESCRIPTION
Mailbox messages
Buffer contents
Tag format
VIDEOCORE TAGS
Get firmware revision
HARDWARE TAGS
Get board model
Get board revision
Get board MAC address
Get board serial
Get ARM memory
Get VC memory
Get clocks
CONFIG TAGS
Get command line
SHARED RESOURCE MANAGEMENT TAGS
Get DMA channels
POWER TAGS
Unique device IDs
Get power state
Get timing
Set power state
CLOCK TAGS
Unique clock IDs
Get clock state
Set clock state
Get clock rate
Set clock rate
Get max clock rate
Get min clock rate
Get turbo
Set turbo
VOLTAGE TAGS
Unique voltage IDs
Get voltage
Set voltage
Get max voltage
Get min voltage
Get temperature
Get max temperature
Allocate memory
Lock memory
Unlock memory
Release Memory
Execute Code
Get Dispmanx Resource mem handle
Get EDID block
FRAME BUFFER TAGS
Allocate buffer
Release buffer
Blank screen
Get physical (display) width/height
Test physical (display) width/height
Set physical (display) width/height
Get virtual (buffer) width/height
Test virtual (buffer) width/height
Set virtual (buffer) width/height
Get depth
Set depth
Get pixel order
Test pixel order
Set pixel order
Get alpha mode
Test alpha mode
Set alpha mode
Get pitch
Get virtual offset
Test virtual offset
Set virtual offset
Get overscan
Test overscan
Set overscan
Get palette
Test palette
Set palette
Set Cursor Info
Set Cursor State

NAME

vcmailbox - the VideoCore mailbox property interface

DESCRIPTION

The mailbox can be used by the ARM on the Raspberry Pi to communicate with the VideoCore processor. From the command line, the vcmailbox (1) can be used for this purpose. The mailbox operates a simple request / response protocol:

•

The response overwrites the request.

•

			The callee is not allowed to return a different buffer address, this allows the caller to make independent asynchronous requests.
	•		The buffer itself is 16-byte aligned as only the upper 28 bits of the address can be passed via the mailbox.
	•		All u64/u32/u16 values are in host CPU endian order.
	•		Unknown tags are ignored (the response bit will not be set).
	•		Response may include unsolicited tags.
	•		Response tag lengths may be longer than expected if additional information is provided in a future format.

•

			The response is truncated to the provided buffer length.
	•		Incompatible changes require a new tag so that where the buffer is the size required by a previous version the truncated part should be readable as per the previous version.
	•		Response length indicates the desired length even when it is longer than the buffer size filled.
	•		Tag value length can be used to infer the version of the request/response.
	•

Tags should be processed in order except where an interface requires multiple tags for a single operation (like the frame buffer).

Mailbox messages

•

The mailbox interface has 28 bits (MSB) available for the value and 4 bits (LSB) for the channel.

•

			Request message: 28 bits (MSB) buffer address
	•		Response message: 28 bits (MSB) buffer address
	•

Channels 8 and 9 are used.

	•		Channel 8: Request from ARM for response by VC
	•		Channel 9: Request from VC for response by ARM (none currently defined)

Buffer contents

	u32		buffer size in bytes (including the header values, the end tag and padding)
	u32		buffer request/response code

Request codes:

	0x00000000		process request
			All other values reserved

Response codes:

	0x80000000		request successful
	0x80000001		error parsing request buffer (partial response)
			All other values reserved
	u8...

sequence of concatenated tags

	u32		0x0 (end tag)
	u8...		padding

Tag format

	u32		tag identifier
	u32		value buffer size in bytes
	u32		Request codes:

b31 clear

			request
	b30-b0		reserved

Response codes:

	b31 set		response
	b30-b0		value length in bytes
	u8...

value buffer

u8...

padding to align the tag to 32 bits.

VIDEOCORE TAGS

Get firmware revision

	Tag:		0x00000001
	Request:		0 bytes
	Response:		4 bytes

u32

firmware revision

HARDWARE TAGS

Get board model

	Tag:		0x00010001
	Request:		0 bytes
	Response:		4 bytes

u32

board model

Get board revision

	Tag:		0x00010002
	Request:		0 bytes
	Response:		4 bytes

u32

board revision

Get board MAC address

	Tag:		0x00010003
	Request:		0 bytes
	Response:		6 bytes

u8...

MAC address in network byte order

Get board serial

	Tag:		0x00010004
	Request:		0 bytes
	Response:		8 bytes

u64

board serial

Get ARM memory

	Tag:		0x00010005
	Request:		0 bytes
	Response:		8 bytes

u32

			base address in bytes
	u32		size in bytes

Future formats may specify multiple base+size combinations.

Get VC memory

	Tag:		0x00010006
	Request:		0 bytes
	Response:		8 bytes

u32

			base address in bytes
	u32		size in bytes

Future formats may specify multiple base+size combinations.

Get clocks

	Tag:		0x00010007
	Request:		0 bytes
	Response:		variable bytes (multiple of 8)

u32

			parent clock id (0 for a root clock)
	u32		clock id

(repeated)

Returns all clocks that exist in top-down, breadth-first order . Clocks that depend on another clock should be defined as children of that clock. Clocks that depend on no other clocks should have no parent. Clock IDs are as in the CLOCK TAGS section below.

CONFIG TAGS

Get command line

	Tag:		0x00050001
	Request:		0 bytes
	Response:		variable bytes

u8...

ASCII command line string

Caller should not assume the string is null terminated.

SHARED RESOURCE MANAGEMENT TAGS

Get DMA channels

	Tag:		0x00060001
	Request:		0 bytes
	Response:		4 bytes

u32

mask

Bits 0-15

			DMA channels 0-15 (0=do not use, 1=usable)
	Bits 16-31		reserved for future use

Caller assumes that the VC has enabled all the usable DMA channels.

POWER TAGS

Unique device IDs

	0x00000000		SD Card
	0x00000001		UART0
	0x00000002		UART1
	0x00000003		USB HCD
	0x00000004		I2C0
	0x00000005		I2C1
	0x00000006		I2C2
	0x00000007		SPI
	0x00000008		CCP2TX
	0x00000009		Unknown (RPi4)
	0x0000000a		Unknown (RPi4)

Get power state

	Tag:		0x00020001
	Request:		4 bytes

u32

			device id
	Response:		8 bytes

u32

			device id
	u32		state

Bit 0

			0=off, 1=on
	Bit 1		0=device exists, 1=device does not exist
	Bits 2-31		reserved for future use

Response indicates current state.

Get timing

	Tag:		0x00020002
	Request:		4 bytes

u32

			device id
	Response:		8 bytes

u32

			device id
	u32		enable wait time in microseconds

Response indicates wait time required after turning a device on before power is stable. Returns 0 wait time if the device does not exist.

Set power state

	Tag:		0x00028001
	Request:		8 bytes

u32

			device id
	u32		state

Bit 0

			0=off, 1=on
	Bit 1		0=do not wait, 1=wait
	Bits 2-31		reserved for future use (set to 0)
	Response:

8 bytes

	u32		device id
	u32		state

Bit 0

			0=off, 1=on
	Bit 1		0=device exists, 1=device does not exist
	Bits 2-31		reserved for future use

Response indicates new state, with/without waiting for the power to become stable.

CLOCK TAGS

Unique clock IDs

	0x00000000		reserved
	0x00000001		EMMC
	0x00000002		UART
	0x00000003		ARM
	0x00000004		CORE
	0x00000005		V3D
	0x00000006		H264
	0x00000007		ISP
	0x00000008		SDRAM
	0x00000009		PIXEL
	0x0000000a		PWM
	0x0000000b		HEVC
	0x0000000c		EMMC2
	0x0000000d		M2MC
	0x0000000e		PIXEL_BVB

All clocks are the base clocks for those peripherals, e.g. 3MHz for UART, 50/100MHz for EMMC, not the dividers applied using the peripheral.

Get clock state

	Tag:		0x00030001
	Request:		4 bytes

u32

			clock id
	Response:		8 bytes

u32

			clock id
	u32		state

Bit 0

			0=off, 1=on
	Bit 1		0=clock exists, 1=clock does not exist
	Bits 2-31		reserved for future use

Set clock state

	Tag:		0x00038001
	Request:		8 bytes

u32

			clock id
	u32		state

Bit 0

			0=off, 1=on
	Bit 1		0=clock exists, 1=clock does not exist
	Bits 2-31		reserved for future use (set to 0)
	Response:

8 bytes

	u32		clock id
	u32		state

Bit 0

			0=off, 1=on
	Bit 1		0=clock exists, 1=clock does not exist
	Bits 2-31		reserved for future use

Get clock rate

	Tag:		0x00030002
	Request:		4 bytes

u32

			clock id
	Response:		8 bytes

u32

			clock id
	u32		rate (in Hz)

Next enable rate should be returned even if the clock is not running. A rate of 0 is returned if the clock does not exist.

Set clock rate

	Tag:		0x00038002
	Request:		12 bytes

u32

			clock id
	u32		rate (in Hz)
	u32		skip setting turbo
	Response:

8 bytes

	u32		clock id
	u32		rate (in Hz)

Next supported enable rate should be returned even if the clock is not running. A rate of 0 is returned if the clock does not exist. The clock rate may be clamped to the supported range.

By default when setting arm freq above default, other turbo settings will be enabled (e.g. voltage, sdram and gpu frequencies). You can disable this effect by setting "skip setting turbo" to 1.

Get max clock rate

	Tag:		0x00030004
	Request:		4 bytes

u32

			clock id
	Response:		8 bytes

u32

			clock id
	u32		rate (in Hz)

Return the maximum supported clock rate for the given clock. Clocks should not be set higher than this.

Get min clock rate

	Tag:		0x00030007
	Request:		4 bytes

u32

			clock id
	Response:		8 bytes

u32

			clock id
	u32		rate (in Hz)

Return the minimum supported clock rate for the given clock. This may be used when idle.

Get turbo

	Tag:		0x00030009
	Request:		4 bytes

u32

			id
	Response:		8 bytes

u32

			id
	u32		level

Get the turbo state for index id. id should be 0. level will be zero for non-turbo and one for turbo.

Set turbo

	Tag:		0x00038009
	Request:		8 bytes

u32

			id
	u32		level
	Response:

8 bytes

	u32		id
	u32		level

Set the turbo state for index id. id should be zero. level will be zero for non-turbo and one for turbo. This will cause GPU clocks to be set to maximum when enabled and minimum when disabled.

VOLTAGE TAGS

Unique voltage IDs

	0x00000000		reserved
	0x00000001		Core
	0x00000002		SDRAM_C
	0x00000003		SDRAM_P
	0x00000004		SDRAM_I

Get voltage

	Tag:		0x00030003
	Request:		4 bytes

u32

			voltage id
	Response:		8 bytes

u32

			voltage id
	u32		value (offset from 1.2V in units of 0.025V)

The voltage value may be clamped to the supported range. A value of 0x80000000 means the id was not valid.

Set voltage

	Tag:		0x00038003
	Request:		8 bytes

u32

			voltage id
	u32		value (offset from 1.2V in units of 0.025V)
	Response:

8 bytes

	u32		voltage id
	u32		value (offset from 1.2V in units of 0.025V)

The voltage value may be clamped to the supported range. A value of 0x80000000 means the id was not valid.

Get max voltage

	Tag:		0x00030005
	Request:		4 bytes

u32

			voltage id
	Response:		8 bytes

u32

			voltage id
	u32		value (offset from 1.2V in units of 0.025V)

Return the maximum supported voltage rate for the given id. Voltages should not be set higher than this.

Get min voltage

	Tag:		0x00030008
	Request:		4 bytes

u32

			voltage id
	Response:		8 bytes

u32

			voltage id
	u32		value (offset from 1.2V in units of 0.025V)

Return the minimum supported voltage rate for the given id. This may be used when idle.

Get temperature

	Tag:		0x00030006
	Request:		4 bytes

u32

			temperature id
	Response:		8 bytes

u32

			temperature id
	u32		value

Return the temperature of the SoC in thousandths of a degree C. id should be zero.

Get max temperature

	Tag:		0x0003000a
	Request:		4 bytes

u32

			temperature id
	Response:		8 bytes

u32

			temperature id
	u32		value

Return the maximum safe temperature of the SoC in thousandths of a degree C. id should be zero. Overclock may be disabled above this temperature.

Allocate memory

	Tag:		0x0003000c
	Request:		12 bytes

u32

			size
	u32		alignment
	u32		flags
	Response:

4 bytes

u32

handle

Allocates contiguous memory on the GPU. size and alignment are in bytes. flags contain:

Image grohtml-3919669-1.png

Lock memory

	Tag:		0x0003000d
	Request:		4 bytes

u32

			handle
	Response:		4 bytes

u32

bus address

Lock buffer in place, and return a bus address. Must be done before memory can be accessed

Unlock memory

	Tag:		0x0003000e
	Request:		4 bytes

u32

			handle
	Response:		4 bytes

u32

status

Unlock buffer. It retains contents, but may move. Needs to be locked before next use. status=0 is success.

Release Memory

	Tag:		0x0003000f
	Request:		4 bytes

u32

			handle
	Response:		4 bytes

u32

status

Free the memory buffer. status=0 is success.

Execute Code

	Tag:		0x00030010
	Request:		28 bytes

u32

			function pointer
	u32		r0
	u32		r1
	u32		r2
	u32		r3
	u32		r4
	u32		r5
	Response:

4 bytes

u32

Calls the function at given (bus) address and with arguments given. E.g. r0 = fn(r0, r1, r2, r3, r4, r5); It blocks until call completes. The (GPU) instruction cache is implicitly flushed. Setting the lsb of function pointer address will suppress the instruction cache flush if you know the buffer hasn’t changed since last execution.

Get Dispmanx Resource mem handle

	Tag:		0x00030014
	Request:		4 bytes

u32

			dispmanx resource handle
	Response:		8 bytes

u32

			0 is successful
	u32		mem handle for resource

Gets the mem_handle associated with a created dispmanx resource. This can be locked and the memory directly written from the arm to avoid having to copy the image data to GPU.

Get EDID block

	Tag:		0x00030020
	Request:		4 bytes

u32

			block number
	Response:		136 bytes

u32

			block number
	u32		status
	u8...		EDID block

This reads the specified EDID block from attached HDMI/DVI device. There will always be at least one block of 128 bytes, but there may be additional blocks. You should keep requesting blocks (starting from 0) until the status returned is non-zero.

FRAME BUFFER TAGS

	•		All tags in the request are processed in one operation.
	•		It is not valid to mix Test tags with Get/Set tags in the same operation and no tags will be returned.
	•		Get tags will be processed after all Set tags.
	•		If an allocate buffer tag is omitted when setting parameters, then no change occurs unless it can be accommodated without changing the buffer base or size.
	•		When an allocate buffer response is returned, the old buffer area (if the base or size has changed) is implicitly freed.

For example:

	1.		The current values/defaults are loaded into a temporary struct
	2.		The tags are used to overwrite some or all of the values
	3.		Validation of Test/Set tags occurs
	4.		The Set changes are applied and responses based on the requested Get/Test/Set tags are written to the buffer Duplicating the same tag in one request/response is prohibited. The expected result is either an error or implementation specified undefined behaviour (such as only using the last instance of the tag).

Allocate buffer

	Tag:		0x00040001
	Request:		4 bytes

u32

			alignment in bytes
	Response:		8 bytes

u32

			frame buffer base address in bytes
	u32		frame buffer size in bytes

If the requested alignment is unsupported then the current base and size (which may be 0 if not allocated) is returned and no change occurs.

Release buffer

	Tag:		0x00048001
	Request:		0 bytes
	Response:		0 bytes

Releases and disables the frame buffer.

Blank screen

	Tag:		0x00040002
	Request:		4 bytes

u32

state

Bit 0

			0=off, 1=on
	Bits 1-31		reserved for future use (set to 0)
	Response:

4 bytes

u32

state

Bit 0

			0=off, 1=on
	Bits 1-31		reserved for future use

Get physical (display) width/height

	Tag:		0x00040003
	Request:		0 bytes
	Response:		8 bytes

u32

			width in pixels
	u32		height in pixels

Note that the "physical (display)" size is the size of the allocated buffer in memory, not the resolution of the video signal sent to the display device.

Test physical (display) width/height

	Tag:		0x00044003
	Request:		8 bytes

u32

			width in pixels
	u32		height in pixels
	Response:

8 bytes

	u32		width in pixels
	u32		height in pixels

Response is the same as the request (or modified), to indicate if this configuration is supported (in combination with all the other settings). Does not modify the current hardware or frame buffer state.

Set physical (display) width/height

	Tag:		0x00048003
	Request:		8 bytes

u32

			width in pixels
	u32		height in pixels
	Response:

8 bytes

	u32		width in pixels
	u32		height in pixels

The response may not be the same as the request so it must be checked. May be the previous width/height or 0 for unsupported.

Get virtual (buffer) width/height

	Tag:		0x00040004
	Request:		0 bytes
	Response:		8 bytes

u32

			width in pixels
	u32		height in pixels

Note that the "virtual (buffer)" size is the portion of buffer that is sent to the display device, not the resolution the buffer itself. This may be smaller than the allocated buffer size in order to implement panning.

Test virtual (buffer) width/height

	Tag:		0x00044004
	Request:		8 bytes

u32

			width in pixels
	u32		height in pixels
	Response:

8 bytes

	u32		width in pixels
	u32		height in pixels

Set virtual (buffer) width/height

	Tag:		0x00048004
	Request:		8 bytes

u32

			width in pixels
	u32		height in pixels
	Response:

8 bytes

	u32		width in pixels
	u32		height in pixels

The response may not be the same as the request so it must be checked. May be the previous width/height or 0 for unsupported.

Get depth

	Tag:		0x00040005
	Request:		0 bytes
	Response:		4 bytes

u32

bits per pixel

Test depth

	Tag:		0x00044005
	Request:		4 bytes

u32

			bits per pixel
	Response:		4 bytes

u32

bits per pixel

Set depth

	Tag:		0x00048005
	Request:		4 bytes

u32

			bits per pixel
	Response:		4 bytes

u32

bits per pixel

The response may not be the same as the request so it must be checked. May be the previous depth or 0 for unsupported.

Get pixel order

	Tag:		0x00040006
	Request:		0 bytes
	Response:		4 bytes

u32

state

0x0

			BGR
	0x1		RGB

Test pixel order

	Tag:		0x00044006
	Request:		4 bytes

u32

			state (as above)
	Response:		4 bytes

u32

state (as above)

Set pixel order

	Tag:		0x00048006
	Request:		4 bytes

u32

			state (as above)
	Response:		4 bytes

u32

state (as above)

The response may not be the same as the request so it must be checked.

Get alpha mode

	Tag:		0x00040007
	Request:		0 bytes
	Response:		4 bytes

u32

state

0x0

			Alpha channel enabled (0 = fully opaque)
	0x1		Alpha channel reversed (0 = fully transparent)
	0x2		Alpha channel ignored

Test alpha mode

	Tag:		0x00044007
	Request:		4 bytes

u32

			state (as above)
	Response:		4 bytes

u32

state (as above)

Set alpha mode

	Tag:		0x00048007
	Request:		4 bytes

u32

			state (as above)
	Response:		4 bytes

u32

state (as above)

The response may not be the same as the request so it must be checked.

Get pitch

	Tag:		0x00040008
	Request:		0 bytes
	Response:		4 bytes

u32

bytes per line

Get virtual offset

	Tag:		0x00040009
	Request:		0 bytes
	Response:		8 bytes

u32

			X in pixels
	u32		Y in pixels

Test virtual offset

	Tag:		0x00044009
	Request:		8 bytes

u32

			X in pixels
	u32		Y in pixels
	Response:

8 bytes

	u32		X in pixels
	u32		Y in pixels

Set virtual offset

	Tag:		0x00048009
	Request:		8 bytes

u32

			X in pixels
	u32		Y in pixels
	Response:

8 bytes

	u32		X in pixels
	u32		Y in pixels

The response may not be the same as the request so it must be checked. May be the previous offset or 0 for unsupported.

Get overscan

	Tag:		0x0004000a
	Request:		0 bytes
	Response:		16 bytes

u32

			top in pixels
	u32		bottom in pixels
	u32		left in pixels
	u32		right in pixels

Test overscan

	Tag:		0x0004400a
	Request:		16 bytes

u32

			top in pixels
	u32		bottom in pixels
	u32		left in pixels
	u32		right in pixels
	Response:

16 bytes

	u32		top in pixels
	u32		bottom in pixels
	u32		left in pixels
	u32		right in pixels

Set overscan

	Tag:		0x0004800a
	Request:		16 bytes

u32

			top in pixels
	u32		bottom in pixels
	u32		left in pixels
	u32		right in pixels
	Response:

16 bytes

	u32		top in pixels
	u32		bottom in pixels
	u32		left in pixels
	u32		right in pixels

The response may not be the same as the request so it must be checked. May be the previous overscan or 0 for unsupported.

Get palette

	Tag:		0x0004000b
	Request:		0 bytes
	Response:		1024 bytes

u32...

RGBA palette values (index 0 to 255)

Test palette

	Tag:		0x0004400b
	Request:		24 bytes..1032 bytes

u32

			offset: first palette index to set (0-255)
	u32		length: number of palette entries to set (1-256)
	u32...		RGBA palette values (offset to offset+length-1)
	Response:

4 bytes

u32

0=valid, 1=invalid

Set palette

	Tag:		0x0004800b
	Request:		24 bytes..1032 bytes

u32

			offset: first palette index to set (0-255)
	u32		length: number of palette entries to set (1-256)
	u32...		RGBA palette values (offset to offset+length-1)
	Response:

4 bytes

u32

0=valid, 1=invalid

The response may not be the same as the request so it must be checked. Palette changes should not be partially applied.

Set Cursor Info

	Tag:		0x00008010
	Request:		24 bytes

u32

			width
	u32		height
	u32		(unused)
	u32		pointer to pixels
	u32		hotspotX
	u32		hotspotY
	Response:

4 bytes

u32

0=valid, 1=invalid

Format is 32bpp (ARGB). Width and height should be >= 16 and (width * height) <= 64.

Set Cursor State

	Tag:		0x00008011
	Request:		16 bytes

u32

			enable (1=visible, 0=invisible)
	u32		x
	u32		y
	u32		flags; 0=display coords, 1=framebuffer coords
	Response:

4 bytes

u32

0=valid, 1=invalid

if Set Cursor Info hasn’t been called a default cursor will be used (64x64 with hotspot at 0,0).