proper naming of SCPI functions handling integer (and other) types about scpi-parser

[j123b567]

Hm, next huge pitfall in my library.

Ok, there are these possibilities:

1. use C style naming in camelCase SCPI_ParamUnsignedLong, SCPI_ParamUnsignedInt, SCPI_ParamLongDouble - my case
2. use shortened C style naming in camelCase SCPI_ResultUInt, SCPI_ResultLong - your case
3. use stdint syle naming in camelCase SCPI_ParamUInt32, SCPI_ParamInt64, SCPI_ParamUInt8 with explicit size
4. use SCPI naming SCPI_ParamUINT64, SCPI_ParamINT8 - almost the same as previous case, but different in float types and extended with "Swapped" types

Number 1 is so long and has same problem as number 2 - it is not intuitive on non 32bit platforms.

Now, I think the best would be 3 or 4 and keep 1 as compatibility macros.

What do you think?

For a generic SCPI library supporting swapped types would make sense. at least with my current limited SCPI knowledge I think so. And if this swapped types are supported then probably the best naming convention would be option 4 (using type names defined in the SCPI standard).

What I am still unsure of, is the purpose of the types listed in section 6.4.2. The list is intended for block data transfers, I am not sure if it also applies to Parameters and Return values. Maybe there is another list specifically for those. The standard is 800 pages long and I just started reading it.

[j123b567]

There are additionaly 260 pages of IEEE488.2.

After reading important parts of SCPI specification,
the list in 6.4.2 is just for binary encoding. Where normal types are for Big-endian systems and swapped types are for Little-endian.

There is also section in format subsystem 9.2
But it just defines that textual representation that can be in format NR1, NR2 or NR3, HEX, OCT or BIN http://cp.literature.agilent.com/litweb/pdf/ads2001/dcpwrsrc/dcps068.html
Other formats are just binary block.

For me, it does not make sense to support "Swapped" types by SCPI_ParamXYZ and SCPI_ResultXYZ.

There is also no need to have explicit support for shorter types then 32bits for now. (or is there?)

We can start with

function	type	original
SCPI_ResultInt32	int32_t	SCPI_ResultInt
SCPI_ResultUInt32	uint32_t
SCPI_ResultUInt32Base	uint32_t	SCPI_ResultIntBase
SCPI_ResultInt64	int64_t
SCPI_ResultUInt64	uint64_t
SCPI_ResultUInt64Base	uint64_t

function	type	original
SCPI_ParamInt32	int32_t	SCPI_ParamInt
SCPI_ParamUInt32	uint32_t	SCPI_ParamUnsignedInt
SCPI_ParamInt64	int64_t
SCPI_ParamUInt64	uint64_t

function	type	original
SCPI_ParamToInt32	int32_t	SCPI_ParamToInt
SCPI_ParamToUInt32	uint32_t	SCPI_ParamToUnsignedInt
SCPI_ParamToInt64	int64_t
SCPI_ParamToUInt64	uint64_t

function	type	original
SCPI_StrToInt32	int32_t	strToLong
SCPI_StrToUInt32	uint32_t	strToULong
SCPI_StrToInt64	int64_t
SCPI_StrToUInt64	uint64_t
SCPI_Int32ToStr	int32_t	SCPI_LongToStr
SCPI_UInt32ToStr	uint32_t
SCPI_Int64ToStr	int64_t
SCPI_UInt64ToStr	uint64_t

Doubles are different story, we can also introduce float/single, double, long double/quad/extened, but I would like to skip this for now.

So option 3 is currently the best for me.

OK, I agree with option 3. Below are some comments.

Endianness is only important when serializing/deserializing data, so for file storage and network transfers. It should be enough if functions handling arbitrary data transfers handle swapping, they would probably have to be aware of the endianness of the toolchain.

We use int16 data for 14 bit ADC and DAC, and uint8 data could be useful for a logic analyzer.

For floating point numbers 16 bits do not offer much precision, so I would implement only 32 and 64 bit floating point types. Also 16 bit single precision floating point is not mentioned in the standard.

In any case just for completeness sake I would support all sizes mentioned in the standard.

[j123b567]

Standard does name only textual representation NRx, but not internal binary representation of the parser. Having one '_ParamInt and '_ResultInt was enough to comply with standard format NR1. NR2 and NR3 are about floating points.

I think, there is a reason to support system native type and everything up. So for example on ARM Cortex-M4, we should support int32 and float as native types and int64 and double as extended types.

You are probably using ADC, DAC and logic analyzer in conjunction with arbitrary data functions.

Returning uint8_t/uint16_t by SCPI_ResultUInt32 is straightforward. It is possible to have jsut macros for smaller types. We can add real functions just for 16bit and 8bit systems. For 32bit and 64bit systems, there is no meaning for these functions.

Filling uint8_t/uint16_t value by parameter is not so straightforward so we can add these functions in next step.

For floating point, I mean

• 32bit single aka float
• 64bit double
• 80bit extended aka long double
• 128bit __float128

no 16bit half precision, because it is not possible to represent it in C.

OK, I understand your reasoning regarding small 8/16 bit types now.

Could you point me to where in the standard regular vs swapped byte ordering is defined as little or big endian, I could not find it by searching for the usual keywords.

I could start coding the function renames and new functions in a separate branch and then offer you a pull request from our fork.

[j123b567]

6.4.2 FORMat

Similarly, to transfer #H12345678 as an INT32 (32-bit integer), transfer the bytes in the order: 12 (hex), 34 (hex), 56 (hex), and 78 (hex). To transfer #H12345678 as an SINT32 (32-bit swapped integer), transfer the bytes in the order: 78 (hex), 56 (hex), 34 (hex), and 12 (hex).

In https://en.wikipedia.org/wiki/Endianness, you can see, that INT32 definition is Big-endian, and SINT32 is Little-endian. Big-endian is easier to read by human - it is in the same order as you write it on the paper - so in sense of SCPI-99, it is "normal" order. Please correct me, if I'm wrong.

I have experience with endianness from hardware development, so I will be able to get it right. To me they are both as easy as they are well documented :). It is usually not enough to say it is big or little, an example is needed in most cases. The quote you copied is clear enough.

I want to make sure our SCPI implementation will be compatible with third party implementations.

[j123b567]

Solved by pull-request #53