VCMAILBOX(7)

📦
version 0-unstable-2024-12 · 2 versions
, in nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

Okay so this is vcmailbox — the VideoCore mailbox property interface, from the VCMAILBOX(7) page in the Miscellaneous Information Manual. Bestie, it’s the protocol situation that lets the ARM on a Raspberry Pi talk to the VideoCore processor. ✨

🎀 DESCRIPTION 🎀

The mailbox is how the ARM on the Raspberry Pi communicates with the VideoCore processor. From the command line, you can use vcmailbox(1) for this. It runs a simple request/response protocol, and here’s the vibe check on how it behaves:

  • 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, because 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).
  • The 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/response code field:
    • 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 🌸

okay so these are the ids you'll be passing around, they're literally the whole personality of this section:

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, bestie. And heads up: a value of 0x80000000 means the id was not valid — so like, don't trust it, it's giving "no thoughts head empty" 💀.

🎚️ 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)

Same deal, queen — the voltage value may be clamped to the supported range, and 0x80000000 means that id was not valid. no cap.

📈 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)

Returns the maximum supported voltage rate for the given id. Voltages should not be set higher than this — that's the vibe check, don't cross it 🙈.

📉 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)

Returns the minimum supported voltage rate for the given id. This may be used when idle — like when the SoC is just chilling, scrolling, not doing much 💅.

🌡️ Get temperature ⭐

Tag:        0x00030006
Request:    4 bytes
            u32    temperature id
Response:   8 bytes
            u32    temperature id
            u32    value

Returns the temperature of the SoC in thousandths of a degree C. And yeah, id should be zero — that's the only one it knows, iykyk.

🔥 Get max temperature 👑

Tag:        0x0003000a
Request:    4 bytes
            u32    temperature id
Response:   8 bytes
            u32    temperature id
            u32    value

Returns the maximum safe temperature of the SoC, also in thousandths of a degree C. id should be zero. Overclock may be disabled above this temperature — so like, that's the ceiling, bestie, literally 🥵.

🧠 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:

  • MEM_FLAG_NORMAL — 0 — normal allocating alias; don't use from ARM
  • MEM_FLAG_DISCARDABLE — 1 << 0 — can be resized to 0 at any time; use for cached data
  • MEM_FLAG_DIRECT — 1 << 2 — 0xC alias uncached
  • MEM_FLAG_COHERENT — 1 << 3 — 0x8 alias; non-allocating in L2 but coherent
  • MEM_FLAG_L1_NONALLOCATING — 3 << 2 — Allocating in L2
  • MEM_FLAG_ZERO — 1 << 4 — Initialise buffer to all zeros
  • MEM_FLAG_NO_INIT — 1 << 5 — Don't initialise; default is initialise to all ones
  • MEM_FLAG_HINT_PERMALOCK — 1 << 6 — Likely to be locked for long periods of time

🔒 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 — like, that's not optional, that's a requirement, periodt 🔐.

🔓 Unlock memory 🦋

Tag:        0x0003000e
Request:    4 bytes
            u32    handle
Response:   4 bytes
            u32    status

Unlock buffer. It retains contents, but may move — yeah, it's allowed to relocate, so don't get attached to where it was. 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. bye bestie 🫶

🏃 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    r0

Calls the function at given (bus) address and with arguments given. E.g.

r0 = fn(r0, r1, r2, r3, r4, r5);

It blocks until the call completes — like it's literally just standing there waiting, no multitasking main character energy. The (GPU) instruction cache is implicitly flushed. Setting the lsb of the function pointer address will suppress the instruction cache flush if you know the buffer hasn't changed since last execution — that's a big "if", so be careful, ngl 🙈.

🖼️ 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 — that's the whole point, it's a shortcut and it slays 💅.

📺 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 — that's your stop signal, bestie, don't loop forever 🌀.

🖥️ FRAME BUFFER TAGS 🖥️

okay before we get into the tags themselves, there are some ground rules and you need to know them:

  • 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 — yeah, that's a whole wasted round trip, embarrassing 😭
  • 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). So like, don't do it. fr fr.

🧱 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 — so like, you get told no and nothing happens. gentle rejection ✨.

🗑️ Release buffer 🫶

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

Releases and disables the frame buffer. zero bytes in, zero bytes out, very efficient queen 💅.

🌑 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

Bit 0 is the whole personality: 0 = off, 1 = on. Bits 1–31 are reserved for future use — so set them to 0 on the way in, and just leave them be on the way out 🙈.

📐 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. yes this trips everyone up. no you're not dumb. it's just like that 🦋.

🧪 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 — it's a vibe check, not a commitment 💅.

🎚️ 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 — so like, actually read the response, bestie, don't assume 😭.

🖼️ 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 — cute little window into a bigger picture, iconic 🌈.

🧪 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

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 — again, just checking, not doing 👑

🎚️ 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. same rules as above, don't skip the check 🙈.

🎨 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

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 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 — yep, check it, always, every time 🫶.

Get pixel order 🎨

  • Tag: 0x00040006
  • Request: 0 bytes
  • Response: 4 bytes
u32    state
       0x0    BGR
       0x1    RGB

okay so this one just tells you which way round your colours are living rn — 0x0 means BGR, 0x1 means RGB. that's it, that's the whole tag 💅

Test pixel order

  • Tag: 0x00044006
  • Request: 4 bytes
u32    state (as above)
  • Response: 4 bytes
u32    state (as above)

the response comes back as the same as the request (or modified, bestie), and that's literally how it tells you whether this configuration is supported — in combination with all the other settings, iykyk. does not modify the current hardware or frame buffer state, so it's a vibe check, not a commitment 🫶

Set pixel order

  • Tag: 0x00048006
  • Request: 4 bytes
u32    state (as above)
  • Response: 4 bytes
u32    state (as above)
heads up: the response may not be the same as the request, so you have to check it. like actually check it. don't just assume it slayed 😭

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

three whole vibes for the alpha channel and honestly each one is a different personality 🌈

Test alpha mode

  • Tag: 0x00044007
  • Request: 4 bytes
u32    state (as above)
  • Response: 4 bytes
u32    state (as above)

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 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. no cap, always check 💀

Get pitch

  • Tag: 0x00040008
  • Request: 0 bytes
  • Response: 4 bytes
u32    bytes per line

one single u32 telling you the bytes per line. short, sweet, iconic 👑

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

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 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. so if you get 0 back, that's a no from the hardware babe 🫠

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

four numbers, four edges, all of them in pixels. top, bottom, left, right, in that order, no chaos 🌸

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

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 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. same deal as the offset, 0 means unsupported, don't fight it ✋

Get palette

  • Tag: 0x0004000b
  • Request: 0 bytes
  • Response: 1024 bytes
u32... RGBA palette values (index 0 to 255)

a whole 1024 bytes of palette, all 256 entries from index 0 to 255, each one RGBA. that's a lot of colour and we love that for us 🎀

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

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 ✨

note the size range bestie — it's 24 bytes..1032 bytes, not a fixed size, because length can be anywhere from 1 to 256 💜

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. and palette changes should not be partially applied — it's all or nothing, no half-finished palette looks, periodt 🔥

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. yes, that math is correct, and yes, it's a whole moment 😭 also there's an (unused) field sitting there being decorative, love that for it 💅

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). so like, no setup needed, the cursor just shows up ready to go 👑

fr fr, that's the end of the tags — every single one of them, no skips, no "you get the idea" 💖

okay bestie that's the whole page 🎀 you just read VCMAILBOX(7), and the very last line of the real manpage is the footer with the source/version and the date on it — you know the vibe, that little signature at the bottom. i'm not gonna copy it out for you, just know it's there, holding it down, being iconic 🌈✨🫶

bye ily, go read your mailbox tags responsibly 💜🌸

📦 where this page comes from