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

[Amaan Cheval]

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.)

>
>
> 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

>>
>>
>> > 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
>> >
>
>