Confusing definition

RE: Confusing definition

michurin — Fri, 15 Nov 2013 13:44:23 GMT

An application does care what is it reading/writing. In your code memory is statically allocated by the library which obviously has no clue about any data object and thus should be uint8_t data[] or uint8_t data[MAX_SIZE]. My point is that application code should not need to ever declare a variable but create a typedef to parse in/out data

RE: Confusing definition

Ole Morten — Fri, 15 Nov 2013 13:40:00 GMT

I'm wasn't offended, but I find it strange to downvote an answer, not because it's wrong, but because you personally disagree with it. Even when re-reading your original question and my answer, I honestly think I've answered the exact questions you were raising.

Since I don't know a lot about your proficiency with C, I found it appropriate to include some pointers for further information in case my explanation wasn't clear. This may also be useful for other people that later may find this question.

I do agree with your general intentions of writing clear code, it's just that we disagree on whether this particular definition is clear or not. Using a well-established pattern, even though an apparently slightly controversial one, is normally exactly what I'd say is a good solution.

Warnings should of course always be avoided, and that something works is in itself no excuse for having out-of-spec code, it's just that this snippet in question is not out-of-spec.

I'm not going to go further into your try to make this a discussion on education and profession, but I can assure you that most people working in our software department are properly educated software engineers.

RE: Confusing definition

Ole Morten — Fri, 15 Nov 2013 13:28:20 GMT

I'm not sure I understand what you mean about static declarations. My point was that application code should not need to ever declare a variable of this type (although possibly a pointer to one).

Unfortunately, I don't think we'll ever fully agree on what is most readable and not here, but I've added a request internally to consider this question again, either adding a more extensive comment or possibly also change the declaration to [], to indicate that the length is in fact unknown at compile time.

RE: Confusing definition

michurin — Fri, 15 Nov 2013 13:26:30 GMT

"I'm a little unsure why you found my answer worthy a down-vote, though, as I seriously tried to explain why this was there and what it means."

This is mostly result of my frustration and I did instantly try to remove but a) I'm not smart enough to figure out how to do so, b) this website doesn't allow to.
I was unhappy with your intent to explain me C and not the subject of the matter. If you will this is sort of religious war between software professionals and electrical engineers who are writing code... Software people are trained always to write code that not only works but it is portable, warning free, readable and clear how it does so when EE guys are usually stopping with "it works now" and maybe adding some comments...
I'm sorry if in any way offended you.

RE: Confusing definition

michurin — Fri, 15 Nov 2013 13:14:58 GMT

"in my opinion whether that's any clearer is mostly a matter of taste, when most of this array may very well be uninitialized memory." I'm always applying the rule: clearly define the object and use it's definition. In other words in my application expects a message it needs to know how to interpret it. So typedef enum { MON, TUE, WED, THU, FRI, SAT, SUN } my_app_t is much better than uint8_t week_day; And when the message structure is typedef struct { my_app_t begin; my_app_t end; } my_msg_t; I'd verify that len is == sizeof(my_msg_t) and then will use it as data->begin and data->end and not data[0] and data[1] and getting warning about data[1]... BTW Warnings should be strictly prohibited - compiler doesn't understand your intent and therefore such code is not portable even if it is correct for particular case.

Isn't if clear and very readable?!

uint8_t

RE: Confusing definition

michurin — Fri, 15 Nov 2013 13:01:08 GMT

I'm trying to response as soon as I can to beat the time difference, so excuse me it is little bit aster 6 in the morning here... Your said:"Beware that you are never expected to initialize a struct of this type, as it's only an event structure". There is option static winch forces a compiler to initialize memory with 0 and yes this is static and not dynamic memory. That is exactly what SD is doing. BTW please mention the exact type: we're talking about quite few in this discussion.

http://c-faq.com/struct/structhack.html char data[] is defined in C99 and not in C89 as you said before. char data[1] is defined in both standards. Yet it is very tastefulness to use [1] as commenting it as variable length. In this case adding extra pointer and all hassles which come with it is much better for readability. It worth it from my stand point especially if this code is published for other people reading/using. Don't see any issues with static allocation by SD array of MAX_MTU size and application casting it to the any type it knows and needs.

Thank you for coming back to this discussion.

RE: Confusing definition

Ole Morten — Fri, 15 Nov 2013 12:15:12 GMT

Beware that you are never expected to initialize a struct of this type, as it's only an event structure, initialized by the softdevice to notify you as an application of an incoming Write Command / Request.

If you are to initialize some other struct employing the same concept, you would manually have to make sure to initialize it with appropriate size for the data you want to fit.

After checking a little more, it's apparently known as the "struct hack", and explained in more detail here, including how to initialize such struct: http://c-faq.com/struct/structhack.html

RE: Confusing definition

Ole Morten — Fri, 15 Nov 2013 12:11:22 GMT

This array will always have a length >= 1. For the write event in particular, it can be up to BLE_L2CAP_MTU_DEF-3 bytes, as given in the Bluetooth Core Specification, Volume 3, Part F, section 3.4.5.1 and 3.4.5.3.

As I mentioned in another comment below, the actual length will indeed be variable, and depends on how much data the peer device actually wrote.

RE: Confusing definition

Ole Morten — Fri, 15 Nov 2013 12:09:11 GMT

I'm sorry for the delay here, but we've been busy with internal training lately.

I guess you're right that another option instead of using the [1] would have been to use [BLE_L2CAP_MTU_DEF], but in my opinion whether that's any clearer is mostly a matter of taste, when most of this array may very well be uninitialized memory.

This array will actually be variable length, since it will contain whatever was in the write event coming over the air. From the S110 side, you have no control over this, it's only limited by the peer device and the Bluetooth Spec.

I'm a little unsure why you found my answer worthy a down-vote, though, as I seriously tried to explain why this was there and what it means. I'm sorry if I came off rude, but I can very well see why this seems confusing. What I can't quite understand is how you can insist that I and my explanation is wrong.

RE: Confusing definition

michurin — Wed, 13 Nov 2013 22:08:46 GMT

This is the answer: ble_stack_handler_init(). Don't like it though but this is matter of taste and > de gustibus non est disputandum .
Even taking programming stile aside yet the comments must be better and cleaner.

RE: Confusing definition

Guest — Wed, 13 Nov 2013 18:11:57 GMT

Matt, are you saying that length can't exceed one byte? It seems to me wrong... Yet we have another ambiguity...

RE: Confusing definition

Bastiaan — Wed, 13 Nov 2013 18:11:57 GMT

Matt, are you saying that length can't exceed one byte? It seems to me wrong... Yet we have another ambiguity...

RE: Confusing definition

Matt — Wed, 13 Nov 2013 16:52:49 GMT

I think the confusion here is about the comment associated with the struct member data. It is clearly an array of length one, but the comment documenting it says it is variable length. If data were more than one element long the it could be undestood that the maximum expected size was always allocated but not always used, but here data is only one element. I suppose this struct could be populated with zero or one elements in data which would make it variable length.

So the questions:

Is it valid for length to be zero, implying data should be ignored?
is it valid for length to be one, implying data contains a single element?
If zero length is not valid, is the comment stating that data is variable length erroneous (i.e. the result of copying a template, pasting, editing names, and not updating the comments)?

RE: Confusing definition

michurin — Wed, 13 Nov 2013 02:39:48 GMT

Please notice that we're arguing NOT about C but about stile and readability.

RE: Confusing definition

michurin — Wed, 13 Nov 2013 02:30:32 GMT

"to make it clear that the array is placed inside the struct, and not just a pointer to somewhere else." Understood. To achieve that one has to allocate the maximum possible length and then length will become variable from 1 to max. If such maximum length is defined as one how come it possible be variable as the comment says?! Also this approach means that EACH write event has to have its own type and if so how this type is defined inside the common library header?

I'm afraid that this dialog is going to nowhere and if so it is probably the best to stop it as is unresolved...

RE: Confusing definition

michurin — Tue, 12 Nov 2013 17:53:17 GMT

Sorry again...How can one implement variable length? Byte by byte with the offset 1? Why then have member len? I have serious trouble understanding your point. Yes one can create ble_gatts_evt_X_write_t, ble_gatts_evt_Y_write_t, ble_gatts_evt_Z_write_t and so on and in this case each event will have its own constant not variable length. Or use ble_gatts_evt_write_t with the length 1 and use offset if more than one byte is required. Or I'm totally misunderstanding what those types are trying to achieve...

Lets say I have LED which is using event write to turn it on and off(bool) and I have a DAC and need to set it up(uint16_t). How to manage this combination?

Thanks!

RE: Confusing definition

Ole Morten — Tue, 12 Nov 2013 17:35:05 GMT

This isn't really feasible, as the value within this array can be any data, of any format. If you look into the on-air operations, there is no requirement that this data is structured in any way. Also, even if the characteristic value have a certain structure, the data used here can be offset, and hence have no structure after all. A variable sized array is therefore the only reasonable option as far as I can see.

RE: Confusing definition

Ole Morten — Tue, 12 Nov 2013 17:33:04 GMT

I'm sorry, but I can't really help that you find it confusing, but this is perfectly valid C, and the use case is fine: to make it clear that the array is placed inside the struct, and not just a pointer to somewhere else.

I'd again like to recommend having a look at the blog post I linked. Also remember that this struct is inside a ble_evt_t, and where it is primarily used, in BLE_STACK_HANDLER_INIT(), space is allocated like this: static uint32_t EVT_BUFFER[CEIL_DIV(sizeof(ble_evt_t) + (MTU_SIZE), sizeof(uint32_t))]; This makes sure that sufficient space will actually be allocated, since the MTU_SIZE is added to the sizeof(ble_evt_t), exactly to accommodate the variable size arrays that are part of several events.

RE: Confusing definition

michurin — Tue, 12 Nov 2013 16:06:51 GMT

One more thing: if array has predefined length then it needs to be less than uint16_t len; /* Length of the incoming data. */.

The way I see the intention of the developer is:

typedef union {
unit8_t event_x[1];  /* event x message */
uint16_t event_y[2];/* event y message */
void *event_z; /* event z message */
/* more event messages if necessary */
} event_message_t; /* union will have the size of known largest message */
struct
{
...
uint16_t len; /* Length of the incoming data; len <= sizeof(event_message_t); */
event_message_t data;
}ble_gatts_evt_write_t;

RE: Confusing definition

michurin — Tue, 12 Nov 2013 13:02:32 GMT

Sorry Ole, I'm not satisfied. some_t data[X] allocates memory for X elements of some_t, in our case uint8_t data[1] allocates exactly one byte. Yet the comment says variable length! Is this not confusing? One needs to choose array of predefine length of exact or max_len size or void pointer which application will cast to the necessary type. Once again I'm finding existing typedef including its comment confusing: If one has more then one write event and they do have different length of writing data then more then one typedef will be required.

RE: Confusing definition

Ole Morten — Tue, 12 Nov 2013 10:57:06 GMT

The point of this declaration is that the array is actually located here, and it's not just a pointer to another area. In C99, you would write this as data[], but this is not legal in C89, hence this [1].

Having it like this


struct
{
    uint8_t * data;
} ble_gatts_evt_write_t;

would imply there is just a pointer to some other memory area in the actual event structure, while this


struct
{
    uint8_t data[]; // or data[1] in C89
} ble_gatts_evt_write_t;

shows that the entire data is actually located in this memory area.

Initially, it was a requirement for the softdevice headers to be C89 compliant, and even though we've abandoned this, some things like this still lingers in the code. However, when using this buffer, these two declarations are mostly equivalent, although it may matter in case you need to copy the structure.

It seems to me that this blog post explains the difference between a pointer and an array in a good way, if the difference is still unclear.