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

Wed Jul 18 13:59:58 UTC 2018

On Wed, Jul 18, 2018 at 6:56 PM, Gedare Bloom <gedare at rtems.org> wrote:
> 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.
>

Gotcha, thanks.

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

Most of the others weren't double-spaced in the source, so my patch
isn't either.
In this one instance, the spaces do get compressed when typeset, so
the final result is consistent regardless.

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