Videocore/Firmware linux API

I looked into firmware/opt/vc/ today, and read through the examples. The example is using vc_dispmanx -prefixed commands.

Then I peeked inside the videocore library itself. It's a little bit of a messed up with all sorts of commands, of which I'm not sure what of those commands have some use.

Since I like to try my hand on this kind of things, I wonder where to get documentation for the firmware linux API, or something other such?

Whatever was the case, I'd like to experiment with desktop environments of different kinds. Wondering how to control/access surfaces from other processes, so that compositing window manager could be buildt.

Also wondering.. shouldn't this thing be able to detect display changes? After all those display ports ought be hotpluggable shouldn't they?

[jamesh]

The library to access the VC has been around since VC1 days (10 years?), and has been built on since then, so there is quite a menagerie of commands I'm afraid. dispmanx is a VC library for handling bitmaps, but I'm not sure there is a document available (i.e. to the public)  describing all the commands/api's. IIRC dispmanx is being deprecated in favour of a different library, one of the Khronos ones I think. Can't remember the name offhand. AT least that one will be documented as its a standard API.

Why are the hello_pi -examples using that API if it's deprecated in favor of a some made by khronos?

BTW. Is it this? openwf

[jamesh]

Because dispmanx x is in the process of being deprecated. Hasn't been fully dispatched yet. Yes, I think OpenWF is what will be used, but don't quote me on it.

If you are going to spend months on providing the new API, could you provide some docs for the existing one even if it's deprecated?

I'd really like to get this going. And I'd need to be able to:

• provide, retrieve and access video surfaces of processes
• detect displays and initialize them for rendering (appears there's already example for this)

It's enough if I could do it somehow for now!

[jamesh]

If you are going to spend months on providing the new API, could you provide some docs for the existing one even if it's deprecated?

I'd really like to get this going. And I'd need to be able to:

• provide, retrieve and access video surfaces of processes
• detect displays and initialize them for rendering (appears there's already example for this)

It's enough if I could do it somehow for now!

All the docs I have access to are Broadcom confidential I am afraid, and I have no idea who to talk to to release then, or the amount of work required to get them in a state where release is possible.

Three days ago there was added OpenMAX ilcomponents documentation into the firmware repository: https://github.com/raspberrypi/firmware ... umentation

There's some functions that look like interesting, but is this the library you mentioned earlier? It didn't look like easy to grasp. And didn't find anything else but video encoding/decoding in it for now.

I'd be glad if you could provide something. But don't let my interests go over more important tasks. Although if someone was doing xorg support recently, he might know how to do what I need. I'd probably get all right with an additional example in hello_pi.

[jamesh]

Not the same stuff. I think documentation on dispmanx was what was requested.

OpenMAX is a complete and utter nightmare to use btw.

I went through the include file firmware/opt/vc/include/interface/vmcs_host/vc_dispmanx.h, it may not be so tricky to use without any docs.

It looks a lot like it'd allow multiple GLE-framebuffers at the same time, but not compositing on them. Am I correct?

Code: Select all

int vc_dispman_init( void );
void vc_dispmanx_stop( void );
int vc_dispmanx_rect_set( VC_RECT_T *rect, uint32_t x_offset, uint32_t y_offset, uint32_t width, uint32_t height );


These look quite clear. Apparently dispmanx provides a rectangle API.. seems retarded really.

Code: Select all

DISPMANX_RESOURCE_HANDLE_T vc_dispmanx_resource_create( VC_IMAGE_TYPE_T type, uint32_t width, uint32_t height, uint32_t *native_image_handle );
int vc_dispmanx_resource_write_data( DISPMANX_RESOURCE_HANDLE_T res, VC_IMAGE_TYPE_T src_type, int src_pitch, void * src_address, const VC_RECT_T * rect );
int vc_dispmanx_resource_write_data_handle( DISPMANX_RESOURCE_HANDLE_T res, VC_IMAGE_TYPE_T src_type, int src_pitch, VCHI_MEM_HANDLE_T handle, uint32_t offset, const VC_RECT_T * rect );
int vc_dispmanx_resource_read_data( DISPMANX_RESOURCE_HANDLE_T handle, const VC_RECT_T* p_rect, void *dst_address, uint32_t dst_pitch );
int vc_dispmanx_resource_delete( DISPMANX_RESOURCE_HANDLE_T res );


This also seems quite very much self-explanatory. These ones are for GPU resource buffers.

Code: Select all

// Opens a display on the given device
DISPMANX_DISPLAY_HANDLE_T vc_dispmanx_display_open( uint32_t device );
// Opens a display on the given device in the request mode
DISPMANX_DISPLAY_HANDLE_T vc_dispmanx_display_open_mode( uint32_t device, uint32_t mode );
// Open an offscreen display
DISPMANX_DISPLAY_HANDLE_T vc_dispmanx_display_open_offscreen( DISPMANX_RESOURCE_HANDLE_T dest, VC_IMAGE_TRANSFORM_T orientation );
// Change the mode of a display
int vc_dispmanx_display_reconfigure( DISPMANX_DISPLAY_HANDLE_T display, uint32_t mode );
// Sets the desstination of the display to be the given resource
int vc_dispmanx_display_set_destination( DISPMANX_DISPLAY_HANDLE_T display, DISPMANX_RESOURCE_HANDLE_T dest );
// Set the background colour of the display
int vc_dispmanx_display_set_background( DISPMANX_UPDATE_HANDLE_T update, DISPMANX_DISPLAY_HANDLE_T display,                                                                        uint8_t red, uint8_t green, uint8_t blue );
// get the width, height, frame rate and aspect ratio of the display
int vc_dispmanx_display_get_info( DISPMANX_DISPLAY_HANDLE_T display, DISPMANX_MODEINFO_T * pinfo );
// Closes a display
int vc_dispmanx_display_close( DISPMANX_DISPLAY_HANDLE_T display );


These are almost self-explanatory. Apparently opens a display handle, which can be attached to a resource buffer above.

Code: Select all

// Updates
// Start a new update, DISPMANX_NO_HANDLE on error
DISPMANX_UPDATE_HANDLE_T vc_dispmanx_update_start( int32_t priority );
// Add an elment to a display as part of an update
DISPMANX_ELEMENT_HANDLE_T vc_dispmanx_element_add ( DISPMANX_UPDATE_HANDLE_T update, DISPMANX_DISPLAY_HANDLE_T display,
                                                                     int32_t layer, const VC_RECT_T *dest_rect, DISPMANX_RESOURCE_HANDLE_T src,
                                                                     const VC_RECT_T *src_rect, DISPMANX_PROTECTION_T protection,
                                                                     VC_DISPMANX_ALPHA_T *alpha,
                                                                     DISPMANX_CLAMP_T *clamp, DISPMANX_TRANSFORM_T transform );
// Change the source image of a display element
int vc_dispmanx_element_change_source( DISPMANX_UPDATE_HANDLE_T update, DISPMANX_ELEMENT_HANDLE_T element,
                                                        DISPMANX_RESOURCE_HANDLE_T src );
// Change the layer number of a display element
int vc_dispmanx_element_change_layer ( DISPMANX_UPDATE_HANDLE_T update, DISPMANX_ELEMENT_HANDLE_T element,
                                                        int32_t layer );
// Signal that a region of the bitmap has been modified
int vc_dispmanx_element_modified( DISPMANX_UPDATE_HANDLE_T update, DISPMANX_ELEMENT_HANDLE_T element, const VC_RECT_T * rect );
// Remove a display element from its display
int vc_dispmanx_element_remove( DISPMANX_UPDATE_HANDLE_T update, DISPMANX_ELEMENT_HANDLE_T element );
// Ends an update
int vc_dispmanx_update_submit( DISPMANX_UPDATE_HANDLE_T update, DISPMANX_CALLBACK_FUNC_T cb_func, void *cb_arg );
// End an update and wait for it to complete
int vc_dispmanx_update_submit_sync( DISPMANX_UPDATE_HANDLE_T update );
// Query the image formats supported in the VMCS build
int vc_dispmanx_query_image_formats( uint32_t *supported_formats );

//New function added to VCHI to change attributes, set_opacity does not work there.
int vc_dispmanx_element_change_attributes( DISPMANX_UPDATE_HANDLE_T update,
                                                            DISPMANX_ELEMENT_HANDLE_T element,
                                                            uint32_t change_flags,
                                                            int32_t layer,
                                                            uint8_t opacity,
                                                            const VC_RECT_T *dest_rect,
                                                            const VC_RECT_T *src_rect,
                                                            DISPMANX_RESOURCE_HANDLE_T mask,
                                                            VC_IMAGE_TRANSFORM_T transform );

//xxx hack to get the image pointer from a resource handle, will be obsolete real soon
uint32_t vc_dispmanx_resource_get_image_handle( DISPMANX_RESOURCE_HANDLE_T res);

//Call this instead of vc_dispman_init
void vc_vchi_dispmanx_init (VCHI_INSTANCE_T initialise_instance, VCHI_CONNECTION_T **connections, uint32_t num_connections );

// Take a snapshot of a display in its current state.
// This call may block for a time; when it completes, the snapshot is ready.
int vc_dispmanx_snapshot( DISPMANX_DISPLAY_HANDLE_T display,
                                           DISPMANX_RESOURCE_HANDLE_T snapshot_resource,
                                           VC_IMAGE_TRANSFORM_T transform );


These last ones looks like they'd have something to do with updating the screen. But otherwise not really certain about them.

As ever dealing with an undocumented API is tiresome...after some experimenting I have a good idea how to use dispmanx.

This after noon I was thinking about messing with: vc_dispmanx_resource_write_data_handle()

It was less than helpful when no library actually exposed that interface.

This after noon I was thinking about messing with: vc_dispmanx_resource_write_data_handle()

It was less than helpful when no library actually exposed that interface.

Might be worth submitting a bug report? https://github.com/raspberrypi/firmware/issues
(assuming you're already updated to the latest firmware, of course)

I just checked the latest firmware from a few days back. No luck. I've registered an issue.

I got a response. Essentially the call doesn't do anything.

This is where some documentation might come in handy.

As far as I know, you cant much of the SoC docs without an NDA from broadcom?