Embedded/elua
1
0
Fork 0
mirror of https://github.com/elua/elua.git synced 2025-01-25 01:02:54 +08:00
Code Issues Projects Releases Wiki Activity

reformatted and updated faq.html

Browse Source
This commit is contained in:
Bogdan Marinescu 2009-03-06 19:18:50 +00:00
parent 303d97561d
commit 6bafdfe9b2
1 changed files with 112 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

298
doc/en/faq.html
View File

@ -1,209 +1,135 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html><head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<meta http-equiv="Content-Language" content="en-us"><title>Product</title>
<meta http-equiv="Content-Language" content="en-us"><title>eLua FAQ</title>
<link rel="stylesheet" type="text/css" href="../style.css"></head>
<body style="background-color: rgb(255, 255, 255);">
<h3>eLua Frequently Asked Questions</h3><br><p>Welcome to the official eLua FAQ!
It is assumed that you already know <a>what eLua is</a>, so here's a list of questions you might find useful while exploring eLua.</p>
<ul><li><p><a href="faq.html#learnlua">How can I learn Lua? Is it hard?</a><br></p></li><li><p><a href="faq.html#helpelua">How can I help eLua?</a><br></p></li><li><p><a href="faq.html#comercial">Can I use eLua in my commercial, closed source project?</a><br></p></li><li><p><a href="faq.html#fast">Is eLua fast enough?</a><br></p></li><li><p><a href="faq.html#minimuns">What are the minimum requirements for eLua?</a><br></p></li><li><p><a href="faq.html#portability">Since
I'm using the Lua platform modules (uart, spi, pwm, tmr...), can I
trust my peripheral code to run the same on all my platforms?</a><br></p></li><li><p><a href="faq.html#luaversions">What's the deal with floating-point Lua and integer only Lua?</a><br></p></li><li><p><a href="faq.html#windows">All your tutorials give instructions on how to compile eLua under Linux, yet you seem to use a lot of Windows tools. How come?</a><br></p></li><li><p><a href="faq.html#cygwin">Will you ever post instructions about how to compile toolchains under Cygwin in Windows?</a><br></p></li><li><p><a href="faq.html#bytecode">I
know that Lua can be compiled to bytecode, so I compiled one of the
eLua examples with luac and tried to run it on my eLua board, but it
didn't work. Is this a bug in eLua?</a><br></p></li><li><p><a href="faq.html#outofmemory">I get "out of memory" errors when I run my Lua programs, what should I do?</a><br></p></li></ul>
<p><br></p>
<h3>eLua Frequently Asked Questions</h3><p>Welcome to the official <b>eLua</b> FAQ!
It is assumed that you already know what <b>eLua</b>, so here's a list of questions (and their answers) that you might find useful.</p>
<ul>
<li><a href="faq.html#learnlua">How can I learn Lua? Is it hard?</a></li>
<li><a href="faq.html#helpelua">How can I help eLua?</a>
<li><a href="faq.html#comercial">Can I use eLua in my commercial, closed source project?</a>
<li><a href="faq.html#fast">Is eLua fast enough?</a>
<li><a href="faq.html#minimum">What are the minimum requirements for eLua?</a></li>
<li><a href="faq.html#portability">Since I'm using the Lua platform modules (uart, spi, pwm, tmr...), can I trust my peripheral code to run the
same on all my platforms?</a></li>
<li><a href="faq.html#luaversions">What's the deal with floating-point Lua and integer only Lua?</a></li>
<li><a href="faq.html#windows">All your tutorials give instructions on how to compile eLua under Linux, yet you seem to use a lot of Windows tools.
How come?</a>
<li><a href="faq.html#cygwin">Will you ever post instructions about how to compile toolchains under Cygwin in Windows?</a></li>
<li><a href="faq.html#bytecode">I know that Lua can be compiled to bytecode, so I compiled one of the eLua examples with luac and tried to run it on
my eLua board, but it didn't work. Is this a bug in eLua?</li>
<li><a href="faq.html#outofmemory">I get "out of memory" errors when I run my Lua programs, what should I do?</li>
</ul>
<hr>
<p><a name="learnlua"></a>
<strong>Q: How can I learn Lua? Is it hard?</strong></p>
<a name="learnlua"><h2>How can I learn Lua? Is it hard?</h2></a>
<p>Lua is a minimalistic language (yet very powerful) which is quite easy to learn. Once you understand the basic concepts you'll find yourself writing
Lua programs in notime. The main resource is the <a target="_blank" href="http://www.lua.org/">Lua homepage</a>. In the
<a target="_blank" href="http://www.lua.org/docs.html">documentation page</a> you'll find the reference manual and the first version of the excellent
"Programming in Lua" book. I recommend purchasing the second version of this book, since it's likely that this is all you'll ever need to learn
Lua. Another very good resource is the <a target="_blank" href="http://lua-users.org/wiki/">Lua wiki</a>. If you need more help, check the
<a target="_blank" href="http://www.lua.org/community.html">community page</a>. Lua has a very friendly and active community.</p>
<p>A: Lua is a minimalistic language (yet very powerful) which is quite
easy to learn. Once you understand the basic concepts you'll find
yourself writing Lua programs in notime. The main resource is the <a target="_top" href="http://www.lua.org/">Lua homepage</a>. In the <a target="_top" href="http://www.lua.org/docs.html">documentation page</a>
you'll find the reference manual and the first version of the excellent
"Programming in Lua" book. I recommend purchasing the second version of
this book, since it's likely that this is all you'll ever need to learn
Lua. Another very good resource is the <a target="_top" href="http://lua-users.org/wiki/">Lua wiki</a>. If you need more help, check the <a target="_top" href="http://www.lua.org/community.html">community page</a>. Lua has a very friendly and active community.</p><p></p><br><p><a name="helpelua"></a>
<strong>Q: How can I help eLua?</strong></p>
<a name="helpelua"><h2>How can I help eLua?</h2></a>
<p><b>eLua</b> has many ambitious goals, so it would be great to have more people working on it. Take a look at the
<a href="status.html#roadmap">roadmap page</a>, and if you see something there that you'd like to work on, don't hesitate to
<a href="overview.html#contacts">contact us</a>. Also, if you'd like to make a donation to the project (money, or maybe a development board)
rest assured that wwe won't say no :) It also helps a lot if you test <b>eLua</b> on your own board and you find a bug or an
incomplete feature. Or if you just thought about a cool feature that you'd like to see in <b>eLua</b>.
If so, feel free to <a href="overview.html#contacts">contact us</a>.</p>
<p>A: OK, so I lied, this is NOT a frequently asked question :)
However, if you really want to help eLua, keep in mind that we're
looking for developers. eLua has many ambitious goals, so it would be
great to have more people working on it. Take a look at the <a href="status.html#roadmap">roadmap page</a>, and if you see something there that you'd like to implement, don't hesitate to <a href="overview.html#contacts">contact us</a>.
Also, if you'd like to make a donation to the project (money, or maybe
a development board) rest assured that wwe won't say no :) It also
helps a lot if you test eLua on your own board and you find a bug or an
incomplete feature. Or if you just thought about a cool feature that
you'd like to see in eLua. If so, feel free to <a href="overview.html#contacts">contact us</a>.</p><p></p>
<a name="comercial"><h2>Can I use eLua in my commercial, closed source project?</h2></a>
<p>Starting with version 0.6, <b>eLua</b> distributed under a MIT license, so you can use it in your close source projects. Prior to this it was
distributed under GPL, which restricted its usage to open source applications only. Be careful though, <b>eLua</b> includes some 3rd party libraries,
each with its own licensing terms that might be more restrictive than MIT. See <a href="overview.html#license">the eLua license</a> for details.</p>
<p><a name="comercial"></a>
<strong>Q: Can I use eLua in my commercial, closed source project?</strong></p>
<a name="fast"></a><h2>Is eLua fast enough?</h2></a>
<p>This pretty much depends on what you expect. If you expect your Lua code to run as fast as your compiled C code, this won't happen, simply because C
is a compiled language, while Lua is an interpreted language. That said, you'll be happy to know that Lua is one of the fastest interpreted languages
out there. If you really need both high speed and Lua, you can write your speed critical code sections in C and export them as a Lua module.
This way you get the best of both worlds. We don't have any official benchmarks about Lua speed on embedded devices, but you might want to check the
TV-B-Gone example on the <a href="examples.html">##examples page</a>.TV-B-Gone is a "software remote control" application coded directly in <b>eLua</b>.
If you're familiar with the remote control protocols, you'll know that this kind of application is quite "real time", and delays in the order of
milliseconds or even less can make your software remote control fail. Yet this sample runs without problems on a 50MHz Cortex (Thumb2) CPU. This should
give you a fairly intuitive view on the speed of eLua.</p>
<p>A: ### This needs to be updated for the BSD license .........</p><p></p>
<p><a name="fast"></a>
<strong>Q: Is eLua fast enough?</strong></p>
<p>A: This pretty much depends on what you expect. If you expect your
Lua code to run as fast as your compiled C code, this won't happen,
simply because C is a compiled language, while Lua is an interpreted
language. That said, you'll be happy to know that Lua is one of the
fastest interpreted languages out there. If you really need both high
speed and Lua, you can write your speed critical code sections in C and
export them as a Lua module. This way you get the best of both worlds.
We don't have any official benchmarks about Lua speed on embedded
devices, but you might want to check the TV-B-Gone example on the <a href="examples.html">examples page</a>.
TV-B-Gone is a "software remote control" application coded directly in
eLua. If you're familiar with the remote control protocols, you'll know
that this kind of application is quite "real time", and delays in the
order of milliseconds or even less can make your software remote
control fail. Yet this sample runs without problems on a 50MHz Cortex
(Thumb2) CPU. This should give you a fairly intuitive view on the speed
of eLua.</p><p></p>
<p><a name="minimuns"></a>
<strong>Q: What are the minimum requirements for eLua?</strong></p>
<p>A: It's hard to give a precise answer to this. As a general rule for
<a name="minimum"><h2>What are the minimum requirements for eLua?</h2></a>
<p>It's hard to give a precise answer to this. As a general rule for
a 32-bit CPU, we recommend at least 256k of Flash (program memory) and
at least 64k of RAM. However, this isn't a strict requirement. A
stripped down, integer-only version of eLua can definetely fit in 128k
of Flash, and depending on your type of application, 32k of RAM might
prove just fine. It largely depends on your needs.</p><p></p>
prove just fine. It largely depends on your needs.</p>
<p><a name="portability"></a>
<strong>Q: Since I'm using the Lua platform modules (uart, spi, pwm,
tmr...), can I trust my peripheral code to run the same on all my
platforms?</strong></p>
<a name="portability"><h2>Since I'm using the Lua platform modules (uart, spi, pwm, tmr...), can I trust my peripheral code to run the same on all my
platforms?</h2></a>
<p>Unfortunately, no. While <b>eLua</b> makes it possible to have a common code on different platforms using the <a href="">##platform interface</a>,
it can't possibly provide the same functionality on all platforms, since all MCUs are not created equal. It is very recommended
(and many times imperative) to have an understanding of the peripherals on your particular MPU before you start writing your code.
This, of course, is not particular to <b>eLua</b>, but it's especially important since the platform interface might give the impression that it
offers an uniform functionality over all platforms, when in fact the only thing in common is often just the interface itself (that is, the methods and
variables you can access in a given module). <b>eLua</b> tries to help here by giving you an error when you try to access a physical resource that is
not available (for example a timer, a PWM channel, or a PIO pin/port), but it doesn't try to cover all the possible platform-related issues, since this
would increase the code size and complexity too much. These are some caveats that come to mind (note that these are only a few examples, the complete
list is much longer):</p>
<ul>
<li><b>timers</b>: from all the platforms on which <b>eLua</b> runs, only the Luminary Cortex CPUs has rock solid 32-bit timers. You can do pretty much
everything you need with them. All the other platforms have 16-bit timers, which imposes some limits on the range of delays you can achieve with them.
Make sure to use tmr.mindelay(id) and tmr.maxdelay(id) to check the actual resolution of your timers, and adapt your code accordingly. To 'compensate'
for this, it's not possible to change the base timer frequency on the Cortex CPUs, but it is possible on most other platforms :) So be sure to also check
the result of tmr.setclock(id)</li>
<li>also, when using timers, remember that if you're using XMODEM and/or the "term" module, one of them (generall TMR0) is used by both of them. So, if
you change the TMR0 base clock in your code, be sure to restore the original setting before returning to the <b>eLua</b> shell.</li>
<li><b>PWM</b>: the Cortex CPUs have 6 PWM channels, but channels 0/1, 2/3 and 4/5 respectively share the same base clock setting. So, when you're
changing the base clock for channel 1, you're also changing the base clock for channel 0; if channel 0 was already running, you won't like
what will happen next. This time no eLua function can save you, you simply need you know your CPU architecture.</li>
<li><b>GPIO</b>: only some platform have internal pullups for the GPIO pins (others might also have pulldowns). However, in this case you're safe, as
<b>eLua</b> will signal an error if you try to execute a pullup operatin on a platform that does not support it.</li>
</ul>
<p>The lesson here is clear: understand your platform first!</p>
<p>A: Unfortunately, no. While eLua makes it possible to have a common
code on different platforms using the platform interface
(docs/platform_interface.txt), it can't possibly provide the same
functionality on all platforms, since all CPUs are not created equal.
It is very recommended (and many times imperative) to have an
understanding of the peripherals on your particular CPU before you
write your code. This, of course, is not particular to eLua, but it's
especially important since the platform interface might give the
impression that it offers an uniform functionality over all platforms,
when in fact the only thing in common is often just the interface
itself (that is, the methods and variables you can access in a given
module). eLua tries to help here by giving you an error when you try to
access a physical resource that is not available (for example a timer,
a PWM channel, or a PIO pin/port), but it doesn't try to cover all the
possible platform-related issues, since this would increase the code
size and complexity too much. These are some caveats that come to mind
(note that these are only a few examples, the complete list is much
longer):</p>
<a name="luaversions"><h2>What's the deal with floating-point Lua and integer only Lua?</h2></a>
<p>Lua is build around a number type. Every number in Lua will have this type. By default, this number type is a double. This means that even if your
program only does integer operations, they will still be treated as doubles. On embedded platforms this is a problem, since the floating point
operations are generally emulated in software, thus they are very slow. This is why <b>eLua</b> gives you "integer only Lua": a Lua with the default
number type changed to long. The advantages are increased speed and smaller code size (since we can force Newlib to "cut" the floating point code from
printf/scanf and friends, which has quite a strong impact on the code size) and increased speed. The downside is that you'll loose the ability to do
any floating point operations (although a separate module that will partially overcome this limitation will be provided in the future).</p>
<a name="windows"><h2>All your tutorials give instructions on how to compile eLua under Linux, yet you seem to use a lot of Windows tools. How come?</h2></a>
<p>It's true that we do all the <b>eLua</b> development under Linux, since we find Linux an environment much more suited for development. At the same
time it's true that most of the tools that come with my development boards run under Windows. So we choose to use the best of both world: Bogdan runs
Linux under a <a target="_blank" href="http://www.virtualbox.org">VirtualBox</a> emulator, and does verything else under Windows. Dado does everything on
Linux and runs Windows under <a href="http://www.vmware.com" target="_blank">VMWare</a>. Both options are nice if you master your environment. To make
everything even more flexible, Bogdan keeps his VirtualBox Ubuntu image on an external WD passport disk that he can carry with him wherever he goes,
so he can work on eLua whenever he has a bit of spare time :)</p>
<ul><li>timers: from all the platforms on which eLua runs, only
the Luminary Cortex CPUs has rock solid 32-bit timers. You can do
pretty much everything you need with them. All the other platforms have
16-bit timers, which imposes some limits on the range of delays you can
achieve with them. Make sure to use tmr.mindelay(id) and
tmr.maxdelay(id) to check the actual resolution of your timers, and
adapt your code accordingly. To 'compensate' for this, it's not
possible to change the base timer frequency on the Cortex CPUs, but it
is possible on most other platforms :) So be sure to also check the
result of tmr.setclock(id)</li><li>also, when using timers,
remember that if you're using XMODEM and/or the "term" module, TMR0 is
used by both of them. So, if you change the TMR0 base clock in your
code, be sure to restore the original setting before returning to the
shell. You can change this static timer assignment by modifying
src/main.c. It might also be possible to change it dynamically in the
future, although I see little use for this.</li><li>PWM: the
Cortex CPUs have 6 PWM channels, but channels 0/1, 2/3 and 4/5
respectively share the same base clock setting. So, when you're
changing the base clock for channel 1, you're also changing the base
clock for channel 0; if channel 0 was already running, you won't like
what will happen next. This time no eLua function can save you, you
simply need you know your CPU architecture.</li><li>GPIO: only
some platform have internal pullups for the GPIO pins, while Cortex is
the only platform that also provides pulldowns for its GPIOs. However,
in this case you're safe, as eLua will signal an error if you try to
execute a pullup operatin on a platform that does not support it.</li></ul>
<a name="cygwin"><h2>Will you ever post instructions about how to compile toolchains under Cygwin in Windows?</h2></a>
<p>Bogdan: If I ever have way too much spare time on my hands, yes. Otherwise, no. There are many reasons for this. As I already mentioned, I favour Linux
over Windows when it comes to developing applications. Also, I noticed that the GNU based toolchains are noticeable slower on Cygwin than on Linux, so
experimenting with them can prove frustrating. Also, compiling under Linux and Cygwin should be quite similar,so try starting from my Linux based
tutorials, they might work as well on Cygwin.</p>
<p>The lesson here is clear: understand your platform first!</p><p></p>
<a name="bytecode"><h2>I know that Lua can be compiled to bytecode, so I compiled one of the eLua examples with luac and tried to run it on my eLua
board, but it didn't work. Is this a bug in eLua?</h2></a>
<p>This is not a bug in <b>eLua</b>, it's a bit more subtle than that. See <a href="using.html#cross">the cross-compile section</a> for a full discussion
about this problem and its fix.</p>
<p><a name="luaversions"></a>
<strong>Q: What's the deal with floating-point Lua and integer only Lua?</strong></p>
<p>A: Lua is build around a number type. Every number in Lua will have
this type. By default, this number type is a double. This means that
even if your program only does integer operations, they will still be
treated as doubles. On embedded platforms this is a problem, since the
floating point operations are generally emulated in software, thus they
are very slow. This is why eLua gives you "integer only Lua": a Lua
with the default number type changed to long. The advantages are
increased speed and smaller code size (since we can force Newlib to
"cut" the floating point code from printf/scanf and friends, which has
quite a strong impact on the code size) and increased speed. The
downside is that you'll loose the ability to do any floating point
operations.</p><p></p>
<p><a name="windows"></a>
<strong>Q: All your tutorials give instructions on how to compile eLua
under Linux, yet you seem to use a lot of Windows tools. How come?</strong></p>
<p>A: It's true that we do all the eLua development under Linux, since we
find Linux an environment much more suited for development. At the same
time it's true that most of the tools that come with my development
boards run under Windows. So we choose to use the best of both world: Bogdan runs&nbsp;Linux under an Virtual Machine Manager (<a target="_top" href="http://www.virtualbox.org/">VirtualBox</a>) and do&nbsp;everything else under Windows. Dado does everything on Linux and runs Windows under <a href="http://www.vmware.com" target="_top">VMWare</a>. Both options are nice if you master your environment. To make everything even more flexible, Bogdan keeps his
VirtualBox Ubuntu image on an external WD passport disk that he can
carry with him wherever he goes, so he can work on eLua whenever he has a
bit of spare time :)</p><p></p>
<p><a name="cygwin"></a>
<strong>Q: Will you ever post instructions about how to compile toolchains under Cygwin in Windows?</strong></p>
<p>A: Bogdan: If I ever have way too much spare time on my hands, yes.
Otherwise, no. There are many reasons for this. As I already mentioned,
I favour Linux over Windows when it comes to developing applications.
Also, I noticed that the GNU based toolchains are noticeable slower on
Cygwin than on Linux, so experimenting with them can prove frustrating.
Also, compiling under Linux and Cygwin should be quite similar, so try
starting from my Linux based tutorials, they might work as well on
Cygwin.</p><p></p>
<p><a name="bytecode"></a>
<strong>Q: I know that Lua can be compiled to bytecode, so I compiled
one of the eLua examples with luac and tried to run it on my eLua
board, but it didn't work. Is this a bug in eLua?</strong></p>
<p>A: This is not a bug in eLua, it's a bit more subtle than that. It's
true that ARM and i386 are very similar when it comes to data types:
all the fundamental data types have the same length, and they are both
little endian. So, in theory, if you compile a Lua source file on PC
you should be able to run the compiled bytecode on your eLua board
without any modifications. But there's a problem here: the default
double precision floating point representation is different on ARM and
PC. So, while the two data types have the same endianess and size, they
are represented differently in memory. This means that you can't use
the "regular" luac compiler for this task. However, starting with
version 0.5, you can cross-compile Lua code on PC to run on target.&nbsp;</p><p></p>
<p><a name="outofmemory"></a>
<strong>Q: I get "out of memory" errors when I run my Lua programs, what should I do?</strong></p>
<p>A: There are a number of things you can try to overcome this:</p>
<ul><li>precompile your source to bytecode:&nbsp; If you use bytecode instead of
source code Lua won't need to compile your source, so you save some RAM.</li><li>try
to avoid using too many strings: strings are immutable in Lua. That
means that a statement like s = s .. "\n" (where s is a string) will
create a new string each time it's called. If this happens a lot (for
example in a loop), your memory will quickly run out because of all the
strings. If you really need to do frequent string operations, put them
in a table and then use <a href="http://www.lua.org/manual/5.1/manual.html#5.5">table.concat</a> to make a string from your table.</li><li>controll Lua's garbage collection&nbsp;manually: if you're still running out of memory, try
calling collectgarbage('collect') from your code, which will force a
garbage collection and thus might free some memory.</li></ul><br><br></body></html>
<a name="outofmemory"><h2>I get "out of memory" errors when I run my Lua programs, what should I do?</h2></a>
<p>There are a number of things you can try to overcome this:</p>
<ul>
<li><b>enable the LTR patch</b>: you can get very significant improvements if you enable the LTR patch in your <b>eLua</b> image. See
<a href="">##here</a> for more details about LTR, and <a href="building.html">here</a> for instructions about enabling LTR.</li>
<li><b>precompile your source to bytecode</b>: if you use bytecode instead of source code Lua won't need to compile your source, so you save some RAM.</li>
<li><b>try to avoid using too many strings</b>: strings are immutable in Lua. That means that a statement like <i>s = s .. "\n"</i> (where s is a string)
will create a new string each time it's called. If this happens a lot (for example in a loop), your memory will quickly run out because of all the
strings. If you really need to do frequent string operations, put them in a table and then use
<a target="_blank" href="http://www.lua.org/manual/5.1/manual.html#5.5">table.concat</a> to make a string from your table.</li>
<li><b>control Lua's garbage collection manually</b>: if you're still running out of memory, try calling <i>collectgarbage('collect')</i> from your code,
which will force a garbage collection and thus might free some memory.</li>
</ul>
</body></html>