Wanted: Porting guide / developer guide

[rambo]

Hi there, I've been looking around github pages and the wiki (and tried to search the forum) but...

It would be very nice to have some sort of developer guide that would explain the basics of how this beast works and how to for example implement a module in C and expose functions/data. Reading the source of course gives this info but it's a bit laborious (been doing that for the last few hours)

Another related thing would be a porting guide, what the python interpreter needs to be able to run, how to handle text input/output streams etc. Especially how to make the memory management play nice with other memory managers (I'm currently trying to figure out how to run uPy in a ChibiOS thread, not that I'm super familiar with ChibiOS either but see http://forum.micropython.org/viewtopic. ... 5&start=10 for background), I guess one could just allocate different blocks of memory for them in the linked script but that's a poor compromise, better would be to allow them to somehow share.

The Differences page on github was an excellent start (and the bare-arm tree also was nice since it does nothing extra), but I would like a bit more info/pointers on what is important and what is optional etc.

ps. Is there IRC channel or something for more realtime pestering of the resident gurus ??

[dhylands]

stmhal/led.c/.h is probably a fairly nice example to look at.

https://github.com/micropython/micropyt ... led.c#L301 introduces a type, which has its name denoted by MP_QSTR_LED.
This particular constant if generated from: https://github.com/micropython/micropyt ... ort.h#L105
The actual generated file is: build-PYBV10/genhdr/qstrdefs.generated.h and the entry for LED looks like:

Code: Select all

Q(LED, (const byte*)"\x88\xdc\x03\x00" "LED")

so you wind up with a so called "interned" string.

When you do:

Code: Select all

led = pyb.LED(1)

then the .make_new method of the LED type will be called.

If you do a dir command on pyb.LED you'll be able to see the attributes, and these will correspond to the entries in the .locals_dict entry of the type.

Code: Select all

>>> dir(pyb.LED)
['on', 'off', 'toggle', 'intensity']

The attributes could be of any type, in this particular instance, they're all functions. The 4 lines starting: https://github.com/micropython/micropyt ... led.c#L287 declare the 4 python objects which are contained within the locals_dict. And they all point to C functions. The 1 in MP_DEFINE_CONST_FUN_OBJ_1 says that this function takes 1 argument. The python interpreter will do that checking for you.

MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN declares that a function takes a variable number of objects (you specify the min and max number of arguments). There are a bunch of variants of these macros. Look here for more: https://github.com/micropython/micropyt ... /obj.h#L94

The C function will be passed python objects, and the exact signature will depend on which macro you use. The exact signatures for the functions can be found here: https://github.com/micropython/micropyt ... obj.h#L182

Your C function then needs to call various functions (like mp_obj_int to get an integer value). The function you need should all be in obj.h

All of the C functions need to return something. If there isn't anything logical to return, then return mp_const_none.

Use dir(pyb) to see the various types defined. They mostly all have .c files in the stmhal directory. Search for MP_QSTR_XXX where XXX is the name of the type to find the name of the C file containing the type.

Finally, the pyb_led_type is registered to be in the pyb module here: https://github.com/micropython/micropyt ... pyb.c#L378

That's a quick and dirty overview.

And by all means ask away.

I'm not aware of an IRC channel, but I wouldn't mind seeing one of those either (I live on IRC for my day job)

[dhylands]

And about the memory. Right now, the garbage collector assumes that it owns the memory you pass to it via gc_init.

Right now, for a bare metal port, that corresponds the to beginning and end of the heap.

For an os, presumably, you'd allocate some block of memory, and pass the address of the beginning and end of that block of memory to gc_init, and that would become the python heap.

https://github.com/micropython/micropyt ... ain.c#L296
https://github.com/micropython/micropyt ... ain.c#L278

[rambo]

Thanks. Any rules of thumb on how much memory one should give to uPy for the gc allocator ?

Chibi has this funky "core" allocator that the heap and other allocators can ask for more memory from (I'm not quite sure how the handle discontinuous regions, I just skimmed over the code quickly), anyway it allows the various things to "share" the same heap memory from linker instead of having to allocate separate regions at link time (AFAIUnderstand it, I might be wrong).

[dhylands]

I think that you probably want the amount of memory to be fairly easy to configure.

It's really going to depend on the project and how much heap the chibi portion of your code uses, versus how much the python portion will use.

I would probably start off with a simple scheme (pyhon gets X, chibi gets the rest). Then later on, if you can figure out a way to make it be more dynamic, you can change to that.

As a rough guess, I'd probably want to give python about half of the 128K.

[dhylands]

ps. Is there IRC channel or something for more realtime pestering of the resident gurus ??

So I'll be hanging around in the #micropython channel on freenode (irc.freenode.net). My IRC nick is dhylands. My nick will be there 24/7 (I use irccloud.com), although I won't be. When I'm not available (i.e. on vacation) I'll sometimes remember to put |afk (away from keyboard) or |pto (paid-time-off) or something else at the end of my nick if I'm unavailable.

I'm located in Pacific timezone, which is UTC-8 or UTC-7 depending on the time of the year.

I get notified of any requests that start with dhylands: so I'll see it eventually, and I'll respond when I see it, unless its obvious somebody else has.

[stijn]

haven't used IRC in 10 years or so - is there something like a web-based no-signup client or so, or what is a decent Windows client these days (still mIrc?)

[rambo]

is there something like a web-based no-signup client or so

http://webchat.freenode.net/?randomnick ... hon&uio=d4 seems to work.

IRCCloud was mentioned, I use it as well: It keeps persistent connections for you so you get notifications when you log back in if someone pinged you while you were away etc, very handy. I have spare invites (PM your email address if you want one: first come, first serve) if they're still running in invite-only mode (haven't checked in a while).

[stijn]

IRCCloud is publicly open now but thanks anyway; 4$ a month is a bit steep though or am I missing the point? I mean, about 5$ a month fives you a complete linux VM (on DigitalOcean or Azure for instance) on which you can keep a native client open 24/7, next to all the goodness that comes from a server OS of course.

[dhylands]

IRCCloud is publicly open now but thanks anyway; 4$ a month is a bit steep though or am I missing the point? I mean, about 5$ a month fives you a complete linux VM (on DigitalOcean or Azure for instance) on which you can keep a native client open 24/7, next to all the goodness that comes from a server OS of course.

They have a free option:
https://www.irccloud.com/pricing

I used to run a local server, but I just wanted something simple. For occasional use, using one of the local clients (mirc, ChatZilla, etc) is probably more appropriate. Since I work remotely, and I use IRC every day, I like irccloud. Especially since they have phone apps that sync up as well. I also have 3 different computers, plus my phone that I use quite regularly, and I find using the same nick on all of those and seeing the same history to be quite useful.