[Xcb] GSoC,2011

[Josh Triplett]

[A note for future mails: please CC all mails on this project to the XCB
mailing list.]

On Tue, May 03, 2011 at 05:26:10PM +0530, vikash agrawal wrote:
> I wanted to seek some guidance on my GSoC project which is on XCB/XKB.
> My exams are concluding on May 28th, as a result I am not able to devote any
> of my time to the project, and also after this I will have to do a two day
> train journey to reach home. I was planning of having a *schedule* something
> like this ( *Do lemme know if this is correct or should I change the
> procedure, as you are an expert on the project* ) :-

Having other constraints on your time during the summer will make this
project significantly more difficult, but we really can't do anything
about that at this point.

>    - June 1,2 - Brush up my concepts on XML

You'll definitely need to understand how to *read* the XCB protocol
descriptions, but at least in theory you won't need to worry about the
details of XML too much.  The xcbgen framework handles that for you.  On
the other hand, you'll end up doing some hacking on Python.

However, one key point: don't try to do all your brushing-up in advance
by anticipating what you need.  Start with the project, dive in, and
figure out what you need as you go.

As a start, I would recommend making sure you can actually compile
libxcb from source on your system.

>    - June 3,4 - Brush up concepts in C, that I am not used to like Structure
>    padding, etc. ( It would be of great help if you could just list a few of
>    them that you feel are necessary and you think I wont be aware of )

This might help as a start:
http://en.wikipedia.org/wiki/Data_structure_alignment

>    - June 5,6 - Autotools
>    - June 7,8,9,10th - libx11 [1]

You don't need to worry about either autotools or Xlib at all for this
project.

>    - June 11,12,13 - XCB proto [2]
>    - June 14,15 - Developers guide [3] and Modular Developer Guide [4]

Don't worry about these either unless you get stuck when building
libxcb.

>    - June 16, 17,18,19 and 20th - Read all the necessary documentation if
>    needed and as guided by you
> 
>    - June 22 - Begin my actual coding
>    - As marked by pharris I would first try to patch this [5] bug. So, far I
>    haven't made any open source contribution and as a result I lack this skill
>    majorly, ( and would need your severe guidance on this ) which I did
>    confront to pharris and he did acknowledged this with open arms.
>    - *After this I would need guidance on todo which part first as the part
>    of my project*.

I think you will find that the bug you linked to (fixing XCB's padding)
represents a summer's worth of work by itself; plan on spending the bulk
of your time there, and don't worry about anything else.  If you get
past that and still want more to do, we can easily come up with
something. :)

The fundamental rules for X structure padding, as far as we know
(someone else from the XCB list should chime in with a counterexample if
these rules doesn't universally work):

- Primitive types have a natural alignment equal to their size: align
  1-byte types (char, CARD8, ...) on 1-byte boundaries, 2-byte types
  (CARD16, INT16, ...) on 2-byte boundaries, and 4-byte types (CARD32,
  INT32) on 4-byte boundaries.  Note that xcbgen has a list of the
  primitive types.  (Also note that the "double" type, size 8, still
  only requires 4-byte alignment, as far as we know; nothing in the X
  protocol should require more than 4-byte alignment.)
- When building a structure, track the current offset from the beginning
  of the structure (or specifically, the offset mod 4: 0, 1, 2, or 3),
  and for each field, pad to the alignment required by that field's
  type.
- Structure types have an alignment equal to the largest alignment
  required by any of the fields in that structure.
- Lists have the same alignment as their element type.
- Unions have the largest alignment of any type they contain.
- At the end of a structure, add padding out to the alignment of that
  structure.  So, a structure containing a CARD32 and a CARD8 should
  have size 8, with 3 bytes of padding at the end.  This ensures
  appropriate alignment when using that structure in a list.

Hope that helps,
Josh Triplett