Hi Thomas,
On 19/07/2016 16:38, Thomas Gleixner wrote:
> On Tue, 19 Jul 2016, Eric Auger wrote:
>> msi_doorbell_pages sum up the number of iommu pages of a given order
>
> adding () to the function name would make it immediately clear that
> msi_doorbell_pages is a function.
>
>> +/**
>> + * msi_doorbell_pages: compute the number of iommu pages of size 1 << order
>> + * requested to map all the registered doorbells
>> + *
>> + * @order: iommu page order
>> + */
>
> Why are you adding the kernel doc to the header and not to the implementation?
I am confused by this comment. I was told in the past that it was better
to put the comments in the API header. On your side do you want me to
move all function kernel-doc comments to the implementation.
Looking at kernel-doc-nano-HOWTO.txt, I was not able to find any
indication about the best choice.
I will now run the kernel-doc script to check the conformance of my
comments.
Thank you for your patience!
Best Regards
Eric
>
>> +int msi_doorbell_pages(unsigned int order);
>> +
>> #else
>>
>> static inline struct irq_chip_msi_doorbell_info *
>> @@ -47,6 +55,12 @@ msi_doorbell_register_global(phys_addr_t base, size_t size,
>> static inline void
>> msi_doorbell_unregister_global(struct irq_chip_msi_doorbell_info *db) {}
>>
>> +static inline int
>> +msi_doorbell_pages(unsigned int order)
>
> What's the point of this line break?
>
>> +{
>> + return 0;
>> +}
>> +
>> #endif /* CONFIG_MSI_DOORBELL */
>>
>> #endif
>> diff --git a/kernel/irq/msi-doorbell.c b/kernel/irq/msi-doorbell.c
>> index 0ff541e..a5bde37 100644
>> --- a/kernel/irq/msi-doorbell.c
>> +++ b/kernel/irq/msi-doorbell.c
>> @@ -60,3 +60,55 @@ void msi_doorbell_unregister_global(struct irq_chip_msi_doorbell_info *dbinfo)
>> mutex_unlock(&irqchip_doorbell_mutex);
>> }
>> EXPORT_SYMBOL_GPL(msi_doorbell_unregister_global);
>> +
>> +static int compute_db_mapping_requirements(phys_addr_t addr, size_t size,
>> + unsigned int order)
>> +{
>> + phys_addr_t offset, granule;
>> + unsigned int nb_pages;
>> +
>> + granule = (uint64_t)(1 << order);
>> + offset = addr & (granule - 1);
>> + size = ALIGN(size + offset, granule);
>> + nb_pages = size >> order;
>> +
>> + return nb_pages;
>> +}
>> +
>> +static int
>> +compute_dbinfo_mapping_requirements(struct irq_chip_msi_doorbell_info *dbinfo,
>> + unsigned int order)
>
> I'm sure you can find even longer function names which require more line
> breaks.
>
>> +{
>> + int ret = 0;
>> +
>> + if (!dbinfo->doorbell_is_percpu) {
>> + ret = compute_db_mapping_requirements(dbinfo->global_doorbell,
>> + dbinfo->size, order);
>> + } else {
>> + phys_addr_t __percpu *pbase;
>> + int cpu;
>> +
>> + for_each_possible_cpu(cpu) {
>> + pbase = per_cpu_ptr(dbinfo->percpu_doorbells, cpu);
>> + ret += compute_db_mapping_requirements(*pbase,
>> + dbinfo->size,
>> + order);
>> + }
>> + }
>> + return ret;
>> +}
>> +
>> +int msi_doorbell_pages(unsigned int order)
>> +{
>> + struct irqchip_doorbell *db;
>> + int ret = 0;
>> +
>> + mutex_lock(&irqchip_doorbell_mutex);
>> + list_for_each_entry(db, &irqchip_doorbell_list, next) {
>
> Pointless braces
>
>> + ret += compute_dbinfo_mapping_requirements(&db->info, order);
>> + }
>> + mutex_unlock(&irqchip_doorbell_mutex);
>> +
>> + return ret;
>> +}
>> +EXPORT_SYMBOL_GPL(msi_doorbell_pages);
>
> So here is a general rant about your naming choices.
>
> struct irqchip_doorbell
> struct irq_chip_msi_doorbell_info
>
> struct irq_chip {
> .... *(*msi_doorbell_info);
> }
>
> irqchip_doorbell_mutex
>
> msi_doorbell_register_global
> msi_doorbell_unregister_global
>
> msi_doorbell_pages
>
> This really sucks. Your public functions start sensibly with msi_doorbell.
>
> Though what is the _global postfix for the register/unregister functions for?
> Are there _private functions in the pipeline?
>
> msi_doorbell_pages() is not telling me what it does. msi_calc_doorbell_pages()
> would describe it right away.
>
> You doorbell info structure can really do with:
>
> struct msi_doorbell_info;
>
> And the wrapper struct around it is fine with:
>
> struct msi_doorbell;
>
> Thanks,
>
> tglx
>
--
To unsubscribe from this list: send the line "unsubscribe kvm" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
