When designing embedded hardware you probably want to visually express what embedded software will be performing and how different functions depend on each other. How to make software documentation simple clear and informative. If you are developer, you may want to explain your ideas understandably without loads of code text. So depending on what level information has to be provided you may choose any of following.
Data Flow Diagram
Data flow diagrams are used when you need to see the processes and what data is transferred between different functions. This way each process or function is expressed as block (or any other shape) while lines shows what information passes between processes.
As you can see in example figure simple data flow diagram is presented. Without program code it is easy to read how program operates:
Data flow diagram for embedded programs may have various forms and types. You may represent what data is transferred between states, but all additional information added expands data flow diagram to impossible sizes especially for big functions. If bigger program needs to be represented, it is better to cut digram in several smaller pieces with connections or use another representation form like State Diagrams.
State diagrams are different from Data flow diagrams because they represent each possible state of software and what inputs case it to change to another state. In many cases State diagrams may be more useful especially if embedded design deal with many buttons and parameters.
At some level state diagrams may be similar to neural networks, when one or several parameters changes program state like several neural inputs may change neuron output. Reading and creating of state diagrams is easy task. Just draw all states as shapes (circle or other figure) and then draw arrows with state changing input parameter. It may be a button, interrupt, timer overflow and so on. But again in complex systems state diagrams become huge and reading is may be difficult because of many relating parameters. One way is to simplify state diagrams to bigger abstract states what makes them similar to flow charts.
Flow charts are more detail and time consuming diagrams. They are not very popular because they aren’t very flexible especially where interrupts are present, but Flow Charts are good where single thread execution need to be described.
Flow charts, data flow diagrams and state diagrams are hard to maintain as they are not a part of program. Charts are easy to read, but maintaining them not always worth a time spent to draw them. If code is changed or updated frequently it may be difficult to track them on charts. Of course there are tools like UML and so on, but they usually deal with objective programming techniques.
There is solution to be more robust but not so visual â€“ Pseudo Code
What is Pseudo Code. This technique is pretty widely used because of it simplicity and robustness. Pseudo code can be written during programming process and then extracted from code. This is nothing more than high level or logical description of each program step. So simply write Pseudocode as comments trying to describe what flags, variables, and other embedded program elements are manipulated by function. What you get by doing this? First of all descriptive comments what allows you to follow code to you or anyone else. Other good thing that these comments can be extracted from code with special program which automatically generates program documentation.
If serial data available, read the data,
do some proprietary stuff I cannot reveal, then
store the data in a flrst in, flrst out (FIFO) buffer.
If the buffer gets too full, and if XOFF was not sent yet,
send XOFF to the host.
If there are data in the FIFO buffer, and if the output interface
is ready, send a byte from the FIFO buffer to the output.
If the buffer gets close to empty, and if XON was not sent yet,
send XON to the host.
If you need you can write pseudo code before program writing, also this is handy when multiple programmers are working on a project. Pseudo code can contain all necessary information that allows developing code parts independently. For instance timer information in milliseconds, RS232 data speed and so on.
Pseudocode is easy to track. If you change something in program, then you update the comments so pseudo-code is updated.
It is good practice to combine documentation techniques including graphical information like high level state diagram, flow chart may represent some specific protocol, data flow is useful where human-machine interaction is present like in security systems how user logs in and so on.
Last advice. Always document or even comment you programs because it is enough for one month to pass when you forget many details in your code. And it takes much more time to read and understand code than commented pseudo-code.