/alps/pcitool

#ifndef _PCILIB_BANK_H

#define _PCILIB_BANK_H

#include <pcilib.h>

#define PCILIB_REGISTER_BANK_INVALID		((pcilib_register_bank_t)-1)

#define PCILIB_REGISTER_BANK0 			0					/**< First BANK to be used in the event engine */

#define PCILIB_REGISTER_BANK1 			1

#define PCILIB_REGISTER_BANK2 			2

#define PCILIB_REGISTER_BANK3 			3

#define PCILIB_REGISTER_BANK_CONF		64					/**< Configuration registers */

#define PCILIB_REGISTER_BANK_PROPERTY           65                                      /**< Registers abstracting properties and other computed registers */

#define PCILIB_REGISTER_BANK_DMACONF		96					/**< DMA configuration in the software registers */

#define PCILIB_REGISTER_BANK_DMA		97					/**< First BANK address to be used by DMA engines */

#define PCILIB_REGISTER_BANK_DMA0		PCILIB_REGISTER_BANK_DMA		/**< First BANK address to be used by DMA engines */

#define PCILIB_REGISTER_BANK_DMA1		(PCILIB_REGISTER_BANK_DMA + 1)		/**< Second BANK address to be used by DMA engines */

#define PCILIB_REGISTER_BANK_DMA2		(PCILIB_REGISTER_BANK_DMA + 2)		/**< Third BANK address to be used by DMA engines */

#define PCILIB_REGISTER_BANK_DMA3		(PCILIB_REGISTER_BANK_DMA + 3)		/**< Fourth BANK address to be used by DMA engines */

#define PCILIB_REGISTER_BANK_DYNAMIC		128					/**< First BANK address to map dynamic XML configuration */

#define PCILIB_REGISTER_PROTOCOL_INVALID	((pcilib_register_protocol_t)-1)

#define PCILIB_REGISTER_PROTOCOL0		0					/**< First PROTOCOL address to be used in the event engine */

#define PCILIB_REGISTER_PROTOCOL_DEFAULT	64					/**< Default memmap based protocol */

#define PCILIB_REGISTER_PROTOCOL_SOFTWARE	65					/**< Software registers */

#define PCILIB_REGISTER_PROTOCOL_PROPERTY       66                                      /**< Protocol to access registers interfacing properties */

#define PCILIB_REGISTER_PROTOCOL_DMA		96					/**< First PROTOCOL address to be used by DMA engines */

#define PCILIB_REGISTER_PROTOCOL_DYNAMIC	128					/**< First PROTOCOL address to be used by plugins */

typedef uint8_t pcilib_register_bank_t;						/**< Type holding the bank position within the field listing register banks in the model */

typedef uint8_t pcilib_register_bank_addr_t;					/**< Type holding the bank address number */

typedef uint8_t pcilib_register_protocol_t;					/**< Type holding the protocol position within the field listing register protocols in the model */

typedef uint8_t pcilib_register_protocol_addr_t;				/**< Type holding the protocol address */

typedef struct pcilib_register_bank_context_s pcilib_register_bank_context_t;

typedef enum {

    PCILIB_MODEL_MODIFICATON_FLAGS_DEFAULT = 0,

    PCILIB_MODEL_MODIFICATION_FLAG_OVERRIDE = 1,				/**< Instructs to override the existing registers/banks/etc... */

    PCILIB_MODEL_MODIFICATION_FLAG_SKIP_EXISTING = 2				/**< If flag is set, pcilib will just skip existing registers/banks/etc instead of reporting a error */

} pcilib_model_modification_flags_t;

typedef enum {

    PCILIB_ADDRESS_RESOLUTION_FLAGS_DEFAULT = 0,

    PCILIB_ADDRESS_RESOLUTION_FLAG_BUS_ADDRESS = 1,				/**< Resolve bus address instead of VA */

    PCILIB_ADDRESS_RESOLUTION_FLAG_PHYS_ADDRESS = 2,				/**< Resolve hardware address instead of VA */

    PCILIB_ADDRESS_RESOLUTION_MASK_ADDRESS_TYPE = 3,

    PCILIB_ADDRESS_RESOLUTION_FLAG_READ_ONLY = 4,				/**< Request read-only memory, in case if read-write resolution is impossible */

    PCILIB_ADDRESS_RESOLUTION_FLAG_WRITE_ONLY = 8,				/**< Request write-only resolution, in case if read-write resolution is impossible */

    PCILIB_ADDRESS_RESOLUTION_MASK_ACCESS_MODE = 12

} pcilib_address_resolution_flags_t;

typedef struct {

    pcilib_version_t version;

    pcilib_register_bank_context_t *(*init)(pcilib_t *ctx, pcilib_register_bank_t bank, const char *model, const void *args);			/**< Optional API call to initialize bank context */

    void (*free)(pcilib_t *pcilib, pcilib_register_bank_context_t *ctx);									/**< Optional API call to cleanup bank context */

    uintptr_t (*resolve)(pcilib_t *pcilib, pcilib_register_bank_context_t *ctx, pcilib_address_resolution_flags_t flags, pcilib_register_addr_t addr); /**< Resolves register virtual address (if supported) */

    int (*read)(pcilib_t *pcilib, pcilib_register_bank_context_t *ctx, pcilib_register_addr_t addr, pcilib_register_value_t *value);		/**< Read from register, mandatory for RO/RW registers */

    int (*write)(pcilib_t *pcilib, pcilib_register_bank_context_t *ctx, pcilib_register_addr_t addr, pcilib_register_value_t value);		/**< Write to register, mandatory for WO/RW registers */

} pcilib_register_protocol_api_description_t;

typedef struct {

    pcilib_register_protocol_addr_t addr;					/**< Protocol address used in model for addressing the described protocol */

    const pcilib_register_protocol_api_description_t *api;			/**< Defines all API functions for protocol */

    const char *model;								/**< If NULL, the actually used model is used instead */

    const void *args;								/**< Custom protocol-specific arguments. The actual structure may depend on the specified model */

    const char *name;								/**< Short protocol name */

    const char *description;							/**< A bit longer protocol description */

} pcilib_register_protocol_description_t;

typedef struct {

    pcilib_register_bank_addr_t addr;						/**< Bank address used in model for addressing the described register bank */

    pcilib_register_protocol_addr_t protocol;					/**< Defines a protocol to access registers */

    pcilib_bar_t bar;								/**< Specifies the PCI BAR through which an access to the registers is provided (autodetcted if PCILIB_BAR_DETECT is specified) */

    uintptr_t read_addr;							/**< protocol specific (normally offset in the BAR of the first address used to read registers) */

    uintptr_t write_addr;							/**< protocol specific (normally offset in the BAR of the first address used to write registers) */

    uint8_t access;								/**< Default register size in bits (or word-size in plain addressing mode) */

    size_t size;								/**< The size of the bank in bytes (i.e. number of registers in plain addressing mode multiplied by access; this does not limit number of register names since indefinite number of names can be provided if bit-fields/views are used) */

    pcilib_endianess_t raw_endianess;						/**< Specifies endianess in the plain-addressing mode, PCILIB_HOST_ENDIAN have to be specified if no conversion desired. 

										Conversion applied after protocol. This value does not get into the account in register-access mode */

    pcilib_endianess_t endianess;						/**< Specifies endianess in the register-access mode, this may differ from raw_endianess if multi-word registers are used. 

										This is fully independent from raw_endianess. No double conversion is either performed */

    const char *format;								/**< printf format for the registers, either %lu for decimal output or 0x%lx for hexdecimal */

    const char *name;								/**< short bank name */

    const char *description;							/**< longer bank description */

} pcilib_register_bank_description_t;

/**

  * Default mappings: defines virtual address to register mappings, i.e. how 0x9000 in the following command 

  * will be mapped to the actual register. By comparing with start and end-addresses, we find to which range 

  * 0x9000 belongs to and detect actual bank and offset in it.

  * Simple example: pci -r 0x9000

  * if we specify range { 0x9000, 0x9100, 10, -0x9000}, the example command we print the value of the first

  * register in the bank 10.

  */

typedef struct {

    uintptr_t start;								/**< The first virtual address of the register range */

    uintptr_t end;								/**< The last virtual address of the register range */

    pcilib_register_bank_addr_t bank;						/**< The bank mapped to the specified range */

    long addr_shift;								/**< Address shift, i.e. how much we should add/substract to the virtual address to get address in the register bank */

} pcilib_register_range_t;

struct pcilib_register_bank_context_s {

    const pcilib_register_bank_description_t *bank;				/**< Corresponding bank description */

    const pcilib_register_protocol_api_description_t *api;			/**< API functions */

    pcilib_xml_node_t *xml;							/**< Additional XML properties */

};

#ifdef __cplusplus

extern "C" {

#endif

/**

 * Initalizes context of register banks. This is an internal function and will

 * be called automatically when new register banks are added. On error no new

 * banks are initalized 

 * @param[in,out] ctx - pcilib context

 * @return - error or 0 on success

 */

int pcilib_init_register_banks(pcilib_t *ctx);

/**

 * Destroys contexts of register banks. This is an internal function and will

 * be called during clean-up. 

 * @param[in,out] ctx - pcilib context

 * @param[in] start - specifies first bank to clean (used to clean only part of the banks to keep the defined state if pcilib_init_register_banks has failed)

 */

void pcilib_free_register_banks(pcilib_t *ctx, pcilib_register_bank_t start);

/**

 * Use this function to add new register banks into the model or override configuration

 * of the existing banks. The function will copy the context of banks structure, but name, 

 * description, and other strings in the structure are considered to have static duration 

 * and will not be copied. On error no new banks are initalized.

 * @param[in,out] ctx - pcilib context

 * @param[in] flags - instructs if existing banks should be reported as error (default), overriden or ignored

 * @param[in] n - number of banks to initialize. It is OK to pass 0 if banks variable is NULL terminated (last member of banks array have all members set to 0)

 * @param[in] banks - bank descriptions

 * @param[out] ids - if specified will contain the ids of the newly registered and overriden banks

 * @return - error or 0 on success

 */

int pcilib_add_register_banks(pcilib_t *ctx, pcilib_model_modification_flags_t flags, size_t n, const pcilib_register_bank_description_t *banks, pcilib_register_bank_t *ids);

/**

 * Use this function to add new register protocols into the model. It is error to re-register

 * already registered protocols. The function will copy the context of banks structure, but name, 

 * description, and other strings in the structure are considered to have static duration 

 * and will not be copied. On error no new protocols are initalized.

 * @param[in,out] ctx - pcilib context

 * @param[in] flags - not used

 * @param[in] n - number of protocols to initialize. It is OK to pass 0 if protocols variable is NULL terminated (last member of protocols array have all members set to 0)

 * @param[in] protocols - protocol descriptions

 * @param[out] ids - if specified will contain the ids of the newly registered protocols

 * @return - error or 0 on success

 */

int pcilib_add_register_protocols(pcilib_t *ctx, pcilib_model_modification_flags_t flags, size_t n, const pcilib_register_protocol_description_t *protocols, pcilib_register_protocol_t *ids);

/**

 * Use this function to add new register ranges into the model. It is error register

 * overlapping registered ranges. On error no new ranges are initalized.

 * @param[in,out] ctx - pcilib context

 * @param[in] flags - not used

 * @param[in] n - number of protocols to initialize. It is OK to pass 0 if protocols variable is NULL terminated.

 * @param[in] ranges - range descriptions

 * @return - error or 0 on success

 */

int pcilib_add_register_ranges(pcilib_t *ctx, pcilib_model_modification_flags_t flags, size_t n, const pcilib_register_range_t *ranges);

/**

 * Find the register bank id (offset in \a banks array) corresponding to the specified bank address 

 * @param[in,out] ctx	- pcilib context

 * @param[in] bank	- the address of register bank

 * @return 		- bank id or PCILIB_REGISTER_BANK_INVALID if bank is not found

 */

pcilib_register_bank_t pcilib_find_register_bank_by_addr(pcilib_t *ctx, pcilib_register_bank_addr_t bank);

/**

 * Find the register bank id (offset in \a banks array) corresponding to the specified bank name

 * @param[in,out] ctx	- pcilib context

 * @param[in] bankname	- the name of register bank

 * @return 		- bank id or PCILIB_REGISTER_BANK_INVALID if bank is not found

 */

pcilib_register_bank_t pcilib_find_register_bank_by_name(pcilib_t *ctx, const char *bankname);

/**

 * Find the register bank id (offset in \a banks array) corresponding to the specified bank name or address

 * @param[in,out] ctx	- pcilib context

 * @param[in] bank	- either the name or the address of the required register bank

 * @return 		- bank id or PCILIB_REGISTER_BANK_INVALID if bank is not found

 */

pcilib_register_bank_t pcilib_find_register_bank(pcilib_t *ctx, const char *bank);

/**

 * Find the register protocol id (offset in \a protocols array) corresponding to the specified protocol address 

 * @param[in,out] ctx	- pcilib context

 * @param[in] protocol	- the address of register protocol

 * @return 		- protocol id or PCILIB_REGISTER_PROTOCOL_INVALID if register protocol is not found

 */

pcilib_register_protocol_t pcilib_find_register_protocol_by_addr(pcilib_t *ctx, pcilib_register_protocol_addr_t protocol);

/**

 * Find the register protocol id (offset in \a protocols array) corresponding to the specified protocol name

 * @param[in,out] ctx	- pcilib context

 * @param[in] name	- the name of register protocol

 * @return 		- protocol id or PCILIB_REGISTER_PROTOCOL_INVALID if register protocol is not found

 */

pcilib_register_protocol_t pcilib_find_register_protocol_by_name(pcilib_t *ctx, const char *name);

/**

 * Find the register protocol id (offset in \a protocols array) corresponding to the specified protocol name or address

 * @param[in,out] ctx	- pcilib context

 * @param[in] name	- either the name or the address of the required register protocol

 * @return 		- protocol id or PCILIB_REGISTER_PROTOCOL_INVALID if register protocol is not found

 */

pcilib_register_protocol_t pcilib_find_register_protocol(pcilib_t *ctx, const char *name);

/**

 * Resolves the address of the specified register bank. The address of the register0 in the bank is returned.

 *

 * All address types (virtual address in process address space, physical address, or bus address) can be resolved.

 * The caller has also to specify the requested access mode (read, write, read/write) and the error will be returned

 * if the requested access type is not possible.

 *

 * @param[in,out] ctx	- pcilib context

 * @param[in] flags	- specifies the type of required address (virtual, physical, or bus) and the required access (ro/wo/rw)

 * @param[in] bank	- the id of register bank

 * @return 		- the resolved address or PCILIB_ADDRESS_INVALID on error

 */

uintptr_t pcilib_resolve_bank_address_by_id(pcilib_t *ctx, pcilib_address_resolution_flags_t flags, pcilib_register_bank_t bank);

/**

 * Resolves the address of the specified register bank. The address of the register0 in the bank is returned.

 *

 * All address types (virtual address in process address space, physical address, or bus address) can be resolved.

 * The caller has also to specify the requested access mode (read, write, read/write) and the error will be returned

 * if the requested access type is not possible.

 *

 * @param[in,out] ctx	- pcilib context

 * @param[in] flags	- specifies the type of required address (virtual, physical, or bus) and the required access (ro/wo/rw)

 * @param[in] bank	- the name of register bank

 * @return 		- the resolved address or PCILIB_ADDRESS_INVALID on error

 */

uintptr_t pcilib_resolve_bank_address(pcilib_t *ctx, pcilib_address_resolution_flags_t flags, const char *bank);

/**

 * Resolves the address of the specified register.

 *

 * All address types (virtual address in process address space, physical address, or bus address) can be resolved.

 * The caller has also to specify the requested access mode (read, write, read/write) and the error will be returned

 * if the requested access type is not possible.

 *

 * @param[in,out] ctx	- pcilib context

 * @param[in] flags	- specifies the type of required address (virtual, physical, or bus) and the required access (ro/wo/rw)

 * @param[in] reg	- the id of register

 * @return 		- the resolved address or PCILIB_ADDRESS_INVALID on error

 */

uintptr_t pcilib_resolve_register_address_by_id(pcilib_t *ctx, pcilib_address_resolution_flags_t flags, pcilib_register_t reg);

/**

 * Resolves the address of the specified register.

 *

 * All address types (virtual address in process address space, physical address, or bus address) can be resolved.

 * The caller has also to specify the requested access mode (read, write, read/write) and the error will be returned

 * if the requested access type is not possible.

 *

 * @param[in,out] ctx	- pcilib context

 * @param[in] flags	- specifies the type of required address (virtual, physical, or bus) and the required access (ro/wo/rw)

 * @param[in] bank	- should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise

 * @param[in] regname	- the name of the register

 * @return 		- the resolved address or PCILIB_ADDRESS_INVALID on error

 */

uintptr_t pcilib_resolve_register_address(pcilib_t *ctx, pcilib_address_resolution_flags_t flags, const char *bank, const char *regname);

/**

 * Extracts additional information about the specified register bank. The additional information

 * is model-specific and are provided as extra XML attributes in XML-described register bank.

 * The available attributes are only restricted by used XSD schema.

 * @param[in,out] ctx	- pcilib context

 * @param[in] bank	- register bank id

 * @param[in] attr	- requested attribute name

 * @param[in,out] val	- the value of attribute is returned here (see \ref public_api_value),

 *			pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use

 * @return		- error code or 0 on success

 */ 

int pcilib_get_register_bank_attr_by_id(pcilib_t *ctx, pcilib_register_bank_t bank, const char *attr, pcilib_value_t *val);

/**

 * Extracts additional information about the specified register bank. The additional information

 * is model-specific and are provided as extra XML attributes in XML-described register bank.

 * The available attributes are only restricted by used XSD schema.

 * @param[in,out] ctx	- pcilib context

 * @param[in] bankname	- the name of register bank

 * @param[in] attr	- requested attribute name

 * @param[in,out] val	- the value of attribute is returned here (see \ref public_api_value),

 *			pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use

 * @return		- error code or 0 on success

 */ 

int pcilib_get_register_bank_attr(pcilib_t *ctx, const char *bankname, const char *attr, pcilib_value_t *val);

#ifdef __cplusplus

}

#endif

#endif /* _PCILIB_BANK_H */