Setting timing parameters

Timing is mandatory component of a mode.

The timing parameters are related to the horizontal and vertical blanking intervals. These intervals refer to a part of the process of displaying images on a computer monitor or television screen via raster scanning.

The horizontal blanking interval occurs once per line of image information and is composed of: a horizontal sync pulse, a front porch, and a back porch.

The vertical blanking interval is the time betweeen the end of an active image and the start of the next; it is composed of: a vertical sync pulse, a front porch, and a back porch.

Timing parameters

You'll define the timing parameters based on your display hardware using the wfdcfg_timing structure in Wfdcfg. You'll need the following timing parameters to be set:

pixel_clock_kHz: The frequency (in kHz) that pixels are transmitted at. The clock remains active throughout the entire horizontal and vertical blanking intervals, even when pixels are not being transmitted.
hpixels: The width (in pixels) of the display. Together with vlines, hpixels indicates the resolution of the display.
vlines: The height (in lines) of the display. Together with hpixels, vlines indicates the resolution of the display.
hsw: The width of the horizontal synchronization pulse. This width refers to the amount of time that the horizontal sync pulse is active. The horizontal sync pulse is transmitted at the beginning of each video scanline. Its purpose is to keep start of the horizontal video scanline in the display in sync with the video source that created it. That is, when the scanline reaches the right side of your display, the horizontal sync pulses indicates that it is time to return and start the next scanline at the left side of the display again. The width of this horizontal synchronization pulse is measured in pixels.
vsw: The vertical synchronization pulse width. This width refers to the amount of time that the vertical sync pulse is active. The vertical sync pulse is transmitted at the beginning of each field and frame. Its purpose is to ensure that the display scan starts at the top of the picture at the right time. That is, when the last scanline on the bottom of the display has been reached, the display must return and start the next scanline back at the top of the screen for the next vertical cycle. The width of this vertical synchronization pulse is measured in lines.
hfp: The horizontal front porch is the amount of time between the end of the horizontal active time and the start of the horizontal synchronization pulse. This time allows for the image to settle and to prevent the image from interfering with sync extraction. The horizontal front porch is measured in pixels.
vfp: The vertical front porch is the amount of time between the end of the vertical active time and the start of the vertical synchronization pulse. The vertical front porch is measured in lines.
hbp: The horizontal back porch is the amount of time between the end of the horizontal sync pulse and the start of the next horizontal active time. The horizontal back porch is measured in pixels.
vbp: The vertical back porch is the amount of time between the end of the vertical sync pulse and the start of the next vertical active time. The vertical back porch is measured in lines.
flags: A bitmask of wfdcfg_flags. You can use this field to configure settings that are supported by your display driver. Appropriate settings for this flag are likely based on your display and/or bridge specifications.

Setting timing parameters

The timing parameters that Wfdcfg requires are available in, or can be derived from, the product specfication of your display hardware. Below is a table of typical timings based on display resolutions and refresh rates:

Display	`pixel_clock_kHz`	`hpixels`	`vlines`	`hsw`	`vsw`	`hfp`	`vfp`	`hbp`	`vbp`
800x400 @ 60 Hz	`29760`	`800`	`400`	`72`	`10`	`24`	`3`	`96`	`7`
1024x768 @ 60 Hz (CVT)	`63500`	`1024`	`768`	`104`	`4`	`48`	`3`	`152`	`23`
1280x1024 @ 60 Hz (CVT)	`109000`	`1280`	`1024`	`128`	`7`	`88`	`3`	`216`	`29`
1080p @ 60 Hz (1920x1080)	`148500`	`1920`	`1080`	`44`	`5`	`88`	`4`	`148`	`36`
720p @ 60 Hz (1280x720)	`74250`	`1280`	`720`	`40`	`5`	`110`	`5`	`220`	`20`

You'll need to configure these timing parameters, based on your product specification, in your Wfdcfg source (wfdcfg.c) within a mode structure. The mode may also include extensions, but the timing is the most important part. It's possible that in the following circumstances, you may have multiple entries in your mode array:

when you have more than one physical display connected
when your display supports multiple modes
when you're switching between displays, but only have one connected at a time

For example,


struct mode {
	const struct wfdcfg_timing timing;
	const struct wfdcfg_keyval *ext_list;
};

static const struct mode sample_timings[] = {
	{
		// 800x480 @ 60 Hz
		.timing = {
			.pixel_clock_kHz =  29760,
			.hpixels =  800, .hfp= 24, .hsw= 72, .hbp= 96,  //  992 total
			.vlines  =  480, .vfp=  3, .vsw= 10, .vbp=  7,  //  500 total
			.flags = WFDCFG_INVERT_HSYNC,
		},
		.ext_list = (const struct wfdcfg_keyval[]){
			{ "ext_1_example", .i = 1 },
			{ "ext_2_example", .i = 2 },
			{ NULL }  // marks end of list
		},
	},
	{
		// 1024x768 @ 60 Hz (CVT)
		.timing = {
			.pixel_clock_kHz =  63500,
			.hpixels = 1024, .hfp= 48, .hsw=104, .hbp=152,  // 1328 total
			.vlines  =  768, .vfp=  3, .vsw=  4, .vbp= 23,  //  798 total
			.flags = WFDCFG_INVERT_VSYNC,
		},
		.ext_list = NULL,
	},
	{
		// 1280x1024 @ 60 Hz (CVT)
		.timing = {
			.pixel_clock_kHz = 109000,
			.hpixels = 1280, .hfp= 88, .hsw=128, .hbp=216,  // 1712 total
			.vlines  = 1024, .vfp=  3, .vsw=  7, .vbp= 29,  // 1063 total
			.flags = WFDCFG_INVERT_VSYNC,
		},
		.ext_list = NULL,
	},
	{
		// 1080p @ 60 Hz (1920x1080)
		.timing = {
			.pixel_clock_kHz = 148500,
			.hpixels = 1920, .hfp= 88, .hsw= 44, .hbp=148,  // 2200 total
			.vlines  = 1080, .vfp=  4, .vsw=  5, .vbp= 36,  // 1125 total
			.flags = 0,
		},
		.ext_list = NULL,
	},
	{
		// 720p @ 60 Hz (1280x720)
		.timing = {
			.pixel_clock_kHz =  74250,
			.hpixels = 1280, .hfp=110, .hsw= 40, .hbp=220,  // 1650 total
			.vlines  =  720, .vfp=  5, .vsw=  5, .vbp= 20,  //  750 total
			.flags = 0,
		},
		.ext_list = NULL,
	},
	{
		// marks end of list
		.timing = {.pixel_clock_kHz = 0},
	},
};