mµOS - My micro OS

The build-system tries to do exact dependency tracking and building things in parallel. The Makefile in the users src/ directory includes the main muos/muos.mk Makefile, which in turn includes sub Makefiles for to support different flashing tools and different platforms.

By default the make output is silent. If one adds the "MAKE_DEBUG=1" flag to the make invocation then parallel builds are disabled and the it produces verbose output.

The most importnat build targets are:

The Documentation is writiten in asciidoc and distributed in serveral .txt files and added as special comments to the sources. The pipadoc tool shipped with mµOS is used to extract this Documentation into single text files. For building the Documentation one needs a lua interpreter, the asciidoc toolchain and perhaps dblatex for pdf generation.

Issues are tagged inside source and documentation files. pipadoc takes care of generating a muos_issues.txt and muos_issues.html. There are deliberately only 3 tags for issues:

The build system also prints these issues lists on stderr, so that the relevant source positions are navigateable from an IDE. Which issues are presented there is decided on the currently checked out git branch.

In master only FIXME are shown. In devel FIXME and TODO are shown. for any other branch FIXME, TODO are shown and PLANNED are filtered by that only issues where the pathname matches the current branchname are shown.

Uses the clock to wake the mainloop for scheduling events in near future. near future is defined by the clock configuration, times longer than the muos_shortclock type can not be handled. This times are also affected by the timers prescaler, the faster the clock runs, the shorter are the time spans it can handle. Common ranges are from few milliseconds to many hours.

Events scheduled by the clpq have the highest priority, but are still called synchronously within the mainloop and interrupts enabled.

The mainloop will schedule work on the Workqueues until nothing left to be done. Work is always popped from the front of these queues. There are API’s to push work on the back (preferred case) and on the front of this queues. Pushing something on the front of a queue means that it will be scheduled immediately before anything else pending. Thus one get 4 priority levels for work from this queues.

One can push an optional intptr_t argument together with each scheduled function to give a limited ability to pass data around. If this argument is used it will use additional memory in the queue.

The underlying queue implementation in [lib_queue] can be configured in several ways.

Scheduled with a priority below the clpq and above bgq.

Scheduled with the lowest priority.

The clock runs on timer ticks. These macros convert time from second, ms, µs to ticks. Because this needs to result in a integer number of ticks, the result might be inexact and add a slight drift.

The correct configuration of F_CPU is mandatory for these macros to work correctly.

This is the type with the widest range. With sane configurations it can be ensured that muos_fullclock never overflows. The drawback is that it needs the most memory for its representaton which becomes a problem when storing multiple timestamps in queues. Most often the smaller datatypes muos_clock and muos_shortclock are more approbiate when one handles overflows correctly.

This function is very cheap and gives a consistent time throughout the whole mainloop iteration.

Returns time if each mainloop (also recursive from muos_wait() and muos_yield()) iteration start.

Returns the current time as queried from the hardware.

Returns the current time as queried from the hardware, using the muos_shortclock datatype.

Returns the current time as queried from the hardware, using the muos_fullclock datatype.

returns the time difference between now and start. The result is always positive or zero. Simple overflows on the arguments are respected. Thus the full range of muos_clock is available.

For µC’s which support it, the main frequency can be calibrated by some external signal. For example with some 1 second pulse from a RTC one could call muos_clock_calibrate (muos_clock_now(), MUOS_CLOCK_SECONDS(1)) upon receiving this signal.

There is a special case that if sync is 0 then only the internal state is recorded but no frequency calibration is executed. This is to be used for initialization or when the time elapsed since the last call can’t be determined.

Note that frequency calibration is often too coarse to archive perfect synchronization. You should expect some drift remaining. The configuration specially includes a deadband for this. Otherwise when calibration tries to constantly change the frequency there would be very much jitter on the timing.

The following error codes are used nby mµOS, depending on configuration, some might be disabled when the respective subsystem/driver is not enabled.

Wraps fn which must be a function call returning a muos_error an a check for success or returning the error.

Returns the number of errors which are flagged.

When err is muos_success this function just returns. Thus idioms like

are possible.

When err is already flagged, nothing happens.

The *_isr function is for contexts where interrupts are disabled.

Returns err.

Returns true when the error is flagged, false otherwise.

When err was flagged then return true and clear that flag, otherwise return false.

The *_isr function is for contexts where interrupts are disabled.

Prepare the file states.def, configure the Makefile with -DMUOS_SM_DEF=states.def and -DMUOS_SM_NUM=1.

provide enter/leave functions (empty bodies for example):

Then initialize the state machine within the MUOS_INIT function or somewhere else within the application and eventually call state transitions. Error returns left out in this example:

A global list of all defined states. The user has to supply a file which defines MUOS_SM_STATES. This gets x-macro expanded for various things. Note that all states get prefixed with STATE_ not the usual MUOS_* prefix (these are user application defined states anyway).

STATE_NONE gets always defined as the first member implicitly. This is used to flag the state machine when it is not yet initialized or a state transition is in progress.

For each state the user has to define an enter and a leave function. The MµOS state machine driver calls those for changing states.

When MUOS_SM_NUM is greater than one, then state transition functions take an extra parameter which passes user defined data and wont be changed by the state machine driver.

This functions need to be named state_STATE_enter and state_STATE_leave, where STATE is the state as defined above (without the STATE_ prefix).

The leave function will be called first with the intended state transition in the params field. params[0] is the state to be changed to, params[1..3] are user defined subsequent state parameters. The leave function shall validate the possible state transition and may return an error when the transition is denied. Otherwise it should clean the current state up and return muos_successs. Note that the current state might not be fully initialized when the enter function did not complete and changes into a new state immediately. When the leave function returns any error the state stays unchanged.

The enter function is called to finish the state transition and should set up the new state. Errors on enter shall be handled by changing into another error-handling state.

An uninitialized state machine is initially at STATE_NONE and must be initialized to a first state. Again here the API is different depending on the number of state machines to be defined with MUOS_SM_NUM.

When there is more than one state machine one must identify the state machine with the sm index and an initial extra member gets passed and initialized. Later this extra member gets passed unaltered to to the state transition functions.

MUOS_SM_INIT() shall be used to initialize a state machine. Adds some convenience over calling the muos_sm_init() function directly. MUOS_SM_INIT() takes a number of optional arguments for the parameter array which will be initialized to STATE_NONE if not given. The STATE_ prefix must be omitted here as it gets automatically applied.

The initialization calls the initial states enter function synchronously, on successful return the state machine is fully initialized and running.

Initialization returns an error when sm or initialstate is out of range. The state stays at STATE_NONE then.

A state transition on a initialized state machine will be initiated by calling the MUOS_SM_CHANGE() macro. Again depending on the MUOS_SM_NUM the API may require the index of the state machine to change. The first newstate parameter is the state one would like to change to. Any optional subsequent parameters will passed in the params array or initialized to STATE_NONE if not given.

State changing will validate it’s arguments then call the leave function of the current state. When this succeeds the state is temporally set to STATE_NONE to flag that a state transition is in progress and the state enter function for the gets appended to the hpq.

On scheduling before the enter function for the new state gets called the current state and params will be set to the new state.

muos_sm_params_get() queries the params array for the state machine.

muos_sm_get() returns the current state.

muos_sm_name_get() returns a textual representation of the current state.

muos_sm_ready() returns true when the state is not STATE_NONE. For use as predicate to muos_wait()

The UART runs asynchronously driven by interrupts. Data is transferred byte by byte with immediate cyclic buffers. Where supported the transmitter and receiver can be disabled independently.

Access to the UART is always non-blocking, requests which can’t be served returning or flagging an error.

At startup the receiver is in desynched state and waits for \r to appear in the stream where it changes into the synchronized state and data can be read. This ensures that only complete lines are returned to the program. Details can be be configured. In future it will also synchronize when the line is idle.

I/O comes in blocking and non-blocking variants each can be called independently for TX and RX. Blocking I/O means that the job making the I/O is put on hold and the scheduler is called recursively with muos_wait(). There can be only one non-blocking (per direction) I/O pending at any time. Further attempts to do I/O will result in a muos_tx_blocked or muos_rx_blocked error.

Blocking I/O is in some cases more convenient but needs more space on the stack and few more errors can happen. It still works very well with small buffers which may outweigh the stack costs. Over/under-runs of the buffers can never happen.

Non-Blocking I/O is easier to use when it is used exclusively, then only errors for buffer over/under-runs need to be handled, but the program logic can become more complicated when a lot data needs to be transferred as some requests might be larger than the buffers.

There is also support for registering a function which gets pushed onto the hpq when characters ready for reading. MµOS comes with a line editor which can be used in this place.

MµOS comes with a library to do formatted text output over serial. This library does not use printf alike format strings but provides functions for printing each data type. Actually there are 2 implementations with the same API but different functionality. The first one pushes data directly to the transmission buffer while the second one has its own data queue.

Pushing data directly out makes the code pretty small and the linker will only link functions which are actually used. The downside is that the TX buffer needs to hold every byte to be printed. When it overruns an error is reported, but the output might be truncated. This is suitable for small targets with little I/O demands, as long one can provide a big enough TX buffer.

Uses a tagged queue as front-end for the TX buffer. Tagged means that the data can be stored in binary form with some tag about the type in front. The I/O library then also manages a job on the hpq which does the transfer from the txqueue to he txbuffer. When the TXQUEUE is in use the TX buffer can be configured to hold only few bytes.

The implementation ensures that the most compact form will be stored. This can dramatically reduce the memory footprint for the queue. For example numbers are represented in the smallest binary form possible, constant strings can be stored in Flash ROM and are only referenced from the TXQUEUE.

This advantage comes with some weight on the flash side, the TXQUEUE implementation currently weight over 2k of code, still whenever enough flash space is available it should be the considered.

Another advantage is that operations on the TXQUEUE are atomic. Data gets never truncated when the queue is full and an error is returned, either the whole thing gets pushed or nothing in case of an error. Future plans include to add some begin/commit transactions support too.

For building command line interfaces, mµOS comes with a highly configurable line editor. Over time this is planned to become a complete framework for controlling the program.

One can enable it by choosing it as callback function of the UART receiver MUOS_SERIAL_RXCALLBACK=muos_lineedit. Then the line editor presents a user configurable callback which gets called when a line got terminated.

The Line editor can be configure to handle UTF8 encoded text. This only adds moderate size to the code but causes more serial traffic since editing often forces a complete line redraw. When UTF8 support is disabled and only 7-bit ASCII encoding is supported.

Most common line commands are supported. The is cursor moved with cursor keys or vi keys, other editing keys (Home, End, Backspace, Delete, Overwrite) are supported.

There is a very simple line recall handler which lets one restore the previous line when no edits happened yet (Cursor up) or clear the current line (cursor down). This recall feature is very lightweight and needs only one additional byte of RAM and little over 100 bytes program space.

Implements basic EEPROM operations with reasonable fine grained control of actual semantics. Writes are asynchronous, reading can be configured to do batched access. Upon completion of a request a user supplied callback can be called. This callback should also check if any error happend.

The standard write method does a smart write, as it only erases and writes when necessary. There is also a configureable option for retrying a few times writes when write verification failed before returning an error.

Since EEPROM wears out over time overly frequent writing should be avoided. One safety measure against programming bugs writing data in a tight loop is to add a hard delay before the write. This can be configured but should only be enabled in debug builds.

By its nature EEPROM is considered slow and less timing critical, thus it prefers to schedule callbacks on the BGQ when available.

The configstore comes with different facilities.

With all bells and whistles enabled it is failure tolerant to power glitches and damaged eeprom cells.

The Driver generates a slope which accelerates towards max_speed with decreasing acceleration (steppers have less torque at higher speeds), then running a stretch on constant (max.) speed, then going into deceleration until the target speed is reached. Finally some steps are done at the target speed. As soon a slope is loaded and executed the next slope can be generated in background to allow fluent movement.

Before one can start moving a steppers it needs some preparations. If configured then one needs to enable (energize) the steppers first. This may already be blocked by some external input (Emergency Switch).

An energized stepper still does not know it’s position, further some configuration for the machine parameters (speed limits, prescaler, acceleration/deceleration etc.) is required for all but the simplest raw movements.

With steppers enabled and configuration given the stepper can do slow relative movements. But the origin is not known yet. For this the stepper needs to be zeroed (by probing limit switches or similar). When zeroing is done the steppers becomme fully armed and all movement types are possible.

When a stepper completes one or multiple movements it will usually stay in the highest possible state, staying enabled and keep its position until they become explicitly disabled.

Raw movemnt are provided for low level calibration taskes. Care must been taken when using raw movements because these are not constrained by machine parameters and may cause overload/damages.

Since the generation of slope parameters is relatively expensive it can not be done at the instant the stepper shall start moving but need to be prepared beforehand.

For this the set of slope parameters is doublebuffered and a callback function can be invoked to generate the next set of parameters as soon the current ones get activated.

It is also possible to pregenerate and cache slope parameters for common, esp. short movements.

One should configure the minimum and maximum signal lengths. If a signal is to short then muos_error_cppm_frame will be flagged, while longer signals mark the start of a new frame.

When MUOS_CPPM_FRAME_CLOCKSYNC is enabled, mµOS will adjust the µC speed to the cppm frames. This required MUOS_CPPM_FRAME to be configured correctly. This is a way to get even better timing from µC which uses a poor internal oscillator.

In case the hpq is full when the driver wants to push the MUOS_CPPM_CALLBACK function, the error muos_error_cppm_hpq_callback gets flagged.

The callback function will not be called when erroneous frames are received. The user is advised to implement some watchdog to handle this case.

Stores the time in timer ticks as measuered for each channel directly, after applying some configureable filter. This gives the most precision but also needs more memory. Must be enabled with MUOS_CPPM_RAW.

Stores the channel data as values from -125 to 125 mapping to the range from MUOS_CPPM_COOKED_MIN to MUOS_CPPM_COOKED_MAX. Little overflows from -128 to 127 are tolerated. Cooked values need less memory and are more stable, but have lower precision. Must be enabled with MUOS_CPPM_COOKED.

Sets the debug channel to the given state.

MµOS Interrupt debug channel. User defined interrupts should turn the GPIO on right at the start and off when done.

Macro defining the type of a queue for the given size. To instantiate a queue use MUOS_QUEUEDEF(16) myqueue; for example.

Initialization is not necessary at startup, it is only required for to reinitialize and delete an existing queue.

Returns the number of free elements in the queue.

The type for functions stored in a spriq. This function is called with the time it was to be scheduled. The scheduler passes the spriq entry to the function, this makes it simple to schedule repeating jobs, where this event→when just becomes the new base for next push.

Initialization is not necessary at startup, it is only required for to reinitialize and delete an existing queue.

base must be smaller or equal to the smallest (first) element in the queue. For times this is usually muos_now() or the time the event was scheduled. when can cover the full range of the priority data type.

No return, no error checking!

Macro defining the type of a cbuffer for the given size.

Initialization is not necessary at startup, it is only required for to reinitialize and delete an existing queue.

str must not be a continuation byte

Returns the length of a utf-8 encoded string in characters.

char can point into the middle or to the end of a multibyte sequence, but the sequence must have a proper start byte.

Returns the size in bytes of the given multibyte character sequence.