244 lines
11 KiB
Plaintext
244 lines
11 KiB
Plaintext
Proposed Plan for adding Nano Meters into PCBNEW as the Board Internal Unit
|
|
===========================================================================
|
|
|
|
Author: Dick Hollenbeck November 25, 2011
|
|
|
|
Introduction:
|
|
============
|
|
|
|
This document sketches out a plan to move KiCad's PCBNEW program from deci-mil
|
|
internal units to nanometer internal units. The changes to the code are
|
|
significant enough to describe the basic process before the work is started.
|
|
|
|
Definitions:
|
|
===========
|
|
|
|
*) Board Internal Units (BIU). This is a pseudonym for the engineering units
|
|
used by a BOARD when it is in RAM, and only when it is in RAM. BIU is
|
|
essentially equal to nanometers in the future, and equal to deci-mils currently.
|
|
A BIU refers typically to a measurement or a position on an XY grid, and this is
|
|
because this grid is dimensioned in BIUs along both its X and Y axes. Both X and
|
|
Y can be either positive or negative on this grid. In the case of measurements
|
|
or scalars, there can be a radius, a diameter, a distance (length), and all of
|
|
these can and should be expressed in BIUs, so long we are in RAM and so long as
|
|
we are talking about the objects within the class BOARD instance. One special
|
|
feature of XY points within the BIU coordinate system is that they will always
|
|
be integers. In contrast, distances and other forms of measurements are not
|
|
subject to the same limitation by the very nature of physics. Coordinates are
|
|
always integers because we used signed whole numbers to represent these BIU
|
|
coordinates.
|
|
|
|
*) Snap grid. A snap grid is a subset of the full set of possible XY coordinates
|
|
in the BIU coordinate system. Points falling on the snap grid are evenly spaced
|
|
in X and Y directions and are some integer multiple apart in this 2D space,
|
|
greater than one BIU.
|
|
|
|
Assumptions:
|
|
===========
|
|
|
|
a) It is ok to modify the board file format in order to handle the BIU change.
|
|
|
|
b) Boards saved on disk in the new format will not be readable using old software.
|
|
|
|
c) Since we have no backwards compatibility obligation (see b) above), we can
|
|
make significant changes to the file format while we have this disruption
|
|
opportunity.
|
|
|
|
General:
|
|
=======
|
|
|
|
With nano meters as the Board Internal Unit (BIU), a 32 bit signed integer can
|
|
only hold about 2 meters of positive length and 2 meters of negative length.
|
|
Moreover, because most of the bits within a 32 bit integer can be "used up" to
|
|
hold a typical length within a board, it is very likely that if pure 32 bit
|
|
integer math is done, such as the multiplication of two integers in order to
|
|
calculate a hypotenuse, then there will be an overflow within the 32 bit
|
|
integer. (Another way to think of the BIU acronym is "Board Integer Unit" instead
|
|
of as Board Internal Unit, to pave the way for the BFU, discussed below.)
|
|
|
|
Therefore all intermediate products, quotients, trig, and exponential
|
|
calculations should be done using some larger floating point type. By larger,
|
|
bitness or number of bits is meant. Distances that do not have to be rounded
|
|
back to integer immediately can and should stay in the larger floating point
|
|
"value container" for as long as possible. The typedef name of this floating
|
|
point type is BFU (Board Float Unit). The engineering units on a BFU are the
|
|
same as on a BIU. A typedef is nice so that we can toggle between double and
|
|
"long double" for various compilations, and so that when performing casts, these
|
|
are brief textual expressions.
|
|
|
|
Format Strings:
|
|
==============
|
|
|
|
Because all our save to disk functions use printf() style format strings, we
|
|
discuss how to construct a format string in the most usable way. There should be
|
|
a printf() style format string like "%.6g" for the BFU (cast to a hard coded
|
|
double) enclosed within a #define and its name should be FMT_ENG. This format
|
|
string will be used at least for saving BOARD and MODULE files, and perhaps
|
|
more.
|
|
|
|
FMT_ENG stands for "format string for ENGineering units used out in the file". A
|
|
define is needed simply to provide consistency across many sites of usage. BIUs
|
|
will be scaled before being written to disk in most every case, and since
|
|
scaling is a multiplication, it means casting one of the factors to BFU, and
|
|
then this product is output with a printf() style function using the FMT_ENG
|
|
string segment.
|
|
|
|
That is, the FMT_ENG will be suitable for use with a BFU type. When BFU is set
|
|
to double, then FMT_ENG will be set to "%.6g". When BFU is set to long double
|
|
then FMT_ENG will be set to "%.6Lg". For example:
|
|
|
|
#if USE_DOUBLE_BFU
|
|
typedef double BFU;
|
|
#define FMT_ENG ".%10g"
|
|
#else
|
|
typedef long double BFU;
|
|
#define FMT_ENG ".%10Lg"
|
|
#endif
|
|
|
|
A format string can then be built up using compile time concatenation of
|
|
strings, like this:
|
|
|
|
fprintf( fp, "Value: " FMT_ENG " " FMT_ENG "\n", BFU( biu1 * scale), BFU( biu2 * scale ) );
|
|
|
|
The 3rd and 4th arguments are BFUs, and the casting is done after the multiply
|
|
since the scaling factor is already a double or perhaps even a long double. The
|
|
final argument needs to match the format string, so the final product is wrapped
|
|
in a BFU, which could actually be a truncation down to 64 bit float from 80 bit
|
|
float. The key points are: the calculation must be done in a float type at least
|
|
as bit-wide as BFU, and that the value actually passed to fprintf() must match
|
|
the format string.
|
|
|
|
Choosing BIU Units:
|
|
==================
|
|
|
|
BIUs are only used when a BOARD or MODULE is in RAM. A BIU is equivalent to
|
|
either a 1) deci-mil or 2) nanometer, depending on how the source code is
|
|
compiled. It is not a runtime decision. Form 1) is needed only during the
|
|
preparation phase of the source code transition to nanometers. After the
|
|
transition, only nanometers will be used in the compilation. No runtime
|
|
switching is needed or wanted. Again, BIUs can only be one or the other for a
|
|
given compilation, and this will swing based on a single #define.
|
|
|
|
Eventually we may want to actually use "BIU" as our integer type in source code
|
|
for those lengths which pertain to the board coordinate space. This would give
|
|
us the ability to easily modify it, go to a larger bitness, make the source code
|
|
more readable, and keep the type information out of the variable name. This
|
|
would mean having a point and/or size class based on BIU as the contained
|
|
integer types. This is a nice to have, but not immediately mandatory.
|
|
|
|
There will be a number of places within the source code which will have to be
|
|
doctored up to use the BFU casting. It will take some time to find all these
|
|
sites. During this time it should be possible to continue using deci-mils as the
|
|
BIU for source compilation.
|
|
|
|
There are a quite a number of path ways in and out of BOARDs and MODULEs. Most
|
|
everyone of these pathways involve conversion or scaling of BIUs. An example of
|
|
a pathway in is a BOARD disk file loading function. An example of a pathway out
|
|
of a BOARD is a disk file saving function. Likewise for MODULEs. We can
|
|
characterize the load and save functions by their source and destination
|
|
representations of lengths.
|
|
|
|
BOARDs and MODULEs will soon have a new format, which is basically the existing
|
|
format expressed in um or nm (TBD) rather than in deci-mils. For discussion, we
|
|
will say this new format is in mm, even though it may end up being in um. In
|
|
another year or two we will switch to s-expressions, or sooner if there is a
|
|
volunteer.
|
|
|
|
Here are the required immediate need BOARD load functions:
|
|
|
|
1) Legacy to deci-mil loader. This loader uses a floating point scaling factor
|
|
of unity, since destination is a RAM BOARD using deci-mils as its BIU.
|
|
|
|
2) Legacy to nanometer loader. This loader uses a floating point scaling factor
|
|
of 2540, since destination is a RAM BOARD using nanometers as its BIU, and
|
|
the source format is using deci-mils.
|
|
|
|
3) mm to nanometer loader. This loader uses a floating point scaling factor
|
|
of 1000000, since the destination is a RAM BOARD using nanometers as its BIU.
|
|
|
|
There is no need for a nm to deci-mil loader. (Once somebody saves a file in the
|
|
new format, that format is used going forward, or its backup in the old format.)
|
|
|
|
Now duplicate the above 3 loader types for MODULEs.
|
|
|
|
Here are the required immediate need BOARD save functions:
|
|
|
|
1) deci-mil to deci-mil, using a floating point scaling factor of unity. It
|
|
should be possible to use trailing zero suppression on the deci-mils to get a
|
|
BOARD that is identical to an old BOARD, and this can be used to test the new
|
|
save function, using "diff" with whitespace ignore. This saver is only in play
|
|
when the BIU is compiled to be deci-mils.
|
|
|
|
2) nanometer to mm, using a floating point scaling factor of 1/1000000. This
|
|
saver is only in play when the BIU is compiled to be nanometers.
|
|
|
|
Now duplicate the above 3 saver types for MODULEs.
|
|
|
|
New BOARD and MODULE files will have a new field in them identifying the
|
|
engineering units used, say mm.
|
|
|
|
In actuality, the source code to all 3 loaders, and to all 3 savers can be the
|
|
same source code with a single variable in each case for scaling.
|
|
|
|
All 6 loaders and all 6 savers should be written in parallel with existing
|
|
loaders and savers, so that we can toggle usage back and forth between the two
|
|
for awhile. This means we do not gut existing savers and loaders until the new
|
|
ones are debugged and stable.
|
|
|
|
The new savers and loaders are to be done in the context of a plug-in
|
|
architecture, described elsewhere.
|
|
|
|
Angles and Rotations:
|
|
====================
|
|
|
|
Internally we are switching from using an int to hold 1/10 of degrees angle to a
|
|
typedef called DEGREES. The allowed values that DEGREES can hold will be
|
|
enforced by the user interface policy, decided elsewhere. The engineering units
|
|
in the DEGREES type is degrees, no longer tenths of degrees.
|
|
|
|
/// a value used to hold rotations or angles.
|
|
typedef double DEGREES;
|
|
|
|
|
|
User Interface Changes:
|
|
======================
|
|
|
|
All these changes have to be done in a way where they hinge on one #ifdef.
|
|
|
|
*) The grid dimension choices will have to be changed.
|
|
|
|
*) The drawing routines will have to be changed to handle the case that BIU is
|
|
compiled to be nm. Work towards getting legacy drawing code capable of handling
|
|
a compile time #define to control a single scaling factor. Only the scaling
|
|
factor should need be changed in the final state. Up until then, the work
|
|
required is to inject the BFU casting where needed along with the scaling
|
|
factor(s).
|
|
|
|
*) Remove any funky imperial to metric conversion functions which tried to hide/mask
|
|
problems with lack of BIU precision.
|
|
|
|
*) There may be some fix ups pertaining to "near enough" type testing involving
|
|
the user's mouse position, other than bounding box hit testing which should take
|
|
care of itself (in BIUs). This has more to do with near-ness to a line type
|
|
tests, and these are thought to best be done in screen coordinates anyway, not
|
|
BIUs.
|
|
|
|
Work Tasks:
|
|
==========
|
|
|
|
*) Within PCBNEW, find math expressions involving BIUs and cast them to BFUs
|
|
early enough so that the compiler generates code in the BFU realm.
|
|
|
|
*) Find a way to consistently round values from BFUs back to BIUs, and put that
|
|
code in place. This could be done using a set accessor on a BIU, or other way.
|
|
|
|
*) Fix the User Interface issues mentioned above, and more found later.
|
|
|
|
*) Write the 4 new load and save functions. Vladimir recently committed code
|
|
which can be a starting point for some of these functions, except that the new
|
|
ones should reside within a PLUGIN object where we can save the scaling factor
|
|
variable as a member field of the plugin. In order to meet the requirements
|
|
of all 3 board loaders, we may have to dynamically change the scaling factor
|
|
depending on what we find in the *.brd file and how the plugin is compiled.
|
|
|