Entities,pads and links
實體，墊和鏈接
------------------------
-Entities
- 實體
Entitiesare represented by a struct media_entity instance, defined in include/media/media-entity.h. Thestructure is usually embedded into a higher-level structure, such as a v4l2_subdev or video_deviceinstance, although drivers canallocate entities directly.
實體由一個structmedia_entity實例表示，在include / media / media-entity.h中定義。 結構通常嵌入到一個較高級別的結構，例如v4l2_subdev或video_device實例，雖然驅動程序可以直接分配實體。
Driversinitialize entities by calling
驅動程序通過調用來初始化實體
media_entity_init(struct media_entity *entity, u16 num_pads,
struct media_pad *pads, u16extra_links);
Themedia_entity name, type, flags, revision and group_id fields can be initialized before or after callingmedia_entity_init. Entities embedded in higher-level standard structures can have some of those fields setby the higher-level framework.
Asthe number of pads is known in advance, the pads array is not allocated dynamically but is managed by the entitydriver. Most drivers will embed the pads array in a driver-specific structure, avoiding dynamicallocation.
Driversmust set the direction of every pad in the pads array before calling media_entity_init. The function willinitialize the other pads fields.
Unlikethe number of pads, the total number of links isn't always known in advance by the entity driver. As aninitial estimate, media_entity_init pre-allocates a number of links equal to the number of pads plus anoptional number of extralinks. The links array will be reallocated if it grows beyond the initial estimate.
可以在調用media_entity_init之前或之後初始化media_entity name, type, flags，revision和group_id字段。 嵌入在較高級別標準結構中的實體可以具有由較高級別框架設置其中的某些字段。
由於pad的數目是預先已知的，所以pad陣列不是動態分配的，而是由實體驅動器管理。 大多數驅動程序會將驅動程序陣列嵌入到驅動程序特定的結構中，從而避免動態分配。
驅動程序必須在調用media_entity_init之前設置pad數組中每個pad的方向。 該功能將初始化其他pad字段。
與pad的數量不同，鏈接的總數不總是由實體驅動程序預先知道。 作爲初始估計，media_entity_init預分配等於襯墊數量的鏈路數量加上可選數量的額外鏈路。如果鏈路數組增長超過初始估計，它將被重新分配。
Driversregister entities with a media device by calling
驅動程序通過下面調用向媒體設備註冊實體
media_device_register_entity(structmedia_device *mdev,
struct media_entity*entity);
Entitiesare identified by a unique positive integer ID. Drivers can provide an ID by filling the media_entity id fieldprior to registration, or request the media controller framework to assign an ID automatically. Driversthat provide IDs manually mustensure that all IDs are unique. IDs are not guaranteed to be contiguous even when they are all assignedautomatically by the framework.
實體由唯一的正整數ID標識。 驅動程序可以在註冊之前填充media_entity id字段來提供ID，或者請求媒體控制器框架自動分配ID。 手動提供ID的驅動程序必須確保所有ID是唯一的。 ID不能保證是連續的，即使它們都由框架自動分配。
Driversunregister entities by calling
驅動程序通過調用註銷實體
media_device_unregister_entity(structmedia_entity *entity);
Unregisteringan entity will not change the IDs of the other entities, and the ID will never be reused for a newlyregistered entity.
Whena media device is unregistered, all its entities are unregistered automatically. No manual entitiesunregistration is then required.
註銷實體不會更改其他實體的ID，並且ID將永遠不會重新用於新註冊的實體。
當媒體設備未註冊時，其所有實體都將自動取消註冊。 不需要手動實體註銷。
Driversfree resources associated with an entity by calling
驅動程序通過調用與實體相關聯的自由資源
media_entity_cleanup（structmedia_entity * entity）;
Thisfunction must be called during the cleanup phase after unregistering the entity. Note that the media_entityinstance itself must be freed explicitly by the driver if required.
在註銷實體後，必須在清除階段調用此函數。請注意，如果需要，驅動程序必須顯式釋放media_entity實例本身。
Entitieshave flags that describe the entity capabilities and state.
實體具有描述實體能力和狀態的標誌。
MEDIA_ENT_FL_DEFAULT indicates the default entity for a given type. This can be used to report the defaultaudio and video devices or the default camera sensor.
MEDIA_ENT_FL_DEFAULT表示給定類型的默認實體。這可用於報告默認的音頻和視頻設備或默認相機傳感器。
Logicalentity groups can be defined by setting the group ID of all member entities to the same non-zero value. Anentity group serves no purpose in the kernel, but is reported to userspace during entities enumeration.The group_id field belongs tothe media device driver and must not by touched by entity drivers.
Mediadevice drivers should define groups if several entities are logically bound together. Example usages includereporting
- ALSA, VBI and video nodes that carry the same media stream
- lens and flash controllers associated with a sensor
邏輯實體組可以通過將所有成員實體的組ID設置爲相同的非零值來定義。實體組在內核中不起作用，但在實體枚舉期間會報告給用戶空間。 group_id字段屬於媒體設備驅動程序，且不能由實體驅動程序觸摸。
如果幾個實體在邏輯上綁定在一起，媒體設備驅動程序應該定義組。示例用法包括報告
- 攜帶相同媒體流的ALSA，VBI和視頻節點
- 與傳感器相關聯的透鏡和閃光控制器
- Pads
Padsare represented by a struct media_pad instance, defined in include/media/media-entity.h. Each entitystores its pads in a pads array managed by the entity driver. Drivers usually embed the array in a driver-specific structure.
Padsare identified by their entity and their 0-based index in the pads array. Both information are stored in themedia_pad structure, making the media_pad pointer the canonical way to store and pass link references.
Padshave flags that describe the pad capabilities and state.
MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
Oneand only one of MEDIA_PAD_FL_SINK and MEDIA_PAD_FL_SOURCE must be set for each pad.
pad由一個struct media_pad實例表示，在include / media / media-entity.h中定義。 每個實體將其焊盤存儲在由實體驅動器管理的焊盤陣列中。 驅動程序通常將數組嵌入到驅動程序特定的結構中。
pads由其實體和其在pads陣列中的基於0的索引來標識。 這兩個信息都存儲在media_pad結構中，使media_pad指針可以存儲和傳遞鏈接引用的規範方式。
pads具有描述pad的能力和狀態的標誌。
MEDIA_PAD_FL_SINK表示該pad支持目標數據。
MEDIA_PAD_FL_SOURCE表示該pad支持源數據。
必須爲每個pad設置MEDIA_PAD_FL_SINK和MEDIA_PAD_FL_SOURCE中的一個且僅有一個。
- Links
Linksare represented by a struct media_link instance, defined in include/media/media-entity.h. Each entitystores all links originating at or targeting any of its pads in a links array. A given link is thusstored twice, once in thesource entity and once in the target entity. The array is pre-allocated and grows dynamically asneeded.
- 鏈接
鏈接由structmedia_link實例表示，在include / media / media-entity.h中定義。每個實體存儲源自或針對鏈路陣列中的任何其pads的所有鏈路。因此，給定鏈接被存儲兩次，一次在源實體中，一次在目標實體中。數組是預分配並根據需要動態增長。
Driverscreate links by calling
驅動程序通過調用創建鏈接
media_entity_create_link(struct media_entity *source, u16source_pad,
struct media_entity*sink, u16 sink_pad,
u32 flags);
Anentry in the link array of each entity is allocated and stores pointers to source and sink pads.
Linkshave flags that describe the link capabilities and state.
每個實體的鏈接陣列中的條目被分配並且存儲指向源和接收pads的指針。
鏈接具有描述鏈接能力和狀態的標誌。
MEDIA_LNK_FL_ENABLED indicates that the link is enabled and can beused to transfer media data.When two or more links target a sink pad, only one of them can be enabled at a time.
MEDIA_LNK_FL_IMMUTABLE indicates that the link enabled state can'tbe modified at runtime. IfMEDIA_LNK_FL_IMMUTABLE is set, then MEDIA_LNK_FL_ENABLED must also be set since an immutable link isalways enabled.
MEDIA_LNK_FL_ENABLED表示鏈接已啓用，可用於傳輸媒體數據。當兩個或更多鏈路以接收器焊盤爲目標時，每次只能啓用其中一個。
MEDIA_LNK_FL_IMMUTABLE指示無法在運行時修改鏈接啓用狀態。如果設置MEDIA_LNK_FL_IMMUTABLE，則由於始終啓用不可變鏈接，因此也必須設置MEDIA_LNK_FL_ENABLED。
