Support for shared memory framebuffers for eHVD elements. This allows a Scalable RIP to share eHVD elements across the entire RIP farm, without needing coordination from a raster manager or central controller. More...

#include "skinkit.h"
#include "skinmon.h"
#include "hqatomic.h"
#include "hqspin.h"
#include "hqmemcpy.h"
#include "rhhashmap.h"
#include "mem.h"
#include "hvdshmfb.h"
#include "hvdcache.h"
#include "hvdutil.h"
#include "monany.h"
#include "monlibhvd.h"

Data Structures
struct	shmfb_element_reader

Typedefs
typedef hq_atomic_counter_t	HVD_shmfb_state

typedef struct shmfb_element_reader	shmfb_element_reader

Enumerations
enum	{ HVD_SHMFB_UNINITIALISED , HVD_SHMFB_DEFINING , HVD_SHMFB_DEFINED , HVD_SHMFB_READY , HVD_SHMFB_ERROR }

Functions
void	shmfb_raster_name (char name[SHMFB_RASTER_NAME_MAX], const uint8 cache_id[256], const uint8 setup_id[256], const uint8 element_id[16], unsigned int index)
	Create a unique name for a shared memory raster. More...

void *	shmfb_create_object (const char name, size_t size, rh_hashmap_t handlemap, HqnResult *perr)
	Create a shared memory object with the size specified. More...

void *	shmfb_open_object (const char name, rh_hashmap_t handlemap)
	Try to open an existing shared memory object with the size specified. More...

void	handlemap_release_key (intptr_t key, void *data)
	Key release function for the shared memory object to shared memory handle map.

void	handlemap_release_value (intptr_t key, void *data)
	Value release function for the shared memory object to shared memory handle map.

void	handlemap_remove_address (rh_hashmap_t handlemap, void addr)
	Function to remove a shared memory object from the handle map, closing the shared memory handle as appropriate.

static __forceinline void	set_raster_state (HVD_shmfb_raster *raster, HVD_shmfb_state state)
	Atomically set a shared memory raster state.

static __forceinline void	wait_for_raster_defined (volatile HVD_shmfb_raster *raster)
	Wait for a raster object to be defined. When shared memory raster objects are created the state is CASed to DEFINING, the header information is stored, and then the state is CASed to DEFINED. We need the state to be at least DEFINED to be able to read the number of separations from the raster description, which is the number of expected rasters.

HVD_cache_fns *	shmfb_HVD_cache_fns (void)

HVD_shmfb_raster *	shmfb_raster_create (const uint8 cache_id[256], const uint8 setup_id[256], const uint8 id[16], unsigned int index, RasterDescription pRD, size_t rasterSize, size_t userSize, HqnResult perr)
	Function to create raster handles for passing to HVD_monitor_add_raster() when using shared memory rasters. More...

uint8 *	shmfb_raster_buffer (HVD_shmfb_raster *raster, size_t start, size_t length)
	Get the data address from a shared memory raster handle. More...

void *	shmfb_raster_userdata (HVD_shmfb_raster *raster)
	Get the user data address from a shared memory raster handle. More...

const RasterDescription *	shmfb_raster_description (void *hraster)
	Function to use as hvd_output_page_params::raster_description_fn when using shared memory elements. More...

void	shmfb_raster_error (HVD_shmfb_raster **ppraster)
	The RIP failed to construct a raster. Mark it with error, and release the raster handle. More...

void	shmfb_raster_release (HVD_element pElement, void hraster)
	Function to use as HVD_raster_release_fn callback when using shared memory elements. More...

HqBool	shmfb_recovery_filter (HVD_element *pElement, HVD_recovery_reason_t reason)
	Function to use as HVD_recovery_filter_fn callback when using shared memory elements. More...

void *	shmfb_acquire (size_t size, uint32 id, void data, HqnResult perr)
	Function to use as frame_acquire_fn when using framebuffer support to manage shared memory rasters. More...

void	shmfb_release (void handle, size_t size, void data)
	Function to use as frame_release_fn when using framebuffer support to manage shared memory rasters. More...

uint8 *	shmfb_raster (void *handle, size_t offset, size_t size)
	Function to use as frame_raster_fn when using framebuffer support to manage shared memory rasters. More...

void *	shmfb_element_raster_open (void hraster, RASTER_PLANE plane, HqnResult *perr)
	Function to use as hvd_output_page_params::element_raster_open when using shared memory elements. More...

const uint8 *	shmfb_element_raster_map (void context, void hraster, unsigned int pstartline, unsigned int pnlines, HqnResult *perr)

void	shmfb_element_raster_close (void context, void hraster)

Variables
intptr_t	handlemap_invalid

Detailed Description

Support for shared memory framebuffers for eHVD elements. This allows a Scalable RIP to share eHVD elements across the entire RIP farm, without needing coordination from a raster manager or central controller.

Typedef Documentation

◆ HVD_shmfb_state

typedef hq_atomic_counter_t HVD_shmfb_state

Type for atomically modifyable shared memory state.

◆ shmfb_element_reader

typedef struct shmfb_element_reader shmfb_element_reader

Data needed for reading shmfb element planes. These assume a contiguous layout in memory for all frames of a sheet. When using the framebuffer support, it checks that all sheets have the same rendered_sheet_size, all frames have the same rendered_size_per_band, the same rendered_frame_size, and all planes have the same linesize.

We can calculate the offset of this plane knowing the frame's omitted index, the plane's omitted index, and the rendered size of frames and planes. We can calculate the band number from the line and band height to calculate the offset of the start of the band from the frame, add the plane offset to get the start of the plane in the band, and use the plane's linesize to find the start of the line in the plane. If there is more than one plane per frame, then we also need to limit the number of lines read to the end of the band to avoid encroaching onto another channel.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Values for atomically modifyable shared memory state.

Enumerator
HVD_SHMFB_UNINITIALISED	Not yet initialised.
HVD_SHMFB_DEFINING	Raster define in progress.
HVD_SHMFB_DEFINED	Raster defined (can read fields)
HVD_SHMFB_READY	Raster is ready to use.
HVD_SHMFB_ERROR	Rendering of raster failed, do not use.

Function Documentation

◆ shmfb_create_object()

void* shmfb_create_object	(	const char *	name,
		size_t	size,
		rh_hashmap_t *	handlemap,
		HqnResult *	perr
	)

Create a shared memory object with the size specified.

Parameters

[in]	name	The name of the shared memory object
[in]	size	The size of the shared memory object
[in,out]	handlemap	A hashmap to store the data pointer to shared memory handle correspondence in.
[out]	perr	A location in which an error code is stored, if the shared memory object could not be created.

Returns: A pointer to the shared memory object, or NULL if it could not be created.

◆ shmfb_open_object()

void* shmfb_open_object	(	const char *	name,
		rh_hashmap_t *	handlemap
	)

Try to open an existing shared memory object with the size specified.

Parameters

[in]	name	The name of the shared memory object
[in,out]	handlemap	A hashmap to store the data pointer to shared memory handle correspondence in.

Returns: A pointer to the shared memory object, or NULL if it did not exist.

◆ shmfb_raster_buffer()

uint8* shmfb_raster_buffer	(	HVD_shmfb_raster *	raster,
		size_t	start,
		size_t	length
	)

Get the data address from a shared memory raster handle.

Parameters

[in]	raster	A raster handle previously created by shmfb_raster_create().
[in]	start	The start offset of the portion of the data to return.
[in]	length	The length of the portion of the data to return.

Returns: The address of a raster buffer holding portions of the raster starting at offset start and extending for length. This buffer cannot extend beyond the number of bytes passed in the rasterSize parameter to shmfb_raster_create().

Only one raster buffer can be active at a time; calling this function will invalidate the pointer returned by a previous call.

◆ shmfb_raster_create()

HVD_shmfb_raster* shmfb_raster_create	(	const uint8	cache_id[256],
		const uint8	setup_id[256],
		const uint8	id[16],
		unsigned int	index,
		RasterDescription *	pRD,
		size_t	rasterSize,
		size_t	userSize,
		HqnResult *	perr
	)

Function to create raster handles for passing to HVD_monitor_add_raster() when using shared memory rasters.

Parameters

[in]	cache_id	The cache ID that the raster is being created for.
[in]	setup_id	The setup ID that the raster is being created for.
[in]	id	The element ID that the raster is attached to.
[in]	index	The index of the raster to create.
[in]	pRD	The raster description the raster is being created for.
[in]	rasterSize	The size of the raster data to allocate for this separation. The address of the raster buffer can be recovered using shmfb_raster_buffer().
[in]	userSize	The size of the user data to allocate for this separation. The address of the user data can be recovered using shmfb_raster_userdata().
[out]	perr	A location in which an error code is stored, if the raster handle could not be acquired or created.

Returns: The shared memory raster handle, or NULL if a raster handle could not be acquired or created.

If the pointer returned is non-NULL, then *perr is not modified. If the pointer returned is NULL, then *perr is set to a code greater than MON_CLASS_ERROR indicating the error that occurred. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

◆ shmfb_raster_error()

void shmfb_raster_error ( HVD_shmfb_raster ** ppraster )

The RIP failed to construct a raster. Mark it with error, and release the raster handle.

Parameters

[in] ppraster A location to find the raster previously created by shmfb_raster_create().

◆ shmfb_raster_name()

void shmfb_raster_name	(	char	name[SHMFB_RASTER_NAME_MAX],
		const uint8	cache_id[256],
		const uint8	setup_id[256],
		const uint8	element_id[16],
		unsigned int	index
	)

Create a unique name for a shared memory raster.

Parameters

[out]	name	The shared memory object name storage.
[in]	cache_id	The ID of the cache the raster will be stored in.
[in]	setup_id	The ID of the setup used to construct this raster. If this is not an empty string, the object may persist for longer than one job.
[in]	element_id	The element ID for this raster.
[in]	index	The raster index for this element. There may be more than one raster attached to each element if writing separations.

On exit, name should contain a zero-terminated string with the name of the shared memory object.

The length of names allowed by different platforms for shared memory objects varies widely. Linux doesn't have an explicit length, but shm_open() suggest that the name start with a slash and be less than 255 characters. Windows does not appear to have a limit, beyond the normal file name length. MacOS, however, is severely constrained, supporting only 31 characters. The interface here allows for up to SHMFB_RASTER_NAME_MAX characters, but the expectation is that the platform implementation will produce a name with a smaller limitation.

◆ shmfb_raster_userdata()

void* shmfb_raster_userdata ( HVD_shmfb_raster * raster )

Get the user data address from a shared memory raster handle.

Parameters

[in] raster A raster handle previously created by shmfb_raster_create().

Returns: The address of the user data. This buffer can store the number of bytes passed in the userSize parameter to shmfb_raster_create().

Variable Documentation

◆ handlemap_invalid

intptr_t handlemap_invalid

extern

Invalid value for handle map.

Invalid value for handle map. CreateFileMapping() returns NULL on failure.

Data Structures

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ HVD_shmfb_state

◆ shmfb_element_reader

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ shmfb_create_object()

◆ shmfb_open_object()

◆ shmfb_raster_buffer()

◆ shmfb_raster_create()

◆ shmfb_raster_error()

◆ shmfb_raster_name()

◆ shmfb_raster_userdata()

Variable Documentation

◆ handlemap_invalid