【前言】

        我們學習 Linux 裝置驅動，很多人在一開始往往急於想找到快速入門的方法，希望能有一個提綱挈領的使用說明來幫助我們快速理解 Linux 裝置驅動的設計思路和框架，從而擺脫掉 Linux 核心這頭龐然怪獸。我自己最初也是這樣。然而事與願違，如果學習 Linux 裝置驅動能有這樣的捷徑讓大多數人快速掌握，那麼具備開發 Linux 裝置驅動的能力也就變得不再值錢了。所以，學習 Linux 裝置驅動的正道還是丟掉世俗的浮躁、靜下心來好好閱讀核心原始碼。正如 Linus Torvalds 的神諭那樣，“Read the fucking source code”。我想，這也是做好其它事情的不二法門。

        在這種想法的指引下，在前一陣子對 platform 驅動模型、i2c 驅動模型、ASoC 驅動模型、kobject+kset+ktype 有了大體認識之後，我再次開始閱讀核心中的裝置驅動框架程式碼。說實話，程式碼中的註釋有的時候比我們在書上或網上看到的講解更加清晰直觀。我把 device 結構體的官方註釋翻譯成了中文寫在下面。

【device結構體成員詳解】

/**
 * device 結構體 - 裝置驅動模型中的基礎結構體之一
 * @parent:	裝置所依附的“父裝置”。
 * 		大多數情況下，這樣的父裝置是某種匯流排或主控制器。
 * 		如果該成員變數的值為 NULL 表示當前裝置是一個最“頂端”裝置，
 * 		通常這樣的裝置都不是你想得到的那個。
 * @p:		該成員變數是一個指向裝置結構體中驅動核心部分的私有資料的指標。
 * 		更詳細的資訊可以閱讀 device_private 結構體的註釋。
 * @kobj:	kobj是最“頂層”的抽象類，所有其它的類都繼承自它。
 * @init_name:	裝置結構體所對應的裝置的名稱。
 * @type:	裝置結構體所對應的裝置的型別。
 * 		該成員變數用於標識裝置型別，並存儲著該型別裝置特有的資訊。
 * @mutex:	用於同步驅動中的函式呼叫的互斥鎖。
 * @bus:	裝置所掛接的匯流排的型別。
 * @driver:	該成員變數指向開闢當前裝置結構體空間的裝置驅動。
 * @platform_data: 該成員變數用於儲存和裝置硬體相關的平臺數據。
 * 		示例：對於自定義電路板上的裝置來說，典型的情況譬如嵌入式裝置
 * 		以及一些基於 SOC 的硬體，Linux 系統通常會使用 platform_data 指標指向
 * 		與電路板硬體相關的結構體，這些結構體中的成員描述了它們對應的裝置硬體資源
 * 		以及電路板的電路連線情況。這些被描述的內容可以包括晶片的哪些埠可用，與
 * 		上一代晶片相比有什麼改動，哪個 GPIO 引腳有額外的功能等等。
 * 		這個成員變數的實現使得 BSP 的工作量減小了許多，
 * 		同時也減少了我們為相容不同的電路板而寫的 #ifdefs 語句的數量。
 * @driver_data: 指向驅動特定資訊的私有指標。
 * @power:	用於裝置的電源管理。
 * 		更詳細的資訊可以閱讀 Documentation/power/devices.txt 文件。
 * @pm_domain:	為裝置提供當系統被掛起、
 * 		休眠、喚醒和電源狀態切換時的回撥函式，
 * 		以及子系統級別和驅動級別的回撥函式。
 * @pins:	用於裝置引腳管理。
 *		更詳細的資訊可以閱讀 Documentation/pinctrl.txt 文件。
 * @msi_list:	主機 MSI 描述符。
 * @msi_domain: 裝置結構體所使用的 MSI 域。
 * @numa_node:	與裝置結構體最鄰近的 NUMA 節點。
 * @dma_mask:	DMA掩碼（前提是當前裝置可進行 DMA 操作）。
 * @coherent_dma_mask: 作用和 dma_mask 類似，用於一致性 DMA 地址對映。因為並不是所有
 * 		硬體都支援在 64 位地址下開闢連續的記憶體空間。
 * @dma_pfn_offset: DMA區域範圍在記憶體中的地址偏移量。
 * @dma_parms:	一個低許可權級別的驅動會通過這個成員變數告知 IOMMU 程式碼關於
 * 		段操作限制相關的規則。
 * @dma_pools:	指向 DMA池 的指標（前提是當前裝置可進行 DMA 操作）。
 * @dma_mem:	一致性 DMA 的可讀寫區域。
 * @cma_area:	DMA區域中的連續記憶體空間。
 * @archdata:	晶片架構相關的內容。
 * @of_node:	裝置所在裝置樹的節點。
 * @fwnode:	平臺韌體對應的裝置樹節點。
 * @devt:	用於在 sysfs 中建立裝置檔案。
 * @id:		裝置例項（ID 編號）。
 * @devres_lock: 用於保護裝置上的資源訪問的自旋鎖。
 * @devres_head: 裝置上的資源列表。
 * @knode_class: 用於將當前裝置加入到類列表的節點。
 * @class:	裝置所屬的類。
 * @groups:	裝置的屬性集合（可選）。
 * @release:	當裝置的引用計數減少為 0 時，使用該成員變數所指向的解構函式
 * 		釋放當前裝置結構體。這個成員變數的值應該由當前裝置的建立者進行
 * 		設定（比如成功找到裝置的匯流排驅動）。
 * @iommu_group: 裝置所屬的 IOMMU 集合。
 *
 * @offline_disabled: 如果這個成員變數的值被置 1，則裝置將處於永遠線上狀態。
 * @offline:	如果匯流排型別所轄的 offline() 函式被成功呼叫，則該成員變數的值將被置 1。
 *
 * 在最底層級別，Linux系統中的每個裝置都被一個 device 結構體的
 * 例項所表示。device 結構體中包含了裝置模型核心在描述系統結構時
 * 所需要的資訊。大多數子系統在此基礎上還會查詢它們下屬裝置的額外資訊。
 * 這導致我們很難用少數 device 結構體來表示裝置的所有資訊，所以通常
 * 還會配合 kobject 結構體來描述裝置的更高層資訊。
 */
struct device {
	struct device		*parent;

	struct device_private	*p;

	struct kobject kobj;
	const char		*init_name; /* 裝置的初始化名稱 */
	const struct device_type *type;

	struct mutex		mutex;	/* mutex to synchronize calls to
					 * its driver.
					 */

	struct bus_type	*bus;		/* type of bus device is on */
	struct device_driver *driver;	/* which driver has allocated this
					   device */
	void		*platform_data;	/* Platform specific data, device
					   core doesn't touch it */
	void		*driver_data;	/* Driver data, set and get with
					   dev_set/get_drvdata */
	struct dev_pm_info	power;
	struct dev_pm_domain	*pm_domain;

#ifdef CONFIG_GENERIC_MSI_IRQ_DOMAIN
	struct irq_domain	*msi_domain;
#endif
#ifdef CONFIG_PINCTRL
	struct dev_pin_info	*pins;
#endif
#ifdef CONFIG_GENERIC_MSI_IRQ
	struct list_head	msi_list;
#endif

#ifdef CONFIG_NUMA
	int		numa_node;	/* NUMA node this device is close to */
#endif
	u64		*dma_mask;	/* dma mask (if dma'able device) */
	u64		coherent_dma_mask;/* Like dma_mask, but for
					     alloc_coherent mappings as
					     not all hardware supports
					     64 bit addresses for consistent
					     allocations such descriptors. */
	unsigned long	dma_pfn_offset;

	struct device_dma_parameters *dma_parms;

	struct list_head	dma_pools;	/* dma pools (if dma'ble) */

	struct dma_coherent_mem	*dma_mem; /* internal for coherent mem
					     override */
#ifdef CONFIG_DMA_CMA
	struct cma *cma_area;		/* contiguous memory area for dma
					   allocations */
#endif
	/* arch specific additions */
	struct dev_archdata	archdata;

	struct device_node	*of_node; /* associated device tree node */
	struct fwnode_handle	*fwnode; /* firmware device node */

	dev_t			devt;	/* dev_t, creates the sysfs "dev" */
	u32			id;	/* device instance */

	spinlock_t		devres_lock;
	struct list_head	devres_head;

	struct klist_node	knode_class;
	struct class		*class;
	const struct attribute_group **groups;	/* optional groups */

	void	(*release)(struct device *dev);
	struct iommu_group	*iommu_group;

	bool			offline_disabled:1;
	bool			offline:1;
};