Run Time Information (RTI) ########################## .. WARNING:: This section was written while trying to understand how the RTI is organized. It almost certainly contains errors, and it likely won't be updated with the codebase, so don't belive any of the information here. Nevertheless, it may be helpful for a developer new to GHDL trying to understand the organization of the RTI. Useful Definitions ================== RTI Run Time Information. The information that is used when simulating the design. RTIN Run Time Information Node. The design is organized into a directed graph where the architectures, signals and statements are represented as nodes on the graph. This graph can be cyclic since an architecture may be instantiated many times, and could be recursively instantiated. Context The context of a node is the position in the elaborated design. For example a architecture might be instantiated 4 times in a design, but will have a single RTI node. The data related to that node but specfic to particular instantiation has an address in memory. A context object (`Rti_Context`) bundles an RTI node with an address for it's instantiation data. If this RTI node references another RTI node we can find the relevant instantiation data for that node by considering the context. RTII Run Time Instance Information. This is a record that groups an RTI node with any other data necessary to specify a particular instantiation. The RTII objects create a tree that represents the elaborated design. Currently they are only implemented for RTIN nodes of signals, ports, generics, constants and their subcomponents. RTI Nodes / RTII Nodes ====================== All RTI node records have a `Ghdl_Rtin_Common` record as their first element. This record contains the following elements: Kind \: Ghdl_Rtik This specified what kind of node it is. For example a `process` and an `entity` node are both represented by `Ghdl_Rtin_Block` records but they are distinguished by having a different Kind. Depth \: Ghdl_Rti_Depth The depth indicates the relationship between the RTI Node and the RTI Context. Child nodes often just use the same Context as their parent, and the depth indicates how far up in the hierarchy you go to find where the Context is based. Mode \: Ghdl_Rti_U8 ?? Max_Depth \: Ghdl_Rti_Depth ?? It's also useful to look at some of the other elements that commonly appear in the different RTI Node records. Loc \: Ghdl_Rti_Loc This is an address offset. It tells us where the instantiation data for this node is located relative to the data of it's parent. Linecol \: Ghdl_Index_Type Refers back to a location in the source code. Parent \: Ghdl_Rti_Access Points to the parent. This isn't necessarily the parent in the RTI tree though. For example the `Parent` of an architecture RTI node points at the entity node, however the parent in the tree is the instance RTI. This document will now review that main classes of RTI Nodes. Architecture RTI (Ghdl_Rtin_Block) ----------------------------------- The architecture acts as a simple container for it's children. Create the child tree nodes by looping through `Ghdl_Rti_Block.Children` and keeping the context unchanged. The information about the generics and ports access the entity RTI nodes through `Ghdl_Rti_Block.Parent` using the same context. The instantiation data of an architecture contains a single item, a pointer to the RTI node. This is necessary because it is necessary to store which of the possible architectures of this entity was instantiated. Entity RTI (Ghdl_Rtin_Block) ---------------------------- The RTI of an entity is a `Ghdl_Rti_Block` record (the same as the architecture) and uses the same context as the architecture. It is accessed via the architecture's `Parent` element. The generics and ports can be accessed as the children of the entity. Other Blocks (Package/Process) (Ghdl_Rtin_Block) ------------------------------------------------ The block just loops over it's children. if_generate / case_generate (Ghdl_Rtin_Block) --------------------------------------------- If-Generate and Case-Generate statements are represented with `Ghdl_Rtin_Block` records with Kind `Ghdl_Rtik_If_Generate` and `Ghdl_Rtik_Case_Generate`. Their children are all of Kind `Ghdl_Rtik_Body`, and represent the different possible blocks that could be selected. The instantiation data of a if_generate or case_generate RTI contains two items: 1) A pointer to the context of the selected generate body (instance_pointer). 2) The index of the selected child (block_id) The child node is then created from the RTI node `Ghdl_Rtik_Body.Children(block_id)` combined with the instantiation data given by `instance_pointer`. for_generate (Ghdl_Rtin_Generate) --------------------------------- For-Generate statements are represented with `Ghdl_Rtin_Generate` records with Kind `Ghdl_Rtik_For_Generate`. Their RTI-node structure is different from the `Ghdl_Rtin_Block` record in that rather than having `Nbr_Child` and `Children` elements, it has: Child \: Ghdl_Rti_Access A pointer to the generate body node that is their only child. Size \: Ghdl_Index_Type The amount of memory requrired for the context of their child. The Child element is a generate body. There is only a single RTI-node structure which Child points to, however a different context is used each time we go around the for-generate loop. The context of a for_generate RTI contains a single item: An address which points at the contexts for it's children. Each time we go around the for generate loop we increment the address of the context by `Size` so we looking at the correct context for that instantiation of the contexts of the loop. One complexity of the for-generate is finding the number of times that we go around the loop. The first element in the child generate body is an iterator. That iterator has a type and we can get the bounds of that type by passing it the local context. The type of the iterator for the for-generate loop is implicitly created and placed directly before the for_generate block, so using the local context will work. There might be a bug if the for-generate loop uses a type that wasn't defined implicitly. instance (Ghdl_Rtin_Instance) ----------------------------- An instantiation of an entity is represented by a `Ghdl_Rtin_Instance` node with Kind `Ghdl_Rtik_Instance`. The context contains a single item, which is a pointer to the context of the architecture. The architecture context also contains a single item, which is a pointer to the architecture RTI Node. Port (Ghdl_Rtin_Object) ----------------------- Array Kinds ----------- Ghdl_Rtik_Type_Array A VHDL array where the range is not specified. Ghdl_Rtik_Subtype_Array A VHDL array where the range is specified. A Type_Array together with the bounds. Object_To_Base_Bound -------------------- This function takes an object type and an object's static context location and returns the complex context location and the bounds. When the object is static 
/*
 * This file is subject to the terms of the GFX License. If a copy of
 * the license was not distributed with this file, you can obtain one at:
 *
 *              http://ugfx.org/license.html
 */

/**
 * @file    include/ginput/keyboard.h
 * @brief   GINPUT GFX User Input subsystem header file.
 *
 * @defgroup Keyboard Keyboard
 * @ingroup GINPUT
 * @{
 */

#ifndef _GINPUT_KEYBOARD_H
#define _GINPUT_KEYBOARD_H

#if GINPUT_NEED_KEYBOARD || defined(__DOXYGEN__)

/*===========================================================================*/
/* Type definitions                                                          */
/*===========================================================================*/

#define GINPUT_KEYBOARD_NUM_PORTS		1			// The total number of keyboard inputs

// Event types for various ginput sources
#define GEVENT_KEYBOARD		(GEVENT_GINPUT_FIRST+2)

typedef struct GEventKeyboard_t {
	GEventType		type;				// The type of this event (GEVENT_KEYBOARD)
	uint16_t		instance;			// The keyboard instance
	char			c;					// The Ascii code for the current key press.
										//		The only possible values are 0(NUL), 8(BS), 9(TAB), 13(CR), 27(ESC), 32(SPACE) to 126(~), 127(DEL)
										//		0 indicates an extended only key.
	uint16_t		code;				// An extended keyboard code. Codes less than 128 match their ascii equivelent.
		#define GKEY_NULL		0
		#define GKEY_BACKSPACE	8
		#define GKEY_TAB		9
		#define GKEY_CR			13
		#define GKEY_ESC		27
		#define GKEY_SPACE		32
		#define GKEY_DEL		127
		#define GKEY_UP			0x0101
		#define GKEY_DOWN		0x0102
		#define GKEY_LEFT		0x0103
		#define GKEY_RIGHT		0x0104
		#define GKEY_HOME		0x0105
		#define GKEY_END		0x0106
		#define GKEY_PAGEUP		0x0107
		#define GKEY_PAGEDOWN	0x0108
		#define GKEY_INSERT		0x0109
		#define GKEY_DELETE		0x010A
		#define GKEY_SHIFT		0x0201
		#define GKEY_CNTRL		0x0202
		#define GKEY_ALT		0x0203
		#define GKEY_WINKEY		0x0204
		#define GKEY_RCLKEY		0x0205
		#define GKEY_FNKEY		0x0206
		#define GKEY_FN1		0x0301
		#define GKEY_FN2		0x0302
		#define GKEY_FN3		0x0303
		#define GKEY_FN4		0x0304
		#define GKEY_FN5		0x0305
		#define GKEY_FN6		0x0306
		#define GKEY_FN7		0x0307
		#define GKEY_FN8		0x0308
		#define GKEY_FN9		0x0309
		#define GKEY_FN10		0x030A
		#define GKEY_FN11		0x030B
		#define GKEY_FN12		0x030C
	uint16_t		current_buttons;		// A bit is set to indicate various meta status.
		#define GMETA_KEY_DOWN			0x0001
		#define GMETA_KEY_SHIFT			0x0002
		#define GMETA_KEY_CNTRL			0x0004
		#define GMETA_KEY_ALT			0x0008
		#define GMETA_KEY_WINKEY		0x0010
		#define GMETA_KEY_RCLKKEY		0x0020
		#define GMETA_KEY_FN			0x0040
		#define GMETA_KEY_MISSED_EVENT	0x8000
	uint16_t		last_buttons;			// The value of current_buttons on the last event
} GEventKeyboard;

// Keyboard Listen Flags - passed to geventAddSourceToListener()
#define GLISTEN_KEYREPEATS		0x0001			// Return key repeats (where the key is held down to get a repeat character)
#define GLISTEN_KEYCODES		0x0002			// Return all key presses including extended code key presses (not just ascii codes)
#define GLISTEN_KEYALL			0x0004			// Return keyup's, keydown's and everything in between (but not repeats unless GLISTEN_KEYREPEATS is set).
#define GLISTEN_KEYSINGLE		0x8000			// Return only when one particular extended code key is pressed or released. The particular extended code is OR'd into this value
												//		eg. (GLISTEN_KEYSINGLE | GKEY_CR)
												//		No other flags may be set with this flag.

/*===========================================================================*/
/* External declarations.                                                    */
/*===========================================================================*/

#ifdef __cplusplus
extern "C" {
#endif

	/**
	 * @brief	Create a keyboard input instance
	 *
	 * @param[in] instance	The ID of the keyboard input instance (from 0 to 9999)
	 *
	 * @return	The source handle of the created input instance
	 */
	GSourceHandle ginputGetKeyboard(uint16_t instance);
	
	/**
	 * @brief	Get the current keyboard status
	 *
	 * @param[in] instance	The ID of the keyboard input instance
	 * @param[in] pkeyboard	The keyboard event struct
	 *
	 * @return Returns FALSE on an error (eg invalid instance)
	 */
	bool_t ginputGetKeyboardStatus(uint16_t instance, GEventKeyboard *pkeyboard);

#ifdef __cplusplus
}
#endif

#endif /* GINPUT_NEED_KEYBOARD */

#endif /* _GINPUT_KEYBOARD_H */
/** @} */
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-28 04:28:28 +0000