From mboxrd@z Thu Jan 1 00:00:00 1970 From: Sakari Ailus Subject: [PATCH v3 22/23] v4l: fwnode: Update V4L2 fwnode endpoint parsing documentation Date: Thu, 13 Sep 2018 00:29:41 +0300 Message-ID: <20180912212942.19641-23-sakari.ailus@linux.intel.com> References: <20180912212942.19641-1-sakari.ailus@linux.intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: In-Reply-To: <20180912212942.19641-1-sakari.ailus@linux.intel.com> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: linux-media@vger.kernel.org Cc: devicetree@vger.kernel.org, jacopo@jmondi.org, dri-devel@lists.freedesktop.org, slongerbeam@gmail.com, niklas.soderlund@ragnatech.se List-Id: devicetree@vger.kernel.org VGhlIHNlbWFudGljcyBvZiB2NGwyX2Z3bm9kZV9lbmRwb2ludF9wYXJzZSgpIGFuZAp2NGwyX2Z3 bm9kZV9lbmRwb2ludF9hbGxvY19wYXJzZSgpIGhhdmUgY2hhbmdlZCBzbGlnaHRseTogdGhleSBu b3cgdGFrZQp0aGUgYnVzIHR5cGUgZnJvbSB0aGUgdXNlciBhcyB3ZWxsIGFzIGEgZGVmYXVsdCBj b25maWd1cmF0aW9uIGZvciB0aGUgYnVzCnRoYXQgc2hhbGwgcmVmbGVjdCB0aGUgRFQgYmluZGlu ZyBkZWZhdWx0cy4gRG9jdW1lbnQgdGhpcy4KClNpZ25lZC1vZmYtYnk6IFNha2FyaSBBaWx1cyA8 c2FrYXJpLmFpbHVzQGxpbnV4LmludGVsLmNvbT4KVGVzdGVkLWJ5OiBTdGV2ZSBMb25nZXJiZWFt IDxzdGV2ZV9sb25nZXJiZWFtQG1lbnRvci5jb20+Ci0tLQogaW5jbHVkZS9tZWRpYS92NGwyLWZ3 bm9kZS5oIHwgNTYgKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrLS0tLS0tLS0tLS0tLS0t CiAxIGZpbGUgY2hhbmdlZCwgMzcgaW5zZXJ0aW9ucygrKSwgMTkgZGVsZXRpb25zKC0pCgpkaWZm IC0tZ2l0IGEvaW5jbHVkZS9tZWRpYS92NGwyLWZ3bm9kZS5oIGIvaW5jbHVkZS9tZWRpYS92NGwy LWZ3bm9kZS5oCmluZGV4IDFlYTFhM2VjZjZkNS4uYjRhNDljYTI3NTc5IDEwMDY0NAotLS0gYS9p bmNsdWRlL21lZGlhL3Y0bDItZndub2RlLmgKKysrIGIvaW5jbHVkZS9tZWRpYS92NGwyLWZ3bm9k ZS5oCkBAIC0xMzEsMjEgKzEzMSwzMCBAQCBzdHJ1Y3QgdjRsMl9md25vZGVfbGluayB7CiAgKiBA Zndub2RlOiBwb2ludGVyIHRvIHRoZSBlbmRwb2ludCdzIGZ3bm9kZSBoYW5kbGUKICAqIEB2ZXA6 IHBvaW50ZXIgdG8gdGhlIFY0TDIgZndub2RlIGRhdGEgc3RydWN0dXJlCiAgKgotICogQWxsIHBy b3BlcnRpZXMgYXJlIG9wdGlvbmFsLiBJZiBub25lIGFyZSBmb3VuZCwgd2UgZG9uJ3Qgc2V0IGFu eSBmbGFncy4gVGhpcwotICogbWVhbnMgdGhlIHBvcnQgaGFzIGEgc3RhdGljIGNvbmZpZ3VyYXRp b24gYW5kIG5vIHByb3BlcnRpZXMgaGF2ZSB0byBiZQotICogc3BlY2lmaWVkIGV4cGxpY2l0bHku IElmIGFueSBwcm9wZXJ0aWVzIHRoYXQgaWRlbnRpZnkgdGhlIGJ1cyBhcyBwYXJhbGxlbAotICog YXJlIGZvdW5kIGFuZCBzbGF2ZS1tb2RlIGlzbid0IHNldCwgd2Ugc2V0IFY0TDJfTUJVU19NQVNU RVIuIFNpbWlsYXJseSwgaWYKLSAqIHdlIHJlY29nbmlzZSB0aGUgYnVzIGFzIHNlcmlhbCBDU0kt MiBhbmQgY2xvY2stbm9uY29udGludW91cyBpc24ndCBzZXQsIHdlCi0gKiBzZXQgdGhlIFY0TDJf TUJVU19DU0kyX0NPTlRJTlVPVVNfQ0xPQ0sgZmxhZy4gVGhlIGNhbGxlciBzaG91bGQgaG9sZCBh Ci0gKiByZWZlcmVuY2UgdG8gQGZ3bm9kZS4KLSAqCi0gKiBUaGUgY2FsbGVyIG11c3Qgc2V0IHRo ZSBidXNfdHlwZSBmaWVsZCBvZiBAdmVwIHRvIHplcm8uCisgKiBUaGlzIGZ1bmN0aW9uIHBhcnNl cyB0aGUgVjRMMiBmd25vZGUgZW5kcG9pbnQgc3BlY2lmaWMgcGFyYW1ldGVycyBmcm9tIHRoZQor ICogZmlybXdhcmUuIFRoZSBjYWxsZXIgaXMgcmVzcG9uc2libGUgZm9yIGFzc2lnbmluZyBAdmVw LmJ1c190eXBlIHRvIGEgdmFsaWQKKyAqIG1lZGlhIGJ1cyB0eXBlLiBUaGUgY2FsbGVyIG1heSBh bHNvIHNldCB0aGUgZGVmYXVsdCBjb25maWd1cmF0aW9uIGZvciB0aGUKKyAqIGVuZHBvaW50IC0t LSBhIGNvbmZpZ3VyYXRpb24gdGhhdCBzaGFsbCBiZSBpbiBsaW5lIHdpdGggdGhlIERUIGJpbmRp bmcKKyAqIGRvY3VtZW50YXRpb24uIFNob3VsZCBhIGRldmljZSBzdXBwb3J0IG11bHRpcGxlIGJ1 cyB0eXBlcywgdGhlIGNhbGxlciBtYXkKKyAqIGNhbGwgdGhpcyBmdW5jdGlvbiBvbmNlIHRoZSBj b3JyZWN0IHR5cGUgaXMgZm91bmQgLS0tIHdpdGggYSBkZWZhdWx0CisgKiBjb25maWd1cmF0aW9u IHZhbGlkIGZvciB0aGF0IHR5cGUuCisgKgorICogQXMgYSBjb21wYXRpYmlsaXR5IG1lYW5zIGd1 ZXNzaW5nIHRoZSBidXMgdHlwZSBpcyBhbHNvIHN1cHBvcnRlZCBieSBzZXR0aW5nCisgKiBAdmVw LmJ1c190eXBlIHRvIFY0TDJfTUJVU19VTktOT1dOLiBUaGUgY2FsbGVyIG1heSBub3QgcHJvdmlk ZSBhIGRlZmF1bHQKKyAqIGNvbmZpZ3VyYXRpb24gaW4gdGhpcyBjYXNlIGFzIHRoZSBkZWZhdWx0 cyBhcmUgc3BlY2lmaWMgdG8gYSBnaXZlbiBidXMgdHlwZS4KKyAqIFRoaXMgZnVuY3Rpb25hbGl0 eSBpcyBkZXByZWNhdGVkIGFuZCBzaG91bGQgbm90IGJlIHVzZWQgaW4gbmV3IGRyaXZlcnMgYW5k IGl0CisgKiBpcyBvbmx5IHN1cHBvcnRlZCBmb3IgQ1NJLTIgRC1QSFksIHBhcmFsbGVsIGFuZCBC dC42NTYgYnVzc2VzLgorICoKKyAqIFRoZSBmdW5jdGlvbiBkb2VzIG5vdCBjaGFuZ2UgdGhlIFY0 TDIgZndub2RlIGVuZHBvaW50IHN0YXRlIGlmIGl0IGZhaWxzLgogICoKICAqIE5PVEU6IFRoaXMg ZnVuY3Rpb24gZG9lcyBub3QgcGFyc2UgcHJvcGVydGllcyB0aGUgc2l6ZSBvZiB3aGljaCBpcyB2 YXJpYWJsZQogICogd2l0aG91dCBhIGxvdyBmaXhlZCBsaW1pdC4gUGxlYXNlIHVzZSB2NGwyX2Z3 bm9kZV9lbmRwb2ludF9hbGxvY19wYXJzZSgpIGluCiAgKiBuZXcgZHJpdmVycyBpbnN0ZWFkLgog ICoKLSAqIFJldHVybjogMCBvbiBzdWNjZXNzIG9yIGEgbmVnYXRpdmUgZXJyb3IgY29kZSBvbiBm YWlsdXJlLgorICogUmV0dXJuOiAlMCBvbiBzdWNjZXNzIG9yIGEgbmVnYXRpdmUgZXJyb3IgY29k ZSBvbiBmYWlsdXJlOgorICoJICAgJS1FTk9NRU0gb24gbWVtb3J5IGFsbG9jYXRpb24gZmFpbHVy ZQorICoJICAgJS1FSU5WQUwgb24gcGFyc2luZyBmYWlsdXJlCisgKgkgICAlLUVOWElPIG9uIG1p c21hdGNoaW5nIGJ1cyB0eXBlcwogICovCiBpbnQgdjRsMl9md25vZGVfZW5kcG9pbnRfcGFyc2Uo c3RydWN0IGZ3bm9kZV9oYW5kbGUgKmZ3bm9kZSwKIAkJCSAgICAgICBzdHJ1Y3QgdjRsMl9md25v ZGVfZW5kcG9pbnQgKnZlcCk7CkBAIC0xNjUsMTUgKzE3NCwyMSBAQCB2b2lkIHY0bDJfZndub2Rl X2VuZHBvaW50X2ZyZWUoc3RydWN0IHY0bDJfZndub2RlX2VuZHBvaW50ICp2ZXApOwogICogQGZ3 bm9kZTogcG9pbnRlciB0byB0aGUgZW5kcG9pbnQncyBmd25vZGUgaGFuZGxlCiAgKiBAdmVwOiBw b2ludGVyIHRvIHRoZSBWNEwyIGZ3bm9kZSBkYXRhIHN0cnVjdHVyZQogICoKLSAqIEFsbCBwcm9w ZXJ0aWVzIGFyZSBvcHRpb25hbC4gSWYgbm9uZSBhcmUgZm91bmQsIHdlIGRvbid0IHNldCBhbnkg ZmxhZ3MuIFRoaXMKLSAqIG1lYW5zIHRoZSBwb3J0IGhhcyBhIHN0YXRpYyBjb25maWd1cmF0aW9u IGFuZCBubyBwcm9wZXJ0aWVzIGhhdmUgdG8gYmUKLSAqIHNwZWNpZmllZCBleHBsaWNpdGx5LiBJ ZiBhbnkgcHJvcGVydGllcyB0aGF0IGlkZW50aWZ5IHRoZSBidXMgYXMgcGFyYWxsZWwKLSAqIGFy ZSBmb3VuZCBhbmQgc2xhdmUtbW9kZSBpc24ndCBzZXQsIHdlIHNldCBWNEwyX01CVVNfTUFTVEVS LiBTaW1pbGFybHksIGlmCi0gKiB3ZSByZWNvZ25pc2UgdGhlIGJ1cyBhcyBzZXJpYWwgQ1NJLTIg YW5kIGNsb2NrLW5vbmNvbnRpbnVvdXMgaXNuJ3Qgc2V0LCB3ZQotICogc2V0IHRoZSBWNEwyX01C VVNfQ1NJMl9DT05USU5VT1VTX0NMT0NLIGZsYWcuIFRoZSBjYWxsZXIgc2hvdWxkIGhvbGQgYQot ICogcmVmZXJlbmNlIHRvIEBmd25vZGUuCisgKiBUaGlzIGZ1bmN0aW9uIHBhcnNlcyB0aGUgVjRM MiBmd25vZGUgZW5kcG9pbnQgc3BlY2lmaWMgcGFyYW1ldGVycyBmcm9tIHRoZQorICogZmlybXdh cmUuIFRoZSBjYWxsZXIgaXMgcmVzcG9uc2libGUgZm9yIGFzc2lnbmluZyBAdmVwLmJ1c190eXBl IHRvIGEgdmFsaWQKKyAqIG1lZGlhIGJ1cyB0eXBlLiBUaGUgY2FsbGVyIG1heSBhbHNvIHNldCB0 aGUgZGVmYXVsdCBjb25maWd1cmF0aW9uIGZvciB0aGUKKyAqIGVuZHBvaW50IC0tLSBhIGNvbmZp Z3VyYXRpb24gdGhhdCBzaGFsbCBiZSBpbiBsaW5lIHdpdGggdGhlIERUIGJpbmRpbmcKKyAqIGRv Y3VtZW50YXRpb24uIFNob3VsZCBhIGRldmljZSBzdXBwb3J0IG11bHRpcGxlIGJ1cyB0eXBlcywg dGhlIGNhbGxlciBtYXkKKyAqIGNhbGwgdGhpcyBmdW5jdGlvbiBvbmNlIHRoZSBjb3JyZWN0IHR5 cGUgaXMgZm91bmQgLS0tIHdpdGggYSBkZWZhdWx0CisgKiBjb25maWd1cmF0aW9uIHZhbGlkIGZv ciB0aGF0IHR5cGUuCisgKgorICogQXMgYSBjb21wYXRpYmlsaXR5IG1lYW5zIGd1ZXNzaW5nIHRo ZSBidXMgdHlwZSBpcyBhbHNvIHN1cHBvcnRlZCBieSBzZXR0aW5nCisgKiBAdmVwLmJ1c190eXBl IHRvIFY0TDJfTUJVU19VTktOT1dOLiBUaGUgY2FsbGVyIG1heSBub3QgcHJvdmlkZSBhIGRlZmF1 bHQKKyAqIGNvbmZpZ3VyYXRpb24gaW4gdGhpcyBjYXNlIGFzIHRoZSBkZWZhdWx0cyBhcmUgc3Bl Y2lmaWMgdG8gYSBnaXZlbiBidXMgdHlwZS4KKyAqIFRoaXMgZnVuY3Rpb25hbGl0eSBpcyBkZXBy ZWNhdGVkIGFuZCBzaG91bGQgbm90IGJlIHVzZWQgaW4gbmV3IGRyaXZlcnMgYW5kIGl0CisgKiBp cyBvbmx5IHN1cHBvcnRlZCBmb3IgQ1NJLTIgRC1QSFksIHBhcmFsbGVsIGFuZCBCdC42NTYgYnVz c2VzLgogICoKLSAqIFRoZSBjYWxsZXIgbXVzdCBzZXQgdGhlIGJ1c190eXBlIGZpZWxkIG9mIEB2 ZXAgdG8gemVyby4KKyAqIFRoZSBmdW5jdGlvbiBkb2VzIG5vdCBjaGFuZ2UgdGhlIFY0TDIgZndu b2RlIGVuZHBvaW50IHN0YXRlIGlmIGl0IGZhaWxzLgogICoKICAqIHY0bDJfZndub2RlX2VuZHBv aW50X2FsbG9jX3BhcnNlKCkgaGFzIHR3byBpbXBvcnRhbnQgZGlmZmVyZW5jZXMgdG8KICAqIHY0 bDJfZndub2RlX2VuZHBvaW50X3BhcnNlKCk6CkBAIC0xODMsNyArMTk4LDEwIEBAIHZvaWQgdjRs Ml9md25vZGVfZW5kcG9pbnRfZnJlZShzdHJ1Y3QgdjRsMl9md25vZGVfZW5kcG9pbnQgKnZlcCk7 CiAgKiAyLiBUaGUgbWVtb3J5IGl0IGhhcyBhbGxvY2F0ZWQgdG8gc3RvcmUgdGhlIHZhcmlhYmxl IHNpemUgZGF0YSBtdXN0IGJlIGZyZWVkCiAgKiAgICB1c2luZyB2NGwyX2Z3bm9kZV9lbmRwb2lu dF9mcmVlKCkgd2hlbiBubyBsb25nZXIgbmVlZGVkLgogICoKLSAqIFJldHVybjogMCBvbiBzdWNj ZXNzIG9yIGEgbmVnYXRpdmUgZXJyb3IgY29kZSBvbiBmYWlsdXJlLgorICogUmV0dXJuOiAlMCBv biBzdWNjZXNzIG9yIGEgbmVnYXRpdmUgZXJyb3IgY29kZSBvbiBmYWlsdXJlOgorICoJICAgJS1F Tk9NRU0gb24gbWVtb3J5IGFsbG9jYXRpb24gZmFpbHVyZQorICoJICAgJS1FSU5WQUwgb24gcGFy c2luZyBmYWlsdXJlCisgKgkgICAlLUVOWElPIG9uIG1pc21hdGNoaW5nIGJ1cyB0eXBlcwogICov CiBpbnQgdjRsMl9md25vZGVfZW5kcG9pbnRfYWxsb2NfcGFyc2UoCiAJc3RydWN0IGZ3bm9kZV9o YW5kbGUgKmZ3bm9kZSwgc3RydWN0IHY0bDJfZndub2RlX2VuZHBvaW50ICp2ZXApOwotLSAKMi4x MS4wCgpfX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fXwpkcmkt ZGV2ZWwgbWFpbGluZyBsaXN0CmRyaS1kZXZlbEBsaXN0cy5mcmVlZGVza3RvcC5vcmcKaHR0cHM6 Ly9saXN0cy5mcmVlZGVza3RvcC5vcmcvbWFpbG1hbi9saXN0aW5mby9kcmktZGV2ZWwK From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from nblzone-211-213.nblnetworks.fi ([83.145.211.213]:40966 "EHLO hillosipuli.retiisi.org.uk" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728237AbeIMCgM (ORCPT ); Wed, 12 Sep 2018 22:36:12 -0400 From: Sakari Ailus To: linux-media@vger.kernel.org Cc: devicetree@vger.kernel.org, slongerbeam@gmail.com, niklas.soderlund@ragnatech.se, jacopo@jmondi.org, p.zabel@pengutronix.de, dri-devel@lists.freedesktop.org Subject: [PATCH v3 22/23] v4l: fwnode: Update V4L2 fwnode endpoint parsing documentation Date: Thu, 13 Sep 2018 00:29:41 +0300 Message-Id: <20180912212942.19641-23-sakari.ailus@linux.intel.com> In-Reply-To: <20180912212942.19641-1-sakari.ailus@linux.intel.com> References: <20180912212942.19641-1-sakari.ailus@linux.intel.com> Sender: linux-media-owner@vger.kernel.org List-ID: The semantics of v4l2_fwnode_endpoint_parse() and v4l2_fwnode_endpoint_alloc_parse() have changed slightly: they now take the bus type from the user as well as a default configuration for the bus that shall reflect the DT binding defaults. Document this. Signed-off-by: Sakari Ailus Tested-by: Steve Longerbeam --- include/media/v4l2-fwnode.h | 56 ++++++++++++++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 19 deletions(-) diff --git a/include/media/v4l2-fwnode.h b/include/media/v4l2-fwnode.h index 1ea1a3ecf6d5..b4a49ca27579 100644 --- a/include/media/v4l2-fwnode.h +++ b/include/media/v4l2-fwnode.h @@ -131,21 +131,30 @@ struct v4l2_fwnode_link { * @fwnode: pointer to the endpoint's fwnode handle * @vep: pointer to the V4L2 fwnode data structure * - * All properties are optional. If none are found, we don't set any flags. This - * means the port has a static configuration and no properties have to be - * specified explicitly. If any properties that identify the bus as parallel - * are found and slave-mode isn't set, we set V4L2_MBUS_MASTER. Similarly, if - * we recognise the bus as serial CSI-2 and clock-noncontinuous isn't set, we - * set the V4L2_MBUS_CSI2_CONTINUOUS_CLOCK flag. The caller should hold a - * reference to @fwnode. - * - * The caller must set the bus_type field of @vep to zero. + * This function parses the V4L2 fwnode endpoint specific parameters from the + * firmware. The caller is responsible for assigning @vep.bus_type to a valid + * media bus type. The caller may also set the default configuration for the + * endpoint --- a configuration that shall be in line with the DT binding + * documentation. Should a device support multiple bus types, the caller may + * call this function once the correct type is found --- with a default + * configuration valid for that type. + * + * As a compatibility means guessing the bus type is also supported by setting + * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default + * configuration in this case as the defaults are specific to a given bus type. + * This functionality is deprecated and should not be used in new drivers and it + * is only supported for CSI-2 D-PHY, parallel and Bt.656 busses. + * + * The function does not change the V4L2 fwnode endpoint state if it fails. * * NOTE: This function does not parse properties the size of which is variable * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() in * new drivers instead. * - * Return: 0 on success or a negative error code on failure. + * Return: %0 on success or a negative error code on failure: + * %-ENOMEM on memory allocation failure + * %-EINVAL on parsing failure + * %-ENXIO on mismatching bus types */ int v4l2_fwnode_endpoint_parse(struct fwnode_handle *fwnode, struct v4l2_fwnode_endpoint *vep); @@ -165,15 +174,21 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep); * @fwnode: pointer to the endpoint's fwnode handle * @vep: pointer to the V4L2 fwnode data structure * - * All properties are optional. If none are found, we don't set any flags. This - * means the port has a static configuration and no properties have to be - * specified explicitly. If any properties that identify the bus as parallel - * are found and slave-mode isn't set, we set V4L2_MBUS_MASTER. Similarly, if - * we recognise the bus as serial CSI-2 and clock-noncontinuous isn't set, we - * set the V4L2_MBUS_CSI2_CONTINUOUS_CLOCK flag. The caller should hold a - * reference to @fwnode. + * This function parses the V4L2 fwnode endpoint specific parameters from the + * firmware. The caller is responsible for assigning @vep.bus_type to a valid + * media bus type. The caller may also set the default configuration for the + * endpoint --- a configuration that shall be in line with the DT binding + * documentation. Should a device support multiple bus types, the caller may + * call this function once the correct type is found --- with a default + * configuration valid for that type. + * + * As a compatibility means guessing the bus type is also supported by setting + * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default + * configuration in this case as the defaults are specific to a given bus type. + * This functionality is deprecated and should not be used in new drivers and it + * is only supported for CSI-2 D-PHY, parallel and Bt.656 busses. * - * The caller must set the bus_type field of @vep to zero. + * The function does not change the V4L2 fwnode endpoint state if it fails. * * v4l2_fwnode_endpoint_alloc_parse() has two important differences to * v4l2_fwnode_endpoint_parse(): @@ -183,7 +198,10 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep); * 2. The memory it has allocated to store the variable size data must be freed * using v4l2_fwnode_endpoint_free() when no longer needed. * - * Return: 0 on success or a negative error code on failure. + * Return: %0 on success or a negative error code on failure: + * %-ENOMEM on memory allocation failure + * %-EINVAL on parsing failure + * %-ENXIO on mismatching bus types */ int v4l2_fwnode_endpoint_alloc_parse( struct fwnode_handle *fwnode, struct v4l2_fwnode_endpoint *vep); -- 2.11.0