Some notes about the flags used in the above sequence:
-
--disable-newlib-supplied-syscalls: this deserves a page of its own, but I won't cover it here. For an explanation, see for example this page.
-DPREFER_SIZE_OVER_SPEED -D__OPTIMIZE_SIZE__: compile Newlib for size, not for speed (these are Newlib specific).
-Os -fomit-frame-pointer: tell GCC to optimize for size, not for speed.
-D__BUFSIZ__=256:
+
--disable-newlib-supplied-syscalls: this deserves a page of its own, but I won't cover it here. For an explanation, see for example this page.
-D__PREFER_SIZE_OVER_SPEED -D__OPTIMIZE_SIZE__: compile Newlib for size, not for speed (these are Newlib specific).
-Os -fomit-frame-pointer: tell GCC to optimize for size, not for speed.
-D__BUFSIZ__=256:
again Newlib specific, this is the buffer size allocated by default for
files opened via fopen(). The default is 1024, which I find too much
for an eLua, so I'm using 256 here. Of course, you can change this
diff --git a/doc/pt/bit_ref.html b/doc/pt/bit_ref.html
new file mode 100644
index 00000000..cfdcaf58
--- /dev/null
+++ b/doc/pt/bit_ref.html
@@ -0,0 +1,132 @@
+
+
+
+Product
+
+
+
+
+
+
+Up to date documentation of how to build eLua is always included in the eLua distributions, in the docs directory).
For your convenience, the building instructions are also provided on this page.
+
+
Prerequisites
+
+
Before you start, you might want to check if the list of platform modules and
+eLua components are set according to your needs. See platform_modules
+and elua_components in the distro doc for details.
+
+
Building eLua
+
+
To build eLua you'll need:
+
+
a GCC/Newlib toolchain for your target. Please note that even if
+ you already have a compiled toolchain, the differences in the Newlib configure
+ flags (mainly the --disable-newlib-supplied-syscalls flags) might prevent
+ eLua for building properly on your machine.
Linux. Compiling under windows should be possible, however this isn't tested.
+ I'm using Ubuntu, so I'm also using "apt-get". If you're using a distro with a
+ different package manager you'll need to translate the "apt-get" calls to your
+ specific distribution.
python. It should be already installed; if it's not:
+
+
$ sudo apt-get install python
scons. eLua uses scons instead of make and makefiles, because I find scons
+ much more "natural" and easier to use than make. To install it:
+
+
$ sudo apt-get install scons
your toolchain's "bin" directory (this is generally something like
+ /usr/local/cross-arm/bin, where /usr/local/cross-arm is the directory in which
+ you installed your toolchain) must be in $PATH.
if you're building for the i386 platform, you'll also need "nasm":
+
+
$ sudo apt-get install nasm
+
+
For each platform, eLua assumes a certain name for the compiler/linker/assembler
+executable files, as shown below.
Your build target is specified by two paramters: cpu and board. "cpu" gives the
+name of your CPU, and "board" the name of the board. A board can be associated
+with more than one CPU. This allows the build system to be very flexible. You
+can use these two options together or separately, as shown below:
+
+
cpu=name: build for the specified CPU. A board name will be assigned by the
+ build system automatically.
board=name: build for the specified board. The CPU name will be inferred by
+ the build system automatically.
cpu=name board=name: build for the specified board and CPU.
+
+
For board/CPU assignment look at the beginning of the SConstruct file from the
+base directory, it's self-explanatory.
+
+
The other options are as follows:
+
+
target=lua | lualong: specify if you want to build full Lua (with floating
+ point support) or integer only Lua (lualong). The default is "lua".
cpumode=arm | thumb: for ARM target (not Cortex) this specifies the
+ compilation mode. Its default value is 'thumb' for AT91SAM7X targets and
+ 'arm' for STR9 and LPC2888 targets.
allocator = newlib | multiple: choose between the default newlib allocator
+ (newlib) and the multiple memory spaces allocator (multiple). You should
+ use the 'multiple' allocator only if you need to support multiple memory
+ spaces, as it's larger that the default Newlib allocator (newlib). For more
+ information about this reffer to platform_interface. The default value
+ is 'newlib' for all CPUs except 'lpc2888', since my lpc-h2888 comes with
+ external SDRAM memory and thus it's an ideal target for 'multiple'.
prog: by default, the above 'scons' command will build only the 'elf' file.
+ Specify "prog" to build also the platform-specific programming file where
+ appropriate (for example, on a AT91SAM7X256 this results in a .bin file that
+ can be programmed in the CPU).
+
+
The output will be a file named elua[target][cpu].elf (and also another
+file with the same name but ending in .bin if "prog" was specified for platforms
+that need .bin files for programming).
+If you want the equivalent of a "make clean", invoke "scons" as shown above,
+but add a "-c" at the end of the command line. "scons -c" is also recommended
+after you change the list of modules/components to build for your target (see
+section "prerequisites" of this document), as scons seems to "overlook" the
+changes to these files on some occasions.
+
+
A few examples:
+
+
Clear previously built intermediate files.
+
+
$ scons cpu=at91sam7x256 -c
+
+
Build eLua for the AT91SAM7X256 CPU. The board name is detected as sam7-ex256.
+
+
$ scons cpu=at91sam7x256
+
+
Build eLua for the SAM7-EX256 board. The CPU is detected as AT91SAM7X256.
+
+
$ scons board=sam7-ex256
+
+
Build eLua for the SAM7-EX256 board, but "overwrite" the default CPU. This is
+useful when you'd like to see how the specified board would behave with a
+different CPU (in the case of the SAM7-EX256 board it's possible to switch the
+on-board AT91SAM7X256 CPU for an AT91SAM7X512 which has the same pinout but
+comes with more Flash/RAM memory).
+
+
$ scons board=sam7-ex256 cpu=at91sam7x512
+
+
Build eLua for the lpc2888 CPU. The board name is detected as LPC-H2888. Also,
+the bin file required for target programming is generated.
+
+
$ scons cpu=lpc2888 prog
\ No newline at end of file
diff --git a/doc/pt/comunity.html b/doc/pt/comunity.html
new file mode 100644
index 00000000..7479fe90
--- /dev/null
+++ b/doc/pt/comunity.html
@@ -0,0 +1,27 @@
+
+
+
+Product
+
+
+
+
Our devellopment repository is currently maintained in a
+Subversion Server. If you are interested in following daily commitments to the Bleeding
+Edge trunk development, you can also subscribe to our SVN
+Activity List at https://lists.berlios.de/mailman/listinfo/elua-svn
+
Credits
+
+
The authors of eLua would like
+to thank the colaborative help from the comunity for the
+continuous development of the project. Here's an alphabetical
+ordered non-exhaustive list of contributors:
+
+Alberto Fabiano, André Carregal, Cosmin Filip, Diego Sueiro, Everson Denis, Fabio Pereira, Fernando Araújo, Frédéric Thomas, Ives Cunha, James Snyder, Marcelo Tílio, Marco
+Meggiolaro, Mike Panetta, Pedro Bittencourt, Rafael Barmak,Rafael Sabbagh, Ralph Hempel, Raul Nunes, Ricardo Rosa, Roberto Ierusalimschy, Téo Benjamin, Yuri Takhteyev, ...
+
+If you have an eLua capable hardware, you
+don't need to be a professional developer of the embedded world
+and to understand the details of the eLua building process, to be
+able to have eLua on your nice kits.
eLua project offers pre-built
+binary images for all the supported platforms.
All you have to do is to chose the
+corresponding image file from the table below, flash it into your
+board, connect a serial terminal (or Ethernet if you board supports)
+and enjoy eLua.
+
+eLua binaries, like the source-code distributions,
+include some example programs in it's file system, so you can run and
+play (yes! we have games too! :) them, following the instructions in
+our Using eLua page. The available example programs are described in our Examples page.
+
+If you need a customized binary image for an already supported
+platform (ie: with an autorun program, with some code of yours in the
+File System, with your LAN IP settings, .....) and you don't know how to build eLua, feel free to write us explaining what you need. We may (find some time to :) build one for you and eventually make it available here too.
+
+
To understand what's in a file name (for example elua_lualong_lm3s8962.bin) check our Building eLua page, or at least the last part of it, where the meaning of the file names coming from the build system is explained.
+
+
+
Lua Number refers to the built Lua interpreter number type, float or integer.
RAM Memory Usage is based on included Lua examples execution.
\ No newline at end of file
diff --git a/doc/pt/dl_sources.html b/doc/pt/dl_sources.html
new file mode 100644
index 00000000..0a0e967c
--- /dev/null
+++ b/doc/pt/dl_sources.html
@@ -0,0 +1,52 @@
+
+
+
+Product
+
+
+
Downloading eLua Source Code
Official Releases
+
+
Source code
+
+
The last released version is eLua v0.6 and you can download it here:
+####
+The package includes the complete source code, documentation, building scripts and Lua program examples.
+
+
+
After downloading and unpacking, you can acess eLua's documentation
+in an offline mode, opening the document index_en.html in the /doc
+folder. It will show you a version of this site at the time eLua v0.6
+was released. The online version is constantly updated though and you
+might check it for updated eLua news.
You will find eLua building instructions on the Building eLua page.
+
+
+
Subversion Public Repository
+
+
If you'd rather have the very last development ("bleeding edge") version, just check it out from our Subversion Repository:
+
+
$ svn checkout svn://svn.berlios.de/elua/trunk
+
+
+
Once checked out, the repository can be easily updated by the svn client command:
+
+
$ svn update
+
+
+
Subversion Repository Web Browsing
+
+If you're looking for an easy and user friendly way of browsing through the SVN repository, use the WebSVN interface
Subversion Repository for developers
+
+
If you want to contribute to eLua and need write access to the repository, follow these steps:
Once checked out, the repository can be easily updated:
+
+
$ svn update
+
+
\ No newline at end of file
diff --git a/doc/pt/downloads.html b/doc/pt/downloads.html
new file mode 100644
index 00000000..751ccdc8
--- /dev/null
+++ b/doc/pt/downloads.html
@@ -0,0 +1,7 @@
+
+
+
+Product
+
+
+
Downloads
\ No newline at end of file
diff --git a/doc/pt/eluaapi.html b/doc/pt/eluaapi.html
new file mode 100644
index 00000000..cb9c8bb0
--- /dev/null
+++ b/doc/pt/eluaapi.html
@@ -0,0 +1,15 @@
+
+
+
+Product
+
+
+
+
+
eLua API
+
+
+
+
+
+
\ No newline at end of file
diff --git a/doc/pt/examples.html b/doc/pt/examples.html
new file mode 100644
index 00000000..b11b9b3d
--- /dev/null
+++ b/doc/pt/examples.html
@@ -0,0 +1,144 @@
+
+
+
+Product
+
+
+
+
Lua Code Examples
eLua distros come bundled with nice and fun
+(yes! we have games too! :) Lua programs examples in the File System.
+They are also included in the eLua
+source code distribution, under the /romfs subdirectory. Lua example programs for eLua are also presented and commented here. As previously explained, you can run them directly from eLua's file
+system or you can use the eLua shell and send them via XMODEM, as
+described here.
+
+
hello.lua: the ubiquitous "Hello, World!"
+
+
Runs on: All Targets
+
+Description: To call this a "program" is a gross overstatement, but it's a
+tradition, so we respect it :) It just prints "Hello, World!" on the terminal and
+returns to the shell. Download it only if you feel too lazy to fire up
+the lua interpreter inside eLua and write it yourself :)
Commented Source Code:
print("Hello World")
+
+
info.lua: getting the platform data
+
+
Runs on: All targets except i386
Description:
+This isn't really more advanced than "Hello, World!", but it does show
+an eLua specific module: the platform data module (pd). You can read
+more about the platform modules in the eLua source distribution
+(docs/platform_modules.txt). The program will display the platform
+name, the CPU name, the board name and the CPU clock and then will exit
+to the shell.
Commented Source Code:
-- Uses module pd to access platform data and print it on the Terminal print( "I'm running on platform " .. pd.platform() ) print( "The CPU is a " .. pd.cpu() ) print( "The board name is " .. pd.board() )
+
+
led.lua: the old LED blinker, the new eLua way
+
+
Runs on: All targets except i386
Description:
+Now we get to do something "more embedded": blink a LED. The code ilustrates a few interesting eLua features:
+
+
cross platform code: the code assigns a different pin
+to the LED starting from the board name. You can see how the platform
+data module makes it very easy to write such portable code.
uart, pio, tmr, pd modules: they are all used here.
+
+
Watch it blink, then press any key to return to the eLua shell.
Commented Source Code:
+
+
hangman.lua: taking advantage of your terminal
+
+
Runs on: All Targets except i386
+
+
Description: By far the geekiest example from the eLua distribution (or would it be morse.lua? :), it makes use of
+the term module (docs/terminal_support.txt) to let the user play a
+BSD-like "hangman" directly in his terminal emulator. Run the example
+and enjoy. Currently it has a very small list of words, as this was
+written mainly as a proof of eLua's capabilities, but it's very easy to
+add new words/replace the existing ones. A screenshot can be seen here.
+
+
pwmled.lua: LED blinker, advanced class
Runs on: EK-LM3S8962, EK-LM3S6965
+
+
Description:
+This uses the PWM module to fade the on-board LED in and out, in an
+infinite loop. Not much to say here, the code is very simple, yet the
+results are quite spectacular. Press any key to end the sample and
+return to the shell.
+
+
tvbgone.lua: yes, eLua can do real time!
+
+
Runs on: EK-LM3S8962, EK-LM3S6965
+
+
Description: This is more complex, but also very important for eLua, because it
+proves that real time applications (with relatively strict timing
+requirements) can run from eLua directly. It's the famous TV-B-Gone
+project adapted from LadyAda's kit.
+If you're not familiar with TV-B-Gone, it knows how to do one thing
+very well: power off your TV :) Basically it contains a lot of remote
+control codes (for a lot of TVs) that are continously sent via an IR
+LED. This code uses the PWM module (new in eLua 0.4) and it also does
+file I/O from Lua, since the remote control codes are kept in a
+separate file (which is also part of the ROM file system). To read the
+binary file, the "pack" module (also new in 0.4) is used. To ensure
+that we don't get any unexpected delays, the Lua garbage collector is
+turned off. Take a look at this sample, it's both a very good proof of
+the capabilities of eLua and a good learning resource. To use it on any
+of the Cortex boards (EK-LM3S8962 or EK-LM3S6965) connect an IR LED
+with a resistor between the "PWM2" and "GND" pins of the extension
+connector. Get close to your TV and press the "select" button on your
+board to start sending the IR codes. The on-board LED stays lit while
+the codes are transmitted and shuts off afterwards. Press the "down"
+button on your board to exit the application and return to the shell.
+
+
piano.lua: because PWM is great
Runs on: EK-LM3S8962, EK-LM3S6965, SAM7-EX256
+
+
Description:
+Yet another use for the PWM module, this sample can be used to "play"
+notes via the on-board speaker using the PC keyboard. The on-screen
+keyboard shows what keys you must press for different notes, and you
+can set your octave and inter-note delay. Press ESC to end your eLua
+musical session :) A screenshot can be seen here.
+
+
bisect.lua: floating point at its best
+
+
Runs on: All Targets
+
+
Description: This is taken directly from the official Lua distribution, and it's
+here to show that eLua can do floating point just like on a desktop
+machine, albeit slower. Run it on your target, then run it again, but
+this time on the PC, and compare the results. Yes, they are identical.
+
+
morse.lua: because PWM is great, part II
+
+
Runs on: EK-LM3S8962, EK-LM3S6965, SAM7-EX256
+
+
Description: This uses the same PWM module for Morse code generation. Just enter a
+text, and listen to it getting Morsed on your board's speaker and on a blinking Led. The
+letters and Morse codes are also shown on the terminal. Use '+' and
+'-'' to change the frequency, up and down arrows to change the speed,
+'s' to mute/unmute, and ESC to exit.
+
+
lhttpd.lua: only with (e)Lua ...
+
+
Runs on: EK-LM3S8962, EK-LM3S6965
+
+
Description: This is one of those things that can show the real potential of a
+language (and hopefully the real potential of eLua in this case). As
+you have probably guessed by now, it's a web server written in Lua.
+Except that it is much more than this: it's a scripting web server! That's
+right, you can embed parts of Lua code into your pages, and the server
+will parse them and replace the Lua code with its output. To output
+something from Lua code embedded in a web page, simply use "print" in
+your Lua code. You can also write your pages completely in Lua (again,
+using "print"), the server knows how to handle this too. When is the
+last time you heard about a scripting web server in 256k of Flash/64k
+of RAM?
The full list of features is given below:
+
+
completely written in Lua
can handle a single connection at a time (for now)
can serve text and images (so far)
gets its files from the ROM file system (this will be extended when more filesystems are added)
can
+execute embedded Lua code and replace it with its output (via "print"
+statements). Embed Lua code in your HTML files between tags, make sure
+your HTML file extension is ".pht", and the server will preprocess it
+and replace the Lua code with its output
if a file with
+".lua" extension is requested, it doesn't send the file, but executes
+it and sends its output (via "print" statements)
+
+
This is still work in progress, but it already works quite well.
+Take a look at romfs/index.pht and romfs/test.lua from the source
+distribution for an example of how to include Lua code in your HTML
+files.
\ No newline at end of file
diff --git a/doc/pt/faq.html b/doc/pt/faq.html
new file mode 100644
index 00000000..ecd732f9
--- /dev/null
+++ b/doc/pt/faq.html
@@ -0,0 +1,209 @@
+
+
+
+Product
+
+
+
+
eLua Frequently Asked Questions
Welcome to the official eLua FAQ!
+It is assumed that you already know what eLua is, so here's a list of questions you might find useful while exploring eLua.
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 Lua homepage. In the documentation page
+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 Lua wiki. If you need more help, check the community page. Lua has a very friendly and active community.
+Q: How can I help eLua?
+
+
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 roadmap page, and if you see something there that you'd like to implement, don't hesitate to contact us.
+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 contact us.
+
+
+Q: Can I use eLua in my commercial, closed source project?
+
+
A: ### This needs to be updated for the BSD license .........
+
+
+Q: Is eLua fast enough?
+
+
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 examples page.
+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.
+
+
+Q: What are the minimum requirements for eLua?
+
+
A: 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.
+
+
+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?
+
+
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):
+
+
+
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)
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.
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.
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.
+
+
The lesson here is clear: understand your platform first!
+
+
+
+Q: What's the deal with floating-point Lua and integer only Lua?
+
+
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.
+
+
+
+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?
+
+
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 Linux under an Virtual Machine Manager (VirtualBox) and do everything else under Windows. Dado does everything on Linux and runs Windows under VMWare. 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 :)
+
+
+
+Q: Will you ever post instructions about how to compile toolchains under Cygwin in Windows?
+
+
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.
+
+
+
+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?
+
+
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.
+
+
+
+Q: I get "out of memory" errors when I run my Lua programs, what should I do?
+
+
A: There are a number of things you can try to overcome this:
+
+
precompile your source to bytecode: If you use bytecode instead of
+source code Lua won't need to compile your source, so you save some RAM.
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 table.concat to make a string from your table.
controll Lua's garbage collection 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.
\ No newline at end of file
diff --git a/doc/pt/genericmodules.html b/doc/pt/genericmodules.html
new file mode 100644
index 00000000..91413fd3
--- /dev/null
+++ b/doc/pt/genericmodules.html
@@ -0,0 +1,15 @@
+
+
+
+Product
+
+
+
+
+
eLua Generic Modules
+
+
+
+
+
+
\ No newline at end of file
diff --git a/doc/pt/gpio_ref.html b/doc/pt/gpio_ref.html
new file mode 100644
index 00000000..bd6d1cc1
--- /dev/null
+++ b/doc/pt/gpio_ref.html
@@ -0,0 +1,154 @@
+
+
+
+Product
+
+
+
+
+
[gpio.setpinvalue] pio.setpin(
+value, Pin1, Pin2 ... ): set the value to all the pins in the list
+
+
+ to "value" (0 or 1).
+
+
+
+
+
[gpio.setpinhigh] pio.set(
+Pin1, Pin2, ... ): set the value of all the pins in the list to 1.
+
+
+
+
+
[gpio.getpinvalue] Val1, Val2,
+... = pio.get( Pin1, Pin2, ... ): reads one or more pins and returns
+
+
+ their values (0 or 1).
+
+
+
+
+
[gpio.setpinlow] pio.clear(
+Pin1, Pin2, ... ): set the value of all the pins in the list to 0.
+
+
+
+
+
[gpio.configpin(gpio.DIR,
+gpio.DIR_INPUT)] pio.input( Pin1, Pin2, ... ): set the specified pin(s)
+as input(s).
+
+
+
+
+
+[gpio.configpin(gpio.DIR, gpio.DIR_OUTPUT)] pio.output( Pin1, Pin2, ...
+): set the specified pin(s) as output(s).
+
+
+
+
+
[gpio.setportvalue]
+pio.setport( value, Port1, Port2, ... ): set the value of all the ports
+in the
+
+
+ list to "value".
+
+
+
+
+
[gpio.getportvalue] Val1,
+Val2, ... = pio.getport( Port1, Port2, ... ): reads one or more ports
+and
+
+
+ returns their values.
+
+
+
+
+
[gpio.getportname]
+Port = pio.port( code ): return the physical port number associated
+with the given code. For example, "pio.port( pio.P0_20 )" will return
+0.
+
+
+
+
+
[gpio.getpinnumber] Pin =
+pio.pin( code ): return the physical pin number associated with the
+
+
+given code. For example, "pio.pin( pio.P0_20 )" will return 20.
+
+
+[gpio.togglepin([Pin1],
+[Pin2], ...)]
+
+[gpio.toggleport([Port1],
+[Port2], ...)]
+
+Another idea (can be added to the above ?)
+[gpio.configport(gpio.[FUNCTION], gpio.MASK, [MASK])]
+Ex:
+ gpio.configpin(gpio.DIR,
+gpio.DIR_INPUT) (.DIR_OUTPUT)
+ gpio.configpin(gpio.PULL,
+gpio.PULL_UP) (.PULL_DOWN,
+PULL_NO)
+
+
+[gpio.configport(gpio.DIR, gpio.DIR_INPUT, [Port1], [Port2], ...)]
+pio.port_input( Port1, Port2, ... ): set the specified port(s) as
+input(s).
+
+
+
+
+
+[gpio.configport(gpio.DIR, gpio.DIR_OUTPUT, [Port1], [Port2], ...)]
+pio.port_output( Port1, Port2, ... ): set the specified port(s) as
+output(s).
+
+
+
+
+
+[gpio.configpin(gpio.PULL, gpio.PULL_UP, [Pin1], [Pin2], ...)]
+pio.pullup( Pin1, Pin2, ... ): enable internal pullups on the specified
+pins.Note that some CPUs might not provide this feature.
+
+
+
+
+
+[gpio.configpin(gpio.PULL, gpio.PULL_DOWN, [Pin1], [Pin2], ...)]
+pio.pulldown( Pin1, Pin2, ... ): enable internal pulldowns on the
+specified pins. Note that some CPUs might not provide this feature.
+
+
+
+
+
+[gpio.configpin(gpio.PULL, gpio.PULL_NO, [Pin1], [Pin2], ...)]
+pio.nopull( Pin1, Pin2, ... ): disable the pullups/pulldowns on the
+specifiedpins. Note that some CPUs might not provide this feature.
+
+
+
+What is the real advantage/reason of having a pin "list" on some of
+these functions ? If we cannot build a table with them, there's really
+no great use of this, as we cannot create the list in run time and some
+other proposed functions solve the problem of avoiding more than one
+call for several pins.
+A: It IS usefull and sometimes necessary so it will stay.....
+
+
\ No newline at end of file
diff --git a/doc/pt/net_ref.html b/doc/pt/net_ref.html
new file mode 100644
index 00000000..0a62c30b
--- /dev/null
+++ b/doc/pt/net_ref.html
@@ -0,0 +1,11 @@
+
+
+
+Product
+
+
+
+
+
net
+
+
\ No newline at end of file
diff --git a/doc/pt/news.html b/doc/pt/news.html
new file mode 100644
index 00000000..79a00d56
--- /dev/null
+++ b/doc/pt/news.html
@@ -0,0 +1,138 @@
+
+
+
+Product
+
+
+
+
eLua Project News
+
+
02 February 2009
+
We know that we haven't had an official release in a while now, but
+there's a lot of stuff going on with the project. The next release will
+definitely happen before the enf of February and it will come with a
+lot of interesting new features, including support for two new
+platforms, a completely redesigned documentation system, and a few
+surprises that I won't mention just yet :) So stay tuned, we're working
+hard to make eLua better for you.
+
+
01 November 2008
+
Version 0.5 is released! Among other goodies, it brings TCP/IP support to eLua. Here's the changelog:
+
+
Added support for STR7 CPUs from ST
Added TCP/IP support using the uIP stack
Added support for console and shell over TCP/IP besides the previous serial link
Added the "net" module (eLua's interface to TCP/IP functions)
Added the "cpu" module (eLua's interface to the target CPU)
IMPORTANT NOTE: you'll need to update your binutils to version 2.19 to use this release with Cortex CPUs. The Cortex GCC tutorial was updated with this information.
+
+
Enjoy this new release. The next one will be focused on reducing the
+memory footprint (both Flash and RAM) of eLua, and (hopefully) will
+also come with a nice surprise :)
+
+
16 October 2008
+
The OpenOCD tutorial was updated with a new section about how to use OpenOCD with a STR7 CPU from ST. Also, the about page was updated with more information about the authors of eLua. Expect a new eLua version towards the end of October.
+
+
10 September 2008
+
Version 0.4.1 is released! This is a minor release, its main purpose
+is to "keep in sync" with Lua, thus eLua now has the latest official
+Lua version (5.1.4). You probably don't need to upgrade to this version
+(since 5.1.4 only fixes some minor/exotic bugs in 5.1.3) so I'm only
+providing the source code, without any binaries. Here's the changelog:
+
+
Changed the file system structure; now you can build both Lua versions (floating point and int only) from the same directory
Made the math library configurable using the existent 'platform libraries' mechanism
The
+"os" and "package" modules are no longer loaded by Lua, since they
+can't be used anyway. Because of this, the code size of eLua was
+reduced.
Project documentation updated
+
+
+
02 September 2008
+
Version 0.4 is released! Here's the changelog:
+
+
Added support for LPC2888 (preliminary)
Added PWM module
New
+samples: TV-B-Gone (power off your TV), piano (play piano from your PC
+keyboard), pwmled (fade led on/off), all based on the new PWM module
Added
+support for multiple memory spaces (this can be used to take advantage
+of both the internal CPU RAM and external RAM chips on boards that have
+external RAM)
Autorun: if "autorun.lua" is found in the filesystem, it is executed before starting the shell
Added "pack" (binary data packing/unpacking) and "bit" (binary operations) modules
Build system updated, easier to use, now it knows how to handle "boards" as well as CPUs
Modified the existing platform modules to take less RAM and to report an error when an unavailable resource is requested
OK, this took less time than I expected :) The page on how to use eLua with STR9 CPUs is available here.
+
+
09 August 2008
+
Version 0.3 is released! The project page was updated, with more
+sections to come soon, including a tutorial on how to use eLua with
+STR9 CPUs. Here's the changelog for the 0.3 version:
+
+
Now you can play hangman directly from eLua :), thanks to the new "term" module that handles ANSI escape sequences
Added support for ST STR912FW44
Added support for Cortex LM3S6965
More intuitive and flexible build system (new syntax, component selection at build time)
eLua examples are now part of the repository
Project documentation updated
+
+
+
06 August 2008
+
The web page was updated with an OpenOCD tutorial
+that will continue to grow as more and more targets are added. This
+update is also an informal announcement of the soon to come eLua 0.3
+release, which (among other things) brings support for the STR9-comStick.
+
+
29 July 2008
+
eLua has a new home at BerliOS. Besides the new menu system on the
+home page, the biggest news is that the code repository is now based on
+SVN (as opposed to CVS until now). If you're a developer, this is
+probably good news for you. If not, check the download page to learn
+about the new eLua download locations.
+
+
28 July 2008
+
I got a report that compiling a simple C++ program for a Cortex CPU with a compiler built after my instructions
+failed with a linker error. I checked and I found out that the gcc's
+C++ library (libstdc++) wasn't even build properly for Cortex-M3. My
+bad. I updated the tutorial page. The only modification is in step 4,
+where you need to give more flags to the "make" commands, not just the
+CFLAGS. Thanks for reporting this.
+
+
27 July 2008
+
Version 0.2 is released! Also, as you probably figured out by now,
+the project page was seriously updated. Here's the changelog for the
+0.2 version:
+
+
Added support for Cortex LM3S8962
New platform modules (UART, SPI, Timer, platform data)
First release of the eLua shell
Lua source files can now be sent to target with XMODEM
You can download binary file images from the "files" section, so you don't need to compile eLua yourself
+
+
+
25 July 2008
+
Project page updated to reflect the current eLua status and roadmap.
+Now there is a separate status and roadmap page. Also, version 0.2 is
+about to be released soon, with many new features, improvements and
+support for a new platform. More documentation is on the way, too.
+
+
15 July 2008
+
Added a tutorial on how to make your own eLua USB bootable stick! Get it while it's hot! :)
+
+
11 July 2008
+
eLua version 0.1 is finally out! Be sure to check the download page,
+and also the project page. The build instructions are included in the
+eLua archive. Also, new tutorials (building cross compilers for ARM and
+i386) were added, and the boot into Lua page was updated to reflect the fact that you can build the eLua ELF file yourself now!
+
+
07 July 2008
+
I'm still "brushing" the source code and adding more documentation
+before commiting the first version to CVS. Meanwhile, I prepared a
+(hopefully) nice surprise for all of you who showed interest in eLua
+(and for those of you who didn't, hopefully this will make you curious
+:) ). So, if you ever wanted to boot your PC directly in Lua, take a
+look here.
+That's right: no OS, just GRUB loading a multiboot compliant ELF file!
+The ELF file is build from the exact source tree I'm using to build
+eLua for embedded devices, I only needed to change the platform layer
+(more about this after uploading the sources and adding some
+documentation).
+I hope you'll enjoy this at least as much as I do. While this is only a
+proof of concept, I am not going to abandon the "standalone Lua on PC"
+idea, because it could have some very interesting applications (think
+"BIOS scripting with Lua", Open Firmware with Lua instead of Forth, educational applications and many others.)
+
+
05 July 2008
+
The web page is up! For now you can only read the project description. Also, a tutorial about how to compile a GCC toolchain for the Cortex architecture is available here.
+
+
\ No newline at end of file
diff --git a/doc/pt/overview.html b/doc/pt/overview.html
new file mode 100644
index 00000000..ed55555c
--- /dev/null
+++ b/doc/pt/overview.html
@@ -0,0 +1,98 @@
+
+
+
+Product
+
+
+
+
What is eLua ?
+eLua
+stands for Embedded Lua and the project
+aims to offer the full set of features of the Lua Programming Language to the embedded world. eLua
+is not a striped down sub-sub-set of a language, much on the contrary.
+Besides offering different flavors of full Lua implementations
+(ie: integer or fp numbers, ...), eLua
+extends Lua with some neat types
+for the embedded world (ie: light tables, light functions, ...), to
+allow them to be romable and the aplications to exploit better the
+balance ROM/RAM of the current MCUs.
+Lua is the perfect example of a
+minimal, yet fully
+functional language. Although generally advertised as a "scripting
+language" (and used accordingly especially in the game industry), it is
+also fully capable of running stand-alone programs. Its limited
+resource requirements make it suitable to a lot of microcontroller
+families. Lua's incredible portability (Lua code is ANSI C and runs virtually in every known platform) and eLua's
+roadmap for supporting the most used MCUs on the market, opens to the
+embedded world a new degree of "portability". Write your program in Lua
+and run it, without or with very few modifications, on every eLua supported platform, even with different architectures!
The aim of the project is to have a fully functional Lua development
+environment on the microcontroller itself,
+without the need to install a specific development environment on the PC side.
+Initially, a PC will still be needed in order to edit the Lua programs
+for the microcontroller. But as the project evolves this requirement
+will be relaxed, as a basic editor (also residing on the
+microcontroller) will be usable with a variety of input/output devices.
+
+
Audience
+eLua has a wide and varied audience, from highly skilled developers
+that want to extend their programs with the Lua library facilities and
+portable features, to the newcomer to the embedded world, who wants an
+easy and powerfull environment for prototyping, rapid application
+development, educational or final product quick production.
eLua
+allows new embedded world programmers to use the simplicity and
+powerfullness of the Lua programming language, to hide low-level
+complexities and platform/architecture-dependent features. A whole new
+class of embedded programmers, with no deep knowledge of the peripheral
+details but with powerfull aplications in mind is now possible. Modern
+designers and multimedia artists are already an example of this "class".
On
+the other edge of the category, oldtime and skilled embedded developers
+can create complex and abstract modules, offering a degree of portability
+to the final user never dreamed before on the embedded world.
eLua audience would be among the following categories:
Embedded developers that are looking for a fast, easy to use and powerful way of coding.
First-time
+embedded programmers (or simply first time programmers) that are
+looking for an easy way to "dive" into the embedded programming world.
+eLua is a great learning tool.
People that aren't really
+developers, but want to be able to prototype an embedded system
+fast and painless, without having to learn C for that.
Embedded
+developers that need powerfull meta-language mecanisms for complex code
+algorithms and data description, not offered by the languages available
+to the embedded development world.
Field
+engineers that can go their customer site and debug an eLua module on
+site, without any preparation at all, since the whole development
+environment resides on chip already.
Its origins come from the ReVaLuaTe
+project also developed by Bogdan Marinescu (as a contest entry for the
+2005 Renesas M16CDesign Contest), and the Volta Project, managed by
+Dado Sutter at PUC-Rio from 2005 to 2007.
+
eLua is an Open Source and
+collaborative project and an always growing list of collaborators can
+be found in our Credits
+Page
+
ReVaLuaTe Project
Volta Project
+
Contacts
+
eLua authors can be contacted at:
Bogdan Marinescu: bogdan dot marinescu at gmail dot com
+
+
Dado Sutter: dadosutter at gmail dot com
You are also welcome to share your questions and suggestions on our Mail Discussion List
+
+
License
+
+
eLua is Open Source and is freely
+distributed under the GPL (migrating to BSD soon) licence.
+
The Lua code (with slight modifications) is included in the
+source
+tree and is, of course, licensed under the same MIT license that Lua
+uses.
+
The terms of each of these licences can be viewed on their own
+pages at:
+
\ No newline at end of file
diff --git a/doc/pt/platdependentmodules.html b/doc/pt/platdependentmodules.html
new file mode 100644
index 00000000..153a38b0
--- /dev/null
+++ b/doc/pt/platdependentmodules.html
@@ -0,0 +1,17 @@
+
+
+
+Product
+
+
+
+
+
eLua Platform Dependent
+Modules
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/doc/pt/platdepmodules.html b/doc/pt/platdepmodules.html
new file mode 100644
index 00000000..153a38b0
--- /dev/null
+++ b/doc/pt/platdepmodules.html
@@ -0,0 +1,17 @@
+
+
+
+Product
+
+
+
+
+
eLua Platform Dependent
+Modules
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/doc/pt/pwm_ref.html b/doc/pt/pwm_ref.html
new file mode 100644
index 00000000..0ee9b37c
--- /dev/null
+++ b/doc/pt/pwm_ref.html
@@ -0,0 +1,135 @@
+
+
+
+Product
+
+
+
+
+
pwm
+
+
+
+
It allows Lua to
+use the PWM blocks on the target CPU.
+
+
+
+
[pwm.setup](pwm.setup( id,
+frequency, Active Cycle )
+Data = pwm.setup( id, frequency, duty ): sets the PWM block 'id' to
+generate the specified frequency with the specified duty cycle (duty is
+an integer number from 0 to 100, specifying the duty cycle in
+percents). It returns the actual frequency set on the PWM block.
+
+
+
+
+
+
Here there is a bigger
+change on the proposal.
+
+
The Timer Clock and the
+PWM "frame" frequency would be set up in the same function (.setup)
+
+
The normal control
+function would only set the active cicle (.setcycle)
+
+
The original .setup
+function would then be replaced by:
+
+
+
+
[pwm.setup( id,
+tmrclock, pwm_frequency ) ]
+
+
[pwm.setcycle(
+id, active_cycle )]
+
[pwm.start()]
+pwm.start( id ): start the PWM block 'id'.
+
+
+
+
[pwm.stop()]
+pwm.stop(
+id ): stop the PWM block 'id'.
+
+
+
Data = pwm.setclock( id, clock ):
+set the base clock of the PWM block 'id' to
+
+
the given clock.
+In returns the actual clock set on the PWM block.
+
+
+
+
[pwm.getclock]
+Data
+= pwm.getclock( id ): returns the base clock of the PWM block 'id'.
+
+
+
+
+
+
Is it really necessary to
+have
+.getclock ?? The clock is set by the same program, is seldom changed
+during operation, ..........
+
+
If really needed, it could
+be something like pwm.gettimerclock(id) or something (must be
+discussed.....)
+
A Generic eLua Module is a module that can be used by a Lua program running on any of the supported eLua platforms. Write your code once and it is already automatically ported to the main platforms of the embedded world.
bit
+Bitwise operations in eLua is implemented thru
+the BitLib library, from Reuben Thomas.
+BitLib project is hosted at LuaForge on
+http://luaforge.net/projects/bitlib
+
Res = bit.bnot( value )
+
+unary negation
+
+
+
+
+
Res = bit.band( v1, v2, ... )
+
bitwise
+"and"
+
+
+
+
+
Res = bit.bor( v1, v2, ... )
+
bitwise
+"or"
+
+
+
+
+
Res = bit.bxor( v1, v2, ... )
+
+bitwise"exclusive or"
+
+
+
+
+
Res = bit.lshift( value, pos )
+
+shift "value" left "pos" positions.
+
+
+
+
+
Res = bit.rshift( value, pos )
+
+shift "value" right "pos" positions. The sign is not propagated.
+
+
+
+
+
Res = bit.arshift( value, pos )
+
+shift "value" right "pos" positions. The sign is propagated
+("arithmetic shift").
+
+
+
+
+
Res = bit.bit( bitno )
+
+a shortcut for bit.lshift( 1, bitno )
+
+
+
+
+
Res1, Res2, ... = bit.set( bitno, v1,
+v2, ... )
+
+set the bit at position "bitno" in v1, v2, ... to 1.
+
pio: only
+some platform have internal pullups for the pio pins, while Cortex is
+the only platform that also provides pulldowns for its pios. 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.
+
+
+
[pio.setpinvalue] pio.setpin(
+value, Pin1, Pin2 ... ): set the value to all the pins in the list
+
+
+ to "value" (0 or 1).
+
+
+
+
+
[pio.setpinhigh] pio.set(
+Pin1, Pin2, ... ): set the value of all the pins in the list to 1.
+
+
+
+
+
[pio.getpinvalue] Val1, Val2,
+... = pio.get( Pin1, Pin2, ... ): reads one or more pins and returns
+
+
+ their values (0 or 1).
+
+
+
+
+
[pio.setpinlow] pio.clear(
+Pin1, Pin2, ... ): set the value of all the pins in the list to 0.
+
+
+
+
+
[pio.configpin(pio.DIR, pio.DIR_INPUT)] pio.input( Pin1, Pin2, ... ): set the specified pin(s)
+as input(s).
+
+
+
+
+
+[pio.configpin(pio.DIR, pio.DIR_OUTPUT)] pio.output( Pin1, Pin2, ...
+): set the specified pin(s) as output(s).
+
+
+
+
+
[pio.setportvalue]
+pio.setport( value, Port1, Port2, ... ): set the value of all the ports
+in the
+
+
+ list to "value".
+
+
+
+
+
[pio.getportvalue] Val1,
+Val2, ... = pio.getport( Port1, Port2, ... ): reads one or more ports
+and
+
+
+ returns their values.
+
+
+
+
+
[pio.getportname]
+Port = pio.port( code ): return the physical port number associated
+with the given code. For example, "pio.port( pio.P0_20 )" will return
+0.
+
+
+
+
+
[pio.getpinnumber] Pin =
+pio.pin( code ): return the physical pin number associated with the
+
+
+given code. For example, "pio.pin( pio.P0_20 )" will return 20.
+
+
+[pio.togglepin([Pin1],
+[Pin2], ...)]
+
+[pio.toggleport([Port1],
+[Port2], ...)]
+
+Another idea (can be added to the above ?)
+[pio.configport(pio.[FUNCTION], pio.MASK, [MASK])]
+Ex:
+ pio.configpin(pio.DIR, pio.DIR_INPUT) (.DIR_OUTPUT)
+ pio.configpin(pio.PULL, pio.PULL_UP) (.PULL_DOWN,
+PULL_NO)
+
+
+[pio.configport(pio.DIR, pio.DIR_INPUT, [Port1], [Port2], ...)]
+pio.port_input( Port1, Port2, ... ): set the specified port(s) as
+input(s).
+
+
+
+
+
+[pio.configport(pio.DIR, pio.DIR_OUTPUT, [Port1], [Port2], ...)]
+pio.port_output( Port1, Port2, ... ): set the specified port(s) as
+output(s).
+
+
+
+
+
+[pio.configpin(pio.PULL, pio.PULL_UP, [Pin1], [Pin2], ...)]
+pio.pullup( Pin1, Pin2, ... ): enable internal pullups on the specified
+pins.Note that some CPUs might not provide this feature.
+
+
+
+
+
+[pio.configpin(pio.PULL, pio.PULL_DOWN, [Pin1], [Pin2], ...)]
+pio.pulldown( Pin1, Pin2, ... ): enable internal pulldowns on the
+specified pins. Note that some CPUs might not provide this feature.
+
+
+
+
+
+[pio.configpin(pio.PULL, pio.PULL_NO, [Pin1], [Pin2], ...)]
+pio.nopull( Pin1, Pin2, ... ): disable the pullups/pulldowns on the
+specifiedpins. Note that some CPUs might not provide this feature.
+
+
+
net
+
+
pwm
+
+
+
+
It allows Lua to
+use the PWM blocks on the target CPU.
+
+
+
+
[pwm.setup](pwm.setup( id,
+frequency, Active Cycle )
+Data = pwm.setup( id, frequency, duty ): sets the PWM block 'id' to
+generate the specified frequency with the specified duty cycle (duty is
+an integer number from 0 to 100, specifying the duty cycle in
+percents). It returns the actual frequency set on the PWM block.
+
+
+
+
+
+
Here there is a bigger
+change on the proposal.
+
+
The Timer Clock and the
+PWM "frame" frequency would be set up in the same function (.setup)
+
+
The normal control
+function would only set the active cicle (.setcycle)
+
+
The original .setup
+function would then be replaced by:
+
+
+
+
[pwm.setup( id,
+tmrclock, pwm_frequency ) ]
+
+
[pwm.setcycle(
+id, active_cycle )]
+
[pwm.start()]
+pwm.start( id ): start the PWM block 'id'.
+
+
+
+
[pwm.stop()]
+pwm.stop(
+id ): stop the PWM block 'id'.
+
+
+
Data = pwm.setclock( id, clock ):
+set the base clock of the PWM block 'id' to
+
+
the given clock.
+In returns the actual clock set on the PWM block.
+
+
+
+
[pwm.getclock]
+Data
+= pwm.getclock( id ): returns the base clock of the PWM block 'id'.
+
+
+
+
+
+
spi
+
+Actual_clock = spi.setup( id,
+spi.MASTER | spi.SLAVE, clock, cpol, cpha,
+
+
+ databits):
+set the SPI interface with the given parameters, returns the clock
+
+
+ that
+was set for the interface.
+
+
+
+
+spi.select(
+id
+): sets the selected spi as active (sets the SS line of the given
+interface).
+
+
+
+spi.unselect(
+id ): clears the SS line of the given interface.
+
+
+
+spi.send(
+id, Data1, Data2, ... ): sends all the data to the specified SPI
+
+
+ interface.
+
+
+
+
+[spi.sendrecv(id,
+Out1, Out2, ...)]
+In1,
+In2, ... = spi.send_recv( id, Out1, Out2, ... ): sends all the "out"
+bytesto
+the specified SPI interface and returts the data read after each sent
+byte.
+
+
+Returning
+several values in this blocking way would not complicate some queued
+send implementations ? (ok, this could be another function :)
+
+
+Sending multiple data/chars in a single
+call and not in
+a table argument does not allow the data to be built in run time
+(without some string massage, of course :)
+
+
+
+
+
sys
+
+
[sys.platform()]
+pd.platform(): returns the platform name (f.e. LM3S)
+
+
+
+
[sys.mcu()]
+pd.cpu(): returns the CPU name (f.e. LM3S8962)
+
+
[sys.cpu()]
+would return ARM Cortex M3 in this case.....
+
+
+ [sys.board()]
+pd.board(): returns the CPU board (f.e. EK-LM3S8962)
+
+[term.cleareol]
+term.clreol(): clear from the current cursor position to the end of the
+line
+
+
[term.moveto]
+term.gotoxy( x, y ): position the cursor at the given coordinates
+
+
+
[term.moveup]
+term.up( delta ): move the cursor up "delta" lines
+
+
[term.movedown]
+term.down( delta ): move the cursor down "delta" lines
+
+
[term.moveleft]
+term.left( delta ): move the cursor left "delta" lines
+
+[term.moveright] term.right(
+delta ): move the cursor right "delta" lines
+
+
+[term.getlinecount] Lines = term.lines(): returns the number of lines
+
+
+[term.getcolcount] Cols = term.cols(): returns the number of columns
+
+
+
[term.printstr]
+term.putstr( s1, s2, ... ): writes the specified string(s) to the
+terminal
+
+
+
[term.printchar] term.put( c1, c2, ... ): writes the
+specified character(s) to the terminal
+
+
[term.getx] Cx =
+term.cursorx(): return the cursor X position
+
+
[term.gety] Cy =
+term.cursory(): return the cursor Y position
+
+
[term.inputchar]
+c = term.getch( term.WAIT | term.NOWAIT ): returns a char read from the
+
+ terminal.
+
+
+
+
tmr
+
+
+
It allows Lua to
+execute timer specific operations (delay, read timer value,
+
+
start timer, get
+time difference).
Some notes on timers:
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)
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.
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.
+
+
+
+
tmr.delay( id, delay ): uses timer
+'id' to wait for 'delay' us.
+
+
+
+
Data
+= tmr.read( id ): reads the value of timer 'id'. The returned value is
+
+
platform
+dependent.
+
+
+
+
Data
+= tmr.start( id ): start the timer 'id', and also returns its value at
+
+
the moment of
+start. The returned value is platform dependent.
+
+
+
+
diff
+= tmr.diff( id, end, start ): returns the time difference (in us)
+between
+
+
the timer values
+'end' and 'start' (obtained from calling tmr.start or
+
+
tmr.read). The
+order of end/start is irrelevant.
+
+
+
+
Data = tmr.mindelay( id ): returns
+the minimum delay (in us ) that can be
+
+
achieved by
+calling the tmr.delay function. If the return value is 0, the
+
+
platform layer
+is capable of executing sub-microsecond delays.
+
+
+
+
Data = tmr.maxdelay( id ): returns
+the maximum delay (in us) that can be
+
+
achieved by
+calling the tmr.delay function.
+
+
+
+
Data = tmr.setclock( id, clock ):
+sets the clock of the given timer. Returns the
+
+
actual clock set
+for the timer.
+
+
+
+
Data = tmr.getclock( id ): return
+the clock of the given timer.
+
A Platform Dependent eLua Module is a module that runs only on one or on a few supported eLua platforms. These
+modules make use of specifical devices and features offered by some
+kits and allow eLua aplications to make the best use of the external
+hardware on your platforms.
adc - Analog to Digital Conversion Module
Currently runs on: LM3Sxxxx
The ADC module handles the Analog to Digital Conversion Peripherals.
adc.sample(channel_id) Generate one processed sample.
adc.getsamples(channel_id,
+[count]) Request count samples from the buffer. if singular, an
+integer is returned. if multiple, a table of integers is returned. If
+count is either zero or omitted, all available samples are returned.
adc.maxval(channel_id) Returns the largest integer one can expect fromr this channel on a given platform (based on bit depth).
adc.samplesready(channel_id) Returns the number of samples waiting in the buffer.
adc.dataready(channel_id) If running in non-blocking mode, this will indicate if all of the
+samples requested from the last sample or burst have been acquired and
+are waiting in the buffer.
adc.setmode(channel_id,
+mode) mode 0 sets blocking mode. adc.getsamples will wait for
+requested samples to be captured before returning. mode 1 sets non-blocking mode
adc.setsmoothing(channel_id, length) Set the length of the smoothing filter. This must be a power of 2 (maximum = 128)
adc.getsmoothing(channel_id) Get the current smoothing length in use.
adc.burst(
+channel_id, count, timer_id, frequency) Request that count samples be converted from channel_id, using timer_id at frequency. count must be greater than zero and a power of 2
+
disp
+Currently runs on: LM3Sxxxx
The disp module handles the RIT OLED display usage on Luminary Micro Cortex-M3 boards
+
+disp.init( freq )
freq specifies the SSI Clock Frequency to be used.
This function initializes the SSI interface to the OLED display and configures the SSD1329 controller on the panel.
+disp.enable()
+
Enable the SSI component of the OLED display driver.
freq specifies the SSI Clock Frequency to be used. This function initializes the SSI interface to the OLED display.
+
+
+disp.disable()
+
+
+
disp.on()
+
+
Turns on the OLED display. This function will turn on the OLED display, causing it to display the contents of its internal frame buffer.
+
+
+disp.off()
Turns off the OLED display This
+function will turn off the OLED display. This will stop the
+scanning of the panel and turn off the on-chip DC-DC converter,
+preventing damage to the panel due to burn-in (it has similar
+characters to a CRT in this respect).
+
+disp.clear()
Clears the OLED display. This function will clear the display RAM. All pixels in the display will be turned off.
+ disp.print( str, x, y, gray )
Displays a string on the OLED display.
Calling Arguments: str is a string to be displayed. x is the horizontal position to display the string, specified in columns from the left edge of the display. y is the vertical position to display the string, specified in rows from the top edge of the display. gray is the 4-bit gray scale (intensity) value to be used for displayed text.
This
+function will draw a string on the display. Only the ASCII
+characters between 32 (space) and 126 (tilde) are supported;
+other characters will result in random data being draw on the
+display (based on whatever appears before/after the font in
+memory). The font is mono-spaced, so characters such as ``i'' and
+``l'' have more white space around them than characters such as ``m''
+or ``w''. If the drawing of the string reaches the right edge of the
+display, no more characters will be drawn. Therefore, special
+care is not required to avoid supplying a string that is ``too long''
+to display.
Because the OLED display packs 2 pixels of data in a single byte, the parameter \e ulX must be an even column number (for example, 0, 2, 4, and so on).
+
+
+disp.draw( img, x, y, withd, height, gray )
Displays an image on the OLED display.
img a pointer to the string data representing a rit format image to display. x is the horizontal position to display the string, specified in columns from the left edge of the display. y is the vertical position to display the string, specified in rows from the top edge of the display. width is the width of the image, specified in columns. height is the height of the image, specified in rows.
This
+function will display a bitmap graphic on the display. Because of
+the format of the display RAM, the starting column x and the number of
+columns y must be an integer multiple of two. The image data is
+organized with the first row of image data appearing left to
+right, followed immediately by the second row of image data. Each
+byte contains the data for two columns in the current row, with
+the leftmost column being contained in bits 7:4 and the rightmost
+column being contained in bits 3:0. For example, an image six
+columns wide and seven scan lines tall would be arranged as
+follows (showing how the twenty one bytes of the image would appear on
+the display):
Because the OLED display packs 2 pixels of data in
+a single byte, the parameter x must be an even column number (for
+example, 0, 2, 4, and so on).
+
\ No newline at end of file
diff --git a/doc/pt/spi_ref.html b/doc/pt/spi_ref.html
new file mode 100644
index 00000000..8aecb775
--- /dev/null
+++ b/doc/pt/spi_ref.html
@@ -0,0 +1,100 @@
+
+
+
+Product
+
+
+
+
+
spi
+
+Actual_clock = spi.setup( id,
+spi.MASTER | spi.SLAVE, clock, cpol, cpha,
+
+
+ databits):
+set the SPI interface with the given parameters, returns the clock
+
+
+ that
+was set for the interface.
+
+
+
+
+spi.select(
+id
+): sets the selected spi as active (sets the SS line of the given
+interface).
+
+
+
+spi.unselect(
+id ): clears the SS line of the given interface.
+
+
+
+spi.send(
+id, Data1, Data2, ... ): sends all the data to the specified SPI
+
+
+ interface.
+
+
+
+
+[spi.sendrecv(id,
+Out1, Out2, ...)]
+In1,
+In2, ... = spi.send_recv( id, Out1, Out2, ... ): sends all the "out"
+bytesto
+the specified SPI interface and returts the data read after each sent
+byte.
+
+
+Returning
+several values in this blocking way would not complicate some queued
+send implementations ? (ok, this could be another function :)
+
+
+Sending multiple data/chars in a single
+call and not in
+a table argument does not allow the data to be built in run time
+(without some string massage, of course :)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/doc/pt/status.html b/doc/pt/status.html
new file mode 100644
index 00000000..31a221ce
--- /dev/null
+++ b/doc/pt/status.html
@@ -0,0 +1,418 @@
+
+
+
+Product
+
+
+
+
+
Current Status of Platforms and Modules Supported
+
As already stated, eLua allows you to run Lua completely on
+the
+microcontroller. A fast-growing set of complementary modules is also
+provided, for Lua programming eLua's generic (portable) peripherals.
+
The following features are ready or being implemented:
a very low footprint embedded rom file system, easy to port
+to different types of memory chips and other storage devices
+
a small FAT rw file system layer for SD cards.
+
an embedded editor, to edit Lua programs directly via a
+serial connection or other input devices
+
a minimal "shell" (for file operations, environment
+configuration and other facilities)
+
network support
+
an embedded http server
+
Terminal / Console over Ethernet
+
+
Porting eLua to another compatible platform should be as easy
+and
+painless as possible. Currently this is restricted to platforms for
+which the gcc+newlib combo is available. This might change in the
+future, but please not that this is not a priority of the project at
+this point.
+
Also, the Lua "core" comes in two flavors: "regular Lua"
+(using
+floating point as the number type) and "integer Lua" (using integers).
+We'll add more about this in a future tutorial
+about Lua. For now, it's enough to say that "regular Lua" will be able
+to perform floating point operations (but will be slower because the
+floating point operations will be emulated in software on the MCU),
+while "integer Lua" will only be able to perform operations with
+integer numbers (but support for fixed and even floating point can be
+added with separate modules) and thus will be faster.
+
+
Symbol Legends
+
+
+
+
+
Symbol
+
Meaning
+
+
+
+
Implemented and tested
+
+
+
+
Implemented, not tested
+
+
+
+
Not yet implemented
+
+
+
+
Not applicable
+
+
+
+
Platforms x Modules Supported
The following table shows the status of eLua's modules implementation by
+platform.
+
+
+
+
Module
+
PIO
+
SPI
+
UART
+
TMR
+
PWM
+
NET
+
CPU
+
ADC
+
+
MCU
+
+
LM3S8962
+
+
+
+
+
+
+
+
+
+
+
LM3S6965
+
+
+
+
+
+
+
+
+
+
+
i386
+
+
+
+
+
+
+
+
+
+
+
AT91SAM7X256
+
+
+
+
+
+
+
+
+
+
+
AT91SAM7X512
+
+
+
+
+
+
+
+
+
+
+
STR912FW44
+
+
+
+
+
+
+
+
+
+
+
LPC2888
+
+
+
+
+
+
+
+
+
+
+
STR711FR2
+
+
+
+
+
+
+
+
+
+
+
AVR32
+
+
+
+
+
+
+
+
+
+
+
+
+
+
STM32
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Status of features
+& roadmap
+
The following table shows the status of some existent and
+planned eLua
+features.
GPS - NMEA0183
+Sentences parsing and command handling
+
+
+
+
PID
+- Proportional, Integrative & Derivative Control
+
+
+
+
LCD
+- Liquid Crystal Display support
+
+
+
+
ROT
+- Rotary Switch & Encoder support
+
+
CHDK - Interfacing with Canon cameras also running Lua under CHKD
DISP - External text & graphics displays
FUZZ - Fuzzy Logic Control
HUM - Humity Sensors over SPI, UART, I2C, PIO, ....
TMP - Temperature Sensors over SPI, UART, I2C, PIO, ....
BAR - Pressure Sensors over SPI, UART, I2C, PIO, ....
X10 - X10 Protocol support for X10 Devices Mapping & Control
MCP - Magnetic Compass abstraction
PS2 - Play Station 2 Joystick interfacing support
+
+
If you need a module for a specific device support or logic & modeling abstraction, don't hesitate to suggest it in our eLua User's and Developers List. You may have one ready before you would imagine :)
+
\ No newline at end of file
diff --git a/doc/pt/sys_ref.html b/doc/pt/sys_ref.html
new file mode 100644
index 00000000..af0712ed
--- /dev/null
+++ b/doc/pt/sys_ref.html
@@ -0,0 +1,69 @@
+
+
+
+Product
+
+
+
+
+
sys
+
+
[sys.platform()]
+pd.platform(): returns the platform name (f.e. LM3S)
+
+
+
+
[sys.mcu()]
+pd.cpu(): returns the CPU name (f.e. LM3S8962)
+
+
[sys.cpu()]
+would return ARM Cortex M3 in this case.....
+
+
+ [sys.board()]
+pd.board(): returns the CPU board (f.e. EK-LM3S8962)
+
+
+
Could also be elua.
+
+
Many other miscelania
+functions will need a place to live and sys or elua is more generic
+than pd for it.
+
At first, the idea of an i386 "cross" compiler under Linux seems
+strange. After all, you're already running Linux on a i386 compatible
+architecture. But the compiler is sometimes tied in misterious ways
+with the operating system it's running on (see for example this page
+for some possible symptoms). And after all, you want to use Newlib, not
+libc, and to customize your development environment as much as
+possible. This tutorial will show you how to do that.
+
+
DISCLAIMER: I'm by no means a specialist in the
+GCC/newlib/binutils compilation process. I'm sure that there are better
+ways to accomplish what I'm describing here, however I just wanted a
+quick and dirty way to build a toolchain, I have no intention in
+becoming too intimate with the build process. If you think that what I
+did is wrong, innacurate, or simply outrageously ugly, feel free to contact me and I'll make the necessary corrections. And of course, this tutorial comes without any guarantees whatsoever.
+
+
› Prerequisites
+
To build your toolchain you'll need:
+
+
a computer running Linux: I use Ubuntu 8.04, but any Linux
+will do as long as you know how to find the equivalent of "apt-get" for
+your distribution. I won't be going into details about this, google it
+and you'll sure find what you need. It is also assumed that the Linux
+system already has a "basic" native toolchain installed (gcc/make and
+related). This is true for Ubuntu after installation. Again, you might
+need to check your specific distribution.
GNU binutils: get it from here.
+At the moment of writing this, the latest versions is 2.18, which for
+some weird reason refuses to compile on my system, so I'm using 2.17
+instead.
GCC: version 4.3.0 or newer is recommended. As
+I'm writing this, the latest GCC version is 4.3.1 which I'll be using
+for this tutorial. Download it from here after choosing a suitable mirror.
Newlib: as I'm writing this, the latest official Newlib version is 1.16.0. Download it from the Newlib FTP directory.
Also,
+the tutorial assumes that you're using bash as your shell. If you use
+something else, you might need to adjust some shell-specific commands.
+
+
+
Also, you need some support programs/libraries in order to compile the toolchain. To install them:
Next, decide where you want to install your toolchain. They
+generally go in /usr/local/, so I'm going to assume
+/usr/local/cross-i686 for this tutorial. To save yourself some typing,
+set this path into a shell variable:
+
+
+
+
+
+
$ export TOOLPATH=/usr/local/cross-i686
+
+
+
+
+
› Step 1: binutils
+
+
This is the easiest step: unpack, configure, build.
Now you have your i386 "binutils" (assembler, linker, disassembler ...) in your PATH.
+
› Step 2: basic GCC
+
+
In this step we build a "basic" GCC (that is, a GCC without any
+support libs, which we'll use in order to build all the libraries for
+our target). But first we need to make a slight modification in the
+configuration files. Out of the box, the GCC 4.3.1/newlib combo won't
+compile properly, giving a very weird "Link tests are not allowed after
+GCC_NO_EXECUTABLES" error. After a bit of googling, I found the
+solution for this:
+
+
+
+
+
+
$ tar -xvjf gcc-4.3.1.tar.bz2
+
+
+
$ cd gcc-4.3.1/libstdc++-v3
+
+
+
$ joe configure.ac
+
+
+
+
+
+
+
I'm using "joe" here as it's my favourite Linux text mode editor,
+you can use any other text editor. Now find the line which says
+"AC_LIBTOOL_DLOPEN" and comment it out by adding a "#" before it:
+
+
# AC_LIBTOOL_DLOPEN
+
+
Save the modified file and exit the text editor
+
+
+
+
+
+
$ autoconf
+
+
+
$ cd ..
+
+
+
+
+
+
Great, now we know it will compile, so let's do it:
On my system, the last line above (sudo make install-gcc) terminated
+with errors, because it was unable to find our newly compiled binutils.
+If this happens for any kind of "make install" command, this is a quick
+way to solve it:
+
+
+
+
+
+
$ sudo -s -H
+
+
+
+
+
# export PATH=/usr/local/cross-i686/bin:$PATH # make install-gcc # exit
+
+
+
› Step 3: Newlib
+
+
Once again, Newlib is as easy as unpack, configure, build. But I
+wanted my library to be as small as possible (as opposed to as fast as
+possible) and I only wanted to keep what's needed from it in the final
+executable, so I added the "-ffunction-sections -fdata-sections" flags
+to allow the linker to perform dead code stripping:
$ make
+CFLAGS_FOR_TARGET="-ffunction-sections
+-fdata-sections -D__PREFER_SIZE_OVER_SPEED -D__OPTIMIZE_SIZE__ -Os
+-fomit-frame-pointer -D__BUFSIZ__=256"
+
+
+
$ sudo make install
+
+
+
+
+
+
Some notes about the flags used in the above sequence:
+
+
--disable-newlib-supplied-syscalls: this deserves a page of its own, but I won't cover it here. For an explanation, see for example this page.
-D__PREFER_SIZE_OVER_SPEED -D__OPTIMIZE_SIZE__: compile Newlib for size, not for speed (these are Newlib specific).
-Os -fomit-frame-pointer: tell GCC to optimize for size, not for speed.
-D__BUFSIZ__=256:
+again Newlib specific, this is the buffer size allocated by default for
+files opened via fopen(). The default is 1024, which I find too much
+for an eLua, so I'm using 256 here. Of course, you can change this
+value.
+
+
+
› Step 4: full GCC
+
+
Finally, in the last step of our tutorial, we complete the GCC
+build. In this stage, a number of compiler support libraries are built
+(most notably libgcc.a). Fortunately this is simpler that the Newlib
+compilation step:
+
+
+
+
+
+
+
$ cd gcc-4.3.1/build
+
+
+
$ make all
+
+
+
$ sudo make install
+
+
+
+
+
+
+
› Step 5: all done!
+
+
Now you can finally enjoy your i386 toolchain, and compile eLua with
+it :) After you do, you'll be able to boot eLua directly on your PC, as
+described here, but you won't need to download the ELF file from the eLua project page, since you just generated it using your own toolchain!
+If you need further clarification, or if the above instructions didn't work for you, feel free to contact me.
+
\ No newline at end of file
diff --git a/doc/pt/tc_arm.html b/doc/pt/tc_arm.html
new file mode 100644
index 00000000..397b0acf
--- /dev/null
+++ b/doc/pt/tc_arm.html
@@ -0,0 +1,310 @@
+
+
+
+Product
+
+
+
This tutorial explains how you can create a GCC+Newlib toolchain
+that can be used to compile programs for the ARM architecture, thus
+making it possible to compile programs for the large number of ARM CPUs
+out there. You'll need such a toolchain if you want to compile eLua for
+ARM CPUs. This tutorial is similar to many others you'll find on the
+Internet (particulary the one from gnuarm, on which it's based), but it's a bit more detailed and shows some "tricks" you can use when compiling Newlib.
+
+
DISCLAIMER: I'm by no means a specialist in the
+GCC/newlib/binutils compilation process. I'm sure that there are better
+ways to accomplish what I'm describing here, however I just wanted a
+quick and dirty way to build a toolchain, I have no intention in
+becoming too intimate with the build process. If you think that what I
+did is wrong, innacurate, or simply outrageously ugly, feel free to contact me and I'll make the necessary corrections. And of course, this tutorial comes without any guarantees whatsoever.
+
+
Prerequisites
+
To build your toolchain you'll need:
+
+
a computer running Linux: I use Ubuntu 8.04, but any Linux
+will do as long as you know how to find the equivalent of "apt-get" for
+your distribution. I won't be going into details about this, google it
+and you'll sure find what you need. It is also assumed that the Linux
+system already has a "basic" native toolchain installed (gcc/make and
+related).This is true for Ubuntu after installation. Again, you might
+need to check your specific distribution.
GNU binutils: get it from here.
+At the moment of writing this, the latest versions is 2.18, which for
+some weird reason refuses to compile on my system, so I'm using 2.17
+instead.
GCC: version 4.3.0 or newer is recommended. As
+I'm writing this, the latest GCC version is 4.3.1 which I'll be using
+for this tutorial. Download it from here after choosing a suitable mirror.
Newlib: as I'm writing this, the latest official Newlib version is 1.16.0. Download it from the Newlib FTP directory.
Also,
+the tutorial assumes that you're using bash as your shell. If you use
+something else, you might need to adjust some shell-specific commands.
+
+
+
Also, you need some support programs/libraries in order to compile the toolchain. To install them:
Next, decide where you want to install your toolchain. They
+generally go in /usr/local/, so I'm going to assume
+/usr/local/cross-arm for this tutorial. To save yourself some typing,
+set this path into a shell variable:
+
+
+
+
+
+
$ export TOOLPATH=/usr/local/cross-arm
+
+
+
+
+
› Step 1: binutils
+
This is the easiest step: unpack, configure, build.
Now you have your ARM "binutils" (assembler, linker, disassembler ...) in your PATH.
+
+
Step 2: basic GCC
+
+
In this step we build a "basic" GCC (that is, a GCC without any
+support libs, which we'll use in order to build all the libraries for
+our target). But first we need to make a slight modification in the
+configuration files. Out of the box, the GCC 4.3.1/newlib combo won't
+compile properly, giving a very weird "Link tests are not allowed after
+GCC_NO_EXECUTABLES" error. After a bit of googling, I found the
+solution for this:
+
+
+
+
+
+
$ tar -xvjf gcc-4.3.1.tar.bz2
+
+
+
$ cd gcc-4.3.1/libstdc++-v3
+
+
+
$ joe configure.ac
+
+
+
+
+
I'm using "joe" here as it's my favourite Linux text mode editor,
+you can use any other text editor. Now find the line which says
+"AC_LIBTOOL_DLOPEN" and comment it out by adding a "#" before it:
+
+
# AC_LIBTOOL_DLOPEN
+
+
Save the modified file and exit the text editor
+
+
+
+
+
+
$ autoconf
+
+
+
$ cd ..
+
+
+
+
+
+
Great, now we know it will compile, so let's do it:
On my system, the last line above (sudo make install-gcc) terminated
+with errors, because it was unable to find our newly compiled binutils.
+If this happens for any kind of "make install" command, this is a quick
+way to solve it:
+
+
+
+
+
+
$ sudo -s -H
+
+
+
# export PATH=/usr/local/cross-arm/bin:$PATH
+
+
+
# make install-gcc
+
+
+
# exit
+
+
+
+
+
+
+
Step 3: Newlib
+
+
Once again, Newlib is as easy as unpack, configure, build. But I
+wanted my library to be as small as possible (as opposed to as fast as
+possible) and I only wanted to keep what's needed from it in the final
+executable, so I added the "-ffunction-sections -fdata-sections" flags
+to allow the linker to perform dead code stripping:
$ make
+CFLAGS_FOR_TARGET="-ffunction-sections -fdata-sections
+-DPREFER_SIZE_OVER_SPEED -D__OPTIMIZE_SIZE__ -Os -fomit-frame-pointer
+-D__BUFSIZ__=256"
+
+
+
$ sudo make install
+
+
+
+
+
+
Some notes about the flags used in the above sequence:
+
+
--disable-newlib-supplied-syscalls: this deserves a page of its own, but I won't cover it here. For an explanation, see for example this page
-DPREFER_SIZE_OVER_SPEED -D__OPTIMIZE_SIZE__: compile Newlib for size, not for speed (these are Newlib specific).
-Os -fomit-frame-pointer: tell GCC to optimize for size, not for speed.
-D__BUFSIZ__=256:
+again Newlib specific, this is the buffer size allocated by default for
+files opened via fopen(). The default is 1024, which I find too much
+for an eLua, so I'm using 256 here. Of course, you can change this
+value.
+
+
+
Step 4: full GCC
+
+
Finally, in the last step of our tutorial, we complete the GCC
+build. In this stage, a number of compiler support libraries are built
+(most notably libgcc.a). Fortunately this is simpler that the Newlib
+compilation step:
+
+
+
+
+
+
+
$ cd gcc-4.3.1/build
+
+
+
$ make all
+
+
$ sudo make install
+
+
+
+
+
+
+
Step 5: all done!
+
+
Now you can finally enjoy your ARM toolchain, and compile eLua with it :)
+If you need further clarification, or if the above instructions didn't work for you, feel free to contact me.
+
\ No newline at end of file
diff --git a/doc/pt/tc_cortex.html b/doc/pt/tc_cortex.html
new file mode 100644
index 00000000..e0ed683a
--- /dev/null
+++ b/doc/pt/tc_cortex.html
@@ -0,0 +1,343 @@
+
+
+
+Product
+
+
+
This tutorial explains how you can create a GCC+Newlib toolchain
+that can be used to compile programs for the Cortex (Thumb2)
+architecture, thus making it possible to use GCC to compile programs
+for the increasingly number of Cortex CPUs out there (Luminary Micro, ST,
+with new Cortex CPUs being announced by Atmel and other companies). I
+am writing this tutorial because I needed to work on a Cortex CPU for
+the eLua project and I couldn't find anywhere a complete set of
+instructions for building GCC for this architecture. You'll need such a
+toolchain if you want to compile eLua for Cortex-M3 CPUs.
+
+
DISCLAIMER: I'm by no means a specialist in the
+GCC/newlib/binutils compilation process. I'm sure that there are better
+ways to accomplish what I'm describing here, however I just wanted a
+quick and dirty way to build a toolchain, I have no intention in
+becoming too intimate with the build process. If you think that what I
+did is wrong, innacurate, or simply outrageously ugly, feel free to contact us and I'll make the necessary corrections. And of course, this tutorial comes without any guarantees whatsoever.
+
+
Prerequisites
+
To build your toolchain you'll need:
+
+
a computer running Linux: I use Ubuntu 8.04, but any Linux
+will do as long as you know how to find the equivalent of "apt-get" for
+your distribution. I won't be going into details about this, google it
+and you'll sure find what you need. It is also assumed that the Linux
+system already has a "basic" native toolchain installed (gcc/make and
+related). This is true for Ubuntu after installation. Again, you might
+need to check your specific distribution.
GNU binutils: get it from here.
+At the moment of writing this, the latest versions is 2.18, which for
+some weird reason refuses to compile on my system, so I'm using 2.17
+instead. UPDATE: you MUST use the new binutils 2.19
+distribution for the Cortex toolchain, since it fixes some assembler
+issues. You won't be able to compile eLua 0.5 or higher if you don't
+use binutils 2.19.
GCC: since support for Cortex (Thumb2)
+was only introduced staring with version 4.3.0, you'll need to download
+version 4.3.0 or newer. As I'm writing this, the latest GCC version is
+4.3.1, which I'll be using for this tutorial. Download it from here after choosing a suitable mirror.
Newlib:
+as I'm writing this, the latest official Newlib version is 1.16.0.
+However, the CVS version contains some fixes for the Thumb2
+architecture, some of them in very important functions (like
+setjmp/longjmp), so you'll need to fetch the sources from CVS (this
+will most likely change when a new official Newlib version is
+released). So go to http://sourceware.org/newlib/download.html and follow the instructions there in order to get the latest sources from CVS.
Also,
+the tutorial assumes that you're using bash as your shell. If you use
+something else, you might need to adjust some shell-specific commands.
+
+
+
Also, you need some support programs/libraries in order to compile the toolchain. To install them:
Next, decide where you want to install your toolchain. They
+generally go in /usr/local/, so I'm going to assume
+/usr/local/cross-cortex for this tutorial. To save yourself some
+typing, set this path into a shell variable:
+
+
+
+
+
+
$ export TOOLPATH=/usr/local/cross-cortex
+
+
+
+
+
+
Step 1: binutils
+
+
This is the easiest step: unpack, configure, build.
Now you have your ARM "binutils" (assembler, linker, disassembler ...) in your PATH. They are fully capable of handling Thumb2.
+
+
Step 2: basic GCC
+
+
In this step we build a "basic" GCC (that is, a GCC without any
+support libs, which we'll use in order to build all the libraries for
+our target). But first we need to make a slight modification in the
+configuration files. Out of the box, the GCC 4.3.1/newlib combo won't
+compile properly, giving a very weird "Link tests are not allowed after
+GCC_NO_EXECUTABLES" error. After a bit of googling, I found the
+solution for this:
+
+
+
+
+
+
+
$ tar -xvjf gcc-4.3.1.tar.bz2
+
+
+
$ cd gcc-4.3.1/libstdc++-v3
+
+
+
$ joe configure.ac
+
+
+
+
+
I'm using "joe" here as it's my favourite Linux text mode editor,
+you can use any other text editor. Now find the line which says
+"AC_LIBTOOL_DLOPEN" and comment it out by adding a "#" before it:
+
+
+# AC_LIBTOOL_DLOPEN
+
+
Save the modified file and exit the text editor
+
+
+
+
+
+
$ autoconf
+
+
+
$ cd ..
+
+
+
+
+
+
+
Great, now we know it will compile, so let's do it:
On my system, the last line above (sudo make install-gcc) terminated
+with errors, because it was unable to find our newly compiled binutils.
+If this happens for any kind of "make install" command, this is a quick
+way to solve it:
+
+
+
+
+
+
+
$ sudo -s -H
+
# export PATH=/usr/local/cross-cortex/bin:$PATH
# make install-gcc
# exit
+
+
+
+
+
+
+
Step 3: Newlib
+
+
Again, some modifications are in order before we start compiling.
+Because the CVS version of Newlib doesn't seem to have all the required
+support for Thumb2 yet, we need to tell Newlib to skip some of its
+libraries when compiling:
Save the modified file and exit the text editor $ autoconf
+
+
+
On one of the systems I ran the above sequence, it terminated with
+errors, complaining that autoconf 2.59 was not found. I don't know why
+that happens. 2.59 seems to be quite ancient, and the build ran equally
+well with 2.61 (the version of autoconf on the system that gave the
+error). If this happens to you, first execute autoconf --version to
+find the actual version of your autoconf, then do this:
+
+
+
+
+
+
+
+
+
+
+
$ joe config/override.m4
Look for this line:
[m4_define([_GCC_AUTOCONF_VERSION], [2.59])])
And replace [2.59] with your actual version ([2.61] in my case). $ autoconf
+
+
+
Once again, now we're ready to actually compile Newlib. But we need
+to tell it to compile for Thumb2. As already specified, I'm not a
+specialist when it comes to Newlib's build system, so I chosed the
+quick, dirty and not so elegant solution of providing the compilation
+flags directly from the command line. Also, as I wanted my library to
+be as small as possible (as opposed to as fast as possible) and I only
+wanted to keep what's needed from it in the final executable, I added
+the "-ffunction-sections -fdata-sections" flags to allow the linker to
+perform dead code stripping:
Some notes about the flags used in the above sequence:
+
+
--disable-newlib-supplied-syscalls: this deserves a page of its own, but I won't cover it here. For an explanation, see for example this page.
-DPREFER_SIZE_OVER_SPEED -D__OPTIMIZE_SIZE__: compile Newlib for size, not for speed (these are Newlib specific).
-mcpu=cortex-m3 -mthumb: this tells GCC that you want to compile for Cortex. Note that you need both flags.
-D__thumb2__: again, this is Newlib specific, and seems to be required when compiling Newlib for Cortex.
-Os -fomit-frame-pointer: tell GCC to optimize for size, not for speed.
-D__BUFSIZ__=256:
+again Newlib specific, this is the buffer size allocated by default for
+files opened via fopen(). The default is 1024, which I find too much
+for an eLua, so I'm using 256 here. Of course, you can change this
+value.
+
+
+
Step 4: full GCC
+
+
Finally, in the last step of our tutorial, we complete the GCC
+build. In this stage, a number of compiler support libraries are built
+(most notably libgcc.a). Fortunately this is simpler that the Newlib
+compilation step, as long as you remember that we want to build our
+compiler support libraries for the Cortex architecture:
+
+
+
+
+
+
+
$ cd gcc-4.3.1/build
+
+
+
$ make CFLAGS="-mcpu=cortex-m3 -mthumb" CXXFLAGS="-mcpu=cortex-m3 -mthumb" LIBCXXFLAGS="-mcpu=cortex-m3 -mthumb" all
+
+
+
$ sudo make install
+
+
+
+
+
+
+
All Done!
+
Phew! That was quite a disturbing tutorial, with all that confusing
+flags lurking in every single shell line :) But at this point you
+should have a fully functional Cortex GCC toolchain, which seems to be
+something very rare, so enjoy it with pride.
+If you need further clarification, or if the above instructions didn't
+work for you, feel free to contact us.
+
\ No newline at end of file
diff --git a/doc/pt/tchainbuild.html b/doc/pt/tchainbuild.html
new file mode 100644
index 00000000..ea109ca2
--- /dev/null
+++ b/doc/pt/tchainbuild.html
@@ -0,0 +1,9 @@
+
+
+
+Product
+
+
+
That's right: after following this tutorial, your PC will boot
+directly into Lua! No OS there (this explains why the boot process is
+so fast), just you and Lua. You'll be able to use the regular Lua
+interpreter to write your programs and even use "dofile" to execute Lua
+code.
+
+
Details
+
+
Booting Lua involves using the well known GRUB that will be used to load a multiboot
+compliant ELF file that contains our eLua code. Since the eLua code and
+the build instructions are not available yet, I'll be providing a
+direct link to the ELF file. The code runs in protected mode, so you
+have access to your whole memory. The code does not access any kind of
+storage device (HDD, CDROM, floppy), so if you're worried that it might
+brick your system, you can relax now :) I'm only using some very basic
+keyboard and VGA "drivers", so all you're risking is a system freeze
+(even this is highly unlikely), nothing a good old RESET can't handle
+(be sure to use the hardware reset though, CTRL+ALT+DEL is not handled
+by the code). But just in case, see also the next section.
+
+
Disclaimer
+
+
As already mentioned, the code won't try to access any kind
+of storage (HDD, CDROM, floppy), not even for reading, so you don't
+need to worry about that. Also it doesn't try to reprogram your video
+card registers, so it can't harm it or your monitor. It only implements
+a "protected mode keyboard driver" that can't physically damage
+anything in your system. In short, I made every effort to make the code
+as harmless as possible. I tested it on 5 different computers and in 2 VirtualBox
+emulators, and nothing bad happened. That said, there are no warranties
+of any kind. In the very unlikely event that something bad does happen
+to your system, you have my sincere sympathy, but I can't be held
+responsible for that.
+
+
Prerequisites
+
+
To boot your computer in Lua you'll need:
+
+
a 386 or better computer running Linux. I actually tested
+this only on Pentium class computers, but it should run on a 386
+without problems.
GRUB.
+Since you're running Linux, chances are you're already using GRUB as
+your bootloader. If not, you must install it. You don't need to install
+it on your HDD; a floppy, an USB stick or even a CDROM will work as
+well. I won't cover the GRUB installation procedure here, just google
+for "install grub on floppy/usb/cdrom" and you'll sure find what you're
+looking for. You can try for example here, here or here.
The eLua ELF file. Download it from here. OR download eLua and compile it for the i386 architecture using a toolchain that you can build by following this tutorial.
a text editor to edit your GRUB configuration file.
+
+
+
The rest of this tutorial assumes that you're using Linux with GRUB,
+and that GRUB is located in /boot/grub, which is true for many Linux
+distributions (I'm using Ubuntu 8.04).
+
+
Let's do this
+
+
First, copy the eLua ELF file to your "/boot" directory:
+
$ sudo cp surprise /boot
+
+
Next you need to add another entry to your GRUB menu file (/boot/grub/menu.lst). Edit it and add this entry:
+
+
title Surprise! root (hd0,0) kernel /boot/surprise boot
+
+
+
You may need to modify the root (hd0,0) line above to match your
+boot device. The best way to do this is to look in the menu.lst file
+for the entry that boots your Linux kernel. It should look similar to
+this:
After you find it, simply use the root (hdx,y) line from that entry
+(root (hd0,2) in the example above) in your newly created entry instead
+of root (hd0,0).
+That's it! Now reboot your computer, and when the GRUB boot menu
+appears, choose "Surprise!" from it. You can even type dofile
+"/rom/bisect.lua" to execute the "bisect.lua" test file. Enjoy!
+As usual, if you need more details, you can contact us.
+Also, if you want to have you own USB stick that boots Lua, let me
+know. If enough people manifest their interest in this, I'll add
+another tutorial on how to do it (I already have an USB stick that
+boots Lua, of course :) ).
+
\ No newline at end of file
diff --git a/doc/pt/tut_bootstick.html b/doc/pt/tut_bootstick.html
new file mode 100644
index 00000000..7f324020
--- /dev/null
+++ b/doc/pt/tut_bootstick.html
@@ -0,0 +1,103 @@
+
+
+
+Product
+
+
+
This is follow up of this tutorial.
+After completing it you'll be able to boot eLua directly from your USB
+stick (provided, of course, that your computer can boot from an USB
+stick, which is true for most computers nowadays). You might want to
+check the boot your PC in eLua
+tutorial first for more details. If you have an old USB stick that you
+don't use anymore, and/or the shear geekness of this idea makes you
+feel curious, this tutorial is definitely for you :)
+
+
Disclaimer
+
+
As mentioned here,
+the code won't try to access any kind of storage (HDD, CDROM, floppy),
+not even for reading, so you don't need to worry about that. Also it
+doesn't try to reprogram your video card registers, so it can't harm it
+or your monitor. It only implements a "protected mode keyboard driver"
+that can't physically damage anything in your system. In short, I made
+every effort to make the code as harmless as possible. I tested it on 5
+different computers and in 2 VirtualBox
+emulators, and nothing bad happened. That said, there are no warranties
+of any kind. In the very unlikely event that something bad does happen
+to your system, you have my sincere sympathy, but I can't be held
+responsible for that. Also, I can't be held responsible if you mess up
+your HDD by failing the GRUB installation procedure (even though, once
+again, this shouldn't be possible unless you really insist on messing
+it up). If you're new to computers, this tutorial might not be for you.
+Your call.
+
+
Prerequisites
+
+
To have your own bootable eLua USB stick you'll need:
+
+
an USB stick. I tested this on an 128M USB stick, because
+it's the smallest I could find. You should be OK with a 4M stick or
+even a 2M stick
a computer running Linux. I use Ubuntu, but any other distribution is fine.
GRUB.
+Since you're running Linux, chances are you're already using GRUB as
+your bootloader. If not, you must install it on your HDD, or at least
+know how to install it directly on the USB stick. I won't go into
+details here, google it and you'll find lots of good articles about
+GRUB. This tutorial assumes that you're using GRUB as your bootloader.
The eLua ELF file. Download it from here. OR download eLua and compile it for the i386 architecture using a toolchain that you can build by following this tutorial.
a text editor to edit your GRUB configuration file.
+
+
+
The rest of this tutorial assumes that you're using Linux with GRUB,
+and that GRUB is located in /boot/grub, which is true for many Linux
+distributions.
+
Backup your stick
+
+
Since the stick is going to be formatted, make sure to backup the
+data from your stick first (you can copy it back after finishing the
+tutorial).
+
+
Partition and format your stick
+
+
Depending on your stick, this step might not be required, but
+chances are you'll need to re-partition and re-format your stick before
+installing GRUB on it. The problem is that many sticks have a very
+creative, non-standard partition table, and GRUB doesn't like that. I
+looked at the partition table on my eLua USB stick, and it scared me to
+death, so I had to follow this procedure. In short, you'll need to
+delete all the partitions from your stick, create a new partition, and
+then format it. For a step by step tutorial check here.
+
Install GRUB on your stick
+
+
First, mount your freshly formatted stick (I'm going to assume that the mount directory is /mnt):
+
+
$ sudo mount /dev/sda1 /mnt
+
+
+
(of course, you'll need to change /dev/sda1 to reflect the physical location of your USB stick).
+Then copy the required GRUB files to your stick:
+
+
$ cd /mnt $ mkdir boot $ mkdir boot/grub $ cd /boot/grub $ cp stage1 fat_stage1_5 stage2 /mnt/boot/grub
+
+
+
Copy the eLua ELF file to the GRUB directory as well:
+
+
$ cp surprise /mnt/boot/grub
+
+
+
Create a menu.lst file for GRUB with you favorite text editor (I'm using joe):
+
+
$ cd /mnt/boot/grub $ joe menu.lst title Surprise! root (hd0,0) kernel /boot/grub/surprise boot
+
+
Now it's time to actually install GRUB on the stick.
+
+
$ sudo -s -H # grub Now we need to find the GRUB name of our USB stick. We'll use the "find" command from GRUB and our "surprise" file to accomplish this:
grub> find /boot/grub/surprise (hd2,0)
GRUB should respond with a single line (like (hd2,0) above). If it gives you more than one line, something is wrong. Maybe you also installed eLua on your HDD? If so, delete the /boot/grub/surprise file from your HDD and try again. You might get a different (hdx,y) line. If so, just use it instead of (hd2,0) in the rest of this tutorial.
grub> root (hd2,0) grub> setup (hd2) Checking if "/boot/grub/stage1" exists... yes Checking if "/boot/grub/stage2" exists... yes Checking if "/boot/grub/fat_stage1_5" exists... yes Running "embed /boot/grub/fat_stage1_5 (hd2)"... 15 sectors are embedded. succeeded Running "install /boot/grub/stage1 (hd2) (hd2)1+15 p (hd2,0)/boot/grub/stage2 /boot/grub/menu.lst"... succeeded Done. grub> quit
+
+
+
That's it! Now reboot your computer, make sure that your BIOS is set
+to boot from USB, and enjoy! You can even type dofile "/rom/bisect.lua"
+to execute the "bisect.lua" test file.
+As usual, if you need more details, you can contact us.
+
\ No newline at end of file
diff --git a/doc/pt/tut_openocd.html b/doc/pt/tut_openocd.html
new file mode 100644
index 00000000..87b7df2b
--- /dev/null
+++ b/doc/pt/tut_openocd.html
@@ -0,0 +1,288 @@
+
+
+
+Product
+
+
+
OpenOCD is an open source tool that can be used to connect to a CPU's JTAG
+interface. Using OpenOCD and a physical JTAG connection allows you to
+burn the on-chip flash memory of your CPU (or to load your code
+directly to RAM), to read the internal CPU memory (Flash/RAM) and to
+use gdb to debug your code.
+Needless to say, this is a very handy tool (and especially handy if
+your CPU happens to be built around an ARM core, since in this case you
+can be almost certain that it has a JTAG interface that you can use).
+That said, if your only goal is to burn your firmware, my personal
+suggestion is to avoid using OpenOCD if possible. It has quite a steep
+learning curve, because it is a command line tool that uses
+configuration files with lots of different parameters, and this takes a
+while to get used to. Worse, I feel that it is not very well
+docummented. The project's wiki does give a few good pointers about all
+the configuration parameters, and there are some good OpenOCD tutorials
+out there, but none of them tells the whole story. And the syntax (and
+even some commands) seems to change slightly between releases, which
+makes things even more confusing. This is why I generally choose to use
+a different firmware burning tool when available, and resort to OpenOCD
+only for targets that lack a proper firmware burning tool. If you need
+to debug your code, however, you probably want to use OpenOCD, since
+the alternatives aren't cheap.
+To summarize, you can forget about OpenOCD when:
+
+
your CPU manufacturer provides a special tool for
+firmware burning. This is quite often the case, but more often that not
+the forementioned tools work only in Windows.
you
+must debug your code, but you have a good intuition about where the
+problem is located. In this case, simply connecting a LED to a PIO port
+and turning it on and off from different parts of your code until you
+figure out exactly what's the problem can work wonders. I can't
+remember when was the last time I used gdb for debugging, since "LED
+debugging" was all I needed.
+
+
On the other hand, you should probably use OpenOCD when:
+
+
your CPU manufacturer doesn't provide a special tool for firmware burning (or it does, but it's not what you need).
you're using Linux, MacOS or another OS that is not supported by the firmware burning tool.
you need to do some serious debugging in order to understand what's wrong with your application.
+
+
If you decided that you don't need OpenOCD after all, now it's a
+good time to navigate away from this page and save yourself from some
+possible symptoms of headache. If you need OpenOCD, read on, I'll try
+to make this as painless as possible. However, don't expect this to be
+a full tutorial on OpenOCD, because it's not; my intention is to give
+you just enough data to use OpenOCD for burning eLua on your board.
+Because of this, I won't be covering debugging with OpenOCD here, just
+firmware burning. And, before we begin, please read and understand the
+next paragraph.
+
+
DISCLAIMER: using OpenOCD improperly may force your CPU to behave
+unexpectedly. While physically damaging your CPU as a result of using
+OpenOCD is very hard to accomplish, you might end up with a locked
+chip, or you might erase a memory area that was not supposed to be
+erased, you might even disable the JTAG interface on your chip (thus
+rendering it unusable). If you modify the configuration scripts that
+I'm going to provide, make sure that you know what you're doing. Also,
+I'm not at all an OpenOCD expert, so my configuration scripts might
+have errors, even though I tested them. In short, this tutorial comes
+without any guarantees whatsoever.
+
Getting OpenOCD
+
+
If you're on Windows, the best place to get OpenOCD already compiled and ready to run is to visit the Yagarto home page.
+They provide a very nice OpenOCD installer, and they seem to keep up
+with OpenOCD progress (the versions on the Yagarto site are not
+"bleeding edge", but there are quite fresh nevertheless). If you're on
+Linux, you can always use apt-get or your distribution-specific package
+manager:
+
+
$ sudo apt-get install openocd
+
+
+
There is a catch here though: the OpenOCD version that I get from
+apt-get is dated 2007-09-05, while the Yagarto OpenOCD version is from
+2008-06-19. Since I'm using OpenOCD from Windows (because Ubuntu 8.04
+doesn't seem to handle my USB-to-JTAG adapters very well), my
+instructions are relevant to the Yagarto version. As mentioned in the
+introduction, the meaning and parameters of different commands might
+change between OpenOCD version, so if you want to use the Yagarto
+version on your non Windows system, you'll have to build it from source
+(see below).
+The main resource on how to build OpenOCD from source is the OpenOCD build page from the OpenOCD wiki. Also, a very good tutorial can be found here.
+I'm not going to provide step by step build instructions, since the two
+links that I mentioned cover this very well, and the build process is
+relatively straightforward. However, since both tutorials describe how
+to build the bleeding edge version of OpenOCD, you'll need a slight
+modification do build the Yagarto version instead. The modification is
+in the SVN checkout step. Replace this step:
+
+
$ svn checkout svn://svn.berlios.de/openocd/trunk
+
+
+
With this step ('717' is the SVN revision of the Yagarto OpenOCD build):
Follow the rest of the build instructions, and in the end you should have a working OpenOCD.
+
Supported targets
+
+
I couldn't find a good page with a list of the targets that are
+supported by OpenOCD. So, if you want to check if your particular CPU
+is supported by OpenOCD, I recommend getting the latest sources (as
+described in the previous section) and listing the
+trunk/src/target/target directory:
+
+
$ ls trunk/src/target/target at91eb40a.cfg at91r40008.cfg cfi.c .... str9comstick.cfg ....
+
+
+
If this listing has something that looks like your CPU name, you're
+in luck. OpenOCD has support for LPC from NXP, AT91SAM cfrom Atmel,
+STR7/STR9 from ST, and many others.
+
Using OpenOCD
+
+
To use OpenOCD, you'll need:
+
+
the OpenOCD executable, as described above
a board with a JTAG interface
a JTAG adapter
+
+
+
In some cases, your CPU board might provide a built in JTAG adapter. For example, my LM3S8962
+board provides both an USB-to-JTAG and an USB-to-serial converter built
+on board, switching between them automatically. The same is true for my
+STR9-comStick. On the other hand, my SAM7-EX256 board has only a JTAG connector, I need a separate JTAG adapter to connect to it. I'm using ARM-USB-TINY from Olimex, but there are other affordable USB-to-JTAG adapters out there, like the Amontec JTAGKey-Tiny. Not to mention that you can build your ownt.
+Although USB is my interface of choice, you'll find JTAG adapters for
+PC LPT ports too. The good news is that once you buy a JTAG adapter,
+chances are that it will work with many boards with different CPUs,
+since the JTAG connector layout is standardized and the JTAG adapters
+are generally able to work with different voltages.
+To actually use OpenOCD, you'll need a configuration file. The
+configuration file is the one that lets OpenOCD know about your setup,
+such as:
+
+
* the kind of JTAG interface that you're using. * the actual hardware platform you're using (ATM7TDMI, ARM966 and others). * the memory configuration of your CPU (flash banks). * the script used to program the flash memory.
+
+
+
Presenting a list of all the possible configuration options and
+their meaning is way beside the scope of this document, so I'm not
+going to do it, I'll give an example instead. For the example I'm going
+to use parts of my STR-comStick configuration file (comstick.cfg)
+adapted from the OpenOCD distribution and from other examples (don't
+worry, I'll provide full download links for this file later on). First
+we need to tell OpenOCD that we're using a the STR9-comStick
+USB-to-JTAG adapter:
Also, OpenOCD needs to know what's our target and its memory layout:
+
+
target arm966e little run_and_init 1 arm966e run_and_halt_time 0 50
working_area 0 0x50000000 32768 nobackup
flash bank str9x 0x00000000 0x00080000 0 0 0 flash bank str9x 0x00080000 0x00008000 0 0 0
+
+
+
This tells OpenOCD that our target is an ARM966-E running in little
+endian mode, with two flash memory banks, one that starts at 0x0 and
+it's 0x80000 bytes in size, and another one that starts at 0x80000 and
+it's 0x8000 bytes in size. Finally, OpenOCD must know what's the name
+of our script file (this is the file that is used to pysically program
+the CPU memory):
+
+
#Script used for FLASH programming target_script 0 reset str91x_flashprogram.script
+
+
+
The contents of the str91x_flashprogram.script is very target-dependent:
I'm not even going to attempt to explain this one :) Basically it
+unprotects the flash, erases it, writes the contents of "main.bin" to
+flash, and then resets the CPU. If you need to flash a file with a
+different name, the only thing you need to modify is the "main.bin" in
+the "flash write_bank" line.
+To use all this, you need to tell OpenOCD to use our configuration file:
+
+
openocd-ftd2xx -f comstick.cfg
+
+
+
(note: under Windows, the OpenOCD executable name is often
+"openocd-ftd2xx". Under Linux it's simply "openocd". Replace it with
+the actualy name with your executable.)
+That's it for your OpenOCD crash course. I realise that there's much
+more to learn, so here's a list of links with much better information
+on the subject:
The comstick.cfg configuration file is for prorgramming the
+STR9-comStick. comrst.cfg is for resetting it. The comStick has a very
+interesting habit: after you power it (via USB) it does not start
+executing the code from the internal flash, you need to execute OpenOCD
+with the comreset.cfg script to start it. This script does exactly what
+it says: executes a CPU reset (since the board doesn't have a RESET
+button). This is a very peculiar behaviour, and I'm not sure if it's
+generic or it's only relevant to my particular comStick. I suspect that
+the CPU RESET line isn't properly handled by the on-board USB-to-JTAG
+converter, and the only solution I have for this is to execute this
+script everytime you power the board and everytime you need to do a
+RESET.
+
+
+
Configuration files for LPC2888
+
+
LPC2888 is quite a different animal. I couldn't find any "official"
+LPC2888 configuration file for OpenOCD, so I had to learn how to write
+my own. It works, but I suspect it can be improved. This time, the
+configuration file applies to the latest (SVN) version of OpenOCD, so
+read this tutorial to understand how to get the latest OpenOCD sources
+and how to compile them (this section is based on version 922 of the
+OpenOCD repository). Then use the next file to burn your binary image
+to the chip:
If your image name is not main.bin edit the file and change the
+corresponding line (flash write_bank 0 main.bin 0), then invoke openocd
+like this:
+
+
openocd -f lpc2888.cfg
+
+
+
I'm using ARM-USB-TINY
+from Olimex, but it should be easy to use the script with any other
+JTAG adapter (don't forget to change the script to match your adapter).
For STR7 I'm using the Yagarto OpenOCD build for Windows (repository
+version 717, as described at the beginning of this tutorial). The
+str7prg.cfg configuration file is for prorgramming the STR9-comStick.
+str7rst.cfg is for resetting it. I'm using a STR711FR2 heard board from
+ScTec to
+which I attached a few LEDs and a MAX3232 TTL to RS232 converter for
+the serial communication. The board comes with its own JTAG adadpter,
+but it uses a parallel interface, and since my computer doesn't have
+one, I used the ARM-USB-TINY from Olimex. To use them, invoke the OpenOCD executable like this:
+
+
openocd-ftd2xx -f str7prg.cfg
+
+
+
(note: under Windows, the OpenOCD executable name is often
+"openocd-ftd2xx". Under Linux it's simply "openocd". Replace it with
+the actualy name with your executable.)
+Also, be sure to modify str7_flashprogram.script if your image name is
+not main.bin.
+
\ No newline at end of file
diff --git a/doc/pt/tutorials.html b/doc/pt/tutorials.html
new file mode 100644
index 00000000..439cb8e3
--- /dev/null
+++ b/doc/pt/tutorials.html
@@ -0,0 +1,7 @@
+
+
+
+Product
+
+
+
eLua Tutorials
\ No newline at end of file
diff --git a/doc/pt/uart_ref.html b/doc/pt/uart_ref.html
new file mode 100644
index 00000000..a6a5351b
--- /dev/null
+++ b/doc/pt/uart_ref.html
@@ -0,0 +1,75 @@
+
+
+
+Product
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/doc/pt/using.html b/doc/pt/using.html
new file mode 100644
index 00000000..71168b17
--- /dev/null
+++ b/doc/pt/using.html
@@ -0,0 +1,78 @@
+
+
+
+Product
+
+
+
+
Using eLua
So, you already built and installed eLua and now it is time to have fun with it. It's actually quite easy: all you need is your
+board connected to a PC, running a terminal emulation program. If
+you're using Windows, I strongly recommend TeraTerm.
+It's a freeware, it's very powerful and also easy to use. The native Hyper Terminal progam can do too. On
+Linux,
+you'll probably be stucked with minicom. It is not exactly intuitive
+and it runs in text mode, but it's still very powerful. If you
+google for "minicom tutorial" you'll get the hang of it in no time. You
+can try any other terminal emulator, as long as you set it up
+properly and it gives you the option of transferring files
+via XMODEM, which is what eLua uses at the moment. These are the main
+settings you need to look at:
+
+
port setup: 115200 baud (38400 for STR7)##, 8N1(8 data bits, no parity, one stop bit).
hardware flow control: none
newline handling: "CR" on receive, "CR+LF" on send (some terminal programs won't give you a choice here).
+
+
+
Also, depending on the type of your board, you'll need some way to
+connect the board to a serial port on your PC or to USB if you're
+using an USB to serial converter. For example, as already explained here##,
+the USB port on the LM3Sxxxx boards is dual, so you can use it as an USB
+to serial converter after downloading your firmware, thus you don't
+need any other type of connection. The same is true for the
+STR9-comStick board. On the other hand, for the SAM7-EX256 board you'll
+need to connect a serial cable to the "RS232" connector, provided that
+the jumpers are already set as explained here## and on the MOD711 you will need to add an RS232 converter chip.
+
+
After you setup this PC-eLua board connection and press the "RESET" button on your board, you should see the
+eLua shell prompt. For your
+convenience, the shell documentation is also provided on this page.
+
+
The eLua shell
+
+
After you burn eLua to your board and you connect the board to your terminal
+emulator running on the PC, you'll be greeted with the eLua shell prompt, which
+allows you to:
+
+
get help on shell usage with the help command
run the Lua interpreter in interactive mode just like on do on Linux, Windows and MacOS
run a Lua program from the eLua File System
upload a Lua source file via XMODEM and execute in on board
query the eLua version
list files on eLua File Systems
More details about some of the shell commands are presented below.
+
+
The "recv" command
+
+
To use this, your eLua taret image must be built with support for XMODEM (see
+docs/elua_components.txt for details). Also, your terminal emulation program must
+support sending files via the XMODEM protocol. Both XMODEM with checksum (the
+original version) and XMODEM with CRC are supported, but only XMODEM with 128
+byte packets is allowed (XMODEM with 1K packets won't work).
+To use this feature, enter "recv" at the shell prompt. eLua will respond with
+"Waiting for file ...". At this point you can send the file to the eLua board
+via XMODEM. eLua will receive and execute the file. Don't worry when you see 'C'
+characters suddenly appearing on your terminal after you enter this command,
+this is how the XMODEM transfer is initiated.
+
+
The "lua" command
+
+
This allows you to start the Lua interpreter, optionally passing command line parameters, just
+as you would do from a Linux, Windows or MacOS command prompt. This command has some
+restrictions:
+
+
the command line can't be longer than 50 chars
character escaping is not implemented. For example, the next command won't work
+ because of the ' escape sequences:
+
+
eLua# lua -e 'print('Hello, World!')' -i
+Press CTRL+Z to exit Lua
+lua: (command line):1: unexpected symbol near ''
+
+
However, if you use both '' and "" for string quoting, it will work:
