API function requirements

[Rudolph]

I am trying to extract requirements for the commands from the programming guides, I am thinking about doing unit tests for my library and I need requirements for these that are not derived from my code.
The least I could do with such a list of requirements would be to check it against my header file.

After a number of iterations with ChatGPT the resulting .json starts to look ok:

Code Select Expand


   {
    "prototype": "void cmd_swap( );",
    "layout": [
      "+0 CMD_SWAP(0xFFFF FF01)"
    ]
  },
  {
    "prototype": "void cmd_append( uint32_t ptr, uint32_t num );",
    "layout": [
      "+0 CMD_APPEND(0xFFFF FF1E)",
      "+4 ptr",
      "+8 num"
    ]
  },


I ran into several issues though and I could not fix them all, yet.

First of all, the layout of the document, there a couple of "C prototype" that cross page boundaries so I end up with this:

Code Select Expand


  {
    "prototype": "void cmd_mediafifo ( uint32_t ptr, 119 Product Page Version 2.6 Document Reference No.: BRT_000225 Clearance No.: BRT#129 uint32_t size );",
    "layout": [
      "+0 CMD_MEDIAFIFO (0xFFFF FF39)",
      "+4 ptr"
    ]
  },



Then consistency.
Commands that need to be followed by data like cmd_inflate should have a pointer for that data as parameter and also a parameter for the amount of bytes.
But the real issue is how the "Command layout" looks like.

CMD_INFLATE: +8 ...n byte0 ... byten
CMD_INFLATE2: +9....+n byte1...byten (which is plain wrong since options is 32 bit wide and data starts at byte 0)
CMD_LOADIMAGE: +12 byte 0 / +13 byte 1 / ... ... / +n byte n - creative, but why so different?
CMD_PLAYVIDEO: +8~ +n byte1 ... byten - even more creative and also wrong with byte1
CMD_FLASHSPITX: byte1...byten the data to transmit - does not state the offset
CMD_FLASHWRITE: +12...n bytes1 ...byten
CMD_MEMWRITE: +12 ...n byte0 ... byten


BT82x:
CMD_INFLATE: +12....+n byte1...byten - also not correct as data does not start at byte 1.
CMD_LOADASSET: +12 byte1 ... byten
CMD_LOADWAV: +12~ +n byte1 ... byten

And for text we have these:
CMD_BUTTON: +16 s / +17 ... / ... ... / +n 0
CMD_KEYS: +16 s / ... ... / +n 0
CMD_TOGGLE: +16 s
CMD_TEXT: +12 s / .. .. / .. 0 (null character to terminate string)
CMD_TEXTDIM BT82x: +12 s / .. .. / .. 0


That is nothing that can't be fixed with a little manual editing and/or perhaps a couple more exceptions for the parser,
but a good specification should be correct and consistent across the board.

And I just noticed for example that for BT82x CMD_COPYLIST, CMD_SAVECONTEXT and CMD_RESTRORECONTEXT are skipped, the function prototypes for these do not have the ";" at the end.

[BRT Community]

Hello,

Thank you for your post.

I will enquire with the software team to see if they have a document which covers the C prototypes for each support EVE command.

Best Regards,
BRT Community

[Rudolph]

The prototypes are not what I am looking for, I am looking for what the functions are supposed to do,
hence the extract with the "prototype" and the "layout".

But the important part of my post is, at least BRT_AN_086_BT82X-Series-Programming-Guide_1.0.pdf and BRT_AN_033_BT81X_Series_Programming_Guide_2.6.pdf are not consistent enough to have ChatGPT successfully write a python script to extract function requirements.
I even reached the point now that ChatGPT can no longer fix the script further, the script changes, but the result stays the same.

The data really is not an issue, I get about 95% extracted fine and can fix the rest manually.