iwlagn: document the bus layer API

#ifndef __iwl_bus_h__

#ifndef __iwl_bus_h__

#define __iwl_bus_h__

#define __iwl_bus_h__

/*This file includes the declaration that are exported from the bus layer */

#include <linux/types.h>

#include <linux/types.h>

#include <linux/spinlock.h>

#include <linux/spinlock.h>

/**

 * DOC: Bus layer - role and goal

 *

 * iwl-bus.h defines the API to the bus layer of the iwlwifi driver.

 * The bus layer is responsible for doing very basic bus operations that are

 * listed in the iwl_bus_ops structure.

 * The bus layer registers to the bus driver, advertises the supported HW and

 * gets notifications about enumeration, suspend, resume.

 * For the moment, the bus layer is not a linux kernel module as itself, and

 * the module_init function of the driver must call the bus specific

 * registration functions. These functions are listed at the end of this file.

 * For the moment, there is only one implementation of this interface: PCI-e.

 * This implementation is iwl-pci.c

 */

/**

 * DOC: encapsulation and type safety

 *

 * The iwl_bus describes the data that is shared amongst all the bus layer

 * implementations. This data is visible to other layers. Data in the bus

 * specific area is not visible outside the bus specific implementation.

 * iwl_bus holds a pointer to iwl_shared which holds pointer to all the other

 * layers of the driver (iwl_priv, iwl_trans). In fact, this is the way to go

 * when the transport layer needs to call a function of another layer.

 *

 * In order to achieve encapsulation, iwl_priv cannot be dereferenced from the

 * bus layer. Type safety is still kept since functions that gets iwl_priv gets

 * a typed pointer (as opposed to void *).

 */

/**

 * DOC: probe flow

 *

 * The module_init calls the bus specific registration function. The

 * registration to the bus layer will trigger an enumeration of the bus which

 * will call the bus specific probe function.

 * The first thing this function must do is to allocate the memory needed by

 * iwl_bus + the bus_specific data.

 * Once the bus specific probe function has configured the hardware, it

 * chooses the appropriate transport layer and calls iwl_probe that will run

 * the bus independent probe flow.

 *

 * Note: The bus specific code must set the following data in iwl_bus before it

 *       calls iwl_probe:

 *	* bus->dev

 *	* bus->irq

 *	* bus->ops

 */

struct iwl_shared;

struct iwl_shared;

struct iwl_bus;

struct iwl_bus;

/**

/**

 * struct iwl_bus_ops - bus specific operations

 * struct iwl_bus_ops - bus specific operations

 * @get_pm_support: must returns true if the bus can go to sleep

 * @get_pm_support: must returns true if the bus can go to sleep

 * @apm_config: will be called during the config of the APM configuration

 * @apm_config: will be called during the config of the APM

 * @set_drv_data: set the shared data pointer to the bus layer

 * @set_drv_data: set the shared data pointer to the bus layer

 * @get_hw_id: prints the hw_id in the provided buffer

 * @get_hw_id: prints the hw_id in the provided buffer

 * @write8: write a byte to register at offset ofs

 * @write8: write a byte to register at offset ofs

/**

/**

 * struct iwl_bus - bus common data

 * struct iwl_bus - bus common data

 * @dev - pointer to struct device * that represent the device

 *

 * This data is common to all bus layer implementations.

 *

 * @dev - pointer to struct device * that represents the device

 * @ops - pointer to iwl_bus_ops

 * @ops - pointer to iwl_bus_ops

 * @shrd - pointer to iwl_shared which holds shared data from the upper layer

 * @shrd - pointer to iwl_shared which holds shared data from the upper layer

 * @irq - the irq number for the device

 * @irq - the irq number for the device

 * @reg_lock - protect hw register access

 * @reg_lock - protect hw register access

 */

 */

struct iwl_bus {

struct iwl_bus {

	/* Common data to all buses */

	struct device *dev;

	struct device *dev;

	const struct iwl_bus_ops *ops;

	const struct iwl_bus_ops *ops;

	struct iwl_shared *shrd;

	struct iwl_shared *shrd;

	return bus->ops->read32(bus, ofs);

	return bus->ops->read32(bus, ofs);

}

}

/*****************************************************

* Bus layer registration functions

******************************************************/

int __must_check iwl_pci_register_driver(void);

int __must_check iwl_pci_register_driver(void);

void iwl_pci_unregister_driver(void);

void iwl_pci_unregister_driver(void);