Why <= then >>=?
why not just <?

Are we going to remove hashinit_flags and hashdestroy as well?
We just updated them to use the new KPI, and we inform users that we plan to obsolete them at the same time.
If that's not the case, IMHO, we should include them in the new manual.
Otherwise, we should put a deprecation warning above their functions.

style?

style?

SPDX tag?

Usually contiguous means "physically contiguous" in the kernel (e.g. contigmalloc). malloc() always returns virtually contiguous memory, so if you are only talking about virtual contiguous here, I would remove the word to avoid confusion.

If you make slot and men of type char * instead of void * you can avoid all the char * casts. char * is the pointer spelling of uintptr_t as it were.

Can args be const here? That would clarify that hashfree can't return an error.

This follows exactly logic of hashinit(9):

The hashinit() function allocates hash tables that are sized to largest power of two less than or equal to argument nelements.

And new API offers the same wording. With suggested code we would create a power of two that is greater or equal.

From the hashinit(9) it is not actually clear what they meant with nelements - hash slots or objects stored in the hash? Most modern code treats as the former. But it could be that original logic was that nelements is expected number of objects. In that case logic makes sense, as we don't want guaranteed underfilled hashes. For example, nelements = 5 shall yield in size 4 hash not in size 8.

Pouria, I strongly disagreed with the part of style(9) that suggest to put all variable declarations to the top of the function. And if I remember correct this demand from the style.7 was finally removed.

I find a code much easier to read when variables are limited in their visibility scope. This also sends a hint to any future editor of the code, that the variable is supposed to have a limited visibility for a reason.

John, this can be done for hashalloc() easily and for hashfree() we would need an extra local variable to recast the argument from void *. I can do it if you insist.

But, IMHO, if I give you three code snippets without any extra context, and you need to guess the types and guess what the coder wanted to achieve:

header = header + i * hdrsize;

slot = (char *)mem + i * hdrsize;

slot = mem + i * hdrsize;

, then in the first two cases the result will be obvious to you and in the very last case it will be not. What I'm trying to tell is that (char *)s here are improving readability :) But if you insist, I can do that.

Right now hashfree() may change args->hdrsize, as it calls hashalloc_sizes(). With extra coding this can be avoided, of course.

I do not see a value to put const into API here. The structure is supposed to be opaque to the caller and is not supposed to be used with anything else except this API. Not to be shares with anything else. What value would constness give?

The hashmask or table size is the nature of a hash table. It requires the users to provide the storage of hashmask.

I like this one,

/* Fixed sized hash table */
struct hashtable {
	long hashsize, /* hashmask ? */
	struct {
		LIST_HEAD(generic, generic) head,
		struct mtx          lock,
	} buckets[],
};

void
hashalloc(int elements, struct malloc_type *type, int flags)
{
...
	struct hashtable *tbl = malloc( ... );
	
	tlb->hashsize = hashsize;
	return (tlb);
}

void
hash_init(struct hashtable *tbl)
{

	long hashsize = tlb->hashsize;
	for (i = 0; i < hashsize; i++) {
		LIST_INIT();
		mtx_init();
	}
}

void
hash_destroy(struct hashtable *tbl)
{

	long hashsize = tlb->hashsize;
	for (i = 0; i < hashsize; i++) {
		/* ASSERT LIST_EMPTY */
		mtx_destroy();
	}
}

The size of CK_LIST_HEAD is same with LIST_HEAD. But this design does not meet other usage, say SLIST_HEAD.

For the lock, the a mutex should be sufficient, given it is to protect the bucket only. I'm not sure if other lock type ( say sx ) is required.

All in tree consumers store the size(or mask) separately from the table. There are consumers that create several hash tables of the same size.

If some module (e.g. your module) really wants to join the array of headers and size in one struct, the KPI doesn't forbid that. You can declare the structure in your module and hashalloc() only the table, and store the size.

The size of CK_LIST_HEAD is same with LIST_HEAD. But this design does not meet other usage, say SLIST_HEAD.

Sorry, can't understand this comment. The design supports SLIST_HEAD.

For the lock, the a mutex should be sufficient, given it is to protect the bucket only. I'm not sure if other lock type ( say sx ) is required.

I already see use for rwlocks here. The other locks is what @gallatin suggested. I don't see any problem with adding this support.