[PATCH 0/1] [GSoC - x86_64] User documentation for BSP

Wed Jul 18 13:26:46 UTC 2018

On Wed, Jul 18, 2018 at 9:09 AM, Amaan Cheval <amaan.cheval at gmail.com> wrote:
> Hi!
>
> On Fri, Jul 13, 2018 at 7:32 PM, Joel Sherrill <joel at rtems.org> wrote:
>>
>>
>> On Fri, Jul 13, 2018 at 8:25 AM, Gedare Bloom <gedare at rtems.org> wrote:
>>>
>>> Hello Amaan,
>>>
>>>
>>> On Fri, Jul 13, 2018 at 3:32 AM, Amaan Cheval <amaan.cheval at gmail.com>
>>> wrote:
>>> > The built documentation can more easily be viewed here:
>>> > http://whatthedude.com/rtems/user/html/bsps/bsps-x86_64.html
>>> >
>>> > It feels a bit convoluted to me at the moment. I'd appreciate feedback
>>> > on how
>>> > the documentation may be made more understandable, and on whether the
>>> > current
>>> > approach even seems sustainable - specifically, using FreeBSD's
>>> > bootloader ties
>>> > us into using the UFS filesystem and can slow down the
>>> > iterative-development
>>> > process.
>>> >
>>> I agree. It looks like you have to build FreeBSD at least one time to
>>> use this? Alternatives should be again considered for iterative
>>> improvement.
>
> That's right, and I agree. The only question is, at what point should
> we consider alternatives? After interrupts and the clock driver work
> is completed, if there's time left, or before (i.e. right now)?
>
> Is this too large a barrier to entry, and we'd rather make it easier
> for future contributors to enter, than to have a more complete BSP
> that users and contributors find to be too much effort to practically
> use?
>
> (I'm asking about priorities assuming that there isn't time to do
> _all_ the work, which may or may not be true.)
>

It is better to have a working basic BSP, even if it is a bit
complicated to build from scratch, and have a roadmap for how to make
it simpler to use.

>>
>>
>> Reducing what has to be built is an important goal. But an alternative is
>> to host a pre-built binary of what is required to boot. I did that for a
>> boot
>> floppy for the pc386. There were instructions for making one and they
>> worked but, in practice, just grabbing the floppy image was easier.
>
> Since we likely need the entire FreeBSD hard disk image, not just its
> loader.efi file, this may be a file that's a GB or more. (I've been
> using 8GB just to be safe, so I don't know how small we can make
> this.)
>
> We need the entire FreeBSD image because their kernel is one of the
> few that lets us mount a UFS/ZFS filesystem as read-write (which are
> the only filesystems their loader supports loading the kernel from).
>
> IMO, looking for an alternate solution may well be for the best, but I
> also think it can wait until after we have interrupts and the clock
> driver.
>
> Roughly in the order listed here:
> https://blog.whatthedude.com/post/gsoc-phase-2-status/#upcoming
>
>>
>> Note; you didn't need to use a real floppy. Telling qemu what file
>> was the 1.44 MB image was all that was needed. Combine that with
>> vfat for c: and it worked find.
>>
>> So I think we need both -- RSB for building from source and a pre-built
>> binary.
>>
>>>
>>>
>>> > In my opinion, this system is good _enough_ for now - we can explore
>>> > other
>>> > options later if time permits, but I'd love to hear differing opinions.
>>> >
>>> > P.S. - Joel asked earlier if the QEMU that the RSB builds will suffice -
>>> > for me,
>>> > it didn't because in it "SDL support is disabled" (and so are all other
>>> > graphics
>>> > options). It's likely possible to install FreeBSD without graphics, it
>>> > may not
>>> > be worth the effort of setting up - it's likely easier to update the
>>> > RSB's QEMU
>>> > to also build graphics support.
>>> >
>>> I was going to recommend this. You can make it an option of the qemu
>>> configuration in RSB to enable the support needed. I suggest you talk
>>> to Vijay as he has some experience now with RSB, and also this will
>>> require Chris Johns approval.
>>
>>
>> Everything that wasn't needed was disabled to make it easier to build
>> on multiple hosts. Too many projects are Linux monoculture and
>> getting things built on multiple hosts can be a pain.
>>
>> But I think SDL support needs to be enabled since otherwise we have
>> no way to test graphics at all.
>>
>>>
>>>
>>> Relatedly, does it make sense for you to look at creating an RSB
>>> "recipe" for building the UEFI firmware?
>>
>>
>> See above. I think we need RSB recipes for everything required that
>> we expect to be put together by a user. And we should host binaries
>> along with matching sources for some pre-built versions. I don't want
>> this BSP to be an order of magnitude harder to get started with than
>> any of the others.
>
> +1.
>
>>>
>>>
>>> > P.P.S. - Some of the documentation is double-spaced, but this patch
>>> > isn't. Let me
>>> > know if it ought to be (the README didn't say anything of the sort, and
>>> > it isn't
>>> > consistent throughout).
>>> >
>>>
>>> Stick to one consistent approach within your chapters. If consistency
>>> needs to be dealt with across chapters in a manual or across the set
>>> of manuals, that can be done later and simpler if each chapter is
>>> internally consistent.
>>
>>
>> How did some documentation get to be double-spaced? I thought we
>> had a consistent style of single space or something like 1.5. I have
>> never even thought of changing the line spacing and don't know how. :)
>>
>> Sounds like we need to look at fixing the inconsistent places.
>
> I meant that the source file has 2 spaces after punctuation in some
> places - for eg.
> https://git.rtems.org/rtems-docs/tree/user/bsps/bsps-arm.rst#n10
>

I would just try to be consistent. Can you tell if the extra spaces
get typeset? Many typesetters will ignore multiple blank spaces,
compressing them into one space character, or one newline in case of
multiple blank lines.

>>>
>>>
>>> > Amaan Cheval (1):
>>> >   user: Add x86_64 BSP chapter
>>> >
>>> >  user/bsps/bsps-x86_64.rst | 143
>>> > +++++++++++++++++++++++++++++++++++++++++++++-
>>> >  1 file changed, 142 insertions(+), 1 deletion(-)
>>> >
>>> > --
>>> > 2.16.0.rc0
>>> >
>>
>>