h6. [[GraphicsV]] h6(. » GraphicsV 19 h2. Graphics Vector (42) |_<^{width:3em}. Entry |<^. | |<^. R0|<^. Pointer to [[VIDC List Type 3]] | |<^. R1|<^. Flags (reserved; specify 0) | |/3<^. R4|<^. Bits 0-15: 19 (reason code)| |<^. Bits 16-23: Head number| |<^. Bits 24-31: Driver number| |_<^{width:3em}. Exit |<^. | |/8<^. R0|<^. Result flags: | |<^. Bits 0-1: | |<^. 0 -> Provided mode is unsupported | |<^. 1 -> Mode is supported, and will use the system framestore (i.e. kernel-managed DA 2) | |<^. 2 -> Mode is supported, and will use the external framestore (as defined by R3 & R5) | |<^. 3 -> Mode is supported, but driver doesn't know where the framestore will be (e.g. framestore is managed by another component, like the GPU firmware in the Raspberry Pi) | |<^. Bit 2: The input value of the ExtraBytes control list item was invalid, driver has suggested a new value in R2 | |<^. Bits 3+: Reserved | |<^. R1|<^. Required alignment of start of framebuffer | |<^. R2|<^. Required/suggested ExtraBytes value | |<^. R3|<^. External framebuffer base (iff bits 0-1 of R0 are 2) | |<^. R4|<^. 0| |<^. R5|<^. External framebuffer size (iff bits 0-1 of R0 are 2) | |- |<^. All other registers preserved | h4. Use This is an enhanced version of the [[GraphicsV 7]] call, designed to allow the driver to provide additional feedback to the OS, mainly focusing on describing the framebuffer memory requirements for the mode. h5. Implementation within drivers New drivers are expected to support both GraphicsV 19 and the older [[GraphicsV 7]] call, and any mode that passes GraphicsV 19 vetting must also pass GraphicsV 7 vetting. Since GraphicsV 19 provides a superset of the functionality of GraphicsV 7, the recommended procedure for vetting a mode is that code should call GraphicsV 19 first, and only fall back to GraphicsV 7 if the call wasn't recognised by the driver (R4 nonzero) or if an unhandled result is returned (e.g. R0 has unrecognised flag bits set). Drivers should handle this call as follows: * They should perform a mode vet procedure, as per [[GraphicsV 7]]. However, instead of being restricted to the value of the ExtraBytes [[VIDC control list|control list item]] that is specified in the input, the driver is free to use an ExtraBytes value of its own choosing, subject to the rules described below. * When preparing the result registers, bits 0-1 of R0 should be set to the appropriate value depending on whether the mode is supported, and the type/location of framestore that will be used. * If the mode is supported (bits 0-1 non-zero): ** R1 must specify the required alignment of the framebuffer (as per [[GraphicsV 8]]) ** R2 must specify a valid ExtraBytes value. ** If the mode couldn't be supported using the input ExtraBytes value, bit 2 of R0 must be set to indicate that the new value in R2 should be used instead. ** If the mode is to use an external framestore (bits 0-1 of R0 are 2), R3 and R5 must describe that framestore, as per [[GraphicsV 9]]. * The driver must indicate that the call has been claimed by setting R4 to zero Of course, if a caller does not care about the new functionality introduced by GraphicsV 19, and cannot support modifications to the ExtraBytes item, there is no harm in only using GraphicsV 7. h5. Rules for selecting an ExtraBytes value Typically, the ExtraBytes value returned in R2 will just be the same value that was provided in the input VIDC list (or the default of 0 if the item was absent). However, if using the input ExtraBytes value would mean that the mode can't be supported, the driver can return a different ExtraBytes value in R2 and set bit 2 of R0 to indicate this condition. Note that the returned ExtraBytes value must be greater than the input value; if a smaller value is required, then the driver must fail the entire vet call by setting bits 0-1 of R0 to zero. There's also a third option available: The driver can return a new ExtraBytes value in R2, but leave bit 2 of R0 clear. This allows the driver to hint that a different ExtraBytes value to what was provided in the input may provide better performance. In this case, it's valid for the driver to return an ExtraBytes value that was smaller than the input value. If the ExtraBytes value can affect the choice of framestore location, then the driver should return its result as follows: * If bit 2 of R0 is clear, the framestore information returned in R1, R3 & R5 must reflect the framestore that would be used if the input ExtraBytes value is used * If bit 2 of R0 is set, the framestore information returned in R1, R3 & R5 must reflect the framestore that would be used if the output ExtraBytes value is used Drivers that support GraphicsV 19 must support vetting of the ExtraBytes control list item (so it must be in the list of supported items returned by [[GraphicsV 18]]). h4. Notes For future-proofing, the driver must ensure it checks that the provided VIDC list is a type 3 list. The input flags that are provided in R1 are reserved for future expansion. They are intended to be used to signal that the caller supports extended return results from the driver (e.g. to signal that additional registers may be used to return results). Therefore, drivers should simply ignore any flag bits in R1 which they don't recognise. Instead of calling GraphicsV directly, user software should use [[OS_CheckModeValid]] in order to check if a screen mode is valid. h4. See also * [[GraphicsV]] * [[GraphicsV 7]] * [[OS_CheckModeValid]]