summaryrefslogtreecommitdiff
path: root/support/dktools/changes.dox
blob: 5d3b9d081db6c01d4ffbc3a43ee3a8d798264d8c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
/**	@page	changes	Changes since version 3.

@section	errorreporting		Error reporting

@subsection	errorreportold		Old behaviour
In version 3.x.x many functions had a final dk3_app_t pointer
argument for diagnostics. This argument was allowed to be NULL if
no error reporting was intended.

Use of these functions pulled the dk3app modules into the project
and other modules required by this one...

A resource for error reporting was passed from the calling function
to the called function.

@subsection	errorreportnew		New behaviour
Now the dk4_er_t data type can be used to pass error information
from a called function back to the caller.

A calling function initializes an error report using the
dk4error_init() function, this function sets a special error code
indicating ``No error occured''. The address of the error report
is passed to called functions.

If an error occurs within a called function, the function uses
one of the dk4error_set...() functions or dk4error_copy() to place
an error code and optionally details in the error report.

Sometimes one error results in further errors. In such situations information
about the first error is of most interest. So the dk4error_set...() and
dk4error_copy() functions leave the error report unchanged if it already
contains information about an error.

Information about errors is passed from the called function back to the
caller, it is up to the caller whether to use this information or not.


@section	microcontrollers	Microcontrollers
Using a function from the printf()/scanf() function family pulls many
modules from the standard library into the executable to build.

This is not a problem on desktop or server systems, but microcontroller
systems have a limited amount of memory available.
So the printf()/scanf() functions should not be used when programming
for microcontrollers.

So these functions are used only in a very few places in the 
libdk4c library, mainly in the dk4ma*dbl.c modules.
When programming for microcontrollers, you should avoid to use these modules.

The printf()/scanf() functions are used in some modules of the dk4app
library, this library is not intended for use on microcontrollers.

@section	wincrt			Windows and the C runtime library
You can not rely on having the C runtime library available on Windows
systems. The CRT is typically installed during Visual Studio installation
and is available in MS Download Center.

When developing Windows extension DLLs, Windows drivers or Windows services
you should not use the C runtime library (CRT), use the Windows API instead.

For some tasks (i.e. memory allocation, string copying...)
the Windows API contains mechanisms equivalent to the CRT mechanisms.

For other tasks (i.e. finding a character in a string) there is no
Windows API function available, but the DK libraries contain a self-made
fallback function.

For some mechanisms from CRT (i.e. FILE I/O using functions like
printf()) there is no equivalent mechanism in the Windows API.

You can define DK4_WIN_AVOID_CRT to a non-zero value. This avoids use of the
CRT for mechanisms having an equivalent in the Windows API and for
mechanisms with self-made fallback functions. For mechanisms not available
in the Windows API the CRT functions are used.

You can define DK4_WIN_DENY_CRT to a non-zero value. This completely
denies the use of CRT functions. Some of the DK library modules can not
be compiled this way (i.e. the dk4fop*.c and the dk4fd.c module).

When using Windows API instead of CRT some DK library functions will
produce less descriptive diagnostic messages.
POSIX and Linux man pages for a CRT function contain an ``ERRORS'' section
with a complete list of errno codes for the function.
A programmer using a CRT function on POSIX or Linux systems can check
for all errors which might happen in the function and produce
descriptive messages for all of them.

*/