Re: [PATCH v5 09/26] rust: alloc: implement kernel `Box`

[Danilo Krummrich <dakr@kernel.org>]

On 8/15/24 4:10 PM, Benno Lossin wrote:
> On 15.08.24 16:00, Danilo Krummrich wrote:
>> On Thu, Aug 15, 2024 at 01:24:47PM +0000, Benno Lossin wrote:
>>> On 14.08.24 23:58, Danilo Krummrich wrote:
>>>> On Wed, Aug 14, 2024 at 05:01:34PM +0000, Benno Lossin wrote:
>>>>> On 12.08.24 20:22, Danilo Krummrich wrote:
>>>>>> +///
>>>>>> +/// # Examples
>>>>>> +///
>>>>>> +/// ```
>>>>>> +/// let b = KBox::new(24_u64, GFP_KERNEL)?;
>>>>>> +///
>>>>>> +/// assert_eq!(*b, 24_u64);
>>>>>> +///
>>>>>> +/// # Ok::<(), Error>(())
>>>>>> +/// ```
>>>>>> +pub type KBox<T> = Box<T, super::allocator::Kmalloc>;
>>>>>> +
>>>>>> +/// Type alias for `Box` with a `Vmalloc` allocator.
>>>>>
>>>>> Same here, add that this is supposed to be used for big values (or is
>>>>> this also a general-purpose allocator, just not guaranteeing that the
>>>>> memory is physically contiguous? in that case I would document it
>>>>> here and also on `Vmalloc`).
>>>>
>>>> Same as above, I'd rather not duplicate that. But I'm happy to link things in,
>>>> just not sure what's the best way doing it.
>>>
>>> I took a look at the link and there is the "Selecting memory allocator"
>>> section, but there isn't really just a vmalloc or kmalloc section, it is
>>> rather stuff that we would put in the module documentation.
>>
>> There are no dedicated sections, but...
>>
>>> What I would write on these types would be what to use these boxes for.
>>> eg large allocations, general purpose etc. I don't think that that is
>>> easily accessible from the docs that you linked above.
>>
>> ...this stuff should be covered by the document, e.g.:
>>
>> "The maximal size of a chunk that can be allocated with kmalloc is limited. The
>> actual limit depends on the hardware and the kernel configuration, but it is a
>> good practice to use kmalloc for objects smaller than page size."
>>
>> or
>>
>> "For large allocations you can use vmalloc() and vzalloc(), or directly request
>> pages from the page allocator. The memory allocated by vmalloc and related
>> functions is not physically contiguous."
> 
> Yeah, but for that you have to read big chunks of the document and item
> docs in Rust are often very short, since you only need to know what that
> one item does.

In this specific case I'd argue that the contents of this document should be
read and understood by everyone who attempts to write kernel code anyways,
hence linking it should be fine.

> Would be a good idea to talk about how we can improve this at Kangrejos.
> 
> ---
> Cheers,
> Benno
>