 |
It's the mode number (the content of the list array) that's important for subsequent calls, and not the mode index itself. |
Table of your driver's modeswitcher functions
#include <mode.h>
typedef struct disp_modefuncs {
int (*init) (…);
void (*fini) (…);
void (*module_info) (…);
int (*get_modeinfo) (…);
int (*get_modelist) (…);
int (*set_mode) (…);
int (*wait_vsync) (…);
int (*set_dpms_mode) (…);
int (*set_display_offset) (…);
int (*set_palette) (…);
int (*layer_query) (…);
int (*layer_enable) (…);
int (*layer_disable) (…);
int (*layer_set_surface) (…);
int (*layer_set_source_viewport) (…);
int (*layer_set_dest_viewport) (…);
int (*layer_set_blending) (…);
int (*layer_set_chromakey) (…);
int (*layer_set_brightness) (…);
int (*layer_set_saturation) (…);
int (*layer_set_contrast) (…);
int (*layer_set_hue) (…);
int (*layer_set_alpha_map) (…);
int (*layer_set_flags) (…);
void (*layer_update_begin) (…);
void (*layer_update_end) (…);
void (*layer_reset) (…);
int (*layer_set_order) (…);
int (*set_hw_cursor) (…);
void (*enable_hw_cursor) (…);
void (*disable_hw_cursor) (…);
void (*set_hw_cursor_pos) (…);
int (*i2c_read) (…);
int (*i2c_write) (…);
int (*i2c_writeread) (…);
} disp_modefuncs_t;
The disp_modefuncs_t structure is a table that your driver uses to define the modeswitcher functions that it provides to the graphics framework. Your driver's devg_get_modefuncs() entry point must fill in this structure.
The graphics framework calls this function to initialize your hardware. The prototype is:
int (*init) (disp_adapter_t *ctx,
char *optstring)
This function should return the number of independent displays that this modeswitcher controls, or -1 to indicate an error. For example, if a display card controls both a flat-panel and a monitor simultaneously, and can display a different image on each, this function should return 2.
For more information on where this function fits into the general flow, see “Calling sequence” in the Writing a Graphics Driver chapter.
The graphics framework calls this function to return your hardware to the uninitialized state, deallocate resources, and so on. The prototype is:
void (*fini) (disp_adapter_t *ctx)
For more information on where this function fits into the general flow, see “Calling sequence” in the Writing a Graphics Driver chapter.
The graphics framework calls this function to get information about the module, such as its description and revision numbers. The prototype is:
void (*module_info) (disp_adapter_t *adapter,
disp_module_info_t *info);
This function should fill in the disp_module_info_t structure pointed to by info.
The graphics framework calls this function to get mode information. The prototype is:
int (*get_modeinfo) (disp_adapter_t *ctx,
int dispno,
unsigned mode,
disp_mode_info_t *info)
This function should populate the disp_mode_info_t structure pointed to by info with information pertaining to the mode specified in mode for the display referenced by dispno. See the note about modes in get_modelist() below for more information.
The graphics framework calls this function to get a list of the modes that your driver supports. The prototype is:
int (*get_modelist) (disp_adapter_t *ctx,
int dispno,
disp_mode_t *list,
int index,
int size)
This function should place a maximum of size modes into the array list, starting at the index index, for the display referenced by dispno. The index parameter is in place to allow multiple calls to the get_modelist() function in case there are more modes than will fit into the list array on any given call.
The list of modes is terminated with the constant DISP_MODE_LISTEND. The list of modes must be returned in the exact same order each time, but there's no requirement to arrange the list by any sorting criteria.
|
It's the mode number (the content of the list array) that's important for subsequent calls, and not the mode index itself. |
For example, if your driver returns the following array:
list [0] = 0x1234; list [1] = 0x070B; list [2] = 0x4321; list [3] = DISP_MODE_LISTEND; /* terminate list */
then your get_modeinfo() and set_mode() functions are called with, for example, 0x4321 and not the index 2.
|
The driver should use only the 15 least significant bits of the disp_mode_t type. Thus each entry in list must be less than or equal to 0x7fff. |
The graphics framework calls this function to set the hardware for the display referenced by dispno to the mode specified by mode. The prototype is:
int (*set_mode) (disp_adapter_t *ctx,
int dispno,
unsigned mode,
disp_crtc_settings_t *settings,
disp_surface_t *surf,
unsigned flags)
See the note about modes in get_modelist() above for more information.
The settings parameter is valid only if the mode is a generic mode, which means that the framework can pass an arbitrary X and Y resolution and refresh rate. The driver advertises that it can support generic modes by setting the appropriate flag in the disp_mode_info_t structure when get_modeinfo() is called.
The surf and flags parameters are deprecated and are ignored by the framework.
For more information on where this function fits into the general flow, see “Calling sequence” in the Writing a Graphics Driver chapter.
This function must wait until the display controller for the display referenced by dispno enters the vertical-retrace period. The prototype is:
int (*wait_vsync) (disp_adapter_t *adapter,
int dispno);
There is a per-display counter stored in the ms_ctx member of the disp_adapter_t structure that needs to be incremented when the vertical retrace period is entered. This may be done each time this function is called after the retrace period is entered, but it's OK if the counter is incremented upon every retrace event, whether this function is called or not.
The counter should be incremented as an atomic operation, for example:
atomic_add(&adapter->ms_ctx->vsync_counter[dispno], 1);
Your driver should try to support simultaneous wait_vsync() operations among multiple clients, such that when one client is blocked, another client can still render. This means that while one client is waiting for a vsync to occur, another client could be rendering offscreen, or on a different layer. This can be achieved by unlocking the device before blocking on a event (for example, a pulse from an interrupt handler), and then locking the device again before continuing. While the device is unlocked, other driver entry points may be called.
The driver can cause the device to be locked or unlocked by way of a callback. See disp_adapter_t for details on callbacks into the graphics framework.
 |
The driver should not attempt to use the unlock/relock mechanism from within any entry points other than this one or the wait_vsync entry point from disp_vcapfuncs_t. |
The graphics framework calls this function to set the DPMS mode. mode. The prototype is:
void (*set_dpms_mode) (disp_adapter_t *ctx,
int dispno,
int mode)
Select a DPMS mode for the display referenced by dispno as follows:
| Mode | Meaning |
|---|---|
| 0 | On |
| 1 | Standby |
| 2 | Suspend |
| 4 (not a typo) | Off |
The graphics framework calls this function to set the frame buffer base of the visible display for the display controller referenced by dispno. The prototype is:
void (*set_display_offset) (disp_adapter_t *ctx,
int dispno,
unsigned offset,
int wait_vsync)
If wait_vsync is nonzero, your driver should wait for the next vertical retrace period before returning from this function.
The graphics framework calls this function to set the palette for the display referenced by dispno. The prototype is:
void (*set_palette) (disp_adapter_t *ctx,
int dispno,
int index,
int count,
disp_color_t *pal)
One or more entries in the palette can be set at a time with this function call. The index indicates the starting palette index, and count indicates the number of entries being set. Finally, pal contains an array of color values, one per entry, to set.
|
If this function is specified (i.e. not NULL in the function
pointer set_palette), then it's called regardless of whether or
not the
set_palette()
function in the miscellaneous callouts structure,
disp_draw_miscfuncs_t, has been supplied:
if (disp_modefuncs -> set_palette) {
(*disp_modefuncs -> set_palette) (…);
} else if (disp_draw_miscfuncs -> set_palette) {
(*disp_draw_miscfuncs -> set_palette (…);
}
|
The graphics framework calls this function to query the capabilities of a given layer. The prototype is:
int (*layer_query) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int fmt_idx,
disp_layer_query_t *info);
The arguments to layer_query are:
If the layer_idx or fmt_idx indexes are out of range, this function should return -1, otherwise it should return 0.
The graphics framework calls this function to make the layer specified by layer_idx visible. The prototype is:
int (*layer_enable) (
disp_adapter_t *adapter,
int dispno,
int layer_idx )
The arguments to layer_enable are:
If the dispno or layer_idx indexes are out of range, or the layer can't be disabled or reenabled, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to make the layer specified by layer_idx invisible. The prototype is:
int (*layer_enable) (
disp_adapter_t *adapter,
int dispno,
int layer_idx )
The arguments to layer_disable are:
If the dispno, or layer_idx indexes are out of range, or the layer can't be disabled or re-enabled, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to associate a memory surface with the layer specified by layer_idx. The prototype is:
int (*layer_set_surface) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
unsigned layer_format,
disp_surface_t *surf[] )
The arguments to layer_set_surface are:
The number of surfaces in he array is dependent on the layer format. For example, there are three surfaces for planar YUV, and one for RGB or packed YUV formats.
The memory surfaces were created by the driver's alloc_layer_surface() management entry point. .
If the dispno or layer_idx indexes are out of range, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to set the size of the source viewport for the layer that layer_idx specifies. The prototype is:
int (*layer_set_source_viewport) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int x1, y1,
int x2, y2 )
The arguments to layer_set_source_viewport are:
This function should return -1 if:
Or:
Or:
Otherwise the function should return 0.
The graphics framework calls this function to set the size of the destination viewport for the layer that layer_idx specifies. The prototype is:
int (*layer_set_dest_viewport) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int x1, y1,
int x2, y2 )
The arguments to layer_set_dest_viewport are:
If the dispno or layer_idx indexes are out of range, or the viewport width for the capabilities structure for this layer is outside the ranges specified by dst_max_height, dst_min_height, dst_max_width, and dst_min_width, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to set the layer's blending configuration for the layer specified by layer_idx. The prototype is:
int (*layer_set_blending) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
unsigned alpha_mode,
int m1,
int m2 )
The arguments to layer_set_blending are:
If the dispno or layer_idx indexes are out of range, this function should return -1 to indicate an error, otherwise it should return 0.
If the layer selected by layer_idx doesn't support the combination of flags specified by alpha_mode, this function should return -1, otherwise it should return 0.
For more information on global alpha multipliers, and the currently defined flags, see “Alpha mode bits.”
The graphics framework calls this function to set the layer's chroma-key configuration for the layer specified by layer_idx. The prototype is:
int (*layer_set_chromakey) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
unsigned chroma_mode,
disp_color_t color0,
disp_color_t color1,
disp_color_t mask );
The arguments to layer_set_chromakey are:
DISP_CHROMA_OP_SRC_MATCH and DISP_CHROMA_OP_DST_MATCH are mutually exclusive.
DISP_CHROMA_OP_DRAW and DISP_CHROMA_OP_NO_DRAW are also mutually exclusive.
If 0 is passed for chroma-mode, chroma-keying is disabled.
For more information on chroma key mode bits, see “Chroma mode bits”
If the layer selected by layer_idx doesn't support the combination of flags specified by chroma_mode, this function should return -1, otherwise it should return 0.
The graphics framework calls this function to set the brightness attribute of the layer specified by layer_idx. The prototype is:
int (*layer_set_brightness) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int brightness );
The arguments to layer_set_brightness are:
If the selected layer doesn't support brightness adjustment, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to set the color saturation attribute of the layer specified by layer_idx. The prototype is:
int (*layer_set_saturation) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int saturation );
The arguments to layer_set_saturation are:
If the selected layer doesn't support saturation adjustment, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to set the contrast attribute of the layer specified by layer_idx. The prototype is:
int (*layer_set_contrast) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int contrast );
The arguments to layer_set_contrast are:
If the selected layer doesn't support contrast adjustment, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to set the hue attribute of the layer specified by layer_idx. The prototype is:
int (*layer_set_hue) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int hue );
The arguments to layer_set_hue are:
If the selected layer doesn't support hue adjustment, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to set the alpha map attribute of the layer specified by layer_idx. The prototype is:
int (*layer_set_alpha_map) (
disp_adapter_t *adapter,
int dispno,
int layer,
disp_surface_t *map );
The arguments to layer_set_alpha_map are:
If the selected layer doesn't support alpha maps, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to set various attributes of the layer specified by layer_idx. The prototype is:
int (*layer_set_flags) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
unsigned flag_mask
unsigned flag_values );
The arguments to layer_set_flags are:
The following flags are supported:
If the selected layer isn't supported by one or more of the flags specified by flag_mask, this function should return -1 to indicate an error, otherwise it should return 0.
This function must be called before you make any adjustments to the layer configuration. The driver should attempt to make multiple adjustments atomic, by having the adjustments take effect at the time layer_update_end() is called. The prototype is:
void (*layer_update_begin) (
disp_adapter_t *adapter,
int dispno,
int layer_idx );
The arguments to layer_update_begin are:
The prototype is:
void (*layer_update_end) (
disp_adapter_t *adapter,
int dispno,
int layer_idx );
The arguments to layer_update_end are:
Before any calls are made that affect the layer configuration, layer_update_begin() is called, and subsequently layer_update_end() makes the changes effective.
This function runs after adjustments are made to the layer configuration. Any adjustments made since layer_update_begin() was called, will now take effect.
|
The layer_query() function doesn't affect the layer configuration and is therefore an exception to this rule. |
The prototype is:
void (*layer_reset) (
disp_adapter_t *adapter,
int dispno,
int layer_idx );
The arguments to layer_reset are:
This function resets the specified layer to its initial state.
A layer should be reset to its initial state after a modeswitch.
The initial state is defined as one where:
The prototype is:
int (*layer_set_order) (
disp_adapter_t *adapter,
int dispno,
unsigned order[] );
The arguments to layer_set_order are:
The graphics framework calls this function to set the attributes of the hardware cursor. The prototype is:
int (*set_hw_cursor) (
disp_adapter_t *ctx,
int dispno,
uint8_t *fg_bmp,
uint8_t *bg_bmp,
unsigned fg_color,
unsigned bg_color,
int hotspot_x,
int hotspot_y,
int size_x,
int size_y,
int bmp_stride);
|
The hotspot represents the “active” point of the cursor (e.g. the tip of the arrow in case of an arrow cursor, or the center of the crosshairs in case of a crosshair cursor). |
If the cursor can't be displayed properly, this function should return -1, which causes the framework to show a software cursor instead. For example, if size_x or size_y is too big for the hardware to handle, this function should return -1.
The cursor image itself is defined by two bitmaps. The two colors, fg_color and bg_color apply to the two bitmaps fg_bmp and bg_bmp. Both bitmaps have the same width (size_x), height (size_y), and stride (bmp_stride) values.
For a given pixel within the cursor image, a 0 in both bitmap locations means this pixel is transparent. A 1 in fg_bmp means draw the corresponding pixel using the color given by fg_color. A 1 in bg_bmp means draw the corresponding pixel using the color given by bg_color. If there's a 1 in both bitmaps, then bg_color is to be used.
The dispno argument specifies the display index this cursor is associated with.
The graphics framework calls this function to make the cursor visible. The prototype is:
void (*enable_hw_cursor) (
disp_adapter_t *ctx,
int dispno )
The graphics framework calls this function to make the cursor invisible. The prototype is:
void (*disable_hw_cursor) (
disp_adapter_t *ctx,
int dispno )
The graphics framework calls this function to set the position of the hardware cursor for a given display. The prototype is:
void (*set_hw_cursor_pos) (
disp_adapter_t *ctx,
int dispno,
int x,
int y);
Position the cursor such that the hotspot is located at (x, y) in screen coordinates on the display specified by dispno.
The graphics framework calls this function to perform an I2C master-read transaction. The prototype is:
int (*i2c_read) (
disp_adapter_t *ctx,
int busno,
int slaveaddr,
uint8_t *ibuf,
int ibytes );
This function should read ibytes bytes of data from the I2C bus and store it in the buffer pointed to by ibuf. The bus is specified by the index busno, on the IC2 slave device at address slaveaddr.
The graphics framework calls this function to perform an I2C master-write transaction. The prototype is:
int (*i2c_write) (
disp_adapter_t *ctx,
int busno,
int slaveaddr,
uint8_t *obuf,
int obytes );
This function should write obytes bytes from the buffer obuf to the IC2 bus. The bus is specified by the index busno, on the IC2 slave device at address slaveaddr.
The graphics framework calls this function to perform an I2C master write/read transaction. The transaction performed is what the I2C specification refers to as a combined transfer format. This is typically used to write a register or memory subaddress to the device, followed by a read transfer from that register/memory. The prototype is:
int (*i2c_writeread) (
disp_adapter_t *ctx,
int busno,
int slaveaddr,
uint8_t *obuf,
int obytes,
uint8_t *ibuf,
int ibytes );
This function should write obytes bytes from the buffer obuf to the IC2 bus, and then read ibytes from the IC2 bus to the buffer ibuf. The bus is specified by the index busno, on the IC2 slave device at address slaveaddr.
Neutrino
devg_get_modefuncs(), disp_adapter_t, disp_crtc_settings_t, disp_mode_info_t, disp_module_info_t, disp_surface_t