PCI bus. More...

#include <stdint.h>
#include <ipxe/device.h>
#include <ipxe/tables.h>
#include <ipxe/pci_io.h>

Data Structures
struct	pci_device_id
	A PCI device ID list entry. More...
struct	pci_class_id
	A PCI class ID. More...
struct	pci_device
	A PCI device. More...
struct	pci_driver
	A PCI driver. More...
Defines
#define	PCI_VENDOR_ID 0x00
	PCI vendor ID.
#define	PCI_DEVICE_ID 0x02
	PCI device ID.
#define	PCI_COMMAND 0x04
	PCI command.
#define	PCI_COMMAND_IO 0x0001
	I/O space.
#define	PCI_COMMAND_MEM 0x0002
	Memory space.
#define	PCI_COMMAND_MASTER 0x0004
	Bus master.
#define	PCI_COMMAND_INVALIDATE 0x0010
	Mem.
#define	PCI_COMMAND_PARITY 0x0040
	Parity error response.
#define	PCI_COMMAND_SERR 0x0100
	SERR# enable.
#define	PCI_COMMAND_INTX_DISABLE 0x0400
	Interrupt disable.
#define	PCI_STATUS 0x06
	PCI status.
#define	PCI_STATUS_CAP_LIST 0x0010
	Capabilities list.
#define	PCI_STATUS_PARITY 0x0100
	Master data parity error.
#define	PCI_STATUS_REC_TARGET_ABORT 0x1000
	Received target abort.
#define	PCI_STATUS_REC_MASTER_ABORT 0x2000
	Received master abort.
#define	PCI_STATUS_SIG_SYSTEM_ERROR 0x4000
	Signalled system error.
#define	PCI_STATUS_DETECTED_PARITY 0x8000
	Detected parity error.
#define	PCI_REVISION 0x08
	PCI revision.
#define	PCI_CACHE_LINE_SIZE 0x0c
	PCI cache line size.
#define	PCI_LATENCY_TIMER 0x0d
	PCI latency timer.
#define	PCI_HEADER_TYPE 0x0e
	PCI header type.
#define	PCI_HEADER_TYPE_NORMAL 0x00
	Normal header.
#define	PCI_HEADER_TYPE_BRIDGE 0x01
	PCI-to-PCI bridge header.
#define	PCI_HEADER_TYPE_CARDBUS 0x02
	CardBus header.
#define	PCI_HEADER_TYPE_MASK 0x7f
	Header type mask.
#define	PCI_HEADER_TYPE_MULTI 0x80
	Multi-function device.
#define	PCI_BASE_ADDRESS(n) ( 0x10 + ( 4 * (n) ) )
	PCI base address registers.
#define	PCI_BASE_ADDRESS_0 PCI_BASE_ADDRESS ( 0 )
#define	PCI_BASE_ADDRESS_1 PCI_BASE_ADDRESS ( 1 )
#define	PCI_BASE_ADDRESS_2 PCI_BASE_ADDRESS ( 2 )
#define	PCI_BASE_ADDRESS_3 PCI_BASE_ADDRESS ( 3 )
#define	PCI_BASE_ADDRESS_4 PCI_BASE_ADDRESS ( 4 )
#define	PCI_BASE_ADDRESS_5 PCI_BASE_ADDRESS ( 5 )
#define	PCI_BASE_ADDRESS_SPACE_IO 0x00000001UL
	I/O BAR.
#define	PCI_BASE_ADDRESS_IO_MASK 0x00000003UL
	I/O BAR mask.
#define	PCI_BASE_ADDRESS_MEM_TYPE_64 0x00000004UL
	64-bit memory
#define	PCI_BASE_ADDRESS_MEM_TYPE_MASK 0x00000006UL
	Memory type mask.
#define	PCI_BASE_ADDRESS_MEM_MASK 0x0000000fUL
	Memory BAR mask.
#define	PCI_SUBSYSTEM_VENDOR_ID 0x2c
	PCI subsystem vendor ID.
#define	PCI_SUBSYSTEM_ID 0x2e
	PCI subsystem ID.
#define	PCI_ROM_ADDRESS 0x30
	PCI expansion ROM base address.
#define	PCI_CAPABILITY_LIST 0x34
	PCI capabilities pointer.
#define	PCI_CB_CAPABILITY_LIST 0x14
	CardBus capabilities pointer.
#define	PCI_INTERRUPT_LINE 0x3c
	PCI interrupt line.
#define	PCI_CAP_ID 0x00
	Capability ID.
#define	PCI_CAP_ID_PM 0x01
	Power management.
#define	PCI_CAP_ID_VPD 0x03
	Vital product data.
#define	PCI_CAP_ID_VNDR 0x09
	Vendor-specific.
#define	PCI_CAP_ID_EXP 0x10
	PCI Express.
#define	PCI_CAP_ID_EA 0x14
	Enhanced Allocation.
#define	PCI_CAP_NEXT 0x01
	Next capability.
#define	PCI_PM_CTRL 0x04
	Power management control and status.
#define	PCI_PM_CTRL_STATE_MASK 0x0003
	Current power state.
#define	PCI_PM_CTRL_PME_ENABLE 0x0100
	PME pin enable.
#define	PCI_PM_CTRL_PME_STATUS 0x8000
	PME pin status.
#define	PCI_EXP_DEVCTL 0x08
	PCI Express.
#define	PCI_EXP_DEVCTL_FLR 0x8000
	Function level reset.
#define	PCI_ERR_UNCOR_STATUS 0x04
	Uncorrectable error status.
#define	PCI_CLASS_NETWORK 0x02
	Network controller.
#define	PCI_CLASS_SERIAL 0x0c
	Serial bus controller.
#define	PCI_CLASS_SERIAL_USB 0x03
	USB controller.
#define	PCI_CLASS_SERIAL_USB_UHCI 0x00
	UHCI USB controller.
#define	PCI_CLASS_SERIAL_USB_OHCI 0x10
	OHCI USB controller.
#define	PCI_CLASS_SERIAL_USB_EHCI 0x20
	ECHI USB controller.
#define	PCI_CLASS_SERIAL_USB_XHCI 0x30
	xHCI USB controller
#define	PCI_CLASS(base, sub, progif)
	Construct PCI class.
#define	PCI_EXP_FLR_DELAY_MS 100
	PCI Express function level reset delay (in ms)
#define	PCI_ANY_ID 0xffff
	Match-anything ID.
#define	PCI_CLASS_ID(base, sub, progif)
	Construct PCI class ID.
#define	PCI_DRIVERS __table ( struct pci_driver, "pci_drivers" )
	PCI driver table.
#define	__pci_driver __table_entry ( PCI_DRIVERS, 01 )
	Declare a PCI driver.
#define	__pci_driver_fallback __table_entry ( PCI_DRIVERS, 02 )
	Declare a fallback PCI driver.
#define	PCI_SEG(busdevfn) ( ( (busdevfn) >> 16 ) & 0xffff )
#define	PCI_BUS(busdevfn) ( ( (busdevfn) >> 8 ) & 0xff )
#define	PCI_SLOT(busdevfn) ( ( (busdevfn) >> 3 ) & 0x1f )
#define	PCI_FUNC(busdevfn) ( ( (busdevfn) >> 0 ) & 0x07 )
#define	PCI_BUSDEVFN(segment, bus, slot, func)
#define	PCI_FIRST_FUNC(busdevfn) ( (busdevfn) & ~0x07 )
#define	PCI_LAST_FUNC(busdevfn) ( (busdevfn) \| 0x07 )
#define	PCI_BASE_CLASS(class) ( (class) >> 16 )
#define	PCI_SUB_CLASS(class) ( ( (class) >> 8 ) & 0xff )
#define	PCI_PROG_INTF(class) ( (class) & 0xff )
#define	PCI_ID(_vendor, _device, _name, _description, _data)
#define	PCI_ROM(_vendor, _device, _name, _description, _data) PCI_ID( _vendor, _device, _name, _description, _data )
#define	PCI_FMT "%04x:%02x:%02x.%x"
	PCI device debug message format.
#define	PCI_ARGS(pci)
	PCI device debug message arguments.
Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
void	adjust_pci_device (struct pci_device *pci)
	Enable PCI device.
unsigned long	pci_bar_start (struct pci_device *pci, unsigned int reg)
	Find the start of a PCI BAR.
int	pci_read_config (struct pci_device *pci)
	Read PCI device configuration.
int	pci_find_next (struct pci_device *pci, unsigned int busdevfn)
	Find next device on PCI bus.
int	pci_find_driver (struct pci_device *pci)
	Find driver for PCI device.
int	pci_probe (struct pci_device *pci)
	Probe a PCI device.
void	pci_remove (struct pci_device *pci)
	Remove a PCI device.
int	pci_find_capability (struct pci_device *pci, int capability)
	Look for a PCI capability.
int	pci_find_next_capability (struct pci_device *pci, int pos, int capability)
	Look for another PCI capability.
unsigned long	pci_bar_size (struct pci_device *pci, unsigned int reg)
	Find the size of a PCI BAR.
static void	pci_init (struct pci_device *pci, unsigned int busdevfn)
	Initialise PCI device.
static void	pci_set_driver (struct pci_device pci, struct pci_driver driver, struct pci_device_id *id)
	Set PCI driver.
static void	pci_set_drvdata (struct pci_device pci, void priv)
	Set PCI driver-private data.
static void *	pci_get_drvdata (struct pci_device *pci)
	Get PCI driver-private data.
Variables
struct pci_device_id	__attribute__

Detailed Description

PCI bus.

Definition in file pci.h.

Define Documentation

#define PCI_VENDOR_ID 0x00

PCI vendor ID.

Definition at line 18 of file pci.h.

Referenced by arbel_reset(), and pci_read_config().

#define PCI_DEVICE_ID 0x02

PCI device ID.

Definition at line 21 of file pci.h.

#define PCI_COMMAND 0x04

PCI command.

Definition at line 24 of file pci.h.

Referenced by __vxge_hw_device_pci_e_init(), adjust_pci_device(), atl1e_reset_hw(), atl1e_setup_pcicmd(), bnx2_init_board(), igbvf_sw_init(), myri10ge_net_irq(), pci_bar_size(), tg3_chip_reset(), tg3_get_invariants(), tg3_restore_pci_state(), and tg3_save_pci_state().

#define PCI_COMMAND_IO 0x0001

I/O space.

Definition at line 25 of file pci.h.

Referenced by adjust_pci_device(), and atl1e_reset_hw().

#define PCI_COMMAND_MEM 0x0002

Memory space.

Definition at line 26 of file pci.h.

Referenced by adjust_pci_device(), atl1e_reset_hw(), and atl1e_setup_pcicmd().

#define PCI_COMMAND_MASTER 0x0004

Bus master.

Definition at line 27 of file pci.h.

Referenced by adjust_pci_device(), atl1e_reset_hw(), and atl1e_setup_pcicmd().

#define PCI_COMMAND_INVALIDATE 0x0010

Mem.

write & invalidate

Definition at line 28 of file pci.h.

Referenced by tg3_get_invariants().

#define PCI_COMMAND_PARITY 0x0040

Parity error response.

Definition at line 29 of file pci.h.

Referenced by bnx2_init_board(), and tg3_get_invariants().

#define PCI_COMMAND_SERR 0x0100

SERR# enable.

Definition at line 30 of file pci.h.

Referenced by bnx2_init_board(), and tg3_get_invariants().

#define PCI_COMMAND_INTX_DISABLE 0x0400

Interrupt disable.

Definition at line 31 of file pci.h.

Referenced by myri10ge_net_irq().

#define PCI_STATUS 0x06

PCI status.

Definition at line 34 of file pci.h.

Referenced by pci_find_capability(), skge_reset(), sky2_hw_intr(), and sky2_reset().

#define PCI_STATUS_CAP_LIST 0x0010

Capabilities list.

Definition at line 35 of file pci.h.

Referenced by pci_find_capability().

#define PCI_STATUS_PARITY 0x0100

Master data parity error.

Definition at line 36 of file pci.h.

#define PCI_STATUS_REC_TARGET_ABORT 0x1000

Received target abort.

Definition at line 37 of file pci.h.

#define PCI_STATUS_REC_MASTER_ABORT 0x2000

Received master abort.

Definition at line 38 of file pci.h.

#define PCI_STATUS_SIG_SYSTEM_ERROR 0x4000

Signalled system error.

Definition at line 39 of file pci.h.

#define PCI_STATUS_DETECTED_PARITY 0x8000

Detected parity error.

Definition at line 40 of file pci.h.

#define PCI_REVISION 0x08

PCI revision.

Definition at line 43 of file pci.h.

Referenced by atl1e_sw_init(), dmfe_probe(), falcon_probe_nic_variant(), igbvf_sw_init(), pci_read_config(), rhine_probe(), sis900_probe(), sundance_probe(), tulip_probe(), and vxge_probe().

#define PCI_CACHE_LINE_SIZE 0x0c

PCI cache line size.

Definition at line 46 of file pci.h.

Referenced by ath5k_probe(), ath_pci_probe(), ath_pci_read_cachesize(), tg3_get_invariants(), and tg3_restore_pci_state().

#define PCI_LATENCY_TIMER 0x0d

PCI latency timer.

Definition at line 49 of file pci.h.

Referenced by adjust_pci_device(), ath5k_probe(), ath_pci_probe(), tg3_get_invariants(), and tg3_restore_pci_state().

#define PCI_HEADER_TYPE 0x0e

PCI header type.

Definition at line 52 of file pci.h.

Referenced by pci_find_capability(), and pci_read_config().

#define PCI_HEADER_TYPE_NORMAL 0x00

Normal header.

Definition at line 53 of file pci.h.

Referenced by pci_find_capability().

#define PCI_HEADER_TYPE_BRIDGE 0x01

PCI-to-PCI bridge header.

Definition at line 54 of file pci.h.

Referenced by pci_find_capability().

#define PCI_HEADER_TYPE_CARDBUS 0x02

CardBus header.

Definition at line 55 of file pci.h.

Referenced by pci_find_capability().

#define PCI_HEADER_TYPE_MASK 0x7f

Header type mask.

Definition at line 56 of file pci.h.

Referenced by pci_find_capability().

#define PCI_HEADER_TYPE_MULTI 0x80

Multi-function device.

Definition at line 57 of file pci.h.

Referenced by pci_read_config().

#define PCI_BASE_ADDRESS ( n ) ( 0x10 + ( 4 * (n) ) )

PCI base address registers.

Definition at line 60 of file pci.h.

Referenced by virtio_pci_map_capability().

#define PCI_BASE_ADDRESS_0 PCI_BASE_ADDRESS ( 0 )

Definition at line 61 of file pci.h.

Referenced by __vxge_hw_device_get_legacy_reg(), amd8111e_probe(), bnx2_init_board(), dmfe_probe(), efx_probe(), forcedeth_map_regs(), igbvf_probe(), mlx_pci_init_priv(), pci_read_bases(), phantom_map_crb(), skge_probe(), sky2_probe(), tg3_init_one(), and vxge_probe().

#define PCI_BASE_ADDRESS_1 PCI_BASE_ADDRESS ( 1 )

Definition at line 62 of file pci.h.

#define PCI_BASE_ADDRESS_2 PCI_BASE_ADDRESS ( 2 )

Definition at line 63 of file pci.h.

Referenced by efab_probe(), and efx_probe().

#define PCI_BASE_ADDRESS_3 PCI_BASE_ADDRESS ( 3 )

Definition at line 64 of file pci.h.

#define PCI_BASE_ADDRESS_4 PCI_BASE_ADDRESS ( 4 )

Definition at line 65 of file pci.h.

#define PCI_BASE_ADDRESS_5 PCI_BASE_ADDRESS ( 5 )

Definition at line 66 of file pci.h.

Referenced by forcedeth_map_regs(), and pci_read_bases().

#define PCI_BASE_ADDRESS_SPACE_IO 0x00000001UL

I/O BAR.

Definition at line 67 of file pci.h.

Referenced by efx_probe(), forcedeth_map_regs(), pci_bar(), pci_bar_size(), pci_bar_start(), pci_read_bases(), and virtio_pci_map_capability().

#define PCI_BASE_ADDRESS_IO_MASK 0x00000003UL

I/O BAR mask.

Definition at line 68 of file pci.h.

Referenced by efx_probe(), pci_bar_size(), pci_bar_start(), pci_read_bases(), and prism2_find_plx().

#define PCI_BASE_ADDRESS_MEM_TYPE_64 0x00000004UL

64-bit memory

Definition at line 69 of file pci.h.

Referenced by pci_bar(), and pci_read_bases().

#define PCI_BASE_ADDRESS_MEM_TYPE_MASK 0x00000006UL

Memory type mask.

Definition at line 70 of file pci.h.

Referenced by pci_bar().

#define PCI_BASE_ADDRESS_MEM_MASK 0x0000000fUL

Memory BAR mask.

Definition at line 71 of file pci.h.

Referenced by pci_bar_size(), pci_bar_start(), and pci_read_bases().

#define PCI_SUBSYSTEM_VENDOR_ID 0x2c

PCI subsystem vendor ID.

Definition at line 74 of file pci.h.

Referenced by pcnet32_setup_if_duplex(), tg3_init_one(), and undinet_irq_is_broken().

#define PCI_SUBSYSTEM_ID 0x2e

PCI subsystem ID.

Definition at line 77 of file pci.h.

Referenced by ath_pci_probe(), pcnet32_setup_if_duplex(), tg3_init_one(), and undinet_irq_is_broken().

#define PCI_ROM_ADDRESS 0x30

PCI expansion ROM base address.

Definition at line 80 of file pci.h.

Referenced by undipci_find_rom().

#define PCI_CAPABILITY_LIST 0x34

PCI capabilities pointer.

Definition at line 83 of file pci.h.

Referenced by pci_find_capability().

#define PCI_CB_CAPABILITY_LIST 0x14

CardBus capabilities pointer.

Definition at line 86 of file pci.h.

Referenced by pci_find_capability().

#define PCI_INTERRUPT_LINE 0x3c

PCI interrupt line.

Definition at line 89 of file pci.h.

Referenced by pci_read_config().

#define PCI_CAP_ID 0x00

Capability ID.

Definition at line 92 of file pci.h.

Referenced by pci_find_capability_common().

#define PCI_CAP_ID_PM 0x01

Power management.

Definition at line 93 of file pci.h.

Referenced by bnx2_init_board().

#define PCI_CAP_ID_VPD 0x03

Vital product data.

Definition at line 94 of file pci.h.

Referenced by pci_vpd_init().

#define PCI_CAP_ID_VNDR 0x09

Vendor-specific.

Definition at line 95 of file pci.h.

Referenced by myri10ge_pci_probe(), and virtio_pci_find_capability().

#define PCI_CAP_ID_EXP 0x10

PCI Express.

Definition at line 96 of file pci.h.

Referenced by ath5k_hw_attach(), ath5k_hw_nic_wakeup(), sky2_reset(), sky2_rx_start(), and tg3_get_invariants().

#define PCI_CAP_ID_EA 0x14

Enhanced Allocation.

Definition at line 97 of file pci.h.

Referenced by pciea_offset().

#define PCI_CAP_NEXT 0x01

Next capability.

Definition at line 100 of file pci.h.

Referenced by pci_find_capability_common(), and pci_find_next_capability().

#define PCI_PM_CTRL 0x04

Power management control and status.

Definition at line 103 of file pci.h.

Referenced by bnx2_set_power_state_0(), tg3_get_eeprom_hw_cfg(), tg3_get_invariants(), and tg3_set_power_state_0().

#define PCI_PM_CTRL_STATE_MASK 0x0003

Current power state.

Definition at line 104 of file pci.h.

Referenced by bnx2_set_power_state_0(), tg3_get_eeprom_hw_cfg(), tg3_get_invariants(), and tg3_set_power_state_0().

#define PCI_PM_CTRL_PME_ENABLE 0x0100

PME pin enable.

Definition at line 105 of file pci.h.

Referenced by tg3_get_invariants().

#define PCI_PM_CTRL_PME_STATUS 0x8000

PME pin status.

Definition at line 106 of file pci.h.

Referenced by bnx2_set_power_state_0(), and tg3_set_power_state_0().

#define PCI_EXP_DEVCTL 0x08

PCI Express.

Definition at line 109 of file pci.h.

Referenced by tg3_chip_reset().

#define PCI_EXP_DEVCTL_FLR 0x8000

Function level reset.

Definition at line 110 of file pci.h.

#define PCI_ERR_UNCOR_STATUS 0x04

Uncorrectable error status.

Definition at line 113 of file pci.h.

Referenced by sky2_hw_intr(), and sky2_reset().

#define PCI_CLASS_NETWORK 0x02

Network controller.

Definition at line 116 of file pci.h.

#define PCI_CLASS_SERIAL 0x0c

Serial bus controller.

Definition at line 119 of file pci.h.

#define PCI_CLASS_SERIAL_USB 0x03

USB controller.

Definition at line 120 of file pci.h.

#define PCI_CLASS_SERIAL_USB_UHCI 0x00

UHCI USB controller.

Definition at line 121 of file pci.h.

Referenced by ehci_poll_companions().

#define PCI_CLASS_SERIAL_USB_OHCI 0x10

OHCI USB controller.

Definition at line 122 of file pci.h.

Referenced by ehci_poll_companions().

#define PCI_CLASS_SERIAL_USB_EHCI 0x20

ECHI USB controller.

Definition at line 123 of file pci.h.

Referenced by ehci_companion().

#define PCI_CLASS_SERIAL_USB_XHCI 0x30

xHCI USB controller

Definition at line 124 of file pci.h.

#define PCI_CLASS	(	base,
		sub,
		progif
	)

Value:

( ( ( (base) & 0xff ) << 16 ) | ( ( (sub) & 0xff ) << 8 ) |     \
          ( ( (progif) & 0xff) << 0 ) )

Construct PCI class.

Parameters:

base	Base class (or PCI_ANY_ID)
sub	Subclass (or PCI_ANY_ID)
progif	Programming interface (or PCI_ANY_ID)

Definition at line 132 of file pci.h.

Referenced by ehci_companion(), and ehci_poll_companions().

#define PCI_EXP_FLR_DELAY_MS 100

PCI Express function level reset delay (in ms)

Definition at line 137 of file pci.h.

#define PCI_ANY_ID 0xffff

Match-anything ID.

Definition at line 152 of file pci.h.

Referenced by pci_find_driver(), and undinet_irq_is_broken().

#define PCI_CLASS_ID	(	base,
		sub,
		progif
	)

Value:

{                                  \
        .class = PCI_CLASS ( base, sub, progif ),                          \
        .mask = ( ( ( ( (base) == PCI_ANY_ID ) ? 0x00 : 0xff ) << 16 ) |   \
                  ( ( ( (sub) == PCI_ANY_ID ) ? 0x00 : 0xff ) << 8 ) |     \
                  ( ( ( (progif) == PCI_ANY_ID ) ? 0x00 : 0xff ) << 0 ) ), \
        }

Construct PCI class ID.

Parameters:

base	Base class (or PCI_ANY_ID)
sub	Subclass (or PCI_ANY_ID)
progif	Programming interface (or PCI_ANY_ID)

Definition at line 168 of file pci.h.

#define PCI_DRIVERS __table ( struct pci_driver, "pci_drivers" )

PCI driver table.

Definition at line 236 of file pci.h.

Referenced by pci_find_driver().

struct pci_driver txnic_bgx_driver __pci_driver __table_entry ( PCI_DRIVERS, 01 )

Declare a PCI driver.

BGX PCI driver.

Definition at line 239 of file pci.h.

#define __pci_driver_fallback __table_entry ( PCI_DRIVERS, 02 )

Declare a fallback PCI driver.

Definition at line 242 of file pci.h.

#define PCI_SEG ( busdevfn ) ( ( (busdevfn) >> 16 ) & 0xffff )

Definition at line 244 of file pci.h.

Referenced by efipci_root(), format_busdevfn_setting(), pci_read_config(), and phantom_probe().

#define PCI_BUS ( busdevfn ) ( ( (busdevfn) >> 8 ) & 0xff )

Definition at line 245 of file pci.h.

Referenced by bofm(), efipci_address(), format_busdevfn_setting(), int13_device_path_info(), pci_read_config(), phantom_probe(), pxenv_undi_get_nic_type(), and undibus_probe().

#define PCI_SLOT ( busdevfn ) ( ( (busdevfn) >> 3 ) & 0x1f )

Definition at line 246 of file pci.h.

Referenced by bofm(), efipci_address(), format_busdevfn_setting(), int13_device_path_info(), pci_read_config(), phantom_probe(), pxenv_undi_get_nic_type(), undi_load(), and undibus_probe().

#define PCI_FUNC ( busdevfn ) ( ( (busdevfn) >> 0 ) & 0x07 )

Definition at line 247 of file pci.h.

Referenced by bofm(), efipci_address(), format_busdevfn_setting(), int13_device_path_info(), intel_probe(), intelx_probe(), intelxl_probe(), pci_read_config(), phantom_probe(), pxenv_undi_get_nic_type(), tg3_get_device_address(), tg3_mdio_init(), undi_load(), and undibus_probe().

#define PCI_BUSDEVFN	(	segment,
		bus,
		slot,
		func
	)

Value:

( ( (segment) << 16 ) | ( (bus) << 8 ) |                        \
          ( (slot) << 3 ) | ( (func) << 0 ) )

Definition at line 248 of file pci.h.

Referenced by efipci_open(), pci_find_next(), and phantom_probe().

#define PCI_FIRST_FUNC ( busdevfn ) ( (busdevfn) & ~0x07 )

Definition at line 251 of file pci.h.

Referenced by ehci_poll_companions(), hunt_probe(), and pci_read_config().

#define PCI_LAST_FUNC ( busdevfn ) ( (busdevfn) | 0x07 )

Definition at line 252 of file pci.h.

Referenced by ehci_companion().

#define PCI_BASE_CLASS ( class ) ( (class) >> 16 )

Definition at line 254 of file pci.h.

Referenced by pxenv_undi_get_nic_type().

#define PCI_SUB_CLASS ( class ) ( ( (class) >> 8 ) & 0xff )

Definition at line 255 of file pci.h.

Referenced by pxenv_undi_get_nic_type().

#define PCI_PROG_INTF ( class ) ( (class) & 0xff )

Definition at line 256 of file pci.h.

Referenced by pxenv_undi_get_nic_type().

#define PCI_ID	(	_vendor,
		_device,
		_name,
		_description,
		_data
	)

Value:

{       \
        .vendor = _vendor,                                              \
        .device = _device,                                              \
        .name = _name,                                                  \
        .driver_data = _data                                            \
}

Definition at line 266 of file pci.h.

#define PCI_ROM	(	_vendor,
		_device,
		_name,
		_description,
		_data
	)	PCI_ID( _vendor, _device, _name, _description, _data )

Definition at line 272 of file pci.h.

#define PCI_FMT "%04x:%02x:%02x.%x"

PCI device debug message format.

Definition at line 276 of file pci.h.

Referenced by adjust_pci_device(), bofm(), bofm_en(), bofm_probe(), bofm_register(), bofm_remove(), bofm_test(), bofm_test_init(), bofm_unregister(), efipci_open(), efipci_read(), efipci_root(), efipci_start(), efipci_supported(), efipci_write(), hunt_probe(), nvs_vpd_init(), nvs_vpd_nvo_init(), nvs_vpd_read(), nvs_vpd_resize(), nvs_vpd_write(), pci_bar(), pci_probe(), pci_remove(), pci_settings_fetch(), pci_vpd_find(), pci_vpd_find_tag(), pci_vpd_init(), pci_vpd_read_dword(), pci_vpd_resize(), pci_vpd_write_dword(), pcibus_probe(), pciea_bar_value(), phantom_map_crb(), uhci_root_speed(), and vxge_probe().

#define PCI_ARGS ( pci )

Value:

PCI_SEG ( (pci)->busdevfn ), PCI_BUS ( (pci)->busdevfn ),       \
        PCI_SLOT ( (pci)->busdevfn ), PCI_FUNC ( (pci)->busdevfn )

PCI device debug message arguments.

Definition at line 279 of file pci.h.

Referenced by adjust_pci_device(), bofm(), bofm_en(), bofm_probe(), bofm_register(), bofm_remove(), bofm_test(), bofm_test_init(), bofm_unregister(), efipci_open(), efipci_read(), efipci_root(), efipci_start(), efipci_supported(), efipci_write(), hunt_probe(), nvs_vpd_init(), nvs_vpd_nvo_init(), nvs_vpd_read(), nvs_vpd_resize(), nvs_vpd_write(), pci_bar(), pci_probe(), pci_remove(), pci_settings_fetch(), pci_vpd_find(), pci_vpd_find_tag(), pci_vpd_init(), pci_vpd_read_dword(), pci_vpd_resize(), pci_vpd_write_dword(), pcibus_probe(), pciea_bar_value(), phantom_map_crb(), uhci_root_speed(), and vxge_probe().

Function Documentation

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL )

void adjust_pci_device ( struct pci_device * pci )

Enable PCI device.

Parameters:

pci	PCI device

Set device to be a busmaster in case BIOS neglected to do so. Also adjust PCI latency timer to a reasonable value, 32.

Definition at line 149 of file pci.c.

References DBGC, PCI_ARGS, PCI_COMMAND, PCI_COMMAND_IO, PCI_COMMAND_MASTER, PCI_COMMAND_MEM, PCI_FMT, PCI_LATENCY_TIMER, pci_read_config_byte(), pci_read_config_word(), pci_write_config_byte(), and pci_write_config_word().

Referenced by a3c90x_probe(), amd8111e_probe(), arbel_probe(), ath5k_probe(), ath_pci_probe(), atl1e_probe(), b44_probe(), bnx2_init_board(), dmfe_probe(), efab_probe(), efx_probe(), ehci_probe(), ena_probe(), exanic_probe(), forcedeth_probe(), golan_pci_init(), hermon_bofm_probe(), hermon_probe(), hvm_probe(), icplus_probe(), ifec_pci_probe(), igbvf_probe(), intel_probe(), intelx_probe(), intelxl_probe(), intelxvf_probe(), jme_probe(), linda_probe(), mlx_pci_init_priv(), myri10ge_pci_probe(), myson_probe(), natsemi_probe(), pcnet32_probe(), phantom_probe(), pnic_probe(), qib7322_probe(), realtek_probe(), rhine_probe(), rtl818x_probe(), sis190_init_board(), sis900_probe(), skeleton_probe(), skge_probe(), sky2_probe(), sundance_probe(), tg3_init_one(), tlan_probe(), tulip_probe(), txnic_bgx_probe(), txnic_pf_probe(), uhci_probe(), velocity_probe(), virtnet_probe_legacy(), virtnet_probe_modern(), vmxnet3_probe(), vxge_probe(), w89c840_probe(), and xhci_probe().

                                                  {
        unsigned short new_command, pci_command;
        unsigned char pci_latency;

        pci_read_config_word ( pci, PCI_COMMAND, &pci_command );
        new_command = ( pci_command | PCI_COMMAND_MASTER |
                        PCI_COMMAND_MEM | PCI_COMMAND_IO );
        if ( pci_command != new_command ) {
                DBGC ( pci, PCI_FMT " device not enabled by BIOS! Updating "
                       "PCI command %04x->%04x\n",
                       PCI_ARGS ( pci ), pci_command, new_command );
                pci_write_config_word ( pci, PCI_COMMAND, new_command );
        }

        pci_read_config_byte ( pci, PCI_LATENCY_TIMER, &pci_latency);
        if ( pci_latency < 32 ) {
                DBGC ( pci, PCI_FMT " latency timer is unreasonably low at "
                       "%d. Setting to 32.\n", PCI_ARGS ( pci ), pci_latency );
                pci_write_config_byte ( pci, PCI_LATENCY_TIMER, 32);
        }
}

unsigned long pci_bar_start	(	struct pci_device *	pci,
		unsigned int	reg
	)

Find the start of a PCI BAR.

Parameters:

pci	PCI device
reg	PCI register number

Return values:

start BAR start address

Reads the specified PCI base address register, and returns the address portion of the BAR (i.e. without the flags).

If the address exceeds the size of an unsigned long (i.e. if a 64-bit BAR has a non-zero high dword on a 32-bit machine), the return value will be zero.

Definition at line 96 of file pci.c.

References pci_bar(), PCI_BASE_ADDRESS_IO_MASK, PCI_BASE_ADDRESS_MEM_MASK, and PCI_BASE_ADDRESS_SPACE_IO.

Referenced by amd8111e_probe(), arbel_probe(), bnx2_init_board(), dmfe_probe(), efab_probe(), efx_probe(), ehci_probe(), exanic_probe(), flexboot_nodnic_alloc_uar(), forcedeth_map_regs(), golan_alloc_uar(), golan_pci_init(), hermon_bofm_probe(), hermon_probe(), hvm_probe(), igbvf_probe(), mlx_pci_init_priv(), phantom_map_crb(), skge_probe(), sky2_probe(), tg3_init_one(), undipci_find_rom(), virtio_pci_map_capability(), vmxnet3_probe(), vxge_probe(), and xhci_probe().

                                                                         {
        unsigned long bar;

        bar = pci_bar ( pci, reg );
        if ( bar & PCI_BASE_ADDRESS_SPACE_IO ) {
                return ( bar & ~PCI_BASE_ADDRESS_IO_MASK );
        } else {
                return ( bar & ~PCI_BASE_ADDRESS_MEM_MASK );
        }
}

int pci_read_config ( struct pci_device * pci )

Read PCI device configuration.

Parameters:

pci	PCI device

Return values:

rc	Return status code

Definition at line 177 of file pci.c.

References device_description::bus_type, BUS_TYPE_PCI, pci_device::busdevfn, device::children, device_description::class, pci_device::class, device::desc, pci_device::dev, device_description::device, pci_device::device, ENODEV, INIT_LIST_HEAD, device_description::ioaddr, pci_device::ioaddr, device_description::irq, pci_device::irq, device_description::location, device::name, PCI_BUS, PCI_FIRST_FUNC, PCI_FUNC, PCI_HEADER_TYPE, PCI_HEADER_TYPE_MULTI, PCI_INTERRUPT_LINE, pci_read_bases(), pci_read_config_byte(), pci_read_config_dword(), PCI_REVISION, PCI_SEG, PCI_SLOT, PCI_VENDOR_ID, device::siblings, snprintf(), device_description::vendor, and pci_device::vendor.

Referenced by bofm_test_init(), efipci_open(), ehci_companion(), and pci_find_next().

                                               {
        uint32_t busdevfn;
        uint8_t hdrtype;
        uint32_t tmp;

        /* Ignore all but the first function on non-multifunction devices */
        if ( PCI_FUNC ( pci->busdevfn ) != 0 ) {
                busdevfn = pci->busdevfn;
                pci->busdevfn = PCI_FIRST_FUNC ( pci->busdevfn );
                pci_read_config_byte ( pci, PCI_HEADER_TYPE, &hdrtype );
                pci->busdevfn = busdevfn;
                if ( ! ( hdrtype & PCI_HEADER_TYPE_MULTI ) )
                        return -ENODEV;
        }

        /* Check for physical device presence */
        pci_read_config_dword ( pci, PCI_VENDOR_ID, &tmp );
        if ( ( tmp == 0xffffffff ) || ( tmp == 0 ) )
                return -ENODEV;

        /* Populate struct pci_device */
        pci->vendor = ( tmp & 0xffff );
        pci->device = ( tmp >> 16 );
        pci_read_config_dword ( pci, PCI_REVISION, &tmp );
        pci->class = ( tmp >> 8 );
        pci_read_config_byte ( pci, PCI_INTERRUPT_LINE, &pci->irq );
        pci_read_bases ( pci );

        /* Initialise generic device component */
        snprintf ( pci->dev.name, sizeof ( pci->dev.name ), "%04x:%02x:%02x.%x",
                   PCI_SEG ( pci->busdevfn ), PCI_BUS ( pci->busdevfn ),
                   PCI_SLOT ( pci->busdevfn ), PCI_FUNC ( pci->busdevfn ) );
        pci->dev.desc.bus_type = BUS_TYPE_PCI;
        pci->dev.desc.location = pci->busdevfn;
        pci->dev.desc.vendor = pci->vendor;
        pci->dev.desc.device = pci->device;
        pci->dev.desc.class = pci->class;
        pci->dev.desc.ioaddr = pci->ioaddr;
        pci->dev.desc.irq = pci->irq;
        INIT_LIST_HEAD ( &pci->dev.siblings );
        INIT_LIST_HEAD ( &pci->dev.children );

        return 0;
}

int pci_find_next	(	struct pci_device *	pci,
		unsigned int	busdevfn
	)

Find next device on PCI bus.

Parameters:

pci	PCI device to fill in
busdevfn	Starting bus:dev.fn address

Return values:

busdevfn Bus:dev.fn address of next PCI device, or negative error

Definition at line 229 of file pci.c.

References end, ENODEV, memset(), PCI_BUSDEVFN, pci_init(), pci_num_bus(), pci_read_config(), and rc.

Referenced by pcibus_probe(), and pciscan_exec().

                                                                    {
        static unsigned int end;
        int rc;

        /* Determine number of PCI buses */
        if ( ! end )
                end = PCI_BUSDEVFN ( 0, pci_num_bus(), 0, 0 );

        /* Find next PCI device, if any */
        for ( ; busdevfn < end ; busdevfn++ ) {
                memset ( pci, 0, sizeof ( *pci ) );
                pci_init ( pci, busdevfn );
                if ( ( rc = pci_read_config ( pci ) ) == 0 )
                        return busdevfn;
        }

        return -ENODEV;
}

int pci_find_driver ( struct pci_device * pci )

Find driver for PCI device.

Parameters:

pci	PCI device

Return values:

rc	Return status code

Definition at line 254 of file pci.c.

References pci_class_id::class, pci_device::class, pci_driver::class, pci_device_id::device, pci_device::device, driver, ENOENT, for_each_table_entry, id, pci_driver::id_count, pci_driver::ids, pci_class_id::mask, PCI_ANY_ID, PCI_DRIVERS, pci_set_driver(), pci_device_id::vendor, and pci_device::vendor.

Referenced by efipci_start(), efipci_supported(), and pcibus_probe().

                                               {
        struct pci_driver *driver;
        struct pci_device_id *id;
        unsigned int i;

        for_each_table_entry ( driver, PCI_DRIVERS ) {
                if ( ( driver->class.class ^ pci->class ) & driver->class.mask )
                        continue;
                for ( i = 0 ; i < driver->id_count ; i++ ) {
                        id = &driver->ids[i];
                        if ( ( id->vendor != PCI_ANY_ID ) &&
                             ( id->vendor != pci->vendor ) )
                                continue;
                        if ( ( id->device != PCI_ANY_ID ) &&
                             ( id->device != pci->device ) )
                                continue;
                        pci_set_driver ( pci, driver, id );
                        return 0;
                }
        }
        return -ENOENT;
}

int pci_probe ( struct pci_device * pci )

Probe a PCI device.

Parameters:

pci	PCI device

Return values:

rc	Return status code

Searches for a driver for the PCI device. If a driver is found, its probe() routine is called.

Definition at line 286 of file pci.c.

References DBGC, pci_device::device, pci_device::driver, pci_device::id, pci_device::ioaddr, pci_device::irq, pci_device::membase, pci_device_id::name, PCI_ARGS, PCI_FMT, pci_driver::probe, rc, strerror(), and pci_device::vendor.

Referenced by bofm_probe(), efipci_start(), and pcibus_probe().

                                         {
        int rc;

        DBGC ( pci, PCI_FMT " (%04x:%04x) has driver \"%s\"\n",
               PCI_ARGS ( pci ), pci->vendor, pci->device, pci->id->name );
        DBGC ( pci, PCI_FMT " has mem %lx io %lx irq %d\n",
               PCI_ARGS ( pci ), pci->membase, pci->ioaddr, pci->irq );

        if ( ( rc = pci->driver->probe ( pci ) ) != 0 ) {
                DBGC ( pci, PCI_FMT " probe failed: %s\n",
                       PCI_ARGS ( pci ), strerror ( rc ) );
                return rc;
        }

        return 0;
}

void pci_remove ( struct pci_device * pci )

Remove a PCI device.

Parameters:

pci	PCI device

Definition at line 308 of file pci.c.

References DBGC, pci_device::driver, PCI_ARGS, PCI_FMT, and pci_driver::remove.

Referenced by bofm_remove(), efipci_start(), efipci_stop(), and pcibus_remove().

                                           {
        pci->driver->remove ( pci );
        DBGC ( pci, PCI_FMT " removed\n", PCI_ARGS ( pci ) );
}

int pci_find_capability	(	struct pci_device *	pci,
		int	cap
	)

Look for a PCI capability.

Parameters:

pci	PCI device to query
cap	Capability code

Return values:

address Address of capability, or 0 if not found

Determine whether or not a device supports a given PCI capability. Returns the address of the requested capability structure within the device's PCI configuration space, or 0 if the device does not support it.

Definition at line 36 of file pciextra.c.

References PCI_CAPABILITY_LIST, PCI_CB_CAPABILITY_LIST, pci_find_capability_common(), PCI_HEADER_TYPE, PCI_HEADER_TYPE_BRIDGE, PCI_HEADER_TYPE_CARDBUS, PCI_HEADER_TYPE_MASK, PCI_HEADER_TYPE_NORMAL, pci_read_config_byte(), pci_read_config_word(), PCI_STATUS, PCI_STATUS_CAP_LIST, and status.

Referenced by ath5k_hw_attach(), ath5k_hw_nic_wakeup(), bnx2_init_board(), myri10ge_pci_probe(), pci_vpd_init(), pciea_offset(), sky2_reset(), sky2_rx_start(), tg3_get_invariants(), and virtio_pci_find_capability().

                                                            {
        uint16_t status;
        uint8_t pos;
        uint8_t hdr_type;

        pci_read_config_word ( pci, PCI_STATUS, &status );
        if ( ! ( status & PCI_STATUS_CAP_LIST ) )
                return 0;

        pci_read_config_byte ( pci, PCI_HEADER_TYPE, &hdr_type );
        switch ( hdr_type & PCI_HEADER_TYPE_MASK ) {
        case PCI_HEADER_TYPE_NORMAL:
        case PCI_HEADER_TYPE_BRIDGE:
        default:
                pci_read_config_byte ( pci, PCI_CAPABILITY_LIST, &pos );
                break;
        case PCI_HEADER_TYPE_CARDBUS:
                pci_read_config_byte ( pci, PCI_CB_CAPABILITY_LIST, &pos );
                break;
        }
        return pci_find_capability_common ( pci, pos, cap );
}

int pci_find_next_capability	(	struct pci_device *	pci,
		int	pos,
		int	cap
	)

Look for another PCI capability.

Parameters:

pci	PCI device to query
pos	Address of the current capability
cap	Capability code

Return values:

address Address of capability, or 0 if not found

Determine whether or not a device supports a given PCI capability starting the search at a given address within the device's PCI configuration space. Returns the address of the next capability structure within the device's PCI configuration space, or 0 if the device does not support another such capability.

Definition at line 73 of file pciextra.c.

References PCI_CAP_NEXT, pci_find_capability_common(), and pci_read_config_byte().

Referenced by virtio_pci_find_capability().

                                                                          {
        uint8_t new_pos;

        pci_read_config_byte ( pci, pos + PCI_CAP_NEXT, &new_pos );
        return pci_find_capability_common ( pci, new_pos, cap );
}

unsigned long pci_bar_size	(	struct pci_device *	pci,
		unsigned int	reg
	)

Find the size of a PCI BAR.

Parameters:

pci	PCI device
reg	PCI register number

Return values:

size BAR size

It should not be necessary for any Etherboot code to call this function.

Definition at line 90 of file pciextra.c.

References cmd, PCI_BASE_ADDRESS_IO_MASK, PCI_BASE_ADDRESS_MEM_MASK, PCI_BASE_ADDRESS_SPACE_IO, PCI_COMMAND, pci_read_config_dword(), pci_read_config_word(), pci_write_config_dword(), pci_write_config_word(), size, and start.

Referenced by __vxge_hw_device_get_legacy_reg(), amd8111e_probe(), efab_probe(), efx_probe(), ehci_probe(), exanic_probe(), forcedeth_map_regs(), hvm_probe(), igbvf_probe(), phantom_map_crb(), tg3_init_one(), virtio_pci_map_capability(), vxge_probe(), and xhci_probe().

                                                                        {
        uint16_t cmd;
        uint32_t start, size;

        /* Save the original command register */
        pci_read_config_word ( pci, PCI_COMMAND, &cmd );
        /* Save the original bar */
        pci_read_config_dword ( pci, reg, &start );
        /* Compute which bits can be set */
        pci_write_config_dword ( pci, reg, ~0 );
        pci_read_config_dword ( pci, reg, &size );
        /* Restore the original size */
        pci_write_config_dword ( pci, reg, start );
        /* Find the significant bits */
        /* Restore the original command register. This reenables decoding. */
        pci_write_config_word ( pci, PCI_COMMAND, cmd );
        if ( start & PCI_BASE_ADDRESS_SPACE_IO ) {
                size &= ~PCI_BASE_ADDRESS_IO_MASK;
        } else {
                size &= ~PCI_BASE_ADDRESS_MEM_MASK;
        }
        /* Find the lowest bit set */
        size = size & ~( size - 1 );
        return size;
}

static void pci_init	(	struct pci_device *	pci,
		unsigned int	busdevfn
	)		`[inline, static]`

Initialise PCI device.

Parameters:

pci	PCI device
busdevfn	PCI bus:dev.fn address

Definition at line 302 of file pci.h.

References pci_device::busdevfn.

Referenced by bofm_test_init(), efipci_open(), ehci_companion(), pci_find_next(), pci_settings_fetch(), uhci_root_speed(), and undinet_irq_is_broken().

                                                                              {
        pci->busdevfn = busdevfn;
}

static void pci_set_driver	(	struct pci_device *	pci,
		struct pci_driver *	driver,
		struct pci_device_id *	id
	)		`[inline, static]`

Set PCI driver.

Parameters:

pci	PCI device
driver	PCI driver
id	PCI device ID

Definition at line 313 of file pci.h.

References pci_device::dev, pci_device::driver, driver, device::driver_name, id, and pci_device::id.

Referenced by bofm_find_driver(), and pci_find_driver().

                                                               {
        pci->driver = driver;
        pci->id = id;
        pci->dev.driver_name = id->name;
}

static void pci_set_drvdata	(	struct pci_device *	pci,
		void *	priv
	)		`[inline, static]`

Set PCI driver-private data.

Parameters:

pci	PCI device
priv	Private data

Definition at line 327 of file pci.h.

References pci_device::priv, and priv.

Referenced by a3c90x_probe(), arbel_probe(), ath5k_probe(), ath_pci_probe(), atl1e_init_netdev(), b44_probe(), efab_probe(), ehci_probe(), ena_probe(), exanic_probe(), flexboot_nodnic_probe(), forcedeth_probe(), golan_probe_normal(), hermon_bofm_probe(), hermon_probe(), hunt_probe(), hvm_probe(), icplus_probe(), ifec_pci_probe(), igbvf_probe(), intel_probe(), intelx_probe(), intelxl_probe(), intelxvf_probe(), jme_probe(), linda_probe(), myri10ge_pci_probe(), myson_probe(), natsemi_probe(), pcnet32_probe(), phantom_probe(), pnic_probe(), qib7322_probe(), realtek_probe(), rhine_probe(), rtl818x_probe(), sis190_probe(), skeleton_probe(), skge_probe(), skge_remove(), sky2_probe(), sky2_remove(), tg3_init_one(), txnic_bgx_probe(), txnic_pf_probe(), uhci_probe(), undipci_probe(), undipci_remove(), velocity_probe(), virtnet_probe_legacy(), virtnet_probe_modern(), vmxnet3_probe(), vxge_probe(), vxge_remove(), and xhci_probe().

                                                                          {
        pci->priv = priv;
}

static void* pci_get_drvdata ( struct pci_device * pci ) [inline, static]

Get PCI driver-private data.

Parameters:

pci	PCI device

Return values:

priv	Private data

Definition at line 337 of file pci.h.

References pci_device::priv.

Referenced by a3c90x_remove(), arbel_remove(), ath5k_remove(), ath_pci_remove(), atl1e_remove(), b44_remove(), efab_remove(), ehci_remove(), ena_remove(), exanic_remove(), flexboot_nodnic_remove(), forcedeth_remove(), golan_remove_normal(), hermon_bofm_remove(), hermon_remove(), hunt_remove(), hvm_remove(), icplus_remove(), ifec_pci_remove(), igbvf_remove(), intel_remove(), intelx_remove(), intelxl_remove(), intelxvf_remove(), jme_remove(), linda_remove(), myri10ge_pci_remove(), myson_remove(), natsemi_remove(), pcnet32_remove(), phantom_remove(), pnic_remove(), qib7322_remove(), realtek_remove(), rhine_remove(), rtl818x_remove(), sis190_remove(), skeleton_remove(), skge_remove(), sky2_remove(), tg3_remove_one(), txnic_bgx_remove(), txnic_pf_remove(), uhci_remove(), undipci_remove(), velocity_remove(), virtnet_remove(), vmxnet3_remove(), vxge_close(), vxge_irq(), vxge_open(), vxge_open_vpaths(), vxge_poll(), vxge_remove(), and xhci_remove().

                                                                {
        return pci->priv;
}

Variable Documentation

struct pci_device_id __attribute__

Data Structures

Defines

Functions

Variables

Detailed Description

Define Documentation

Function Documentation

Variable Documentation